Archive

How to use Application.AutoPercentEntry in the xlwings API way

The AutoPercentEntry property of the Application object in Excel is a feature that controls the automatic conversion of decimal numbers into percentages when entered into cells. When this property is set to True, any decimal value (e.g., entering 0.15) typed into a cell will automatically be formatted as a percentage (15%). This can significantly streamline data entry in scenarios where percentage inputs are frequent, reducing the need for manual formatting. However, it’s important to note that this is a global application setting, meaning it affects all open workbooks and worksheets. Users should be cautious, as enabling it might inadvertently convert decimal data intended as other numeric types.

In the xlwings API, which provides a powerful bridge between Python and Excel, you access this property through the app object, which represents the Excel application. The property is available for both getting its current state and setting it to a new value.

Syntax in xlwings:

app.api.AutoPercentEntry

• Get: current_state = app.api.AutoPercentEntry
• Set: app.api.AutoPercentEntry = new_value
• Parameters: This property does not take parameters. It is a Boolean property where True enables automatic percentage entry and False disables it.

Code Examples:

1. Checking the Current Setting:

import xlwings as xw
app = xw.apps.active # Get the active Excel application
is_enabled = app.api.AutoPercentEntry
print(f"AutoPercentEntry is currently set to: {is_enabled}")

2. Enabling AutoPercentEntry:

import xlwings as xw
app = xw.apps.active
app.api.AutoPercentEntry = True
print("AutoPercentEntry has been enabled.")
# Now, entering 0.2 in a cell will display as 20%.

3. Disabling AutoPercentEntry:

import xlwings as xw
app = xw.apps.active
app.api.AutoPercentEntry = False
print("AutoPercentEntry has been disabled.")
# Decimal entries will now remain as decimals unless manually formatted.

4. Practical Workflow Example: This script toggles the setting, enters a test value, and then restores the original state.

import xlwings as xw
app = xw.apps.active
original_setting = app.api.AutoPercentEntry

# Enable for a task
app.api.AutoPercentEntry = True
wb = app.books.active
ws = wb.sheets[0]
ws.range('A1').value = 0.35 # Will appear as 35% in Excel
print("Test value 0.35 entered into A1 with AutoPercentEntry ON.")

# Restore original setting
app.api.AutoPercentEntry = original_setting
print(f"AutoPercentEntry restored to {original_setting}.")

How to use Application.AutomationSecurity in the xlwings API way

The AutomationSecurity property of the Application object in Excel is a crucial setting for controlling macro security when automating Excel through external applications like Python using the xlwings library. It determines the security level that Excel uses when opening files programmatically, which can affect whether macros are enabled or disabled automatically. This property is particularly important in scenarios where automation scripts need to ensure consistent security behavior, especially in environments with varying macro settings. By setting AutomationSecurity, developers can programmatically override the default security settings of Excel, providing more control over macro execution during automated processes. This helps in maintaining security protocols while allowing necessary macros to run in controlled automation tasks.

In xlwings, the AutomationSecurity property is accessed through the app object, which represents the Excel application. The syntax for setting or getting this property is straightforward, as it corresponds directly to the Excel Object Model. The property accepts integer values that correspond to specific security levels defined by Excel. The primary values are:

• 1 (msoAutomationSecurityLow): This setting enables all macros to run without prompting. It is useful in trusted environments but poses security risks if used with untrusted files.
• 2 (msoAutomationSecurityByUI): Excel uses the macro security level set in the user interface (via Trust Center settings). This is the default behavior when automation is initiated.
• 3 (msoAutomationSecurityForceDisable): This setting disables all macros automatically, regardless of the file’s trust settings. It is the most secure option, preventing any macro execution.

To use this property in xlwings, you first need to instantiate an Excel application object. The property can be set before opening a workbook to influence how Excel handles macros in that file. For example, if you want to ensure macros are disabled during an automated data processing task, you can set AutomationSecurity to 3. Conversely, if you trust the source and need macros to run, set it to 1. It’s essential to note that changing this property affects all subsequent workbooks opened in that instance of Excel until it is changed again or the application is closed.

