tox.ini

# This file provides configurations for tox-based project automation tasks. Generally, this project uses tox similar
# to how some other projects use build-systems.

# Base tox configurations. Note, the 'envlist' will run in the listed order whenever 'tox' is used without an -e
# specifier.
[tox]
requires =
    tox-uv>=1,<2
    tox>=4,<5
envlist =
    lint
    stubs
    {py311, py312, py313}-test
    coverage
    docs
    install

# This forces tox to create a 'sterile' environment into which the project with all dependencies is installed prior to
# running the requested tasks, isolating the process from the rest of the system. This is almost always the desired
# runtime mode.
isolated_build = True

# Note: The 'basepython' argument should either be set to the oldest version in the supported stack or to the main
# version. It controls the specific ruleset used to format and (especially) style-check the code. Also, existing
# stubs prevent mypy from checking source code, so they are removed before linting.
[testenv: lint]
description =
    Runs static code formatting, style and typing checkers. Mypy may not work properly until py.typed marker is
    added by 'stubs' task.
deps =
    mypy[faster-cache]>=1,<2
    ruff>=0,<1
    types-pyyaml>=6,<7
basepython = py311
commands =
    automation-cli purge-stubs
    ruff check --select I --fix
    ruff format
    mypy . --strict --extra-checks --warn-redundant-cast

# Note: if py.typed is not present, generates the marker in the highest library directory before generating stub files.
# Builds and uses the distribution package to generate the stubs.
[testenv: stubs]
description =
    Generates the py.typed marker and the stub files using the built library wheel. Formats the stubs with ruff before
    moving them to appropriate source sub-directories.
deps =
    mypy[faster-cache]>=1, <2
    ruff>=0,<1
depends = lint
commands =
    automation-cli process-typed-markers
    stubgen -o stubs --include-private --include-docstrings -p ataraxis_automation -v
    automation-cli process-stubs
    ruff check --select I --fix
    ruff format

# Note: The test source code should be written to import and use intended library name, as the project is compiled and
# installed as a library prior to running the tests. Therefore, the tests need to be designed to test the distributed
# library, rather than the source code.
[testenv: {py311, py312, py313}-test]
package = wheel
description =
    Runs unit and integration tests for each of the python versions listed in the task name. Uses 'loadgroup' balancing
    and all logical cores to optimize runtime speed while allowing manual control over which cores execute tasks (see
    pytest-xdist documentation).
deps =
    pytest>=8,<9
    pytest-cov>=6,<7
    pytest-xdist>=3,<4
    coverage[toml]>=7,<8
setenv =
    # Sets environment parameters, which includes intermediate coverage aggregation file used by coverage.
    COVERAGE_FILE = reports{/}.coverage.{envname}
commands =
    # Make sure the --cov is always set to the intended library name, so that coverage runs on the whole library
    # exactly once.
    pytest --import-mode=append --cov=ataraxis_automation --cov-config=pyproject.toml --cov-report=xml \
    --junitxml=reports/pytest.xml.{envname} -n logical --dist loadgroup

[testenv:coverage]
skip_install = true
description =
    Combines test-coverage data from multiple test runs (for different python versions) into a single html file. The
    file can be viewed by loading the 'reports/coverage_html/index.html'.
setenv = COVERAGE_FILE = reports/.coverage
depends = {py311, py312, py313}-test
deps =
    junitparser>=3,<4
    coverage[toml]>=7,<8
commands =
    junitparser merge --glob reports/pytest.xml.* reports/pytest.xml
    coverage combine --keep
    coverage xml
    coverage html

# Uses '-j auto' to parallelize the build process and '-v' to make it verbose.
[testenv:docs]
description =
    Builds the API documentation from source code docstrings using Sphinx. The result can be viewed by loading
    'docs/build/html/index.html'.
depends = uninstall
deps =
    sphinx>=8,<9
    importlib_metadata>=8,<9
    sphinx-rtd-theme>=3,<4
    sphinx-click>=6,<7
    sphinx-autodoc-typehints>=2,<3
commands =
    sphinx-build -b html -d docs/build/doctrees docs/source docs/build/html -j auto -v

[testenv:build]
skip-install = true
description =
    Builds the source code distribution (sdist) and the binary distribution package (wheel). Use 'upload' task to
    subsequently upload built wheels to PIP.
deps =
    build>=1,<2
    hatchling>=1,<2
allowlist_externals =
    docker
commands =
    python -m build . --sdist
    python -m build . --wheel

# You can pass the '--replace-token' flag from the command line to replace the token stored in the .pypirc file.
[testenv:upload]
description =
    Uses twine to upload all files inside the '/dist' folder to pip, ignoring any files that are already uploaded.
    Uses API token stored in '.pypirc' file or provided by user to authenticate the upload.
deps =
    twine>=5,<6
allowlist_externals =
    distutils
commands =
    automation-cli acquire-pypi-token {posargs:}
    twine upload dist/* --skip-existing --config-file .pypirc

# Note: This task automatically uses the latest version of the package uploaded to PIP and expects it to contain
# sdist archive. Ideally, it should be used together with the build and twine tasks, as that would ensure the recipe
# always matches the latest distributed code version.
[testenv:recipe]
description =
    Uses grayskull to parse the source code tarball stored on pip and generate the recipe used to submit the
    package to conda-forge. The submission process has to be carried out manually, see
    https://conda-forge.org/docs/maintainer/adding_pkgs/ for more details.
deps =
    grayskull>=2,<3
commands =
    automation-cli generate-recipe-folder
    grayskull pypi ataraxis_automation -o recipe --strict-conda-forge --list-missing-deps -m Inkaros

[testenv:install]
depends =
    lint
    stubs
    {py311, py312, py313}-test
    coverage
    docs
description =
    Builds and installs the project into the specified conda environment. If the environment does not exist, creates
    it before installing the project.
commands =
    automation-cli install-project --environment-name axa_dev

[testenv:uninstall]
description =
    Uninstalls the project from the specified conda environment. If the environment does not exist
    this task silently succeeds.
commands =
    automation-cli uninstall-project --environment-name axa_dev

[testenv:create]
description =
    Creates a minimally-configured conda environment using the requested python version and installs conda- and pip-
    dependencies extracted from pyproject.toml file into the environment. Does not install the project!
commands =
    automation-cli create-env --environment-name axa_dev --python-version 3.13
    rm -rf {envdir}

[testenv:remove]
description =
    Removes the requested conda environment, if it is installed locally.
commands =
    automation-cli remove-env --environment-name axa_dev

[testenv:provision]
description =
    Provisions an already existing environment by uninstalling all packages from the environment and then installing the
    project dependencies using pyproject.toml specifications.
commands =
    automation-cli provision-env --environment-name axa_dev --python-version 3.13

[testenv:export]
description =
    Exports the requested conda environment to the 'envs' folder as a .yml file and as a spec.txt with revision history.
commands =
    automation-cli export-env --environment-name axa_dev

[testenv:import]
description =
    Discovers and imports (installs) a new or updates an already existing environment using the .yml file
    stored in the 'envs' directory.
commands =
    automation-cli import-env --environment-name axa_dev

[testenv:rename]
description =
    Replaces the base environment name used by all files inside the 'envs' directory with the user-input name.
commands =
    automation-cli rename-environments

[testenv:adopt]
description =
    Adopts a Sun Lab template-generated project by replacing default placeholders with user-provided information.
commands =
    automation-cli adopt-project