Archive

How to use Application.Goto in the xlwings API way

The Goto method of the Application object in Excel is a powerful feature for navigating to a specific range, reference, or named location within a workbook. It is particularly useful for quickly moving the active cell or selection to a predefined area, which can enhance user interaction and automate navigation tasks in scripts. In xlwings, this functionality is accessed through the api property, which provides direct access to the underlying Excel object model, allowing for precise control similar to VBA.

Functionality:
The primary function of Goto is to shift the active cell or selection to a specified target. This target can be a Range object, a cell reference as a string, or a defined name (e.g., a named range). It can also scroll the window to make the target visible if it is not currently in view. This is especially beneficial in large worksheets where manual scrolling is inefficient, as it streamlines navigation during automated processes.

Syntax:
In xlwings, the Goto method is called via the Application object. The syntax is:

app.api.Goto(Reference, Scroll)

• Reference: This parameter is required and specifies the destination. It can be:
• A Range object (e.g., app.range('A1') or app.range('Sheet1!B5')).
• A string representing a cell address (e.g., 'Sheet2!C10').
• A string representing a defined name (e.g., 'MyNamedRange').
• Scroll: This optional parameter is a boolean value (True or False). If set to True, Excel will scroll the window to bring the target into view. The default value is False, meaning no scrolling occurs unless necessary.

Code Examples:

1. Navigate to a specific cell using a string reference:

import xlwings as xw
app = xw.apps.active # Get the active Excel application
app.api.Goto(Reference='Sheet1!D20', Scroll=True)

This moves the active cell to D20 on Sheet1 and scrolls the window to ensure it is visible.

2. Navigate to a named range:

import xlwings as xw
app = xw.apps.active
app.api.Goto(Reference='SalesData', Scroll=False)

Assuming ‘SalesData’ is a defined name in the workbook, this selects that range without scrolling.

3. Navigate using a Range object from xlwings:

import xlwings as xw
app = xw.apps.active
target_range = app.books['Workbook1.xlsx'].sheets['Data'].range('F15')
app.api.Goto(Reference=target_range.api, Scroll=True)

Here, the api property of the xlwings Range object is passed as the Reference, ensuring compatibility with the Excel object model.

4. Navigate to a range in another workbook:

import xlwings as xw
app = xw.apps.active
app.api.Goto(Reference="[Budget.xlsx]Annual!A1", Scroll=True)

How to use Application.GetSaveAsFilename in the xlwings API way

The GetSaveAsFilename method of the Application object in Excel is a powerful tool for prompting users to specify a filename and location for saving a file, without actually performing the save operation. This is particularly useful in scenarios where you need to obtain a user-defined file path for further processing, such as exporting data, creating reports, or setting a save destination in a macro. In xlwings, this functionality is accessed through the api property, which provides direct access to the underlying Excel object model.

Functionality:
The primary function of GetSaveAsFilename is to display the standard “Save As” dialog box. It returns the full path selected by the user as a string. If the user cancels the dialog, it returns False. This allows your script to conditionally proceed based on user input, ensuring flexibility and user control over file operations.

Syntax in xlwings:
The method is called via the Excel Application object. The basic xlwings API syntax is:

file_path = xw.apps[app_key].api.GetSaveAsFilename(InitialFilename, FileFilter, FilterIndex, Title, ButtonText)

Parameters:

• InitialFilename (Optional, Variant): Suggests a default filename. If omitted, the current workbook’s name is used.
• FileFilter (Optional, Variant): A string specifying file type filters. It consists of pairs: a description and the file extension, separated by commas, with pairs delimited by semicolons. For example, "Excel Files (*.xlsx), *.xlsx, Text Files (*.txt), *.txt".
• FilterIndex (Optional, Variant): The index number (1-based) of the default file filter to use from FileFilter. If omitted, the first filter is used.
• Title (Optional, Variant): The title text displayed in the dialog box. If omitted, the default title is shown.
• ButtonText (Optional, Variant): On Macintosh only, the text for the save button.

Code Examples:

1. Basic Usage: Prompt the user for a filename with a default suggestion.

import xlwings as xw

