Archive

How to use Application.ClusterConnector in the xlwings API way

The ClusterConnector member of the Application object in Excel’s object model is a specialized interface for managing connections to Power Pivot data models in a clustered environment, such as SQL Server Analysis Services (SSAS) tabular models. In xlwings, this provides programmatic control over how Excel interacts with these external data sources, enabling automation of data refresh and connection management within a workbook. This is particularly useful in enterprise scenarios where data models are hosted on scalable, high-availability servers.

Syntax in xlwings:
The property is accessed through the Application object. In xlwings, the Application is typically represented by the app object when you instantiate Excel.

app.api.ActiveWorkbook.ClusterConnector

Note: ClusterConnector is a property that returns a WorkbookConnection object when the active workbook is connected to a Power Pivot model in a cluster. It is not a method. This property is read-only in the context of xlwings via the Excel API.

Key Functionality and Usage:
The primary purpose is to retrieve the connection string and details of the clustered Power Pivot connection. You can inspect properties like OLEDBConnection.Server and OLEDBConnection.Connection to understand the data source. This allows for verification or logging of connection parameters. It’s important to note that directly modifying the ClusterConnector via xlwings is limited; its main use is for informational purposes or to trigger a refresh of the connected model.

Code Examples:

1. Retrieving Cluster Connection Details:
   This example checks if the active workbook has a cluster connector and prints its server name and connection string.

import xlwings as xw

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

# Ensure a workbook is active
if app.books.active is not None:
    wb = app.books.active
    try:
        # Access the ClusterConnector property
        cluster_conn = wb.api.ClusterConnector

        # Get the OLEDB connection details
        oledb_conn = cluster_conn.OLEDBConnection
        print(f"Server: {oledb_conn.Server}")
        print(f"Connection String: {oledb_conn.Connection}")

        # Check if it's a Power Pivot connection
        if cluster_conn.Type == 5: # xlConnectionTypeOLEDB for Power Pivot
        print("This is a Power Pivot cluster connection.")
    except AttributeError:
        print("No active Power Pivot cluster connection found in this workbook.")

2. Refreshing Data via Cluster Connection:
   This example refreshes all data connections, including the Power Pivot model connected through the cluster.

import xlwings as xw

app = xw.apps.active
wb = app.books.active

# Refresh all data in the workbook, which includes the cluster-connected model
wb.api.RefreshAll()

# Alternatively, refresh a specific connection if known
# wb.connections["YourConnectionName"].Refresh()

Important Notes:

• The ClusterConnector property is only available if the workbook contains a Power Pivot data model connected to an SSAS cluster. Otherwise, accessing it may raise an AttributeError.
• In xlwings, you interact with this through the underlying Excel API (.api attribute), so a solid understanding of the Excel object model is beneficial.
• For automation, common tasks involve refreshing data, but direct manipulation of cluster settings (like changing the server) is typically done through Excel’s UI or server-side configuration, not via this property in xlwings.

How to use Application.ClipboardFormats in the xlwings API way

The Application.ClipboardFormats property in Excel VBA returns an array that lists the data formats currently available on the Clipboard. This is useful for programmatically determining what type of data (e.g., text, bitmap, HTML) has been copied, allowing your xlwings script to handle pasting operations intelligently or to verify clipboard content before proceeding. In xlwings, you access this property through the Application object, which represents the Excel application instance.

Functionality:
The primary function is to inspect the clipboard. It does not alter the clipboard’s contents. By retrieving the array of format IDs, you can check for the presence of specific formats (like xlClipboardFormatText or xlClipboardFormatBitmap) to decide the appropriate course of action in your automation script, such as conditional pasting or data validation.

Syntax in xlwings:

import xlwings as xw

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

• app: This is your xlwings App object.
• .api: This provides direct access to the underlying Excel VBA object model.
• ClipboardFormats: This is the property being called. It takes no arguments.
  The property returns a 1-based array (Variant) containing the integer IDs of the available formats. If the clipboard is empty, it may return None or an empty variant. The specific integer IDs correspond to Excel’s XlClipboardFormat enumeration. Common values include:
• 1: xlClipboardFormatText
• 2: xlClipboardFormatBitmap
• 8: xlClipboardFormatHTML
• -4142: xlClipboardFormatLink (DDE link)

Code Examples:

1. Basic Retrieval and Display:

import xlwings as xw
import sys

app = xw.apps.active
formats = app.api.ClipboardFormats

