Archive

How to use Application.ActiveWindow in the xlwings API way

The Application.ActiveWindow property in Excel’s object model is a crucial component for interacting with the currently active workbook window through xlwings. It returns a Window object that represents the topmost window in the application’s window stack. This property is read-only, meaning you cannot set a specific window as active directly via this property; instead, you activate a window using the Window.Activate method. The primary functionality of ActiveWindow is to allow developers to inspect and manipulate properties of the active window, such as its view settings, zoom level, scroll positions, and split panes, enabling dynamic control over the user’s interface during automation tasks.

In xlwings, the API call for accessing the ActiveWindow property is straightforward. The syntax follows the pattern of chaining properties from the main App object, which represents the Excel application instance. The typical usage is: app.api.ActiveWindow. Here, app is an instance of xlwings.App connected to a running Excel application. The .api attribute provides direct access to the underlying COM object model, allowing you to call native Excel VBA properties and methods. The ActiveWindow property does not take any parameters. Once accessed, it returns a Window object, from which you can further access its members, such as Window.View, Window.Zoom, or Window.ScrollRow.

For example, to retrieve and print the current zoom percentage of the active window, you can use the following xlwings code:

import xlwings as xw

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

# Access the ActiveWindow property
active_window = app.api.ActiveWindow

# Get the zoom level (property returns an integer)
zoom_level = active_window.Zoom
print(f"The active window zoom level is: {zoom_level}%")

Another common use case is to control the scroll position of the active window. You can set the first visible row and column to customize what data is in view. The following example demonstrates how to scroll to a specific cell location:

import xlwings as xw

app = xw.apps.active
active_window = app.api.ActiveWindow

# Scroll to make row 50 and column C (3) visible at the top-left corner
active_window.ScrollRow = 50
active_window.ScrollColumn = 3

Additionally, you can check and modify the window view, such as switching between normal view and page break preview. This is useful when preparing reports for printing. The View property accepts integer values corresponding to different view modes. Common values include: xlNormalView (1) for normal view, xlPageBreakPreview (2) for page break preview, and xlPageLayoutView (3) for page layout view. Here is an example:

import xlwings as xw
from xlwings.constants import xlPageBreakPreview

app = xlwings.apps.active
active_window = app.api.ActiveWindow

# Switch to page break preview mode
active_window.View = xlPageBreakPreview # or use integer 2

How to use Application.ActiveSheet in the xlwings API way

In the Excel object model, the Application object represents the entire Excel application, and its ActiveSheet property is crucial for interacting with the currently active worksheet in the active workbook. This is particularly useful in automation scripts where operations need to be performed on the sheet that the user is currently viewing or has selected. In xlwings, a powerful Python library for Excel automation, the ActiveSheet property can be accessed through the App object, which corresponds to the Excel Application. This property returns a Sheet object, enabling developers to read, write, and manipulate data, formats, and other elements directly on the active sheet without needing to reference it by name. This dynamic access simplifies code when dealing with user interactions or when the active sheet changes during runtime.

The syntax for accessing the ActiveSheet property in xlwings is straightforward. After establishing a connection to Excel (either by creating a new instance or connecting to an existing one), you can retrieve the active sheet using the App object. The general format is as follows:

import xlwings as xw

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

# Access the active sheet
active_sheet = app.active_sheet

Here, app represents the Application object in Excel, and active_sheet is a Sheet object in xlwings. This property does not take any parameters, as it simply returns the currently active worksheet. If no workbook is open or no sheet is active, it may raise an error, so it’s good practice to handle such scenarios with error checking. The returned Sheet object can then be used to call various methods and properties, such as range, cells, or name, to perform specific tasks.

For example, to read data from a specific cell on the active sheet, you can use the range method. Suppose you want to get the value from cell A1 on the active sheet. The code would be:

import xlwings as xw

# Connect to Excel
app = xw.apps.active

# Get the active sheet
active_sheet = app.active_sheet

# Read the value from cell A1
cell_value = active_sheet.range('A1').value
print(f"The value in A1 is: {cell_value}")

This example demonstrates how ActiveSheet provides a direct entry point to the user’s current context in Excel. Another common use case is to write data to the active sheet. For instance, you might want to insert a timestamp or update a cell with calculated results. Here’s how you can set a value in cell B2:

import xlwings as xw
from datetime import datetime

app = xw.apps.active
active_sheet = app.active_sheet

