Blog

How to use Application.MoveAfterReturnDirection in the xlwings API way

The Application.MoveAfterReturnDirection property in Excel’s object model is a useful setting that controls the direction the active cell moves after the user presses the Enter key. When data entry is performed, this property determines whether the selection moves down, up, left, or right, which can significantly improve workflow efficiency in repetitive data entry tasks. In xlwings, this property can be accessed and modified through the api property, which provides direct access to the underlying Excel VBA object model.

Functionality:
This property dictates the post-entry navigation behavior in Excel. It is particularly beneficial for users who need to enter data in a specific pattern, such as filling out forms or tables row by row or column by column. By setting the direction, users can avoid manually repositioning the cell pointer after each entry, reducing errors and saving time.

Syntax in xlwings:
The property is accessed via the Application object. In xlwings, you first obtain the Excel application instance, typically through xlwings.App or from an existing workbook. The property can be both read and written.

# To get the current direction
direction = app.api.MoveAfterReturnDirection

# To set a new direction
app.api.MoveAfterReturnDirection = new_direction

The new_direction parameter is an integer that corresponds to a specific movement direction. The possible values are defined by the Excel constants xlDown, xlUp, xlToLeft, and xlToRight. In xlwings, you can use the equivalent integer values or import the constants from xlwings.constants. The standard mappings are:

Constant (in VBA)	xlwings Constant	Integer Value	Movement Direction
xlDown	xlDown	-4121	Down
xlUp	xlUp	-4162	Up
xlToLeft	xlToLeft	-4159	Left
xlToRight	xlToRight	-4161	Right

Code Examples:
Here are practical examples demonstrating how to use the MoveAfterReturnDirection property with xlwings.

1. Reading the Current Direction:

import xlwings as xw

# Connect to the active Excel instance
app = xw.apps.active

# Get the current move direction
current_direction = app.api.MoveAfterReturnDirection
print(f"Current MoveAfterReturnDirection: {current_direction}")

2. Setting the Direction to Move Right:

import xlwings as xw
from xlwings.constants import xlToRight

app = xw.apps.active
# Set the direction to move right after Enter
app.api.MoveAfterReturnDirection = xlToRight # or use -4161
print("Direction set to move right after Enter.")

3. Setting the Direction to Move Up:

import xlwings as xw

app = xw.apps.active
# Using the integer value for xlUp
app.api.MoveAfterReturnDirection = -4162
print("Direction set to move up after Enter.")

4. Temporarily Changing Direction for Data Entry:

import xlwings as xw
from xlwings.constants import xlDown, xlToRight

app = xw.apps.active
# Save the original direction
original_direction = app.api.MoveAfterReturnDirection

# Change to move down for vertical data entry
app.api.MoveAfterReturnDirection = xlDown
print("Enter data vertically. Press Enter to move down.")

# After data entry, revert to the original setting
app.api.MoveAfterReturnDirection = original_direction
print("Reverted to the original direction.")

How to use Application.MoveAfterReturn in the xlwings API way

The MoveAfterReturn member of the Application object in Excel VBA controls the direction the cell selection moves after pressing the Enter key in a worksheet. This feature is primarily used to enhance data entry efficiency by automatically navigating to the next cell in a specified direction (e.g., down, up, left, or right) instead of remaining in the current cell. In xlwings, this functionality can be accessed and manipulated through the api property, which provides direct access to the underlying Excel object model.

Functionality:
The MoveAfterReturn property determines whether Excel moves the selection after pressing Enter. When enabled, it works in conjunction with the MoveAfterReturnDirection property to define the direction of the move. This is particularly useful in data entry tasks where you need to quickly input data across rows or columns without manually selecting each cell.

Syntax in xlwings:
In xlwings, you interact with this property via the Excel Application object retrieved from a workbook or app instance. The basic syntax is:

app = xw.apps.active # or xw.App() for a new instance
app.api.MoveAfterReturn = True # or False to disable

To set the direction, use:

app.api.MoveAfterReturnDirection = xlDirection # xlDirection is an integer value

The MoveAfterReturnDirection parameter accepts integer values corresponding to Excel constants. Common values include:

• xlDown (or 1): Move down (default).
• xlToRight (or 2): Move to the right.
• xlUp (or 3): Move up.
• xlToLeft (or 4): Move to the left.