if formats is not None:
    # Convert the returned COM array to a Python list for easy handling
    # On Windows, the returned object is often a `tuple` when accessed via pywin32.
    format_list = list(formats)
    print(f"Available Clipboard Formats (IDs): {format_list}")
else:
    print("Clipboard is empty or formats cannot be retrieved.")

2. Checking for a Specific Format Before Pasting:
   This example checks if text is available on the clipboard before pasting into a specific cell.

import xlwings as xw

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

formats = app.api.ClipboardFormats

# Check if Text format (ID 1) is present
if formats is not None and 1 in formats:
    sht.range("A1").select() # Select the target cell
    app.api.Selection.PasteSpecial(Paste=-4163) # xlPasteValues = -4163
    # Alternatively, for a more xlwings-native approach after checking:
    # text_data = pyperclip.paste() # Using pyperclip module
    # sht.range("A1").value = text_data
else:
    print("No text format found on clipboard. Pasting aborted.")

3. Logging Available Formats for Debugging:

import xlwings as xw
import logging

logging.basicConfig(level=logging.INFO)
app = xw.apps.active

formats = app.api.ClipboardFormats
if formats:
    logging.info("Clipboard Snapshot:")
    for fmt_id in formats:
        # Map some known IDs for better readability
        format_names = {1: "Text", 2: "Bitmap", 8: "HTML", -4142: "DDE Link"}
        name = format_names.get(fmt_id, f"Unknown ID ({fmt_id})")
    logging.info(f" - {name}")

How to use Application.Charts in the xlwings API way

The Charts member of the Application object in Excel’s object model represents the collection of all chart sheets in a workbook. In xlwings, this is accessed via the api property, which provides direct access to the underlying Excel object model. This allows for advanced chart management, such as adding new chart sheets, modifying existing ones, or iterating through all charts in the application. Using Charts is particularly useful when you need to work with chart sheets specifically, as opposed to embedded charts within worksheets.

Functionality:
The Charts collection enables you to create, access, and manipulate chart sheets. Chart sheets are standalone sheets that contain only a chart, separate from worksheet data. You can add new chart sheets, reference existing ones by name or index, and perform operations like copying, moving, or deleting them. This is essential for automating report generation or dashboard creation where charts need to be organized independently.

Syntax:
In xlwings, you typically access Charts through the workbook or application context. The general syntax is:

• app.api.Charts: Returns the Charts collection for the entire Excel application, including all open workbooks.
• wb.api.Charts: Returns the Charts collection for a specific workbook (where wb is a workbook object).

Key methods and properties include:

• Add([Before], [After], [Count]): Adds new chart sheets. Parameters are optional: Before and After specify the sheet position (as a sheet object), and Count sets the number of sheets to add (default is 1).
• Item(Index): Returns a single Chart object by index (integer) or name (string).
• Count: Property that returns the number of chart sheets in the collection.

For parameters like Before and After, you can use sheet references, such as wb.sheets['Sheet1'].api, to position the new chart sheet relative to existing sheets.

Examples:
Here are xlwings API code examples demonstrating the use of the Charts member:

1. Adding a new chart sheet to a workbook:

import xlwings as xw

# Connect to an existing workbook or create a new one
wb = xw.Book('example.xlsx')
app = xw.apps.active

# Add a new chart sheet named "SalesChart" at the end
new_chart = wb.api.Charts.Add()
new_chart.Name = "SalesChart"
print(f"Added chart sheet: {new_chart.Name}")

2. Accessing and iterating through all chart sheets in the application:

import xlwings as xw

app = xw.apps.active

# Count the total chart sheets across all open workbooks
total_charts = app.api.Charts.Count
print(f"Total chart sheets in application: {total_charts}")

# Iterate through each chart sheet and print its name
for chart in app.api.Charts:
print(chart.Name)

3. Creating a chart sheet with specific positioning:

import xlwings as xw

wb = xw.Book('data.xlsx')
# Add a chart sheet before the first worksheet
first_sheet = wb.sheets[0].api
new_chart = wb.api.Charts.Add(Before=first_sheet)
new_chart.Name = "AnalysisChart"

# You can then use the Chart object to set data sources or formats
# For example, set a chart type (assuming data is prepared)
new_chart.ChartType = 51 # 51 corresponds to xlLineMarkers in Excel constants

4. Deleting a chart sheet by name:

import xlwings as xw

wb = xw.Book('report.xlsx')
# Delete a chart sheet named "OldChart"
try:
    wb.api.Charts("OldChart").Delete()
    print("Deleted chart sheet: OldChart")
