Automation Tools¶

Provides the assets that support various project development automation Command Line Interface (CLI) commands exposed by the ‘cli’ module. Implements the logic of all automation tasks.

class ataraxis_automation.automation.ProjectEnvironment(activate_command, deactivate_command, create_command, create_from_yaml_command, remove_command, install_dependencies_command, update_command, export_yaml_command, export_spec_command, install_project_command, uninstall_project_command, environment_name, environment_directory)¶

Bases: object

Encapsulates the data used to interface with the project’s mamba environment.

This class resolves and stores executable commands used to manage the project environment and important metadata information used by these commands.

Notes

This class should not be instantiated directly. Instead, use the resolve_environment_commands() class method to get an instance of this class.

activate_command: str¶: Stores the command used to activate the project’s mamba environment.

create_command: str¶: Stores the command used to generate a minimally-configured mamba environment.

create_from_yaml_command: str | None¶: Stores the command used to create a new mamba environment from an existing .yml file.

deactivate_command: str¶: Stores the command used to deactivate any current environment and switch to the base environment.

environment_directory: Path¶: Stores the path to the project’s mamba environment directory.

environment_exists()¶

Determines whether the environment can be activated (exists).

Return type:: bool

environment_name: str¶: Stores the name of the project’s mamba environment with the appended os-suffix.

export_spec_command: str¶: Stores the command used to export the project’s mamba environment to a spec.txt file with revision history.

export_yaml_command: str¶: Stores the command used to export the project’s mamba environment to a .yml file.

install_dependencies_command: str¶: Stores the command used to install all project dependencies into the project’s mamba environment using uv.

install_project_command: str¶: Stores the command used to build and install the project as a library into the project’s mamba environment.

remove_command: str¶: Stores the command used to remove (delete) the project’s mamba environment.

classmethod resolve_project_environment(project_root, environment_name, python_version='3.13', environment_directory=None, *, prerelease=False)¶

Generates the mamba and uv commands used to manipulate the project- and os-specific mamba environment and packages them into a ProjectEnvironment instance.

Parameters:

project_root (Path) – The absolute path to the root directory of the processed project.
environment_name (str) – The base-name of the project’s mamba environment.
python_version (str, default: '3.13') – The Python version to use as part of the new environment creation or provisioning runtimes.
environment_directory (Path | None, default: None) – Optional. The absolute path to the directory used by the mamba / conda manager to store Python environments. This argument only needs to be provided if the automatic (default) environment resolution fails.
prerelease (bool, default: False) – Determines whether uv is allowed to install prerelease versions of dependencies.

Return type:

ProjectEnvironment

Returns:

The resolved ProjectEnvironment instance.

Raises:

RuntimeError – If the host OS is unsupported, mamba or uv is not accessible, or the mamba environments directory cannot be resolved and no manual override is provided.
ValueError – If the project name cannot be extracted from pyproject.toml or duplicate dependencies are found.

uninstall_project_command: str¶: Stores the command used to uninstall the project library from the project’s mamba environment.

update_command: str | None¶: Stores the command used to update an already existing mamba environment using an existing .yml file.

ataraxis_automation.automation.colorize_message(message, color, *, wrap=True)¶

Modifies the input string to include an ANSI color code and, if necessary, formats the message by wrapping it at 120 characters.

Parameters:

message (str) – The input message string to format and colorize.
color (str) – The ANSI color code to use for coloring the message.
wrap (bool, default: True) – Determines whether to format the message by wrapping it at 120 lines.

Return type:

str

Returns:

The colorized and wrapped (if requested) message string.

ataraxis_automation.automation.delete_stubs(library_root)¶

Removes all .pyi stub files from the root library directory and its subdirectories.

Parameters:: library_root (Path) – The absolute path to the root library directory.
Return type:: None

ataraxis_automation.automation.format_message(message)¶

Formats input message strings to follow the general Sun lab and project Ataraxis style.