Here is a code example demonstrating the use of AutomationSecurity in xlwings:

import xlwings as xw

# Start a new Excel application instance
app = xw.App(visible=False) # Run Excel in the background

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

# Set AutomationSecurity to disable all macros (msoAutomationSecurityForceDisable)
app.api.AutomationSecurity = 3
print("AutomationSecurity set to disable all macros.")

# Open a workbook that contains macros
wb = app.books.open('example_with_macros.xlsx')

# Perform some operations, such as reading data
data = wb.sheets['Sheet1'].range('A1').value
print(f"Data from A1: {data}")

# Set AutomationSecurity back to use UI settings (msoAutomationSecurityByUI)
app.api.AutomationSecurity = 2
print("AutomationSecurity reset to UI default.")

# Close the workbook without saving
wb.close()

# Quit the Excel application
app.quit()

How to use Application.AutoFormatAsYouTypeReplaceHyperlinks in the xlwings API way

The AutoFormatAsYouTypeReplaceHyperlinks member of the Application object in Excel is a property that controls whether Excel automatically formats text that resembles a hyperlink address into a clickable hyperlink as you type. This is part of the “AutoFormat as you type” feature, which can help in quickly creating interactive documents by converting typed URLs or network paths into functional links without manual formatting. In xlwings, this property is accessible via the Application object’s API, allowing you to programmatically check or set this automation setting, which can be particularly useful in scripts that prepare or clean Excel workbooks for specific user interactions.

Syntax in xlwings:
In xlwings, you interact with this property through the app object, which represents the Excel Application. The property is exposed as a boolean attribute. The syntax is straightforward:

app.api.AutoFormatAsYouTypeReplaceHyperlinks

This property can be both read and written. When reading, it returns True if the feature is enabled, and False if disabled. When writing, you can set it to True to enable automatic hyperlink formatting, or False to disable it. There are no additional parameters or arguments for this property, as it is a simple toggle.

Example Usage with xlwings:
Below is a practical example demonstrating how to use the AutoFormatAsYouTypeReplaceHyperlinks property in a Python script with xlwings. This example checks the current setting, toggles it based on a condition, and then types some text to observe the effect (if Excel is visible). Note that changes to this setting may affect the user’s Excel session, so it’s often used in controlled environments or reset afterward.

import xlwings as xw

# Start or connect to an Excel application
app = xw.App(visible=True) # Set visible=True to see the typing effect
wb = app.books.add()

# Access the AutoFormatAsYouTypeReplaceHyperlinks property
current_setting = app.api.AutoFormatAsYouTypeReplaceHyperlinks
print(f"Current AutoFormatAsYouTypeReplaceHyperlinks setting: {current_setting}")

# Toggle the setting: enable if disabled, or disable if enabled
new_setting = not current_setting
app.api.AutoFormatAsYouTypeReplaceHyperlinks = new_setting
print(f"Setting changed to: {new_setting}")

# To see the effect, type a URL in a cell (requires Excel to be visible and active)
if app.visible:
    sheet = wb.sheets[0]
    sheet.range('A1').value = "Visit https://www.example.com for more info."
    # If enabled, Excel will format the URL as a hyperlink automatically as you type.
    # Note: In xlwings, setting cell value programmatically may not trigger the "as you type" feature,
    # as it simulates direct value insertion rather than keystroke-by-keystroke typing.
    # The feature primarily works during manual typing in the Excel interface.

    # Restore the original setting (optional, for user convenience)
    app.api.AutoFormatAsYouTypeReplaceHyperlinks = current_setting

# Save and close
wb.save('hyperlink_example.xlsx')
wb.close()
app.quit()

Important Notes:

