Blog

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.