Archive

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()

How to use Application.MailSession in the xlwings API way

The MailSession property of the Application object in Excel’s object model provides access to the MAPI (Messaging Application Programming Interface) mail session for the current user. Through xlwings, this property can be utilized to interact with the email system integrated with Excel, enabling automation of email-related tasks such as sending workbooks or reports directly from an Excel session. This is particularly useful in scenarios where automated email dispatch is required based on data processed in Excel.

Functionality:
The MailSession property returns a MAPI session handle (as a Long integer) if a mail session is active. This handle can be used with Windows API calls or other libraries to perform email operations. However, note that xlwings does not have direct, high-level methods for email; instead, it exposes this property to allow low-level access, which can be combined with Python’s ctypes or pywin32 libraries for extended functionality. It is primarily read-only and indicates whether an email session is logged in.

Syntax in xlwings:
In xlwings, you access the MailSession property via the Application object. The syntax follows the standard xlwings pattern for properties. Since it’s a property, you retrieve its value without parentheses.

import xlwings as xw

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

# Access the MailSession property
mail_session_handle = app.api.MailSession

• Parameters: The MailSession property does not take any parameters.
• Return Value: It returns a Long integer representing the MAPI session handle. If no mail session is active, it may return 0 or an error. In practice, you should check for a non-zero value to confirm an active session.

Example Usage:
Below is a practical example demonstrating how to use MailSession in xlwings to check for an active email session and then perform a simple action, such as sending the active workbook via email using Excel’s built-in SendMail method (which relies on an active mail session). This example assumes you have an email client configured and logged in.

import xlwings as xw

# Start or connect to Excel
app = xw.apps.active

# Check the MailSession property
session_handle = app.api.MailSession
print(f"MAPI Session Handle: {session_handle}")

if session_handle != 0:
    # If a mail session is active, you can proceed with email-related tasks
    # For instance, send the active workbook via email
workbook = app.books.active
    # Use the SendMail method, which requires recipient(s) and optionally subject
    # Note: SendMail is a method of the Workbook object in Excel's object model
    # Here, we specify a recipient email address and a subject
    recipient = "example@domain.com"
    subject = "Report from Excel Automation"

    # Call the SendMail method via xlwings api
    # Parameters: Recipients (as string or array), Subject (optional)
    workbook.api.SendMail(Recipients=recipient, Subject=subject)
    print("Email sent successfully.")
else:
    print("No active mail session found. Please log in to your email client.")

How to use Application.LibraryPath in the xlwings API way

The LibraryPath property of the Application object in Excel is a read-only string that returns the complete path to the folder where the Microsoft Excel library (or add-ins) is installed on the user’s system. This path is typically where Excel stores its built-in add-in files (with .xlam, .xll extensions, etc.) and is part of the application’s installation directory structure. In xlwings, this property can be accessed via the api property, which provides direct access to the underlying Excel object model. It is useful for developers who need to programmatically locate Excel’s library directory, for instance, when loading specific add-ins, referencing template files stored with Excel, or ensuring file paths are correctly resolved in cross-platform scenarios.

Syntax in xlwings:
The property is accessed through the Application object. In xlwings, you typically start by instantiating an App or using the active app. The syntax is:

app.api.LibraryPath

• app: This is an xlwings App object representing the Excel application instance.
• api: This property exposes the native Excel object model (via COM or AppleScript).
• LibraryPath: The property name, which requires no parameters.

The return value is a string containing the full directory path (e.g., C:\Program Files\Microsoft Office\root\Office16\LIBRARY on Windows). Note that the exact path may vary based on the Office version, installation type, or operating system.

Example Usage:
Here are practical xlwings API code examples demonstrating how to retrieve and use the LibraryPath property:

1. Basic Retrieval:
   This example gets the library path from the active Excel application and prints it.

import xlwings as xw
# Connect to the active Excel instance
app = xw.apps.active
# Access the LibraryPath property
lib_path = app.api.LibraryPath
print(f"Excel Library Path: {lib_path}")

2. Using with New Instance:
   If you launch a new Excel application via xlwings, you can obtain its library path similarly.

import xlwings as xw
# Start a new Excel application
app = xw.App(visible=True)
# Get the library path
lib_path = app.api.LibraryPath
print(f"Library folder: {lib_path}")
# Optionally, you can list files in the library directory
import os
if os.path.exists(lib_path):
    files = os.listdir(lib_path)
    print(f"Files in library: {files[:5]}") # Show first 5 files
app.quit()

