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.")