Example Usage:
Here is a practical example that demonstrates how to configure MoveAfterReturn using xlwings to streamline data entry in an Excel workbook. This script enables the feature and sets the direction to move right after each Enter press, which is ideal for entering data across columns.

import xlwings as xw

# Connect to the active Excel instance or start a new one
app = xw.apps.active

# Enable MoveAfterReturn
app.api.MoveAfterReturn = True

# Set the direction to move right after pressing Enter
app.api.MoveAfterReturnDirection = 2 # Equivalent to xlToRight

# Optional: Print the current settings to verify
print(f"MoveAfterReturn enabled: {app.api.MoveAfterReturn}")
print(f"MoveAfterReturnDirection: {app.api.MoveAfterReturnDirection}")

# Open or create a workbook for data entry
wb = app.books.active
ws = wb.sheets[0]

# Example: Input data into cells to see the effect
ws.range('A1').value = 'Enter data in A1 and press Enter to move to B1'

How to use Application.MouseAvailable in the xlwings API way

The Application.MouseAvailable property in Excel’s object model is a read-only property that returns a Boolean value indicating whether a mouse is available on the system. This can be useful in scenarios where your automation script needs to adapt its behavior based on the presence of a mouse, such as avoiding mouse-dependent operations on systems without one, or providing alternative user interface cues. In xlwings, you access this property through the Application object, which is typically represented by the app object when you connect to an Excel instance.

The syntax in xlwings for accessing the MouseAvailable property is straightforward, as it maps directly to the underlying Excel object model. You can retrieve its value using the following format:

app.mouse_available

Here, app is an instance of the xlwings App class, which represents the Excel application. The property does not take any parameters, and it returns True if a mouse is available, or False otherwise. This is a property, so you read it like an attribute; you cannot set or modify its value.

For example, consider a situation where you are developing a macro or an automated report that includes interactive elements like shapes or buttons that require mouse clicks for user interaction. Before executing such mouse-dependent steps, you might want to check for mouse availability to ensure the script runs smoothly or to log an appropriate message. Below is a practical xlwings code example:

import xlwings as xw

# Connect to the active Excel instance or start a new one
app = xw.apps.active

# Check if a mouse is available
if app.mouse_available:
    print("Mouse is available. Proceeding with mouse-dependent operations.")
    # For instance, you could activate a worksheet and select a range
    wb = app.books.active
    ws = wb.sheets[0]
    ws.range("A1").select() # This selection might rely on mouse interaction in some contexts
else:
    print("No mouse detected. Skipping mouse-dependent steps or using keyboard alternatives.")
    # Implement fallback logic, such as using keyboard shortcuts or focusing on data processing only

How to use Application.MergeInstances in the xlwings API way

The MergeInstances property of the Application object in Excel is a powerful feature for users who work with shared workbooks in a multi-user environment. When a workbook is shared, multiple users can edit it simultaneously, creating separate instances of the workbook that may contain different changes. The MergeInstances property allows you to programmatically merge these separate instances back into a single, consolidated workbook, ensuring that all user edits are combined. This is particularly useful for collaborative projects where data consistency and consolidation are critical. In xlwings, this property can be accessed and manipulated through the Application object, providing a way to automate the merging process in Python scripts, which can enhance workflow efficiency and reduce manual errors.

In xlwings, the syntax for accessing the MergeInstances property is straightforward. It is a property of the Application object, so you first need to get a reference to the Excel application. The property returns a collection of Workbook objects that represent the instances of a shared workbook that are currently open and available for merging. You can use this collection to iterate through instances or perform merge operations. Note that MergeInstances is read-only; you cannot directly set it to merge workbooks. Instead, you typically use it in conjunction with other methods or properties to manage shared workbooks. The key parameters or aspects to consider include ensuring the workbook is shared (via the Workbook.IsShared property) and that multiple instances are open. There are no direct method parameters for MergeInstances itself, as it is a property, but its usage often involves checking the count of instances or accessing specific workbooks in the collection.

For example, to check if there are multiple instances of a shared workbook open and ready to merge, you can use the following xlwings code. This example demonstrates how to access the MergeInstances property and print the number of instances:

import xlwings as xw

# Connect to the Excel application
app = xw.apps.active # or xw.App() for a new instance

# Check if the active workbook is shared
if app.books.active.is_shared:
# Access the MergeInstances property
merge_instances = app.api.MergeInstances
# Get the count of instances
instance_count = merge_instances.Count
print(f"Number of merge instances available: {instance_count}")