3. Practical Application – Loading an Add-in:
   You can use the LibraryPath to construct full paths to add-ins. This example checks for a specific add-in and loads it if available.

import xlwings as xw
import os
app = xw.apps.active
lib_path = app.api.LibraryPath
# Define a target add-in name (e.g., Analysis ToolPak)
addin_name = "ANALYS32.XLL"
addin_path = os.path.join(lib_path, addin_name)
# Check if the add-in exists and load it
if os.path.exists(addin_path):
    app.api.AddIns(addin_name).Installed = True
    print(f"Loaded add-in from: {addin_path}")
else:
    print(f"Add-in not found at {addin_path}")

How to use Application.Left in the xlwings API way

The Application.Left property in the xlwings API is a read-write attribute that allows you to get or set the distance, in points, from the left edge of the screen to the left edge of the main Excel application window. This property is part of the Excel object model and is accessible through xlwings, enabling you to programmatically control the positioning of the Excel window on the user’s display. This can be particularly useful for automating the layout of multiple applications or ensuring Excel opens in a specific location for consistency across sessions.

Functionality:

• Get: Retrieve the current left position of the Excel application window relative to the screen.
• Set: Adjust the left position of the Excel application window to a new coordinate.

Syntax:
In xlwings, you access this property via the app object, which represents the Excel application instance. The syntax is straightforward:

# To get the current left position
left_position = app.api.Left

# To set a new left position
app.api.Left = new_value

• Parameters:
• new_value: A numeric value (float or integer) representing the new left position in points. One point is 1/72 of an inch. The value is relative to the screen’s left edge; setting it to 0 aligns the window’s left edge with the screen’s left edge. Negative values can move the window partially off-screen, while positive values shift it to the right.

Example Usage:
Here are practical code instances demonstrating how to use the Application.Left property with xlwings:

1. Getting the Current Left Position:
   This example retrieves the current left position of the Excel window and prints it.

import xlwings as xw
# Connect to the active Excel instance
app = xw.apps.active
# Get the left position
current_left = app.api.Left
print(f"The Excel window is {current_left} points from the left edge of the screen.")

2. Setting the Left Position to a Specific Value:
   This example moves the Excel window to a new left position, such as 100 points from the left edge.

import xlwings as xw
# Connect to the active Excel instance
app = xw.apps.active
# Set the left position to 100 points
app.api.Left = 100
print("Excel window has been moved to 100 points from the left edge.")

3. Centering the Excel Window Horizontally:
   This example calculates the screen width (using the Width property of the application window) and sets the left position to center the window horizontally. Note that this requires knowing the screen’s width or using additional properties; here, we assume a screen width of 1440 points for demonstration.

import xlwings as xw
app = xw.apps.active
screen_width = 1440 # Example screen width in points
window_width = app.api.Width # Get the current width of the Excel window
# Calculate centered left position
centered_left = (screen_width - window_width) / 2
app.api.Left = centered_left
print(f"Excel window centered at {centered_left} points from the left.")

4. Adjusting Position Based on User Input or Conditions:
   This example shows how to dynamically adjust the left position, such as moving the window further right if it’s currently too close to the left edge.

import xlwings as xw
app = xw.apps.active
if app.api.Left < 50:
    app.api.Left = 200 # Move to 200 points if too far left
    print("Window moved to a more rightward position.")
else:
    print("Window position is acceptable.")

How to use Application.LargeOperationCellThousandCount in the xlwings API way

The LargeOperationCellThousandCount property of the Excel Application object is a relatively specialized setting that controls performance and memory usage during large-scale operations in Excel. Specifically, it determines the threshold (in thousands of cells) at which Excel switches to a more memory-efficient, but potentially slower, calculation mode for certain operations like sorting, filtering, or applying formatting to large ranges. When the number of cells involved in an operation exceeds this threshold, Excel optimizes for memory conservation, which can prevent out-of-memory errors but may impact speed. This property is particularly relevant for developers and advanced users who work with very large datasets and need to fine-tune Excel’s performance behavior programmatically.

In the xlwings API, which provides a powerful bridge between Python and Excel, you access this property through the Application object. The syntax for getting or setting the LargeOperationCellThousandCount property is straightforward, as it is exposed as a property of the xlwings App object. There is no specific method with parameters; instead, you directly read or assign an integer value to it.

Syntax in xlwings:

# To get the current threshold value (in thousands of cells)
threshold = app.api.LargeOperationCellThousandCount

# To set a new threshold value (in thousands of cells)
app.api.LargeOperationCellThousandCount = new_value