• The AutoFormatAsYouTypeReplaceHyperlinks property affects the entire Excel application session, not just a specific workbook. Changing it will influence all open workbooks and future typing actions.
• In xlwings, when you set a cell’s value using .value, Excel may not apply the “as you type” formatting because it is not simulating real-time keystrokes. The feature is designed for manual entry in the Excel GUI. Therefore, toggling this property via xlwings is more about configuring the environment for user interaction rather than for programmatic data insertion.
• This property is part of Excel’s application-level options, so it’s persistent across sessions if saved in the user’s settings, but xlwings changes are temporary for the current session unless explicitly saved via Excel’s options dialog.

How to use Application.AutoCorrect in the xlwings API way

The AutoCorrect feature in Excel is a powerful tool for automatically correcting common typing errors, capitalizing days of the year, and expanding text abbreviations. Through xlwings, you can programmatically access and control these settings via the Application object’s AutoCorrect property. This allows for automation of tasks such as disabling auto-capitalization of days, adding custom replacement entries, or checking if a specific text string is in the AutoCorrect list.

Functionality
The AutoCorrect object provides control over Excel’s AutoCorrect options. Key capabilities include:

• Managing automatic capitalization of days of the week.
• Controlling the first letter capitalization in sentences.
• Adding, removing, or checking text replacements (e.g., replacing “(c)” with “©”).
• Enabling or disabling various auto-formatting features.

Syntax and Parameters
In xlwings, you access it through the app object (an instance of xw.App). The basic syntax is:

app.api.AutoCorrect.MemberName

Where MemberName is a property or method of the AutoCorrect object. Common members include:

Member	Type	Description	Parameters/Values
CapitalizeNamesOfDays	Property	Gets or sets whether days are auto-capitalized.	Boolean (True/False)
TwoInitialCapitals	Property	Controls auto-correction of two initial capitals.	Boolean
AddReplacement(What, Replacement)	Method	Adds a custom text replacement.	What (String): Text to replace. Replacement (String): New text.
DeleteReplacement(What)	Method	Removes a custom replacement.	What (String): Text entry to delete.
ReplacementList(Index)	Property	Returns a specific replacement pair.	Index (Integer): Position in the list (1-based).

Code Examples
Here are practical examples using xlwings:

1. Disable auto-capitalization of days:

import xlwings as xw
app = xw.App(visible=False)
app.api.AutoCorrect.CapitalizeNamesOfDays = False
app.quit()

2. Add a custom text replacement:

import xlwings as xw
app = xw.App(visible=False)
# Replace "xlw" with "xlwings"
app.api.AutoCorrect.AddReplacement("xlw", "xlwings")
app.quit()

3. Check and delete a replacement:

import xlwings as xw
app = xw.App(visible=False)
# Delete if "xlw" exists in the list
try:
    app.api.AutoCorrect.DeleteReplacement("xlw")
    print("Replacement deleted.")
except Exception as e:
    print("Entry not found:", e)
app.quit()

4. Iterate through replacement list (first 5 entries):

import xlwings as xw
app = xw.App(visible=False)
ac = app.api.AutoCorrect
for i in range(1, 6):
try:
    item = ac.ReplacementList(i)
    print(f"Index {i}: {item}")
except:
    break
app.quit()

How to use Application.Assistance in the xlwings API way

The Application.Assistance member in Excel’s object model provides access to the Help system, allowing developers to display specific Help topics programmatically. In xlwings, this functionality is exposed through the api property, which grants direct access to the underlying Excel VBA object model. This is particularly useful for creating user-friendly applications where context-sensitive help can be triggered based on user actions or inputs.

Functionality:
The primary purpose of Application.Assistance is to show a designated Help topic to the user. It can display built-in Excel Help topics using their unique Help IDs, which are often numeric or string identifiers. This enables developers to guide users directly to relevant documentation without requiring them to manually search through the Help system.

Syntax:
In xlwings, the syntax to call this member is:

app.api.Assistance.ShowHelp(HelpFile, HelpContextID)