# Optionally, iterate through each instance
for i in range(instance_count):
    instance = merge_instances.Item(i + 1) # Excel collections are 1-based
    print(f"Instance {i + 1}: {instance.Name}")
else:
    print("The active workbook is not shared. MergeInstances is not applicable.")

In this code, app.api.MergeInstances is used to access the underlying Excel object model property, as xlwings provides a bridge to the COM API. The Count property gives the total number of instances, and Item retrieves a specific Workbook instance. Note that indexing in Excel collections starts at 1, so we use i + 1 in the loop. This example helps identify available instances but does not perform the actual merge; merging typically involves saving and consolidating changes through Excel’s built-in features or additional VBA methods, which can be invoked via api if needed. For instance, you might use app.api.ActiveWorkbook.MergeWorkbook after ensuring instances are ready, but this requires careful handling of shared workbook settings.

Another practical use case is to automate the merging process when multiple users have edited a shared workbook. Suppose you have a script that runs periodically to consolidate data. You can extend the previous example to prompt a merge if instances are detected. Here’s a simplified illustration:

import xlwings as xw

app = xw.apps.active
if app.books.active.is_shared:
    instances = app.api.MergeInstances
    if instances.Count > 1:
        print("Merging instances...")
        # In a real scenario, you might save and close instances first
        # Then use Excel's merge functionality, e.g., via:
        # app.api.ActiveWorkbook.MergeWorkbook("path_to_another_instance")
        # This part depends on specific Excel methods and may require error handling
        print("Merge initiated manually or via additional API calls.")
    else:
        print("Only one instance found; no merge needed.")
else:
    print("Workbook is not shared.")

How to use Application.MeasurementUnit in the xlwings API way

The MeasurementUnit property of the Application object in Excel is a relatively niche but useful feature when dealing with international or regional document settings. This property allows you to retrieve or set the default measurement unit used in the Excel application for various interface elements, such as ruler units, column widths, row heights, and dialog box measurements. The primary utility lies in ensuring consistency when macros or automated processes depend on specific unit systems, especially when sharing workbooks across different regional versions of Excel. For instance, a macro designed assuming inches for column widths might behave unexpectedly if the application is set to centimeters. By programmatically controlling the MeasurementUnit property, you can standardize the environment, enhancing the reliability of your xlwings automation scripts.

Syntax and Parameters

In xlwings, you access this property through the Application object. The property is both readable and writable, accepting integer values that correspond to specific measurement units.

• xlwings API Call Format:

# To get the current measurement unit
current_unit = xw.apps.active.api.MeasurementUnit

# To set the measurement unit
xw.apps.active.api.MeasurementUnit = new_unit_value

Note: The .api attribute provides direct access to the underlying Excel VBA object model.

• Parameter Values:
  The new_unit_value is an integer from the XlMeasurementUnit enumeration. The common values are:

Constant Name (VBA)	Value	Description
xlInches	0	Measurement is in inches.
xlCentimeters	1	Measurement is in centimeters.
xlMillimeters	2	Measurement is in millimeters.

You can use either the integer values directly or, for better code readability, define the constants in your Python script (e.g., xlInches = 0).

Code Examples

Here are practical examples demonstrating how to use the MeasurementUnit property with xlwings.

1. Retrieving the Current Measurement Unit:
   This script checks the current setting and prints a descriptive message.

import xlwings as xw

# Connect to the active Excel instance
app = xw.apps.active

# Get the current measurement unit
unit_constant = app.api.MeasurementUnit

# Interpret the value
unit_map = {0: "Inches", 1: "Centimeters", 2: "Millimeters"}
unit_name = unit_map.get(unit_constant, "Unknown Unit")

print(f"The current application measurement unit is: {unit_name} (Value: {unit_constant})")

2. Setting the Measurement Unit and Applying a Change:
   This example changes the global measurement unit to centimeters and then adjusts the width of the first column accordingly. This showcases how the property affects subsequent actions.

import xlwings as xw

# Define constants for clarity (these are not built into xlwings)
xlInches = 0
xlCentimeters = 1
xlMillimeters = 2

app = xw.apps.active
wb = app.books.active
ws = wb.sheets[0]

# Set the application's measurement unit to Centimeters
app.api.MeasurementUnit = xlCentimeters
print("Measurement unit set to Centimeters.")