Here, app refers to an instance of the xlwings App class, which represents the Excel application. The .api attribute provides direct access to the underlying Excel object model (via pywin32 on Windows or appscript on macOS), allowing you to use properties like LargeOperationCellThousandCount. The new_value is an integer representing the threshold in thousands of cells. For example, a value of 1000 sets the threshold to 1,000,000 cells (since 1000 * 1000 = 1,000,000). The default value in Excel is typically 300000 (for 300 million cells), but this can vary based on the Excel version and system configuration. Setting it to 0 disables the large operation optimization, which might be useful for maximizing speed when sufficient memory is available.

Code Examples:
Below are practical xlwings API code snippets demonstrating how to use the LargeOperationCellThousandCount property in Python. These examples assume you have an Excel application running and an xlwings App instance connected to it.

Example 1: Retrieving the Current Threshold

import xlwings as xw

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

# Get the current LargeOperationCellThousandCount value
current_threshold = app.api.LargeOperationCellThousandCount
print(f"Current large operation cell threshold: {current_threshold} thousand cells")
# This might output something like: Current large operation cell threshold: 300000 thousand cells

Example 2: Modifying the Threshold for a Specific Workbook

import xlwings as xw

# Start a new Excel instance or connect to an existing one
app = xw.App(visible=True)

# Set the threshold to 500,000 thousand cells (i.e., 500 million cells)
app.api.LargeOperationCellThousandCount = 500000
print("Threshold updated to 500,000 thousand cells.")

# Open a workbook and perform a large operation (e.g., sorting a big range)
wb = app.books.open('large_dataset.xlsx')
sheet = wb.sheets[0]
# Assuming a large range is sorted, Excel will use the new threshold for optimization
sheet.range('A1:D1000000').api.Sort(Key1=sheet.range('A1'), Order1=1)

# Reset to default (e.g., 300000) if needed
app.api.LargeOperationCellThousandCount = 300000
wb.save()
wb.close()
app.quit()

Example 3: Disabling the Optimization for Maximum Speed

import xlwings as xw

with xw.App(visible=False) as app:
# Disable the large operation optimization by setting threshold to 0
app.api.LargeOperationCellThousandCount = 0
wb = app.books.add()
sheet = wb.sheets[0]
# This may speed up operations on large ranges if memory is plentiful
sheet.range('A1').value = [[i] for i in range(1000000)] # Writing 1 million cells
print("Large operation performed with optimization disabled.")
# Remember to re-enable if needed for other workbooks
app.api.LargeOperationCellThousandCount = 300000

How to use Application.LanguageSettings in the xlwings API way

The LanguageSettings member of the Application object in Excel provides access to regional and language settings, which is particularly useful for applications that need to adapt to different locales or determine the language version of Excel in use. This member returns a LanguageSettings object, which can be used to retrieve information such as the language identifiers (LCIDs) for the user interface, help, and installed language packs. In xlwings, this functionality is accessible through the api property, allowing Python scripts to interact with these settings programmatically.

The syntax in xlwings for accessing the LanguageSettings member is straightforward. After establishing a connection to Excel via xlwings.App, you can use the api property to reference the Excel Application object and then access LanguageSettings. For example, app.api.LanguageSettings returns the LanguageSettings object. Key properties include LanguageID, which takes an MsoAppLanguageID constant to specify the language type, such as msoLanguageIDUI for the user interface or msoLanguageIDHelp for help content. These constants are part of the Microsoft Office object model and can be referenced using their numeric values in xlwings if not directly available. For instance, msoLanguageIDUI corresponds to the value 2, and msoLanguageIDHelp corresponds to 3. To retrieve the LCID, you call properties like LanguageID with the appropriate constant. This allows developers to check the current language settings and adjust their code behavior accordingly, such as localizing messages or formatting data based on the user’s locale.

A practical code example in xlwings demonstrates how to use the LanguageSettings member. Start by importing xlwings and creating an instance of the Excel application. Then, access the LanguageSettings object to get language identifiers. For instance, to obtain the LCID for the user interface language, you can use the LanguageID property with the constant for the UI. In xlwings, since constants might not be directly exposed, you can use their known integer values. Here’s a sample script:

import xlwings as xw

# Connect to the active Excel instance or start a new one
app = xw.App(visible=False) # Set to True if you want to see Excel
try:
# Access the LanguageSettings object
lang_settings = app.api.LanguageSettings

# Define constants for language IDs (using example values)
msoLanguageIDUI = 2 # Constant for user interface language
msoLanguageIDHelp = 3 # Constant for help language