• HelpFile: This is a string parameter that specifies the name of the Help file. For built-in Excel Help, this is typically set to "" (an empty string) or None to use the default Excel Help file. If using a custom Help file, provide its full path or name.
• HelpContextID: This parameter can be a string or numeric value that identifies the specific Help topic. For Excel’s built-in topics, this ID is often a numeric code corresponding to a particular subject. The exact IDs can be found in Excel’s VBA object model documentation or through developer resources. For example, the Help ID for the “Format Cells” dialog is "xlMainWindow" or a specific numeric ID like 27010 for certain topics.

Example:
Below is an xlwings code example that demonstrates how to use Application.Assistance to display a Help topic. This example assumes Excel is already running and a workbook is open via xlwings.

import xlwings as xw

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

# Display a built-in Excel Help topic, e.g., for general assistance
# Using an empty string for HelpFile defaults to Excel's Help
# The HelpContextID "xlMainWindow" opens the main Help window
app.api.Assistance.ShowHelp(HelpFile="", HelpContextID="xlMainWindow")

# Alternatively, to show a specific topic by numeric ID (example ID)
# This might open a topic like "About Excel" (ID varies by version)
app.api.Assistance.ShowHelp(HelpFile="", HelpContextID=27010)

# For a custom Help file (if available), specify the file path
# app.api.Assistance.ShowHelp(HelpFile="C:\\Help\\CustomHelp.chm", HelpContextID=100)

Notes:

• The effectiveness of this method depends on the availability and correctness of Help IDs. Some IDs may change between Excel versions, so testing across versions is recommended.
• If the HelpFile parameter is left empty and a valid HelpContextID is provided, Excel will attempt to open the corresponding topic in its default Help system.
• In cases where the Help topic cannot be found, Excel may display a generic Help window or an error, depending on the version.

How to use Application.AskToUpdateLinks in the xlwings API way

The Application.AskToUpdateLinks property in Excel’s object model is a Boolean value that controls whether Excel prompts the user to update links when opening a workbook containing external links. When set to True (the default), Excel displays a dialog box asking the user if they want to update the links. When set to False, Excel opens the workbook without prompting and does not automatically update the links, which can speed up the opening process in automated scripts or when the user does not need the latest linked data.

In xlwings, you can access and manipulate this property through the App object, which represents the Excel application. The syntax is straightforward: app.api.AskToUpdateLinks. Here, app is your xlwings App instance, and the .api attribute provides direct access to the underlying Excel object model, allowing you to use the standard Application object properties and methods. The property accepts and returns a Boolean value (True or False). It’s important to note that this setting is application-wide, meaning it affects all workbooks opened in that Excel instance while the setting is active.

For example, to disable the prompt for updating links when opening a workbook, you can set AskToUpdateLinks to False. This is particularly useful in automation scenarios where you want to suppress user interactions. After opening the workbook, you might want to restore the original setting to avoid affecting other operations. Here’s a code example:

import xlwings as xw

# Start Excel application (visible or not)
app = xw.App(visible=False)

# Disable the prompt for updating links
app.api.AskToUpdateLinks = False

# Open a workbook that contains external links
wb = app.books.open('workbook_with_links.xlsx')

# Perform operations on the workbook...
# For instance, you can manually update links if needed:
    # wb.api.UpdateLinks()

# Re-enable the prompt for future operations
app.api.AskToUpdateLinks = True

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

In this example, we start by creating an Excel application instance with visible=False to run in the background. Setting app.api.AskToUpdateLinks = False ensures that no dialog appears when opening workbook_with_links.xlsx. If you need to update the links programmatically, you can call wb.api.UpdateLinks() (though this is not directly related to AskToUpdateLinks). Finally, we reset the property to True before closing to maintain default behavior for other uses, and then clean up by closing the workbook and quitting the app.

Another common use case is to check the current state of this property. You can retrieve its value to determine if prompts are enabled:

import xlwings as xw

app = xw.App(visible=True)
current_setting = app.api.AskToUpdateLinks
print(f"AskToUpdateLinks is currently set to: {current_setting}")
# This might output: AskToUpdateLinks is currently set to: True
app.quit()

How to use Application.ArbitraryXMLSupportAvailable in the xlwings API way

ArbitraryXMLSupportAvailable is a read-only property of the Application object in the Excel object model. This property returns a Boolean value that indicates whether Excel supports the use of arbitrary XML schemas. Specifically, it checks if the installed version of Excel has the capability to work with custom-defined XML maps and schemas beyond the built-in XML features. This is particularly relevant for developers who need to import, export, or manipulate data using non-standard XML formats directly within Excel. When this property returns True, it means the Excel instance can handle arbitrary XML mappings; if False, such functionality is not available, typically in older versions of Excel.

In xlwings, you access this property through the Application object, which is the top-level object representing the Excel application itself. The xlwings API provides a Pythonic way to interact with Excel’s COM interface, allowing you to check this property directly from your Python script.

Syntax in xlwings:

app.ArbitraryXMLSupportAvailable

• app: This is an instance of the xlwings App class, which corresponds to the Excel Application object. You typically obtain it by creating a new instance (app = xw.App()) or by connecting to an existing one (app = xw.apps.active).
• The property takes no parameters and returns a Boolean (True or False).

Code Example:
Below is a practical example demonstrating how to use the ArbitraryXMLSupportAvailable property in xlwings. This script checks if the current Excel application supports arbitrary XML schemas and prints a message accordingly. It also handles the Excel application properly by quitting after the operation.

import xlwings as xw

# Start or connect to an Excel application
app = xw.App(visible=False) # Set visible=True to see the Excel window

try:
    # Check if arbitrary XML support is available
    xml_support = app.api.ArbitraryXMLSupportAvailable

    if xml_support:
        print("This Excel instance supports arbitrary XML schemas.")
    else:
        print("Arbitrary XML schema support is NOT available in this Excel version.")

    # Optional: Display the Boolean value
    print(f"Value of ArbitraryXMLSupportAvailable: {xml_support}")

except AttributeError as e:
    print(f"Error accessing property: {e}. This may indicate an older Excel version or API issue.")

finally:
    # Close the Excel application
    app.quit()

Explanation:

• The script uses app.api.ArbitraryXMLSupportAvailable to access the property. In xlwings, the .api attribute provides direct access to the underlying Excel COM object model, ensuring compatibility with properties like this one.
• The try-except block catches AttributeError, which might occur if the property is not available in the Excel version being used (though this property is present in most modern versions).
• The finally block ensures that the Excel application is closed properly using app.quit(), which is good practice to avoid lingering processes.

How to use Application.Application in the xlwings API way

The Application object in Excel’s object model represents the entire Excel application, and in xlwings, it is accessed through the app property of a Book object or directly when creating an instance. The Application member provides a wide range of properties and methods to control the Excel environment, manage workbooks, and customize application-level settings. In xlwings, these are exposed via the api property, allowing Python scripts to interact with Excel’s COM interface seamlessly. This enables automation of tasks such as adjusting screen updating, calculating workbooks, or retrieving application information, enhancing efficiency in data analysis and visualization workflows.

Functionality:
The Application member allows control over global Excel behaviors. Key functionalities include managing calculation modes (automatic or manual), controlling screen updating to improve performance during macro execution, accessing version information, and handling events. It also provides access to other objects like workbooks and add-ins, enabling comprehensive automation.

Syntax:
In xlwings, the Application member is accessed through an App instance. The basic syntax is:
app.api.Application.PropertyOrMethod
Where app is an xlwings App object. For methods, parameters follow the method name, and their meanings align with Excel VBA documentation. Common parameters include:

