How to use Application.UserName in the xlwings API way

The Application.UserName property in Excel’s object model represents the name of the current user as set in the Excel application options. In xlwings, this property can be accessed to retrieve or set the user name, which is useful for personalizing workbooks, tracking user activity, or implementing user-specific logic in automated Excel tasks. This property reflects the name entered under “File > Options > General > User name” in Excel, and changes made via xlwings will update this setting globally within the Excel instance.

Functionality:
The primary function is to get or set the current user’s name in Excel. This can be utilized to customize workbook behavior, such as displaying personalized messages, logging user interactions, or controlling access to certain features based on the user. It is a straightforward way to integrate user identity into automation scripts.

Syntax:
In xlwings, the Application object is accessed through the app property of a workbook or directly via xw.apps. The UserName property is used as follows:

• To get the current user name: user_name = app.user_name
• To set a new user name: app.user_name = "NewUserName"
  Here, app refers to an instance of the Excel application (e.g., xw.App or xw.apps.active). The property is a string, and setting it requires a valid string input; if no argument is provided or an invalid type is used, Excel may raise an error.

Parameters:
The UserName property does not take parameters in the traditional sense, as it is a property getter/setter. When setting, the value must be a string representing the desired user name. There are no additional options or enumerations; any text can be used, but it is typically limited to alphanumeric characters and common symbols.

Examples:
Below are practical xlwings API code instances demonstrating the use of Application.UserName:

1. Retrieving the Current User Name:
   This example connects to the active Excel instance and prints the current user name.

import xlwings as xw
# Connect to the active Excel application
app = xw.apps.active
# Get the user name
current_user = app.user_name
print(f"Current user: {current_user}")

2. Setting a New User Name:
   This example changes the user name to a custom value and verifies the update.

import xlwings as xw
# Start a new Excel instance (or use an existing one)
app = xw.App(visible=True)
# Set a new user name
app.user_name = "JohnDoe"
# Check the updated name
updated_user = app.user_name
print(f"Updated user: {updated_user}")
# Close the application
app.quit()

3. Using User Name for Personalization:
   This example retrieves the user name and uses it to personalize a message in a workbook.

import xlwings as xw
# Open a specific workbook
wb = xw.Book("example.xlsx")
app = wb.app
# Get user name and insert into a cell
user = app.user_name
wb.sheets[0].range("A1").value = f"Welcome, {user}!"
# Save and close
wb.save()
wb.close()