# Write the current date and time to cell B2
active_sheet.range('B2').value = datetime.now()
print("Timestamp added to B2.")

Additionally, you can perform more complex operations, such as clearing contents or formatting. To clear all data from the active sheet, use the clear method:

import xlwings as xw

app = xw.apps.active
active_sheet = app.active_sheet

# Clear all contents and formats from the active sheet
active_sheet.clear()
print("Active sheet cleared.")

How to use Application.ActiveProtectedViewWindow in the xlwings API way

The ActiveProtectedViewWindow property of the Application object in Excel returns a ProtectedViewWindow object that represents the active Protected View window. This is particularly useful when working with files opened in Protected View, a security feature that opens potentially unsafe files (like those from the internet) in a restricted mode to prevent malicious code from running. Through xlwings, you can access this property to interact with the active Protected View window, such as checking its existence, obtaining details about the opened file, or even closing it. This enables automation scripts to handle files that trigger Protected View, ensuring robust workflow management even with security-restricted documents.

Syntax in xlwings:

app.active_protected_view_window

• Return Value: This property returns an xlwings ProtectedViewWindow object if there is an active Protected View window. If no Protected View window is active, it returns None.
• Parameters: The property does not accept any parameters.
• Important: The ActiveProtectedViewWindow property is only available and meaningful when Excel has a file open in Protected View. Attempting to access it when no Protected View window is active will simply return None, so it’s essential to check for this condition in your code.

Examples of xlwings API Usage:

1. Checking for an Active Protected View Window:
   This example demonstrates how to verify if a file is currently open in Protected View and print a message accordingly.

import xlwings as xw

app = xw.apps.active # Get the active Excel application
pv_window = app.active_protected_view_window

if pv_window is not None:
    print(f"A Protected View window is active. Source: {pv_window.source_name}")
else:
    print("No active Protected View window found.")

2. Closing the Active Protected View Window:
   In this scenario, the script closes the active Protected View window. This is useful for automating the process of exiting Protected View, perhaps to proceed with editing the file programmatically.

import xlwings as xw

app = xw.apps.active
pv_window = app.active_protected_view_window

if pv_window:
    print(f"Closing Protected View window for: {pv_window.source_name}")
    pv_window.close() # Closes the Protected View window
else:
    print("No window to close.")

3. Accessing File Information from Protected View:
   Here, we retrieve and display details about the file in Protected View, such as its name and path, which can be logged or used for further processing.

import xlwings as xw

app = xw.apps.active
pv_window = app.active_protected_view_window

if pv_window:
    print(f"File in Protected View: {pv_window.source_name}")
    print(f"File path: {pv_window.source_path}")
    # The workbook object in Protected View is read-only; you can access data but not modify it.
    wb = pv_window.workbook
    print(f"Workbook name: {wb.name}")

How to use Application.ActivePrinter in the xlwings API way

The ActivePrinter property of the Application object in Excel’s object model is accessible through the xlwings library, enabling Python scripts to retrieve or set the name of the currently active printer for the Excel application. This is particularly useful for automating print-related tasks, such as ensuring reports are sent to a specific printer without manual intervention, or for auditing and logging which printer is set as default within a workbook session. By using xlwings, you can integrate this Excel functionality directly into Python workflows, allowing for seamless control over printing configurations in automated processes.

Syntax in xlwings:
In xlwings, the ActivePrinter property is accessed through the app object, which represents the Excel application. The property is both readable and writable, meaning you can get the current printer name or change it programmatically. The syntax is straightforward:

• To get the active printer: app.active_printer
• To set the active printer: app.active_printer = "Printer Name"
  The property returns or accepts a string value representing the printer name. The name should match exactly as configured in the system, including any driver or port details if applicable. For example, on Windows, it might appear as “HP LaserJet on Ne00:” or a similar format. If the specified printer is not available, Excel may default to another or throw an error, so it’s advisable to verify printer availability beforehand.

Code Examples with xlwings:
Here are practical examples demonstrating how to use the ActivePrinter property in xlwings:

1. Retrieving the Current Active Printer:
   This example connects to a running Excel instance, retrieves the active printer name, and prints it to the console. It’s useful for diagnostics or logging.

import xlwings as xw
# Connect to the active Excel application
app = xw.apps.active
# Get the active printer name
current_printer = app.active_printer
print(f"The active printer is: {current_printer}")

2. Setting the Active Printer to a Specific Device:
   This example sets the active printer to a desired printer, such as “Brother MFC-L2750DW series Printer” on a Windows system. Ensure the printer name is accurate to avoid issues.