except Exception as e:
    print(f"Error: {e}")

How to use Application.ChartDataPointTrack in the xlwings API way

The ChartDataPointTrack member of the Application object in the Excel object model is a Boolean property that controls whether data points in charts are tracked when the underlying data changes. When this property is set to True, Excel automatically updates data labels and other data point-related elements to reflect changes in the source data. This is particularly useful in dynamic dashboards or reports where the chart data is frequently updated, as it ensures visual elements remain synchronized without manual intervention. In xlwings, this property can be accessed and modified through the Application object, allowing Python scripts to manage this tracking behavior programmatically.

In xlwings, the syntax for accessing and setting the ChartDataPointTrack property is straightforward. Since it belongs to the Application object, you reference it via the xlwings.App instance. The property is a Boolean, accepting True or False values. Here’s the basic syntax:

import xlwings as xw

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

# Get the current value of ChartDataPointTrack
current_setting = app.api.ChartDataPointTrack
print(f"Current setting: {current_setting}")

# Set ChartDataPointTrack to True to enable tracking
app.api.ChartDataPointTrack = True

# Set it to False to disable tracking
app.api.ChartDataPointTrack = False

In this code, app.api provides direct access to the underlying Excel object model, allowing you to use the ChartDataPointTrack property as defined in Excel’s VBA documentation. There are no additional parameters for this property; it’s a simple read/write Boolean. When enabled, it affects all charts in the workbook that are linked to dynamic data sources, ensuring data points update automatically. This can be especially beneficial when combined with other xlwings features for data manipulation, such as updating cell values from Python, as changes will propagate to charts seamlessly.

Here’s a practical example demonstrating the use of ChartDataPointTrack with xlwings. Suppose you have an Excel workbook with a chart that visualizes sales data, and you’re updating the data from Python. By enabling ChartDataPointTrack, you ensure the chart’s data points adjust automatically:

import xlwings as xw
import pandas as pd

# Start or connect to Excel
app = xw.App(visible=True) # Make Excel visible for demonstration
wb = app.books.open('sales_report.xlsx') # Open a workbook with a chart
sheet = wb.sheets['Data']

# Enable ChartDataPointTrack for automatic updates
app.api.ChartDataPointTrack = True
print("Chart data point tracking enabled.")

# Simulate updating the underlying data with new sales figures
new_data = pd.DataFrame({
'Month': ['Jan', 'Feb', 'Mar'],
'Sales': [15000, 18000, 22000]
})
sheet.range('A1').value = new_data # Overwrite the existing data range

# The chart linked to this data range will now update its data points automatically
# For instance, if data labels were showing, they’d reflect the new Sales values

# Optional: Disable tracking after updates if needed
app.api.ChartDataPointTrack = False
print("Tracking disabled after updates.")

# Save and close
wb.save()
app.quit()

How to use Application.Cells in the xlwings API way

The Application object’s Cells member in Excel’s object model is an essential property for accessing and manipulating individual cells or ranges through their row and column indices. In xlwings, this functionality is primarily accessed via the api property, which exposes the underlying Excel object model, allowing for precise control over cell references.

Functionality:
The Cells property returns a Range object representing a single cell, specified by its row and column numbers. This is particularly useful for programmatically referencing cells without relying on A1-style notation, enabling dynamic cell access in loops or calculations based on numerical indices.

Syntax:
In xlwings, you access the Cells property through the Application object’s api. The basic syntax is:

app.api.Cells(RowIndex, ColumnIndex)

• RowIndex (required): An integer specifying the row number of the cell. For example, 1 refers to the first row.
• ColumnIndex (required): An integer specifying the column number of the cell. For example, 1 refers to column A, 2 to column B, and so on. Alternatively, you can use a column letter string, but this is less common in xlwings when using the Cells property directly.

This property is read-write, allowing you to both retrieve and set cell values or properties.

Examples:
Here are practical xlwings API code instances demonstrating the use of the Cells member:

1. Accessing a Single Cell Value:

import xlwings as xw
app = xw.App(visible=False) # Start Excel in the background
workbook = app.books.add() # Create a new workbook
sheet = workbook.sheets.active

# Set value in cell B3 (row 3, column 2) using Cells
sheet.api.Cells(3, 2).Value = "Hello, World!"

# Retrieve the value from cell B3
cell_value = sheet.api.Cells(3, 2).Value
print(cell_value) # Output: Hello, World!