Parameters:: message (str) – The input message string to format.
Return type:: str
Returns:: The formatted message string.

ataraxis_automation.automation.generate_typed_marker(library_root)¶

Crawls the library directory tree and ensures that the py.typed marker exists only at the root level of the directory.

If the ‘py.typed’ is not found in the root directory, adds the marker file. If it is found in any subdirectory, removes the marker file.

Parameters:: library_root (Path) – The path to the root level of the library directory.
Return type:: None

ataraxis_automation.automation.move_stubs(stubs_directory, library_root)¶

Moves typing stub (.pyi) files from the ‘stubs’ directory to the appropriate level(s) of the library directory tree.

This function should be called after running stubgen on the built library package (wheel). It distributes the stubs generated by stubgen to their final destinations in the library source code.

Notes

This function expects that the ‘stubs’ directory has exactly one subdirectory, which contains an __init__.pyi file. This subdirectory is considered to be the library root in the ‘stubs’ directory structure.

Parameters:

stubs_directory (Path) – The absolute path to the project’s “stubs” directory.
library_root (Path) – The absolute path to the root library directory.

Return type:

None

ataraxis_automation.automation.resolve_library_root(project_root)¶

Resolves the absolute path to the project’s root library directory.

Notes

This function relies on the following resolution heuristic: library root is a directory at most one level below /src with an __init__.py file.

Parameters:: project_root (Path) – The absolute path to the root directory of the processed project.
Return type:: Path
Returns:: The absolute path to the root library directory.
Raises:: RuntimeError – If the valid root directory candidate cannot be found based on the determination heuristics.

ataraxis_automation.automation.resolve_project_directory()¶

Resolves the current working directory and verifies that it points to a valid Sun lab project.

Return type:: Path
Returns:: The absolute path to the current working directory, if it points to a valid Sun lab project.
Raises:: RuntimeError – If the current working directory does not point to a valid Sun lab project.

ataraxis_automation.automation.robust_rmtree(path)¶

Removes a directory tree with retry logic to handle transient Windows file locks.

On Windows, antivirus scanners, the Search Indexer, and recently-exited processes can hold file handles briefly after the calling process has finished with them. This function wraps shutil.rmtree() with an onerror handler that clears read-only attributes and an outer retry loop with exponential backoff to tolerate these transient locks. On non-Windows platforms, calls shutil.rmtree() directly with no retry overhead.

Parameters:: path (Path) – The absolute path to the directory tree to remove.
Raises:: PermissionError – If the directory cannot be removed after exhausting all retry attempts on Windows, or immediately on non-Windows platforms.
Return type:: None

ataraxis_automation.automation.verify_pypirc(file_path)¶

Verifies that the target .pypirc file contains valid PyPI authentication credentials (API token).

Notes

This function is not able to verify whether the token is currently active.

Parameters:: file_path (Path) – The absolute path to the .pypirc file to verify.
Return type:: bool
Returns:: True if the .pypirc file appears to contain a well-configured API token and False otherwise.

Command Line Interfaces (CLIs)¶

automation-cli¶

Exposes the helper environment used to automate various project development and building steps.

Commands exposed by this interface are intended to be called via the ‘tox’ automation manager and should not be used directly by end-users.

Usage

automation-cli [OPTIONS] COMMAND [ARGS]...

acquire-pypi-token¶

Ensures that a validly formatted PyPI API token is contained in the .pypirc file stored in the root directory of the project.

Usage

automation-cli acquire-pypi-token [OPTIONS]

Options

-rt, --replace-token¶: If this flag is provided, the command recreates the .pypirc file even if it already contains an API token.

create-environment¶

Creates the project’s mamba environment and installs the project dependencies into the created environment.

Usage

automation-cli create-environment [OPTIONS]

Options

-e, --environment-name <environment_name>¶: Required The name of the project’s mamba environment without the os-suffix, e.g: ‘project_dev’.