• ScreenUpdating: A Boolean property to enable or disable screen refresh.
• Calculation: An enumeration to set calculation mode (e.g., xlCalculationAutomatic, xlCalculationManual).
• Version: A read-only property returning the Excel version string.

For example, to disable screen updating:
app.api.Application.ScreenUpdating = False
To set calculation to manual:
app.api.Application.Calculation = -4135 (where -4135 corresponds to xlCalculationManual).

Code Examples:

1. Controlling Screen Updating and Calculation:
   This example optimizes performance by turning off screen updates and setting calculation to manual before processing data, then restoring settings.

import xlwings as xw
app = xw.App(visible=False) # Start Excel in background
app.api.Application.ScreenUpdating = False
app.api.Application.Calculation = -4135 # Manual calculation
# Perform data operations here, e.g., open a workbook and manipulate data
wb = app.books.open('data.xlsx')
# After operations, restore settings
app.api.Application.Calculation = -4105 # Automatic calculation
app.api.Application.ScreenUpdating = True
wb.save()
app.quit()

2. Retrieving Application Information:
   This example fetches the Excel version and checks the calculation mode, useful for logging or conditional operations.

import xlwings as xw
app = xw.App(visible=False)
version = app.api.Application.Version
calculation_mode = app.api.Application.Calculation
print(f"Excel Version: {version}")
print(f"Calculation Mode: {calculation_mode}") # -4105 for automatic, -4135 for manual
app.quit()

3. Managing Workbooks via Application:
   The Application member can list all open workbooks, aiding in multi-workbook automation.

import xlwings as xw
app = xw.App(visible=True)
# Open multiple workbooks
wb1 = app.books.open('file1.xlsx')
wb2 = app.books.open('file2.xlsx')
# Access workbooks through Application
open_workbooks = app.api.Application.Workbooks
print(f"Number of open workbooks: {open_workbooks.Count}")
for wb in open_workbooks:
    print(wb.Name)
app.quit()

How to use Application.AlwaysUseClearType in the xlwings API way

Functionality
The Application.AlwaysUseClearType property in Excel’s object model is a read/write Boolean that controls whether ClearType font smoothing is used for all text within the Excel application window. ClearType is a Microsoft font rendering technology designed to improve text readability on LCD monitors. When enabled (True), text appears smoother and potentially more legible, especially at smaller font sizes or on certain displays. When disabled (False), Excel uses standard font rendering. This is an application-level setting, meaning it affects all open workbooks and persists across sessions unless changed. In xlwings, you can access and modify this property to programmatically manage the font rendering preference, which can be useful for ensuring consistent visual presentation in automated reports or when deploying Excel-based solutions across different user environments.

Syntax
In xlwings, you access this property via the App object, which represents the Excel application instance. The property is exposed as a simple attribute.

# Get the current value
current_setting = app.AlwaysUseClearType

# Set a new value
app.AlwaysUseClearType = new_value

• app: An xlwings App object instance. Typically obtained via xw.App() (for a new instance) or xw.apps collection (for an existing instance).
• current_setting: Returns a Python bool (True or False).
• new_value: A Python bool (True or False).

Remarks: This property corresponds directly to the Excel VBA Application.AlwaysUseClearType. It is only available on Windows, as ClearType is a Windows-specific technology. Attempting to access it on macOS will raise an AttributeError.

Code Examples

1. Checking the Current Setting:

import xlwings as xw

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

# Get the current ClearType setting
cleartype_enabled = app.AlwaysUseClearType
print(f"ClearType is currently enabled: {cleartype_enabled}")

2. Enabling ClearType Programmatically:

import xlwings as xw

# Start a new Excel instance (or use active)
app = xw.App()

# Ensure ClearType is turned on
app.AlwaysUseClearType = True
print("ClearType has been enabled for this Excel session.")

# ... perform other automation tasks ...

app.quit() # Close the instance

3. Conditional Toggle Based on Current State:

import xlwings as xw

app = xw.apps[0] # Access the first running Excel instance