app.quit()

2. Looping Through a Range of Cells:

import xlwings as xw
app = xw.App(visible=False)
workbook = app.books.add()
sheet = workbook.sheets.active

# Populate a 5x5 grid with numbers using Cells in nested loops
for row in range(1, 6):
for col in range(1, 6):
    sheet.api.Cells(row, col).Value = row * col

# Read and print the values from the grid
for row in range(1, 6):
    row_values = [sheet.api.Cells(row, col).Value for col in range(1, 6)]
    print(row_values)

app.quit()

3. Combining Cells with Other Range Properties:

import xlwings as xw
app = xw.App(visible=False)
workbook = app.books.open("example.xlsx") # Open an existing workbook
sheet = workbook.sheets[0]

# Use Cells to define a range from A1 to C3 by specifying start and end cells
start_cell = sheet.api.Cells(1, 1) # A1
end_cell = sheet.api.Cells(3, 3) # C3
range_obj = sheet.api.Range(start_cell, end_cell)

# Apply formatting to the range
range_obj.Interior.Color = 0x00FF00 # Green background
range_obj.Font.Bold = True

workbook.save()
app.quit()

4. Dynamic Cell Reference Based on Variables:

import xlwings as xw
app = xw.App(visible=False)
workbook = app.books.add()
sheet = workbook.sheets.active

# Use variables for row and column indices
target_row = 10
target_column = 5 # Column E
sheet.api.Cells(target_row, target_column).Value = "Dynamic Entry"

# Access adjacent cells using offsets from a base cell
base_cell = sheet.api.Cells(target_row, target_column)
base_cell.Offset(0, 1).Value = "Next Column" # Cell F10
base_cell.Offset(1, 0).Value = "Next Row" # Cell E11

app.quit()

How to use Application.CellDragAndDrop in the xlwings API way

Application.CellDragAndDrop in xlwings enables or disables the ability to drag and drop cells within Excel. This property is particularly useful when automating Excel through xlwings, as it allows developers to control whether users can interactively move cell contents by dragging—a feature that might interfere with automated processes or require restriction in certain applications. By setting this property, you can ensure the Excel environment behaves predictably during script execution.

Syntax and Parameters in xlwings
In xlwings, you access this property via the Application object. The syntax is straightforward:

app = xw.apps.active # Get the active Excel application
app.api.CellDragAndDrop = value

Here, app.api provides direct access to Excel’s underlying COM object model. The CellDragAndDrop property accepts a Boolean value:

• True (default in Excel): Enables cell drag-and-drop functionality.
• False: Disables cell drag-and-drop, preventing users from moving cells by dragging.

This property is read/write, meaning you can both retrieve its current state and modify it. Note that changes apply to the entire Excel instance and persist until altered again or Excel is restarted. In xlwings, using .api is essential because CellDragAndDrop is a native Excel VBA property not directly wrapped by xlwings’ high-level API.

Code Examples
Below are practical xlwings examples demonstrating how to use CellDragAndDrop:

1. Disabling drag-and-drop to prevent user interference during automation:

import xlwings as xw

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

# Disable cell drag-and-drop
app.api.CellDragAndDrop = False
print("Cell drag-and-drop disabled.")

# Perform automated tasks, e.g., data manipulation
wb = app.books.active
sheet = wb.sheets[0]
sheet.range("A1").value = "Data processing in progress..."

# Re-enable drag-and-drop after completion
app.api.CellDragAndDrop = True
print("Cell drag-and-drop re-enabled.")

2. Checking the current state and toggling the setting:

import xlwings as xw

app = xw.apps.active

# Get the current setting
current_setting = app.api.CellDragAndDrop
print(f"Current CellDragAndDrop setting: {current_setting}")

# Toggle the setting
app.api.CellDragAndDrop = not current_setting
print(f"Toggled to: {app.api.CellDragAndDrop}")

3. Using in a context manager to temporarily disable drag-and-drop:

import xlwings as xw
from contextlib import contextmanager

@contextmanager
def disable_cell_drag_and_drop(app):
"""Temporarily disable cell drag-and-drop."""
original_setting = app.api.CellDragAndDrop
app.api.CellDragAndDrop = False
try:
    yield
finally:
    app.api.CellDragAndDrop = original_setting

# Usage
app = xw.apps.active
with disable_cell_drag_and_drop(app):
# Perform operations without drag-and-drop interference
app.books.active.sheets[0].range("A1:A10").value = [[i] for i in range(10)]
print("Data written with drag-and-drop disabled.")