# Retrieve LCIDs for different language types
ui_lcid = lang_settings.LanguageID(msoLanguageIDUI)
help_lcid = lang_settings.LanguageID(msoLanguageIDHelp)

print(f"User Interface Language LCID: {ui_lcid}")
print(f"Help Language LCID: {help_lcid}")

# Example: Check if the UI language is English (LCID 1033 for en-US)
if ui_lcid == 1033:
    print("Excel is running with English UI.")
else:
    print(f"Excel UI is in another language with LCID: {ui_lcid}")
finally:
    # Clean up by closing the app
    app.quit()

How to use Application.Iteration in the xlwings API way

In Excel, the Application.Iteration property is a global setting that controls whether iterative calculations are enabled. This is particularly useful when dealing with circular references in formulas, where a formula depends on its own result, either directly or indirectly. By enabling iteration, Excel can repeatedly recalculate the worksheet until a specific numeric condition is met, such as reaching a maximum number of iterations or achieving a desired level of change between recalculations. This functionality is essential for solving problems that require convergence, like financial modeling with interest calculations or engineering simulations.

The xlwings API provides a straightforward way to access and modify this property through the Application object. The syntax for getting or setting the Iteration property is as follows:

import xlwings as xw

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

# Get the current iteration setting
iteration_enabled = app.iteration
print(f"Iteration is enabled: {iteration_enabled}")

# Set the iteration setting (True to enable, False to disable)
app.iteration = True

In this syntax, app refers to the xlwings App object, which corresponds to the Excel Application object. The iteration property is a boolean value, where True enables iterative calculations and False disables them. Note that this property is part of the application-level settings, meaning it affects all open workbooks in that Excel instance. When setting iteration to True, it is often paired with other related properties like MaxIterations (maximum number of calculation cycles) and MaxChange (maximum change between iterations to stop calculation), which can also be accessed via xlwings as app.max_iterations and app.max_change, respectively. These properties help fine-tune the iterative process to ensure accurate results without excessive computation.

For example, consider a scenario where you have a worksheet with a circular reference that calculates compound interest iteratively. To enable iteration and set appropriate limits, you might use the following xlwings code:

import xlwings as xw

# Start or connect to Excel
app = xw.apps.active

# Enable iterative calculations
app.iteration = True

# Set maximum iterations to 1000
app.max_iterations = 1000

# Set maximum change threshold to 0.001
app.max_change = 0.001

# Verify the settings
print(f"Iteration enabled: {app.iteration}")
print(f"Max iterations: {app.max_iterations}")
print(f"Max change: {app.max_change}")

# Open a workbook and perform calculations (assuming it has circular references)
wb = app.books.open('financial_model.xlsx')
wb.sheets[0].range('A1').calculate() # Trigger calculation if needed

How to use Application.IsSandboxed in the xlwings API way

The IsSandboxed property of the Application object in Excel’s object model is a read-only Boolean property that indicates whether the current instance of Excel is running in a sandboxed environment. This is particularly relevant for security contexts, such as when Excel is embedded within a web browser or running under certain restricted permissions, like in Office Online or protected view scenarios. In a sandboxed environment, certain operations may be limited or disabled to enhance security, such as accessing external data sources or executing macros. Understanding this property can help developers write more robust and secure code by conditionally enabling or disabling features based on the runtime environment.

In xlwings, you can access this property through the Application object, which is part of the xlwings.App class when interacting with Excel instances. The syntax for accessing the IsSandboxed property in xlwings is straightforward, as it mirrors the Excel object model. Here’s how you can call it:

• Syntax: app.api.IsSandboxed
• app: This is an instance of xlwings.App, representing the Excel application.
• api: This attribute provides direct access to the underlying Excel object model, allowing you to call properties and methods that are not directly wrapped by xlwings.
• IsSandboxed: The property name, which returns a Boolean value (True if Excel is sandboxed, False otherwise).

No parameters are required for this property, as it is a simple property getter. The return value is a Python Boolean, which you can use in conditional statements. It’s important to note that this property may not be available in all versions of Excel; typically, it is supported in newer versions (e.g., Excel 2013 and later) and specific environments. If you try to access it in an unsupported version, you might encounter an AttributeError. To handle this gracefully, you can use error handling or check the Excel version beforehand.

Here’s a code example that demonstrates how to use the IsSandboxed property in xlwings to check the sandbox status of an Excel instance:

import xlwings as xw

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

try:
    # Access the IsSandboxed property via the api attribute