import xlwings as xw
# Start or connect to Excel
app = xw.App(visible=True) # Open Excel visibly
# Set the active printer
app.active_printer = "Brother MFC-L2750DW series Printer on Ne00:"
# Confirm the change by printing the updated name
print(f"Printer set to: {app.active_printer}")
# Perform other tasks, like printing a workbook
app.books.add().api.PrintOut() # Example print command
app.quit() # Close Excel

3. Switching Printers Based on Conditions:
   In automated reporting, you might switch printers depending on the document type. This example checks the current printer and changes it if needed.

import xlwings as xw
app = xw.apps.active
# Define printer names (adjust based on your setup)
default_printer = "Microsoft Print to PDF"
backup_printer = "HP OfficeJet Pro 8720 on Ne01:"
# Get current printer
if app.active_printer == default_printer:
    # Switch to backup for high-volume printing
    app.active_printer = backup_printer
    print(f"Switched to backup printer: {backup_printer}")
else:
    print(f"Using current printer: {app.active_printer}")

How to use Application.ActiveEncryptionSession in the xlwings API way

The ActiveEncryptionSession property of the Application object in Excel is a read-only property that returns an EncryptionSession object. This property is particularly useful when you are working with encrypted workbooks or files that have Information Rights Management (IRM) restrictions. It provides access to the current encryption session, allowing you to retrieve details about the encryption method, permissions, and other security-related settings that are active for the workbook. This can be essential for automating security audits, managing document access programmatically, or integrating Excel with custom security protocols.

In the xlwings library, which enables Python to interact with Excel via its COM interface, you can access this property through the Application object. The syntax for accessing ActiveEncryptionSession in xlwings is straightforward. Since xlwings mirrors the Excel object model, you typically start by connecting to an Excel instance or creating one, then access the Application object, and finally call the property.

Syntax in xlwings:

encryption_session = app.api.ActiveEncryptionSession

Here, app refers to the xlwings App object, which represents the Excel application. The .api attribute provides direct access to the underlying COM object, allowing you to use Excel’s native properties and methods. The ActiveEncryptionSession property does not take any parameters. It returns an EncryptionSession object, which has its own properties and methods. If no encryption session is active (e.g., the workbook is not encrypted or IRM is not applied), this property may return None or raise an error, so it’s good practice to handle such cases.

Key Points:

• Return Value: An EncryptionSession object that contains information about the current encryption. This object can have properties like ProviderId, AlgorithmId, BlockSize, KeyLength, and methods to check permissions.
• Usage Context: Primarily used with workbooks that are encrypted or protected via IRM. It is not applicable for standard, unencrypted files.
• Error Handling: Always check if the returned object is valid before accessing its properties to avoid runtime errors.

Example Code in xlwings:
Below is a practical example demonstrating how to use the ActiveEncryptionSession property in a Python script with xlwings. This example assumes Excel is running with an encrypted workbook open.

import xlwings as xw

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

# Access the ActiveEncryptionSession property
try:
    encryption_session = app.api.ActiveEncryptionSession

    # Check if an encryption session exists
    if encryption_session is not None:
        # Retrieve encryption details
        provider_id = encryption_session.ProviderId
        algorithm_id = encryption_session.AlgorithmId
        key_length = encryption_session.KeyLength

        print(f"Encryption Provider ID: {provider_id}")
        print(f"Encryption Algorithm ID: {algorithm_id}")
        print(f"Key Length: {key_length}")

    # Example: Check if the session has specific permissions
    # Note: Actual properties may vary based on Excel version and encryption type
    # This is illustrative; refer to Excel's object model for exact properties.
    else:
        print("No active encryption session found. The workbook may not be encrypted.")
except Exception as e:
    print(f"An error occurred: {e}")

In this example, we first connect to the active Excel application using xw.apps.active. Then, we use app.api.ActiveEncryptionSession to get the encryption session object. We retrieve details like the provider and algorithm IDs, and the key length, printing them to the console. Error handling is included to manage cases where no session exists or if there are compatibility issues.

Considerations:

• The availability and behavior of the ActiveEncryptionSession property can depend on the version of Excel and the type of encryption used (e.g., password-based encryption vs. IRM). It’s recommended to test with your specific environment.
• xlwings provides a high-level API, but for advanced properties like this, using .api to access the raw COM object is necessary. Ensure that your Python environment has the necessary permissions to interact with Excel’s COM interface.
• This property is part of Excel’s security features, so it might be subject to system policies or require certain add-ins to be enabled.