How to use Application.Caption in the xlwings API way

The Application.Caption property in Excel VBA is used to get or set the text that appears in the title bar of the main Excel application window. This property is particularly useful for branding, customizing the user interface, or indicating a specific mode or context within a larger application that uses Excel as a component. When you retrieve the Caption, you get the current title text; when you set it, you can change the title to any custom string. It’s important to note that this change is temporary and reverts to the default (“Microsoft Excel”) when Excel is restarted, unless programmatically set again.

In xlwings, you interact with this property through the api property of the main App or Book objects, which provides direct access to the underlying Excel VBA object model. The syntax for accessing the Application.Caption property is straightforward.

Syntax in xlwings:
To get the current caption:

current_caption = xw.apps[0].api.Caption

To set a new caption:

xw.apps[0].api.Caption = "My Custom Excel"

Here, xw.apps[0] refers to the first running Excel instance. The .api attribute exposes the native Excel VBA Application object, allowing you to use its properties and methods directly. The Caption property is a read/write string. No parameters are required for getting or setting; you simply assign a string value to set it.

Code Examples:

1. Retrieving and Printing the Default Caption:

import xlwings as xw
# Ensure Excel is running and get the first instance
app = xw.apps[0]
default_title = app.api.Caption
print(f"The current Excel window title is: {default_title}")
# Typically outputs: The current Excel window title is: Microsoft Excel

2. Setting a Custom Caption for Branding:

import xlwings as xw
app = xw.apps[0]
app.api.Caption = "Data Analysis Suite v2.1"
# The Excel title bar now displays "Data Analysis Suite v2.1"

3. Temporarily Modifying Caption During a Macro Execution:

import xlwings as xw
app = xw.apps[0]
original_caption = app.api.Caption
try:
    app.api.Caption = "Processing... Please Wait"
    # Simulate a long-running operation, e.g., data processing
    import time
    time.sleep(5)
finally:
    app.api.Caption = original_caption # Restore original title
# This provides user feedback during operations.

4. Using Caption to Differentiate Multiple Instances (if applicable):
   If you have multiple Excel instances open via xlwings, you can set unique captions to identify them.

import xlwings as xw
# Assuming two instances are open
app1 = xw.apps[0]
app2 = xw.apps[1]
app1.api.Caption = "Instance 1: Sales Data"
app2.api.Caption = "Instance 2: Financial Reports"

How to use Application.CanRecordSounds in the xlwings API way

The CanRecordSounds property of the Application object in Excel’s object model is a read-only Boolean property that indicates whether the current version and installation of Excel supports the recording of sounds. In practical terms, this property checks if the system has the necessary audio hardware and drivers, and if the Excel application itself is capable of utilizing this feature for operations such as adding sound notes to cells. This can be particularly useful for developers creating macros or applications that need to conditionally include audio functionalities, ensuring compatibility and preventing errors on systems without sound recording capabilities.

In xlwings, the Application object is accessed through the app property of a Book object or directly when creating an application instance. The CanRecordSounds property is exposed as a property of the Application object in xlwings, allowing you to query its value in Python. The syntax for accessing this property is straightforward, as it does not require any parameters. It returns True if sound recording is supported, and False otherwise. This property is rarely used in modern Excel development, as sound note features have been largely deprecated or replaced by other commenting systems, but it remains available for legacy support and specific use cases.

The xlwings API call format for CanRecordSounds is as follows:

app.can_record_sounds

Here, app refers to an instance of the xlwings App class, which corresponds to the Excel Application object. The property is accessed as an attribute, and it returns a Boolean value. There are no parameters to specify, making it simple to integrate into conditional checks within your scripts.

For example, you might use CanRecordSounds to determine whether to enable certain UI elements or to log system capabilities for debugging purposes. Below are two code examples demonstrating its usage with xlwings:

Example 1: Checking sound recording support in an existing Excel instance.

import xlwings as xw

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

# Check if sound recording is supported
if app.can_record_sounds:
    print("Sound recording is supported in this Excel installation.")
else:
    print("Sound recording is not supported.")

Example 2: Creating a new Excel instance and verifying capabilities.

import xlwings as xw

# Start a new Excel application
app = xw.App(visible=True)

# Access the CanRecordSounds property
support_status = app.can_record_sounds
print(f"CanRecordSounds property value: {support_status}")

# Perform actions based on the result
if support_status:
    # Code to add sound-related features could go here
    pass