if not app.AlwaysUseClearType:
    app.AlwaysUseClearType = True
    print("ClearType was off and has now been enabled.")
else:
    print("ClearType was already enabled.")

4. Integrating into a Larger Automation Script (with error handling for cross-platform compatibility):

import xlwings as xw
import sys

def configure_font_rendering(app_instance):
"""Attempt to set ClearType on Windows."""
if sys.platform.startswith('win'):
    try:
        app_instance.AlwaysUseClearType = True
        print("ClearType configured successfully.")
    except AttributeError as e:
        print(f"Could not set AlwaysUseClearType: {e}")
else:
    print("ClearType setting is only applicable on Windows. Skipping.")

# Usage
app = xw.App(visible=True)
configure_font_rendering(app)

# Create a workbook and add some text
wb = app.books.add()
ws = wb.sheets[0]
ws.range('A1').value = "Text displayed with ClearType smoothing (if Windows)."

wb.save('report_with_cleartype.xlsx')
app.quit()

How to use Application.AltStartupPath in the xlwings API way

The AltStartupPath property of the Application object in Excel is a read/write string property that sets or returns the full path to an alternate startup folder. This folder is used by Excel to store and locate files, such as templates, add-ins, or other workbooks, that should be automatically loaded when Excel starts. The primary startup folder is specified by the StartupPath property, but the AltStartupPath provides a secondary, user-defined location. This is particularly useful for managing different sets of startup files for various projects or user profiles without interfering with the default Excel startup configuration.

In xlwings, you can access this property through the xlwings.App object, which represents the Excel application. The property is exposed as a Python attribute, allowing you to get or set its value directly. The syntax for accessing the AltStartupPath property in xlwings is straightforward: you use the app instance (representing the Application object) and reference .api.AltStartupPath. This provides a bridge to the underlying Excel object model. Here is the basic syntax:

• To get the current alternate startup path:
  alt_path = app.api.AltStartupPath
  This returns a string containing the full path, or an empty string if no alternate startup path is set.
• To set a new alternate startup path:
  app.api.AltStartupPath = "C:\\Your\\Folder\\Path"
  You must provide a valid folder path as a string. Note that backslashes in Windows paths should be escaped (e.g., "C:\\Folder") or you can use raw strings (e.g., r"C:\Folder").

The property does not accept parameters beyond the path string itself. It is important to ensure that the specified folder exists and has appropriate permissions; otherwise, Excel may ignore it or throw an error. The AltStartupPath is persistent across Excel sessions if saved in a workbook or template, but setting it via xlwings only affects the current instance unless explicitly saved.

Here are some practical xlwings code examples demonstrating the use of AltStartupPath:

1. Retrieving the Current Alternate Startup Path:
   This example connects to a running Excel instance, retrieves the alternate startup path, and prints it.

import xlwings as xw
app = xw.apps.active # Get the active Excel application
alt_startup_path = app.api.AltStartupPath
print(f"Alternate Startup Path: {alt_startup_path}")

2. Setting a New Alternate Startup Path:
   This example sets a new alternate startup folder and then verifies the change by retrieving it.

import xlwings as xw
app = xw.App(visible=True) # Start a new Excel application
new_path = r"C:\MyExcelStartupFiles" # Use a raw string for Windows path
app.api.AltStartupPath = new_path
# Verify the setting
updated_path = app.api.AltStartupPath
print(f"Updated Alternate Startup Path: {updated_path}")
# Save the setting by saving a workbook or closing properly
app.quit()

3. Checking and Using the Alternate Startup Path for File Operations:
   This example checks if an alternate startup path is set, and if so, lists the files in that folder.

import xlwings as xw
import os
app = xw.apps.active
alt_path = app.api.AltStartupPath
if alt_path and os.path.exists(alt_path):
    files = os.listdir(alt_path)
    print(f"Files in Alternate Startup Path: {files}")
else:
    print("No valid alternate startup path set.")