# Connect to the active Excel instance
app = xw.apps.active
# Get a save filename, suggesting "Report.xlsx"
suggested_path = app.api.GetSaveAsFilename(InitialFilename="Report.xlsx")
if suggested_path != False:
    print(f"User selected: {suggested_path}")
else:
    print("Save dialog was cancelled.")

2. With File Filters: Allow the user to choose between Excel and CSV formats.

import xlwings as xw

app = xw.apps.active
# Define filters for Excel and CSV files
file_filters = "Excel Workbook (*.xlsx), *.xlsx, CSV Files (*.csv), *.csv"
selected_path = app.api.GetSaveAsFilename(FileFilter=file_filters, FilterIndex=2, Title="Export Data")
if selected_path:
    # Process the path (e.g., save data using pandas or other libraries)
    print(f"File will be saved to: {selected_path}")

3. Integration with Data Export: Combine with pandas to save a DataFrame based on user input.

import xlwings as xw
import pandas as pd

# Sample DataFrame
data = pd.DataFrame({'A': [1, 2, 3], 'B': [4, 5, 6]})
app = xw.apps.active
path = app.api.GetSaveAsFilename(InitialFilename="DataExport.csv",
FileFilter="CSV Files (*.csv), *.csv",
Title="Save CSV File")
if path and isinstance(path, str):
    # Ensure the file has the correct extension if not provided by user
    if not path.endswith('.csv'):
        path += '.csv'
        data.to_csv(path, index=False)
        print(f"Data saved to {path}")

How to use Application.GetPhonetic in the xlwings API way

The GetPhonetic member of the Excel Application object is a method that retrieves the Japanese phonetic (furigana) text for a specified string or cell. This is particularly useful when working with Japanese data, as it allows you to programmatically access the phonetic guides often used to indicate the pronunciation of Kanji characters. In xlwings, this functionality is exposed through the api property, which provides direct access to the underlying Excel object model.

The syntax for calling GetPhonetic in xlwings is as follows:

app.api.GetPhonetic(Text)

Where:

• app is an instance of the xlwings App class, representing the Excel application.
• Text (optional): This parameter specifies the text for which to retrieve the phonetic information. It can be a string or a reference to a cell. If omitted, the method returns the phonetic text for the last processed text.

The Text parameter accepts different types of inputs, which determine its behavior:

Input Type	Description
String	A literal text string (e.g., "東京"). The method returns the phonetic text for that string.
Range Reference	A reference to a cell (e.g., app.range('A1')). The method returns the phonetic text for the cell’s value.
Omitted	If the parameter is not provided, Excel uses the last text that was processed for phonetics.

It’s important to note that the GetPhonetic method is primarily designed for Japanese text and may not return meaningful results for other languages. Additionally, the phonetic information must be present in the Excel file; it is often added through features like “Phonetic Guide” in Excel’s UI.

Here are two xlwings code examples demonstrating the use of GetPhonetic:

Example 1: Retrieving phonetic text from a string

import xlwings as xw

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

# Get phonetic text for the Japanese string "東京" (Tokyo)
phonetic_text = app.api.GetPhonetic("東京")
print(phonetic_text) # Output might be "トウキョウ" depending on Excel's settings

Example 2: Retrieving phonetic text from a cell

import xlwings as xw

# Start a new workbook
wb = xw.Book()
sheet = wb.sheets[0]

# Write a Japanese word with phonetic guide to cell A1 (assume phonetic is added via Excel)
sheet.range('A1').value = "東京"

# Retrieve the phonetic text from cell A1
phonetic_text = wb.app.api.GetPhonetic(sheet.range('A1'))
print(phonetic_text) # Output will be the phonetic text associated with the cell's content

How to use Application.GetOpenFilename in the xlwings API way

The Application.GetOpenFilename method in Excel’s object model allows users to display the standard “Open” dialog box, enabling file selection without actually opening any files. This is particularly useful for scenarios where you need to retrieve a file path for further processing, such as importing data, logging, or batch operations. In xlwings, this functionality is accessed through the api property of the App object, providing a direct bridge to Excel’s VBA methods.

Syntax in xlwings:

file_path = xw.apps.active.api.GetOpenFilename(FileFilter, FilterIndex, Title, ButtonText, MultiSelect)