How to use Application.ActiveChart in the xlwings API way

The Application.ActiveChart property in Excel’s object model is a powerful feature that allows developers to programmatically access and manipulate the currently active chart within an Excel application instance. In xlwings, a Python library that bridges Python and Excel on Windows and macOS, this property is exposed through the api property of the App or Book objects, providing a direct gateway to the underlying COM (Component Object Model) or AppleScript engine. This enables seamless automation of chart-related tasks, such as modifying data series, updating formatting, or extracting chart properties, directly from a Python script.

Functionality
The primary purpose of Application.ActiveChart is to retrieve a reference to the chart that is currently active (i.e., selected or in focus) in the Excel user interface. If no chart is active, accessing this property will return None or raise an error, depending on the context. This property is read-only; you cannot set it to activate a specific chart. Instead, it serves as a starting point for any subsequent operations on the active chart, such as changing its type, adjusting axis scales, or exporting it as an image.

Syntax and Parameters
In xlwings, you access this property via the api property of an App or Book object. The syntax is straightforward, as it does not accept any parameters:

active_chart = xw.apps[0].api.ActiveChart
# Or, if working with a specific workbook:
# active_chart = xw.books['MyWorkbook.xlsx'].api.ActiveChart

Here, xw.apps[0] refers to the first Excel application instance opened, and .api provides access to the native Excel object model. The returned active_chart is a COM object representing the active chart, which you can then use with other xlwings api calls or convert to an xlwings Chart object for more Pythonic interaction. Note that if no chart is active, active_chart will be None, so it’s good practice to check for this condition before proceeding.

Code Examples
Below are practical examples demonstrating how to use Application.ActiveChart with xlwings:

1. Check if a Chart is Active and Retrieve Its Title:
   This example verifies whether a chart is active and prints its title if available.

import xlwings as xw

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

if active_chart is not None:
    chart_title = active_chart.ChartTitle.Text
    print(f"Active chart title: {chart_title}")
else:
    print("No chart is currently active.")

2. Modify the Chart Type of the Active Chart:
   Here, we change the active chart to a clustered column chart, using the Excel constant xlColumnClustered (value 51).

import xlwings as xw

app = xw.apps.active
active_chart = app.api.ActiveChart

if active_chart is not None:
    # Change chart type to clustered column
    active_chart.ChartType = 51 # xlColumnClustered
    print("Chart type updated to clustered column.")
else:
    print("No active chart to modify.")

3. Extract Data from the Active Chart’s Series:
   This code snippet loops through each series in the active chart and prints its values and X-axis values.

import xlwings as xw

app = xw.apps.active
active_chart = app.api.ActiveChart

if active_chart is not None:
    for series in active_chart.SeriesCollection():
        series_name = series.Name
        series_values = series.Values
        x_values = series.XValues
        print(f"Series: {series_name}, Values: {series_values}, X Values: {x_values}")

4. Export the Active Chart as an Image:
   The following example exports the active chart to a PNG file in the current directory.

import xlwings as xw
import os

app = xw.apps.active
active_chart = app.api.ActiveChart

if active_chart is not None:
    export_path = os.path.join(os.getcwd(), 'active_chart.png')
    active_chart.Export(export_path)
    print(f"Chart exported to: {export_path}")

How to use Application.ActiveCell in the xlwings API way

The Application.ActiveCell property in Excel’s object model is a crucial feature for interacting with the currently selected cell in the active worksheet. In xlwings, this functionality is accessed through the api property, which provides a direct gateway to the underlying Excel COM (Component Object Model) objects. This allows for precise control and manipulation of the active cell, enabling dynamic data analysis and visualization workflows.

Functionality
The ActiveCell property returns a Range object that represents the single active cell in the active window of the Excel application. If a range of cells is selected, the active cell is the one within that selection where data entry would occur (typically highlighted with a white background in the selection). It is essential for operations that depend on the user’s current focus or for automating tasks relative to the active selection. Through xlwings, you can read or write values, apply formatting, or use it as a reference point for navigating or expanding selections.

Syntax
In xlwings, the ActiveCell is accessed via the Application object from the api. The general syntax is:

active_cell = xw.apps.active.api.ActiveCell

Alternatively, if you have a specific app instance (e.g., when multiple Excel instances are open), you can use:

app = xw.App(visible=True) # or get an existing app
active_cell = app.api.ActiveCell

The returned object is a COM proxy to Excel’s Range, which means you can chain it with other properties and methods available in the Excel object model. Key parameters for related methods (when called on active_cell) include:

• For reading or writing values: active_cell.Value or active_cell.Value2 (use Value2 for unformatted values).
• For formatting: properties like active_cell.Font.Bold = True.
• For navigation: methods like active_cell.Offset(RowOffset, ColumnOffset), where RowOffset and ColumnOffset are integer values specifying the number of rows and columns to move (positive for down/right, negative for up/left).

Examples
Here are practical xlwings API code examples demonstrating the use of Application.ActiveCell:

1. Reading the active cell’s value:

import xlwings as xw
# Ensure Excel is running and a cell is selected
wb = xw.books.active # Get active workbook
active_cell = xw.apps.active.api.ActiveCell
value = active_cell.Value
print(f"The active cell value is: {value}")

2. Writing a value to the active cell and applying formatting:

import xlwings as xw
app = xw.App(visible=True)
wb = app.books.open('example.xlsx')
active_cell = app.api.ActiveCell
active_cell.Value = "Updated Data"
active_cell.Font.Bold = True
active_cell.Interior.Color = 65535 # Yellow fill
wb.save()
app.quit()

3. Using the active cell as a starting point to select a range:

import xlwings as xw
active_cell = xw.apps.active.api.ActiveCell
# Select a range starting from the active cell, e.g., 3 rows down and 2 columns right
target_range = active_cell.Offset(3, 2).Resize(5, 4) # Resize to 5 rows by 4 columns
target_range.Value = [[1, 2, 3, 4] for _ in range(5)] # Fill with sample data

4. Checking the address of the active cell:

import xlwings as xw
active_cell = xw.apps.active.api.ActiveCell
address = active_cell.Address # Returns absolute address like "$A$1"
print(f"Active cell address: {address}")

How to use Application.Wait in the xlwings API way

The Application.Wait method in Excel’s object model is a useful tool for introducing pauses or delays in macro execution, allowing other processes to complete or simply timing operations. In xlwings, this functionality is accessed through the api property, which provides direct access to the underlying Excel object model. The method suspends all Microsoft Excel activity and may prevent the user from interacting with the application during the wait period, so it should be used judiciously, typically for short, controlled delays.

Functionality:
The primary purpose of Application.Wait is to pause the execution of a VBA macro or, in this context, a Python script using xlwings, until a specified time is reached. It is often employed to wait for external data refreshes, allow animations to complete, or synchronize with other applications. Unlike time.sleep() in Python, which halts the entire Python process, Application.Wait specifically halts Excel’s calculation and UI thread, which can be necessary when Excel needs to catch up with operations.

Syntax in xlwings:
The xlwings API call follows the pattern: app.api.Wait(Time). Here, app is an instance of the xlwings App class, representing the Excel application.

• Parameter: Time (required). This is a variant (date/time) argument that specifies the time at which to resume macro execution. It can be provided as a string or a Python datetime object. Excel expects the time in a format it recognizes, typically as a string like "hh:mm:ss" or a serial number representing the date and time.

Parameter Details:
The Time parameter is the future time when execution should continue. If the provided time is in the past, the method returns False immediately, and execution continues without waiting. The time is evaluated based on Excel’s system clock. To specify a duration (e.g., wait 5 seconds), you need to calculate the target time by adding the delay to the current time. For example, use datetime.now() + timedelta(seconds=5) to wait for 5 seconds.

Code Examples:

1. Basic Wait Until a Specific Time: This example pauses the macro until 10 seconds after the current time.

import xlwings as xw
from datetime import datetime, timedelta

app = xw.App(visible=True)
# Open a workbook or perform operations
target_time = datetime.now() + timedelta(seconds=10)
app.api.Wait(target_time) # Wait until 10 seconds from now
app.quit()

2. Wait for a Fixed Duration with Validation: This example waits for 3 seconds and checks if the wait was successful (i.e., the time was in the future).

import xlwings as xw
from datetime import datetime, timedelta

app = xw.App(visible=True)
wb = app.books.open('example.xlsx')
delay = timedelta(seconds=3)
success = app.api.Wait(datetime.now() + delay)
if success:
    print("Wait completed successfully.")
else:
    print("Wait was not executed (time in past).")
