How to use Application.MapPaperSize in the xlwings API way

The MapPaperSize member of the Application object in Excel is a property that enables developers to control whether Excel automatically scales printed output to fit the paper size defined by the printer driver. This is particularly useful when dealing with documents that may be printed on different printers with varying default paper sizes, such as switching between A4 and Letter formats. By setting this property, you can ensure consistent print scaling behavior, preventing unexpected layout changes or scaling issues when printing across diverse systems or regional settings.

Functionality:
The primary function is to manage automatic paper size mapping. When enabled, Excel attempts to match the paper size in the document’s page setup with a similar size available in the current printer’s driver. If a direct match isn’t found, Excel may scale the printout. Disabling this property turns off automatic scaling, which can be beneficial when you require exact, unscaled printing, ensuring the output strictly adheres to the specified page dimensions regardless of the printer’s default.

Syntax in xlwings:
In xlwings, you access this property through the Application object. The property is a Boolean value.

app = xw.apps.active # Or xw.App() for a new instance
app.api.MapPaperSize

• Get the current value: current_setting = app.api.MapPaperSize
• Set the value: app.api.MapPaperSize = True or app.api.MapPaperSize = False

Parameters:
The property accepts a Boolean:

• True: Enables automatic paper size mapping (this is the default in Excel). Excel will adjust scaling to fit the printer’s paper.
• False: Disables automatic mapping. Excel prints without scaling adjustment, using the exact paper size from the page setup.

Code Examples:

1. Check the current setting:

import xlwings as xw
app = xw.apps.active
if app.api.MapPaperSize:
    print("Automatic paper size mapping is ON.")
else:
    print("Automatic paper size mapping is OFF.")

2. Disable automatic paper size mapping for precise printing:

import xlwings as xw
wb = xw.Book(r'C:\Reports\Q1_Summary.xlsx')
app = wb.app
app.api.MapPaperSize = False # Turn off auto-scaling
wb.save()
print("MapPaperSize disabled to ensure exact print dimensions.")

3. Temporarily change setting, print, then restore:

import xlwings as xw
app = xw.apps.active
original_setting = app.api.MapPaperSize # Store original state
try:
    app.api.MapPaperSize = True # Enable mapping for flexible printing
    app.api.ActiveSheet.PrintOut() # Print the active sheet
finally:
    app.api.MapPaperSize = original_setting # Restore original setting
    print("Print job completed with temporary MapPaperSize adjustment.")