• FileFilter: A string specifying the file filtering criteria. For example, "Excel Files (*.xlsx), *.xlsx" restricts selection to .xlsx files. Multiple filters can be separated by commas.
• FilterIndex: An integer indicating the default filter index to use (e.g., 1 for the first filter). If omitted, the first filter is used.
• Title: A string for the dialog box’s title bar. If omitted, the default title “Open” is displayed.
• ButtonText: Reserved for Macintosh; typically ignored on Windows.
• MultiSelect: If set to True, allows multiple file selections, returning an array of file paths; default is False.

Example Usage:
Here is a practical example that prompts the user to select one or more Excel files and prints their paths. This script uses xlwings to interact with an active Excel instance.

import xlwings as xw

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

# Set up file filter for Excel files
file_filter = "Excel Files (*.xlsx), *.xlsx, All Files (*.*), *.*"

# Display the Open dialog with a custom title
selected_files = app.api.GetOpenFilename(FileFilter=file_filter,
FilterIndex=1,
Title="Select Excel Files for Processing",
MultiSelect=True)

# Process the result
if selected_files:
    if isinstance(selected_files, str): # Single file selected
        print(f"Selected file: {selected_files}")
    else: # Multiple files selected (returns a tuple)
        for file in selected_files:
            print(f"Selected file: {file}")
else:
    print("No file was selected.")

Key Points:

• When MultiSelect=True, the method returns a tuple of strings if multiple files are chosen; otherwise, it returns a single string.
• If the user cancels the dialog, the method returns False.
• This method does not open the file; it only retrieves the path(s), giving full control over subsequent actions like reading with pandas or xlwings.

How to use Application.GetCustomListNum in the xlwings API way

The GetCustomListNum member of the Application object in Excel is a method used to retrieve the index number of a custom list that has been defined in the Excel application. Custom lists are often utilized for sorting data in a user-defined order, such as days of the week or months, and they can also be used in functions like MATCH or VLOOKUP to align data with these custom sequences. In xlwings, this functionality is accessible through the api property, which provides direct access to the underlying Excel object model. This method is particularly useful when you need to programmatically determine the position of a specific list within Excel’s custom list collection, enabling dynamic interactions with list-based operations.

Functionality
GetCustomListNum returns a numeric value representing the index of a custom list based on a provided list array. If the specified list matches one of the custom lists defined in Excel, the method returns its index number (starting from 1 for the first custom list). If no match is found, it returns 0. This can assist in validating or identifying custom lists before performing operations like sorting or data alignment.

Syntax
In xlwings, the method is called via the Application object. The syntax is:

index = xw.apps[0].api.GetCustomListNum(list_array)

• list_array: This is a required parameter that specifies the list to be checked. It should be passed as an array or range of values. In xlwings, you can use a Python list or an Excel range object. For example, a Python list like ["Mon", "Tue", "Wed"] or an xlwings range like sheet.range("A1:A3").value.

Parameters and Values
The list_array parameter must be a one-dimensional array of strings or numbers that correspond to the custom list entries in Excel. Excel stores custom lists in a specific order, and the method compares the input array to these stored lists. Note that custom lists are case-insensitive in Excel, so the matching process ignores letter case. If the input array is empty or invalid, the method may return an error or 0.

Code Examples
Here are some xlwings API code instances demonstrating the use of GetCustomListNum:

1. Basic Example with a Python List: Check if a custom list for weekdays exists and get its index.

import xlwings as xw

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

# Define a list to check (e.g., weekdays)
list_to_check = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"]

# Get the custom list index
list_index = app.api.GetCustomListNum(list_to_check)
print(f"The custom list index is: {list_index}")
# Output might be 1 if this is the first custom list, or 0 if not found.

2. Using an Excel Range as Input: Retrieve data from a worksheet and check if it matches a custom list.

import xlwings as xw

# Open a workbook and reference a sheet
wb = xw.Book("example.xlsx")
sheet = wb.sheets["Sheet1"]

# Get values from a range (e.g., cells A1:A5)
range_values = sheet.range("A1:A5").value

# Ensure it's a flat list (xlwings returns a list of lists for 2D ranges)
if isinstance(range_values[0], list):
    range_values = [item for sublist in range_values for item in sublist]

# Check for custom list match
app = xw.apps.active
list_index = app.api.GetCustomListNum(range_values)
if list_index > 0:
    print(f"Custom list found at index: {list_index}")