# Now, set the width of column A to 5 centimeters.
# The .column_width property in xlwings uses the application's current MeasurementUnit.
ws.range('A:A').column_width = 5
print("Column A width set to 5 centimeters.")

# Optional: Switch back to Inches and read the column width
app.api.MeasurementUnit = xlInches
width_in_inches = ws.range('A:A').column_width
print(f"Column A width in inches is approximately: {width_in_inches:.2f}")

How to use Application.MaxIterations in the xlwings API way

The MaxIterations property of the Application object in Excel is a setting that controls the maximum number of iterations Excel will perform when calculating formulas that involve circular references, where a formula refers to its own cell either directly or indirectly. By default, Excel is set to perform a maximum of 100 iterations to resolve such circular calculations, unless the iterative calculation feature is turned off. Adjusting MaxIterations is particularly useful in financial modeling, engineering calculations, or any scenario where iterative solutions are necessary, such as solving equations using circular references with a convergence goal. Through xlwings, you can programmatically read or modify this property to tailor the calculation behavior of an Excel workbook to specific needs, ensuring that complex models converge to a satisfactory level of accuracy.

In xlwings, the MaxIterations property is accessed via the Application object. The syntax for using it is straightforward. To get the current maximum iterations setting, you simply reference the property. To set it, you assign a new integer value. The property is an integer that must be greater than or equal to 1. There are no additional parameters. The basic syntax in xlwings is:

import xlwings as xw

# Connect to the active Excel instance or create one
app = xw.apps.active # or xw.App() for a new instance

# Get the current MaxIterations value
current_max_iter = app.api.MaxIterations

# Set a new MaxIterations value, e.g., to 500
app.api.MaxIterations = 500

Note that app.api provides direct access to the underlying Excel COM object model, allowing you to use properties like MaxIterations as defined in Excel’s VBA documentation. This property works in conjunction with the Iteration property (a boolean that enables or disables iterative calculation) and the MaxChange property (which sets the maximum change between iterations to consider the calculation converged). Typically, you would enable iterative calculation by setting app.api.Iteration = True before adjusting MaxIterations.

Here are practical examples of using MaxIterations with xlwings:

Example 1: Reading and Displaying the Current Setting

import xlwings as xw

app = xw.apps.active
max_iter = app.api.MaxIterations
print(f"The current maximum iterations are set to: {max_iter}")

Example 2: Enabling Iterative Calculation and Increasing MaxIterations
This example turns on iterative calculation if it’s off, sets a higher iteration limit for a more precise convergence, and then triggers a workbook recalculation to apply the settings.

import xlwings as xw

app = xw.apps.active
# Enable iterative calculation
app.api.Iteration = True
# Increase MaxIterations to 1000 for finer convergence
app.api.MaxIterations = 1000
# Optionally, set MaxChange for convergence threshold (default is 0.001)
app.api.MaxChange = 0.0001

# Force a recalculation of all open workbooks to apply changes
app.api.CalculateFull()
print("Iterative calculation enabled with MaxIterations = 1000 and MaxChange = 0.0001.")

Example 3: Resetting to Default Values
To revert to Excel’s default iterative settings, you can disable iterative calculation or set standard values.

import xlwings as xw

app = xw.apps.active
# Disable iterative calculation (MaxIterations becomes irrelevant when off)
app.api.Iteration = False
# Alternatively, reset to default values while keeping iterative calculation on
app.api.MaxIterations = 100
app.api.MaxChange = 0.001
print("Iterative calculation settings reset to defaults.")

Example 4: Integrating with a Specific Workbook’s Calculation
In this scenario, you might adjust MaxIterations only when working with a particular workbook that requires extensive iteration, then restore the original settings afterward to avoid affecting other workbooks.

import xlwings as xw

app = xw.apps.active
# Save original settings
original_iteration = app.api.Iteration
original_max_iter = app.api.MaxIterations

# Open a workbook that needs high iteration
wb = app.books.open('complex_model.xlsx')
app.api.Iteration = True
app.api.MaxIterations = 2000
# Recalculate the workbook
wb.api.Calculate()

# After work, restore original settings
app.api.Iteration = original_iteration
app.api.MaxIterations = original_max_iter
wb.close()
print("Workbook calculated with increased MaxIterations, original settings restored.")