# Continue with other operations, like refreshing data
wb.save()
app.quit()

3. Using a String Time Format: You can also pass the time as a string, though this is less common in dynamic scripts.

import xlwings as xw

app = xw.App(visible=True)
# Wait until 2:30 PM on the current day
app.api.Wait("14:30:00")
app.quit()

Considerations:

• During the wait, Excel becomes unresponsive, so avoid long waits in interactive applications. For longer pauses, consider alternative methods like time.sleep() in a background thread or using events.
• The Application.Wait method returns a Boolean value: True if the wait was successful (i.e., the specified time was in the future), and False if not. This can be used for error handling.
• In xlwings, ensure that the Excel application is properly instantiated via xw.App() before calling api.Wait. Misuse may lead to runtime errors or unexpected behavior.

How to use Application.Volatile in the xlwings API way

The Application.Volatile method in Excel, when invoked via xlwings, marks a user-defined function (UDF) as volatile. A volatile function recalculates every time a calculation occurs in any open workbook, not just when its direct precedents change. This is essential for functions that depend on dynamic data like real-time feeds, random numbers, or the current time. In xlwings, you typically use this within a Python function decorated with @xw.func to control its recalculation behavior.

Functionality:
It ensures that the UDF recalculates with every workbook calculation cycle. This is useful for functions that need to return updated values continuously, such as those fetching live data. However, overuse can slow down performance due to excessive recalculation.

Syntax in xlwings:
In xlwings, you call Application.Volatile within a UDF by accessing the Excel application object. The method takes one optional parameter:

• Volatile(True): Marks the function as volatile (default behavior if called without arguments).
• Volatile(False): Marks the function as non-volatile, meaning it recalculates only when its direct precedents change.

The xlwings API call format is:

xw.apps.active.api.Volatile(True) # For the active Excel application

Here, xw.apps.active refers to the active Excel application instance, and .api provides access to the underlying Excel object model. The parameter True sets volatility; use False to disable it.

Example Usage:
Consider a UDF that returns a random number, which should change on every recalculation. Without volatility, it might only update when explicitly triggered. The xlwings code below defines such a function:

import xlwings as xw
import random

@xw.func
def dynamic_random():
    # Access the Excel application and set the function as volatile
    xw.apps.active.api.Volatile(True)
    # Return a random number between 0 and 1
    return random.random()

# To use this, save the script and import it as an xlwings add-in or run it in an interactive session.

How to use Application.Union in the xlwings API way

The Application.Union method in Excel VBA is used to create a single, combined range from two or more individual ranges. This combined range object can then be used for subsequent operations, such as formatting or data manipulation, applied uniformly across all the included cells. In xlwings, this functionality is accessed through the api property of an xlwings object, which provides direct access to the underlying Excel object model. This allows Python scripts to leverage Excel’s powerful range combination logic seamlessly.

Functionality
The primary function of Union is to create a composite Range object. This is particularly useful when you need to perform the same action on multiple, non-contiguous cell blocks without having to loop through each range separately. It streamlines code and improves efficiency.

Syntax in xlwings
The syntax follows the pattern of accessing the VBA method through the xlwings api:

combined_range = xw.apps[0].api.Union(Range1, Range2, ...)

• xw.apps[0].api: This accesses the Application object of the first open Excel instance via xlwings.
• .Union(): The method call.
• Parameters: Range1, Range2, …: These are two or more Range objects that you want to combine. You must provide at least two Range arguments. These ranges can refer to different worksheets or even different workbooks.
• Return Value: The method returns a new Range object representing the union of all specified ranges.

Code Example
The following xlwings script demonstrates the use of Application.Union. It creates a union of three separate ranges on a sheet and then applies a yellow background fill to all cells within the combined range.

import xlwings as xw

# Connect to the active Excel instance and workbook
app = xw.apps.active
wb = app.books.active
sheet = wb.sheets['Sheet1']

# Define three separate, non-adjacent ranges
range1 = sheet.range('A1:B2')
range2 = sheet.range('D4')
range3 = sheet.range('C6:E7')

# Use the Application.Union method via the api property
# Note: We use .api on the sheet's range objects to get the native Excel Range objects for the Union method.
combined_range = app.api.Union(range1.api, range2.api, range3.api)

# Apply formatting to the entire unioned range
combined_range.Interior.Color = (255, 255, 0) # Yellow fill

# The action above fills cells A1, A2, B1, B2, D4, and the block C6:E7.