else:
    print("No matching custom list found.")

3. Dynamic List Validation: Before sorting data, verify that a custom list exists to avoid errors.

import xlwings as xw

app = xw.apps.active
custom_list = ["Low", "Medium", "High"] # Example priority list

index = app.api.GetCustomListNum(custom_list)
if index == 0:
print("Warning: Custom list not defined. Consider adding it in Excel options.")
else:
# Proceed with sorting or other operations using the list index
print(f"Using custom list index {index} for sorting.")

How to use Application.GetCustomListContents in the xlwings API way

The GetCustomListContents member of the Application object in Excel is a method that retrieves the contents of a custom list. Custom lists are used for custom sorting or filling series, such as a list of department names, weekdays, or months in a specific language order. In xlwings, this method allows Python scripts to access these lists programmatically, enabling dynamic data processing and automation based on user-defined sequences. This is particularly useful for applications that require consistent sorting or pattern generation across different Excel workbooks or when integrating Excel data with other systems.

Syntax:
In xlwings, the GetCustomListContents method is accessed through the app object, which represents the Excel application. The syntax is as follows:

contents = app.api.GetCustomListContents(ListNum)

• ListNum: An integer parameter that specifies the index number of the custom list. In Excel, custom lists are indexed starting from 1. For example, built-in lists like days of the week or months may have specific indices, but user-defined lists are assigned indices based on their creation order. To determine the index of a custom list, you can check Excel’s options under “Advanced” > “General” > “Edit Custom Lists,” where lists are displayed in order, or use VBA to loop through lists programmatically. The method returns a string containing the list items, separated by commas.

Example:
Suppose you have a custom list in Excel containing the sequence “North, South, East, West” for sorting regional data. You can retrieve this list using xlwings to use it in a Python script for data analysis. Here’s a code example:

import xlwings as xw

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

# Assume the custom list is the first user-defined list (index might be 5 or higher, depending on built-in lists)
# In practice, you might need to determine the index dynamically
list_num = 5 # Example index; adjust based on your Excel setup
list_contents = app.api.GetCustomListContents(list_num)

# Output the retrieved list
print("Custom list contents:", list_contents)

# Split the string into a list for further processing
items = list_contents.split(',')
print("List items:", items)

# Use the list for sorting a pandas DataFrame, for instance
import pandas as pd
data = {'Region': ['South', 'East', 'North', 'West']}
df = pd.DataFrame(data)
# Create a categorical type based on the custom list for sorting
df['Region'] = pd.Categorical(df['Region'], categories=items, ordered=True)
df_sorted = df.sort_values('Region')
print("Sorted DataFrame:")
print(df_sorted)

How to use Application.FindFile in the xlwings API way

The FindFile method of the Application object in Excel is a powerful tool for programmatically opening the “Open” dialog box, allowing users to search for and select a file to open within the Excel application interface. This method mimics the action of clicking “File” > “Open” in the Excel ribbon, providing a user-interactive way to locate files without hardcoding file paths in your scripts. In xlwings, which provides a clean Pythonic interface to automate Excel, you can access this Excel method through the api property of the main App or Book objects, giving you direct access to the underlying Excel object model.

Functionality:
The primary function of FindFile is to display the standard Open dialog box. It returns a Boolean value: True if a file is successfully opened, and False if the dialog is canceled by the user. This method is particularly useful in scenarios where the script needs to prompt the user to select a file dynamically, such as in data import routines or when working with files that may change location.

Syntax in xlwings:
In xlwings, you call this method via the api property of an Application object. The typical syntax is:

result = xw.apps[0].api.FindFile()

Or, if you have a specific app instance:

app = xw.App()
result = app.api.FindFile()

The method does not take any parameters. The return value result is a Boolean indicating success (True) or cancellation (False).

Parameters:
FindFile has no parameters in Excel VBA, and this is directly mirrored in xlwings. The method relies entirely on user interaction within the displayed dialog.

Example Usage:
Here is a practical example using xlwings to open the Open dialog and handle the user’s selection:

import xlwings as xw

# Start or connect to Excel
app = xw.App(visible=True) # Ensure Excel is visible to see the dialog

