Universal Wayland Session Manager

When launching an application via a .desktop file, uwsm performs iterative argument replacement to ensure the command line matches the intended Desktop Entry specification.

Supported Field Codes:

• %f: Replaces with the first provided file path.
• %u: Replaces with the first provided path, converted to a URL via path2url.
• %F: Replaces with the full list of provided file paths.
• %U: Replaces with the full list of provided paths, each converted to a URL.
• %c: Replaces with the localized name of the entry.
• %k: Replaces with the filename of the entry.
• %i: If an Icon key exists in the entry, it appends --icon <icon_name> to the command.

Iterative Replacement Logic: If a field code like %f or %u is used and multiple arguments are provided, uwsm generates multiple command lines (one for each argument) to allow for iterative execution of the application for each file/URL provided.

The find_terminal_entry() function searches for an appropriate terminal emulator based on XDG standards and local configurations.

It follows this priority:

1. Explicit Lists: Checks configuration files (e.g., xdg-terminals.list or {desktop}-xdg-terminals.list) in XDG config and data directories. It supports:
   • +entry.desktop: Explicitly include.
   • -entry.desktop: Explicitly exclude.
   • entry.desktop: Standard entry.
   • /execarg_default:entry.desktop:arg: Sets a default execution argument for a specific entry.
2. Application Search: If no explicit list matches, it searches all installed applications for entries that qualify as terminals.
3. Negative Cache: Uses a cache (not-terminals) to remember applications that have been identified as not being terminals to speed up future searches.

Returns a tuple of (terminal_entry_object, entry_id, entry_action) or (None, None, None) if no terminal is found.

entry, entry_id, entry_action = find_terminal_entry()

The MainArg class and associated functions provide tools to parse and validate XDG Desktop Entry strings. This includes handling .desktop files, extracting specific actions (e.g., entry.desktop:action), and resolving paths.

Key capabilities:

• Parsing: Distinguishes between a raw executable path and a Desktop Entry ID or file path.
• Validation: check_entry_basic validates the entry against the XDG spec, checking for required keys like Exec, handling TryExec, and verifying the existence of the target executable.
• Action Extraction: entry_action_keys allows retrieving specific action groups (like Desktop Action <name>) from a .desktop file, including expanded and tokenized Exec strings.
• Visibility: check_entry_showin enforces OnlyShowIn and NotShowIn rules based on the XDG_CURRENT_DESKTOP environment variable.

from uwsm.main import MainArg, check_entry_basic

# Example: Parsing a desktop entry with an action
arg = MainArg("my-app.desktop:open")
print(arg.entry_id)      # "my-app.desktop"
print(arg.entry_action)  # "open"

# Example: Validating an entry
# (Assumes 'entry' is a pyxdg DesktopEntry object)
check_entry_basic(entry, entry_action="open")

These functions provide a mechanism to persist and restore environment variables using runtime files in the uwsm runtime directory.

save_env(filename, env=None, separator="\0")

Saves a dictionary of environment variables to a file.

• filename: The name of the file to create within the uwsm runtime directory.
• env: The dictionary of variables to save. If None, the current os.environ is used. Variables are filtered via filter_varnames.
• separator: The delimiter used between key=value pairs. Defaults to a null byte (\0). Using \n is recommended for systemd EnvironmentFile= usage.

load_env(filename, delete=False)

Reads environment variables from a runtime file.

• filename: The name of the file to read.
• delete: If True, the file is removed after reading.
• Returns: A dictionary of the loaded variables.

# Example: Saving environment for systemd EnvironmentFile
save_env("env_session.conf", env=os.environ, separator="\n")

# Example: Loading environment
env = load_env("env_session.conf", delete=True)