How to use Application.MaxChange in the xlwings API way

The Application.MaxChange property in Excel VBA is used to set or return the maximum amount by which cell values can change during an iterative calculation, such as when using circular references with the iteration feature enabled. In xlwings, this property can be accessed through the Application object, allowing Python scripts to control Excel’s iterative calculation settings programmatically. This is particularly useful for financial modeling, engineering simulations, or any scenario where iterative solutions are required, as it helps define convergence criteria to prevent infinite loops.

Functionality:
MaxChange determines the threshold for changes in cell values between iterations. When Excel performs iterative calculations, it continues recalculating until either the maximum iterations limit is reached or the change in all cell values is less than both MaxChange and MaxIterations settings. By adjusting MaxChange, you can fine-tune the precision of iterative results, balancing accuracy with calculation speed.

Syntax in xlwings:
In xlwings, the MaxChange property is accessed via the Application object. The syntax is straightforward:

app = xw.App() # Connect to an Excel instance
max_change_value = app.api.MaxChange # Get the current MaxChange value
app.api.MaxChange = new_value # Set a new MaxChange value

Here, app is an xlwings App object representing the Excel application. The .api attribute provides access to the underlying Excel object model, allowing direct interaction with properties like MaxChange. The property accepts and returns a float value, representing the maximum change tolerance. For example, setting it to 0.001 means iterations will stop when cell value changes are less than 0.001.

Parameters and Values:

• Value Type: Float (e.g., 0.001, 0.0001). It must be a positive number; setting it to 0 or negative may cause errors or unexpected behavior.
• Default Value: In Excel, the default is 0.001, but this can vary based on user settings or workbook configurations.
• Interaction with Other Settings: MaxChange works in conjunction with MaxIterations (accessible via app.api.MaxIterations). Iterations stop when either the maximum number of iterations is reached or the change in values is below MaxChange.

Code Examples:
Below are practical xlwings API examples demonstrating how to use MaxChange in Python scripts:

1. Retrieving the Current MaxChange Value:
   This example connects to an active Excel instance and prints the current MaxChange setting.

import xlwings as xw
# Connect to the active Excel application
app = xw.apps.active
current_max_change = app.api.MaxChange
print(f"Current MaxChange value: {current_max_change}")

2. Setting MaxChange for Iterative Calculations:
   Here, we set MaxChange to a more precise value and enable iterative calculations by adjusting related properties.

import xlwings as xw
app = xw.App() # Start a new Excel instance
# Configure iterative calculation settings
app.api.Iteration = True # Enable iteration
app.api.MaxIterations = 100 # Set maximum iterations
app.api.MaxChange = 0.0001 # Set tighter change tolerance
print("MaxChange updated to 0.0001 for higher precision.")
# Open a workbook and perform calculations (e.g., with circular references)
wb = app.books.add()
ws = wb.sheets[0]
ws.range("A1").formula = "=B1+1" # Example circular reference setup
ws.range("B1").formula = "=A1*0.5"
wb.save("iterative_example.xlsx")
app.quit()

3. Resetting MaxChange to Default:
   This script resets MaxChange to Excel’s typical default value.

import xlwings as xw
app = xw.apps.active
app.api.MaxChange = 0.001
print("MaxChange reset to default 0.001.")

How to use Application.MathCoprocessorAvailable in the xlwings API way

The Application.MathCoprocessorAvailable property in Excel’s object model is a read-only property that returns a Boolean value indicating whether a math coprocessor is available on the user’s computer. Historically, math coprocessors (or floating-point units) were separate processors that accelerated mathematical calculations. In modern systems, this functionality is integrated directly into the central processing unit (CPU). Therefore, this property primarily serves for backward compatibility and system diagnostics. In practical terms, for most contemporary development, this property will return True, as virtually all modern CPUs include integrated floating-point capabilities. However, it can still be useful in rare scenarios for checking the computational environment, perhaps for legacy application support or detailed system reporting.

In the xlwings library, which provides a Pythonic interface to automate Excel, you access this property through the Application object. The xlwings API closely mirrors the Excel Object Model, making the transition from VBA documentation straightforward.

Syntax in xlwings:

app.math_coprocessor_available

or, using the more explicit attribute name that matches the VBA naming convention:

app.MathCoprocessorAvailable

Both properties are accessible and return a Boolean (bool) value. No parameters are required or accepted for this property.