-p, --python-version <python_version>¶: Required The python version to use for the project’s mamba environment, e.g. ‘3.13’.

-ed, --environment-directory <environment_directory>¶: The absolute path to the local conda / mamba environments directory. This optional argument allows overriding the default environment detection procedure when it fails.

--prerelease¶: Determines whether uv is allowed to install prerelease versions of dependencies.

export-environment¶

Exports the requested mamba environment as .yml and spec.txt files to the /envs directory.

Usage

automation-cli export-environment [OPTIONS]

Options

-e, --environment-name <environment_name>¶: Required The name of the project’s mamba environment without the os-suffix, e.g: ‘project_dev’.

-ed, --environment-directory <environment_directory>¶: The absolute path to the local conda / mamba environments directory. This optional argument allows overriding the default environment detection procedure when it fails.

import-environment¶

Creates or updates the existing project’s mamba environment based on the operating-system-specific .yml file stored in the project /envs directory.

Usage

automation-cli import-environment [OPTIONS]

Options

-e, --environment-name <environment_name>¶: Required The name of the project’s mamba environment without the os-suffix, e.g: ‘project_dev’.

-ed, --environment-directory <environment_directory>¶: The absolute path to the local conda / mamba environments directory. This optional argument allows overriding the default environment detection procedure when it fails.

install-project¶

Builds and installs the project into the specified mamba environment as a library.

Usage

automation-cli install-project [OPTIONS]

Options

-e, --environment-name <environment_name>¶: Required The name of the project’s mamba environment without the os-suffix, e.g: ‘project_dev’.

-ed, --environment-directory <environment_directory>¶: The absolute path to the local conda / mamba environments directory. This optional argument allows overriding the default environment detection procedure when it fails.

--prerelease¶: Determines whether uv is allowed to install prerelease versions of dependencies.

process-stubs¶

Distributes the stub files from the /stubs directory to the appropriate level of the /src or src/library_name directory (depending on the type of the processed project).

Usage

automation-cli process-stubs [OPTIONS]

process-typed-markers¶

Crawls the library root directory and ensures that the ‘py.typed’ marker is found only at the highest level of the library hierarchy (the highest directory with __init__.py in it).

Usage

automation-cli process-typed-markers [OPTIONS]

provision-environment¶

Recreates the project’s mamba environment.

Usage

automation-cli provision-environment [OPTIONS]

Options

-e, --environment-name <environment_name>¶: Required The name of the project’s mamba environment without the os-suffix, e.g: ‘project_dev’.

-p, --python-version <python_version>¶: Required The python version to use for the project’s mamba environment, e.g. ‘3.13’.

-ed, --environment-directory <environment_directory>¶: The absolute path to the local conda / mamba environments directory. This optional argument allows overriding the default environment detection procedure when it fails.

--prerelease¶: Determines whether uv is allowed to install prerelease versions of dependencies.

purge-stubs¶

Removes all existing stub (.pyi) files from the library source code directories.

Usage

automation-cli purge-stubs [OPTIONS]

remove-environment¶

Removes (deletes) the project’s mamba environment if it exists.

Usage

automation-cli remove-environment [OPTIONS]

Options

-e, --environment-name <environment_name>¶: Required The name of the project’s mamba environment without the os-suffix, e.g: ‘project_dev’.

-ed, --environment-directory <environment_directory>¶: The absolute path to the local conda / mamba environments directory. This optional argument allows overriding the default environment detection procedure when it fails.

uninstall-project¶

Uninstalls the project library from the specified mamba environment.

Usage

automation-cli uninstall-project [OPTIONS]

Options

-e, --environment-name <environment_name>¶: Required The name of the project’s mamba environment without the os-suffix, e.g: ‘project_dev’.

-ed, --environment-directory <environment_directory>¶: The absolute path to the local conda / mamba environments directory. This optional argument allows overriding the default environment detection procedure when it fails.