is_sandboxed = app.api.IsSandboxed
    print(f"Excel is running in a sandboxed environment: {is_sandboxed}")

    # Use the property in a conditional statement
    if is_sandboxed:
        print("Restricted mode: Some features may be disabled.")
    else:
        print("Full mode: All features are available.")
except AttributeError:
    print("The IsSandboxed property is not supported in this version of Excel.")
finally:
    # Clean up: close the app if it was created in this script
    if not xw.apps.active:
        app.quit()

How to use Application.International in the xlwings API way

The Application.International property in Excel is a read-only property that returns information about the current country/region and international settings in Excel. This is particularly useful for creating locale-aware macros or scripts that need to adapt to different regional formats, such as date formats, currency symbols, list separators, and more. In xlwings, this property can be accessed via the api object, which provides a direct gateway to Excel’s underlying object model. Understanding how to use International allows developers to write more robust and portable code that functions correctly across various international versions of Excel.

The syntax for accessing the International property in xlwings is straightforward. Since International is a property of the Application object, you first need to get a reference to the Excel application through xlwings, typically via app = xw.App() or by using the active app. Then, you can access the property using app.api.International. The key aspect is that International accepts an index argument (a constant or numeric value) that specifies which setting to return. This index corresponds to Excel’s XlApplicationInternational constants, which are enumerations defining various international parameters. For example, xlCountryCode (value 1) returns the country/region code, while xlCurrencyDigits (value 25) returns the number of decimal digits used in currency formats. The available indices are numerous, and developers should refer to the official Excel VBA documentation for a comprehensive list, as xlwings does not redefine these constants but relies on Excel’s built-in enumerations.

Here is a table of some common XlApplicationInternational indices and their meanings, which can be used with International in xlwings:

Index Constant (VBA Name)	Value	Description
xlCountryCode	1	Returns the country/region code for the current system.
xlCountrySetting	2	Returns the country/region setting from the Windows Control Panel.
xlCurrencyDigits	25	Returns the number of decimal digits used in currency formats.
xlCurrencyCode	27	Returns the currency symbol for the current locale.
xlDateSeparator	17	Returns the date separator character (e.g., “/” or “-“).
xlTimeSeparator	18	Returns the time separator character (e.g., “:”).
xlListSeparator	5	Returns the list separator character (e.g., “,” or “;”).
xlDayCode	21	Returns the day symbol used in date formats.
xlMonthCode	20	Returns the month symbol used in date formats.
xlYearCode	19	Returns the year symbol used in date formats.

In xlwings, you can use these indices by their numeric values directly, as the constants are not natively provided in the xlwings module. However, for clarity, you can define them in your code based on the VBA enumerations. The property returns a value that can be a string, number, or character, depending on the index. It is important to note that the behavior might vary slightly across different Excel versions, so testing in the target environment is recommended.

Below are practical examples of using the Application.International property with xlwings in Python. These examples demonstrate how to retrieve various international settings and use them in data processing or formatting tasks.

Example 1: Retrieving basic locale information.

import xlwings as xw

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

# Get the country/region code (index 1)
country_code = app.api.International[1]
print(f"Country/Region Code: {country_code}")

# Get the list separator (index 5)
list_separator = app.api.International[5]
print(f"List Separator: '{list_separator}'")

# This can be used to dynamically format CSV files or split text based on locale.

Example 2: Working with date and currency formats.

import xlwings as xw

app = xw.apps.active

# Get date and time separators
date_sep = app.api.International[17] # xlDateSeparator
time_sep = app.api.International[18] # xlTimeSeparator
print(f"Date Separator: {date_sep}, Time Separator: {time_sep}")

# Get currency digits and symbol
currency_digits = app.api.International[25] # xlCurrencyDigits
currency_symbol = app.api.International[27] # xlCurrencyCode
print(f"Currency Digits: {currency_digits}, Symbol: {currency_symbol}")

# Use these to format numbers in a worksheet dynamically
sheet = app.books.active.sheets[0]
cell = sheet.range("A1")
cell.value = 1234.56
cell.number_format = f"#{currency_symbol}0.{'0' * currency_digits}" # Custom format based on locale

Example 3: Adapting data parsing based on international settings.

import xlwings as xw

app = xw.apps.active

# Get the day, month, and year codes for date formats
day_code = app.api.International[21] # xlDayCode
month_code = app.api.International[20] # xlMonthCode
year_code = app.api.International[19] # xlYearCode
print(f"Date Format Codes: Day={day_code}, Month={month_code}, Year={year_code}")

# This information can help in parsing date strings from different locales,
# especially when dealing with text data imported into Excel.