Important Note on Naming: xlwings typically converts VBA’s PascalCase property names to snake_case in Python (e.g., MathCoprocessorAvailable becomes math_coprocessor_available). However, for compatibility and clarity, xlwings often provides both naming styles. It is generally recommended to use the snake_case version for consistency with Python conventions.

Code Examples:

1. Basic Check and Print:
   This example simply checks for the coprocessor and prints its status to the console.

import xlwings as xw

# Connect to the active Excel instance or start a new one
app = xw.apps.active

# Access the property
coprocessor_status = app.math_coprocessor_available

# Print the result
print(f"Math Coprocessor Available: {coprocessor_status}")
# Output will typically be: Math Coprocessor Available: True

2. Conditional Logic Based on Availability:
   This example demonstrates how you might use the property to branch logic, perhaps to choose between calculation methods (though this is largely historical).

import xlwings as xw

app = xw.apps.active

if app.math_coprocessor_available:
    print("System has a math coprocessor. Using optimized calculation routines.")
    # Placeholder for code that uses hardware-accelerated math
    # For example, triggering a complex recalculation
    app.calculation = 'automatic'
else:
    print("No math coprocessor detected. Using standard calculation methods.")
    # Placeholder for code that uses simpler, less intensive calculations
    app.calculation = 'manual'
    # Potentially implement iterative calculation with lower precision

3. System Information Report:
   This example collects the property as part of a broader system diagnostic report written back into an Excel workbook.

import xlwings as xw
from datetime import datetime

# Start a new Excel instance and create a workbook
app = xw.App(visible=True)
wb = app.books.add()
sheet = wb.sheets['Sheet1']

# Gather system info
info = {
"Report Generated": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
"Excel Version": app.version,
"Math Coprocessor Available": app.math_coprocessor_available,
"Operating System": app.operating_system
}

# Write the information to the worksheet
sheet.range('A1').value = [[key, str(value)] for key, value in info.items()]

print("System information report created.")

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.")

How to use Application.MailSystem in the xlwings API way

The Application.MailSystem property in Excel’s object model provides information about the email system installed on the user’s computer. This property is read-only and is useful for determining which email application (e.g., Microsoft Outlook, MAPI) is available, allowing for conditional logic in macros or scripts that involve sending emails from Excel. In xlwings, this property can be accessed via the api property of the App or Book objects, which exposes the underlying Excel VBA object model.

Functionality:
The primary purpose of MailSystem is to return an integer value indicating the type of email system installed. This can help in automating email-related tasks, such as sending workbooks or ranges via email, by first checking the available email client. It ensures compatibility and prevents errors in environments where a specific email system might not be present.

Syntax in xlwings:
The property is accessed through the Application object. In xlwings, you typically start with an instance of the Excel application. The syntax is:

mail_system_type = xw.apps[0].api.MailSystem

Alternatively, if you have a specific workbook or app context:

import xlwings as xw
app = xw.App(visible=False) # or use xw.apps.active
mail_info = app.api.MailSystem

This property returns an integer value. The possible values and their meanings are as follows:

Value	Description
0	No email system is installed.
1	Microsoft Outlook is installed.
2	A MAPI (Messaging Application Programming Interface) compliant email system is installed (e.g., some other email clients).

Example Usage:
Here is a practical example of using MailSystem in xlwings to check the email system and perform an action based on the result. This script opens Excel, retrieves the mail system type, and prints a corresponding message. It can be extended to conditionally send emails or trigger other workflows.

import xlwings as xw

# Start or connect to an Excel instance
app = xw.App(visible=False) # Set visible=True to see Excel
try:
    # Access the MailSystem property
    mail_type = app.api.MailSystem

    # Interpret the result
    if mail_type == 0:
        print("No email system is installed. Email features are unavailable.")
    elif mail_type == 1:
        print("Microsoft Outlook is available for email operations.")
    elif mail_type == 2:
        print("A MAPI-compliant email system is installed.")
    else:
        print(f"Unknown mail system type: {mail_type}")

# Example: Conditionally send an email (pseudo-code outline)
# if mail_type == 1:
# # Use Outlook integration (e.g., via win32com or other libraries)
# pass
# elif mail_type == 2:
# # Use MAPI-based methods
# pass

except Exception as e:
    print(f"An error occurred: {e}")
finally:
    # Clean up by closing the Excel instance
    app.quit()