# Display the Open dialog
file_opened = app.api.FindFile()

# Check the result
if file_opened:
    print("A file was successfully opened by the user.")
    # You can now interact with the opened workbook, e.g., get its name
active_book = app.books.active
    print(f"Opened workbook: {active_book.name}")
else:
    print("The Open dialog was canceled by the user.")

# Keep the app open or close as needed
# app.quit()

How to use Application.ExecuteExcel4Macro in the xlwings API way

The ExecuteExcel4Macro member of the Application object in Excel’s object model provides a way to run Excel 4.0 macro functions, which are legacy commands from older versions of Excel. While modern Excel primarily uses VBA, these functions can still be useful for specific tasks that are not directly supported by newer APIs, such as certain financial or engineering calculations. In xlwings, this functionality is accessed through the api property, which exposes the underlying Excel object model, allowing Python scripts to interact with Excel in a manner similar to VBA.

The syntax for calling ExecuteExcel4Macro via xlwings is straightforward. First, you need to obtain the Application object from an xlwings App or Book instance. Then, you can invoke the method. The method takes a single string argument, String, which represents the Excel 4.0 macro function you want to execute. This string should be formatted exactly as it would be in Excel 4.0, including any required arguments. For example, a common function is GET.CELL, which retrieves information about a cell. The parameter is provided as a plain string, and you must ensure it is correctly quoted and concatenated if variables are involved. There is no return value specification in the syntax itself; the output depends on the macro function called.

Here is a basic example that demonstrates how to use ExecuteExcel4Macro with xlwings to get the full path of the active workbook, using the Excel 4.0 function GET.DOCUMENT(1):

import xlwings as xw

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

# Execute the Excel 4.0 macro function to get the full path
full_path = app.api.ExecuteExcel4Macro("GET.DOCUMENT(1)")

print(f"Full path of active workbook: {full_path}")

Another example involves retrieving a specific cell’s value using GET.CELL. This can be useful for getting properties like the cell’s format or formula. In this case, you need to construct a reference string:

import xlwings as xw

# Connect to the active workbook and sheet
wb = xw.books.active
sheet = wb.sheets.active

# Define the cell address, e.g., A1
cell_address = "A1"

# Execute GET.CELL(6, A1) to get the formula in the cell (6 is the type_num for formula)
# Note: The reference must be provided as an R1C1-style reference or a named range
formula_result = wb.app.api.ExecuteExcel4Macro(f'GET.CELL(6, {cell_address})')

print(f"Formula in {cell_address}: {formula_result}")

How to use Application.Evaluate in the xlwings API way

The Application.Evaluate method in Excel is a powerful tool for converting a Microsoft Excel name or a formula string into an actual value or a reference object. In xlwings, this functionality is exposed through the api property of an App or Book object, allowing you to leverage Excel’s calculation engine directly from Python. This is particularly useful for evaluating complex formulas that are easier to express in Excel’s native syntax than to replicate in Python code, or for retrieving the value of a defined name.

The syntax in xlwings follows the pattern of accessing the underlying Excel object model. To call Evaluate, you first obtain the Excel Application object via the api property. The method takes a single string argument, which is the name or formula to be evaluated.

Syntax:

app.api.Evaluate(Name)

• app: This is your xlwings App object (e.g., xlwings.App() or xw.apps.active).
• .api: This property provides direct access to the pywin32 or appscript COM object, enabling calls to the raw Excel VBA object model.
• .Evaluate: The method being called.
• Name (String, Required): A formula, a defined name, or a reference (as a string) that you want Excel to evaluate. This must be provided in the locale of the Excel application or in A1-style notation. For example, "SUM(A1:B10)", "MyNamedRange", or "Sheet1!$C$5".

The method returns the result of the evaluated formula. This can be a simple data type (like a number, string, or boolean), an xlwings.Range object (if the name evaluates to a range reference), or an error.

Code Examples:

1. Evaluating a Mathematical Formula:
   This calculates a formula string and returns the numeric result.

import xlwings as xw

app = xw.App(visible=False)
wb = app.books.add()
# Place values in cells
wb.sheets[0].range('A1').value = 10
wb.sheets[0].range('A2').value = 20

