How to use Worksheet.StandardWidth in the xlwings API way

The StandardWidth property in the Worksheet object of Excel’s object model represents the standard (default) width of all columns in the worksheet, measured in characters using the standard font. This value is a single-precision floating-point number that defines the default column width before any individual column adjustments are made. In xlwings, you can access this property to either retrieve or set the standard column width for a worksheet, which is useful when you need to standardize column sizes or reset them to a default state after custom changes.

Syntax in xlwings:
The StandardWidth property is accessed as an attribute of a Worksheet object in xlwings. It is both readable and writable, allowing you to get or set the value directly. The syntax is straightforward:

• To get the current standard width: worksheet.api.StandardWidth
• To set a new standard width: worksheet.api.StandardWidth = value
  Here, worksheet refers to an xlwings Worksheet object (e.g., obtained via wb.sheets['Sheet1'] or wb.sheets[0]), and value is a float representing the width in characters. Note that in xlwings, this property is accessed through the .api attribute, which provides direct access to the underlying Excel object model (from the pywin32 or appscript libraries), ensuring compatibility with Excel’s native behavior.

Parameters and Values:

• The value parameter when setting StandardWidth must be a positive float. In Excel, typical values range from 0 to 255 characters, but practical widths depend on the default font size (e.g., in Calibri 11-point, a width of 8.43 characters is common). If you set a width outside valid bounds, Excel may adjust it automatically or throw an error.
• When getting the property, it returns a float that reflects the current standard width. If no custom standard width has been set, it often defaults to 8.43 in newer Excel versions, but this can vary based on the workbook’s template or regional settings.

Example Usage in xlwings:
Below are code examples demonstrating how to use the StandardWidth property with xlwings in Python. These assume you have an existing Excel workbook open or created via xlwings.

1. Getting the Standard Width:
   This example retrieves the standard column width from the active worksheet and prints it.

import xlwings as xw
# Connect to an open Excel instance or create a new one
app = xw.App(visible=False) # Set visible=True to see Excel
wb = app.books.add() # Create a new workbook
ws = wb.sheets[0] # Access the first worksheet
# Get the current standard width
current_width = ws.api.StandardWidth
print(f"Current standard column width: {current_width} characters")
# Output might be: Current standard column width: 8.43 characters
wb.close()
app.quit()

2. Setting the Standard Width:
   This example sets a new standard width for all columns in a worksheet and then verifies the change. It can be useful for resetting widths or applying a uniform default.

import xlwings as xw
app = xw.App(visible=False)
wb = app.books.open('example.xlsx') # Open an existing workbook
ws = wb.sheets['DataSheet'] # Access a specific worksheet by name
# Set a new standard width (e.g., 10 characters)
new_width = 10.0
ws.api.StandardWidth = new_width
# Verify the change by retrieving the value
updated_width = ws.api.StandardWidth
print(f"Updated standard column width: {updated_width} characters")
# Save the workbook with the new standard width
wb.save()
wb.close()
app.quit()

3. Resetting to Default and Comparing Widths:
   This example shows how to use StandardWidth in conjunction with individual column widths. It sets a custom standard, adjusts a specific column, and then resets all columns to the standard.

import xlwings as xw
app = xw.App(visible=True) # Make Excel visible for observation
wb = app.books.add()
ws = wb.sheets[0]
# Set a broader standard width
ws.api.StandardWidth = 12.5
# Adjust a specific column (e.g., column A) to a different width
ws.range('A:A').column_width = 15
print(f"Column A width: {ws.range('A:A').column_width}")
print(f"Standard width: {ws.api.StandardWidth}")
# Reset all columns to the standard width by iterating (if needed)
# Note: Setting StandardWidth alone doesn't change already-adjusted columns;
# you may need to loop through columns or use ClearFormats.
# For a quick reset, you can use:
ws.api.Cells.EntireColumn.ColumnWidth = ws.api.StandardWidth
print("All columns reset to standard width.")
wb.close()
app.quit()