else:
    # Fallback or warning message
    print("Audio features will be disabled due to lack of support.")

# Close the application
app.quit()

How to use Application.CanPlaySounds in the xlwings API way

The Application.CanPlaySounds property in Excel’s object model is a read-only Boolean property that indicates whether the current system environment supports playing sounds through Excel. This can be useful for developers to check sound capabilities before attempting to play sounds programmatically, such as via the Speak method or other sound-related features, ensuring compatibility and avoiding errors on systems without sound support. In xlwings, this property is accessed through the Application object, allowing Python scripts to query this setting.

Syntax in xlwings:
In xlwings, the Application.CanPlaySounds property is accessed using the following format:

app = xw.App() # or use xw.apps.active for an existing instance
can_play_sounds = app.api.CanPlaySounds

Here, app represents the xlwings App object connected to an Excel instance, and .api is used to access the underlying Excel object model. The property returns a Boolean value: True if the system can play sounds, and False otherwise. No parameters are required, as it is a simple property check.

Example Usage:
Below is a practical xlwings code example that demonstrates how to use Application.CanPlaySounds to conditionally play a sound or display a message based on system capability. This helps in creating robust applications that adapt to different user environments.

import xlwings as xw

def check_sound_capability():
# Connect to the active Excel instance or start a new one
app = xw.apps.active if xw.apps.count > 0 else xw.App()

# Access the CanPlaySounds property via the Excel object model
can_play = app.api.CanPlaySounds

if can_play:
    print("System supports sound playback. Playing a test sound...")
    # Example: Use Excel's Speak method to play a sound (requires sound support)
    app.api.Speak("Sound is available", True) # True for asynchronous speech
else:
    print("System does not support sound playback. Consider alternative notifications.")
    # Fallback action, like showing a message box
    app.api.Alert("Sound not supported on this system.", Type:=0) # Simple alert

# Clean up if a new app was created
if not xw.apps.count > 0:
    app.quit()

# Run the function
check_sound_capability()

How to use Application.Caller in the xlwings API way

The Application.Caller property in Excel’s object model is a powerful tool for identifying the cell or range that initiated a specific action, such as a macro or a user-defined function (UDF). In xlwings, this property is accessed through the api property of the Application object, allowing Python scripts to interact with Excel in a manner similar to VBA. This functionality is particularly useful for creating dynamic and responsive Excel applications where the script’s behavior depends on the location from which it was called.

Functionality:
Application.Caller returns a Range object representing the cell that called the macro or function. This is essential for UDFs where the function needs to know its own location in the worksheet to perform context-specific calculations or to retrieve adjacent cell values. It can also be used in event-driven macros to determine the source of a trigger.

Syntax in xlwings:
The property is accessed via:

caller_range = xw.apps[0].api.Caller
# or, if you have a specific app or workbook context:
# caller_range = app.api.Caller
# caller_range = book.app.api.Caller

The returned object is a Range from the Excel object model, which xlwings wraps. You can then use its properties and methods, such as Address, Row, Column, or Value.

Parameters:
Application.Caller does not take any parameters. Its return value depends on the context:

• If called from a worksheet function (UDF), it returns the cell containing the function.
• If called from a shape (like a button) assigned to a macro, it returns the shape name as a string.
• If called from a chart or in an unsupported context, it may return an error or None.

Example Usage:

1. In a User-Defined Function (UDF): A UDF that sums the values of the cell to its left and right, using the caller’s position.

import xlwings as xw

@xw.func
def sum_adjacent():
caller = xw.apps[0].api.Caller
left_cell = caller.Offset(0, -1).Value
right_cell = caller.Offset(0, 1).Value
# Handle None values (empty cells)
left = left_cell if left_cell is not None else 0
right = right_cell if right_cell is not None else 0
return left + right

When this function is entered in cell B2, it will sum the values in A2 and C2.

2. In a Macro Triggered by a Button: A script that changes the color of the button’s adjacent cell.

import xlwings as xw

def button_macro():
caller = xw.apps[0].api.Caller
# Assuming caller is a shape name (button), get its top-left cell
# This requires additional logic to map shape to cell, often via TopLeftCell
if isinstance(caller, str): # It's a shape name
    shape = xw.books[0].sheets[0].shapes[caller]
    target_cell = shape.TopLeftCell
    target_cell.color = (255, 0, 0) # Red fill
else: # It's a Range
    caller.color = (255, 0, 0)