# Use Evaluate to compute the sum
result = app.api.Evaluate("SUM(A1:A2)")
print(result) # Output: 30.0
wb.close()
app.quit()

2. Evaluating a Defined Name:
   This retrieves the value or reference associated with a name defined in the workbook.

import xlwings as xw

app = xw.App(visible=False)
wb = app.books.add()
# Define a name for a range
wb.api.Names.Add(Name="MyData", RefersTo="=Sheet1!$A$1:$A$5")
# Put values into the named range
wb.sheets['Sheet1'].range('A1:A5').value = [[1], [2], [3], [4], [5]]

# Evaluate the defined name to get its value (the array)
name_result = app.api.Evaluate("MyData")
print(list(name_result)) # Output: [1.0, 2.0, 3.0, 4.0, 5.0]
wb.close()
app.quit()

3. Evaluating a Formula that Returns a Range Object:
   This is useful for obtaining an xlwings Range object from a string reference.

import xlwings as xw

app = xw.App(visible=True)
wb = app.books.add()
ws = wb.sheets[0]
ws.range('B2').value = "Hello World"

# Evaluate returns a Range COM object, which xlwings wraps.
# The xlwings Range constructor can handle this COM object.
range_ref = app.api.Evaluate("Sheet1!B2")
xl_range = xw.Range(range_ref) # Wrap it in xlwings Range
print(xl_range.value) # Output: Hello World
print(xl_range.address) # Output: $B$2
# wb.close() and app.quit() omitted for an interactive example.

How to use Application.DoubleClick in the xlwings API way

In the Excel object model, the Application.DoubleClick method is a powerful feature that simulates a double-click action on the active cell in Excel. This action can trigger various Excel behaviors, such as entering cell edit mode, opening a cell for formula editing, or activating specific cell features like data validation lists. In xlwings, this functionality is accessible through the api property, which provides direct access to the underlying Excel COM object. This allows Python scripts to automate user interactions that typically require manual double-clicks, enhancing automation workflows in data processing and analysis.

The syntax for using DoubleClick in xlwings is straightforward, as it is called as a method without any parameters. Since it operates on the active cell, it requires that a cell is selected or active in the Excel application. In xlwings, you typically access this through the Application object, which represents the Excel instance. The method is invoked as follows:

app.api.DoubleClick()

Here, app refers to the xlwings App instance connected to Excel. The api property exposes the native Excel COM interface, allowing direct calls to methods like DoubleClick. This method does not take any arguments; it simply performs the double-click action on whatever cell is currently active in Excel. It is important to note that the effectiveness of this method depends on the context—for example, if the active cell contains a formula, double-clicking might place the cursor in the formula bar for editing, while in a cell with data validation, it might open a drop-down list.

To use Application.DoubleClick in xlwings, you must first ensure an Excel application is running and a workbook is open. Below are practical code examples demonstrating its usage:

Example 1: Basic double-click to edit a cell. This example opens Excel, selects a specific cell, and simulates a double-click to enter edit mode.

import xlwings as xw

# Connect to the active Excel instance or start a new one
app = xw.apps.active if xw.apps.active else xw.App()
wb = app.books.active if app.books else app.books.add()
ws = wb.sheets.active

# Select cell A1 and activate it
ws.range('A1').select()
app.api.DoubleClick() # Simulate double-click on A1
# This may allow editing of the cell content in Excel

Example 2: Using double-click in a loop to process multiple cells. This can be useful for automating tasks like checking data validation or triggering macros tied to cell events.

import xlwings as xw

app = xw.apps.active
if app:
    ws = app.books.active.sheets.active
    for cell in ws.range('B1:B5'):
        cell.select() # Make each cell active
        app.api.DoubleClick() # Double-click to interact with each cell
        # Add a pause or other operations as needed, e.g., app.wait(1)

Example 3: Combining with other xlwings features to log actions. This example double-clicks on a cell and then updates another cell with a timestamp.

import xlwings as xw
from datetime import datetime

app = xw.apps.active
if app:
    ws = app.books.active.sheets.active
    target_cell = ws.range('C3')
    target_cell.select()
    app.api.DoubleClick() # Trigger double-click on C3
    # Record the action in cell D3
    ws.range('D3').value = f'Double-clicked at {datetime.now().strftime("%H:%M:%S")}'