tox.ini

# This file provides configurations for tox-based project development and management automation tasks.

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

# Note: The 'basepython' argument should always be set to the earliest supported Python version. The 'ruff check'
# command also covers the test directory, which activates the 'tests/**/*.py' per-file ignores configured in the
# pyproject.toml file. The 'mypy' command stays on the source directory, as the test directory is part of the mypy
# exclusion list.
[testenv:lint]
description =
    Runs static code formatting, style, and typing checkers. Follows the configuration defined in the pyproject.toml
    file.
dependency_groups = dev
basepython = py312
commands =
    automation-cli purge-stubs
    ruff format
    ruff check --fix ./src ./tests
    mypy ./src

[testenv:stubs]
description = Generates the py.typed marker and the .pyi stub files using the project's sdist distribution.
depends = lint
dependency_groups = dev
commands =
    automation-cli process-typed-markers
    stubgen -o stubs --include-private -p ataraxis_data_structures -v
    automation-cli process-stubs
    ruff format
    ruff check --select I --fix ./src

[testenv:{py312, py313, py314}-test]
package = wheel
description =
    Runs unit and integration tests for each of the python versions listed in the task name and aggregates test
    coverage data. Uses 'loadgroup' balancing and all logical cores to optimize task runtime speed.
dependency_groups = dev
setenv = COVERAGE_FILE = reports{/}.coverage.{envname}
commands =
    pytest --import-mode=importlib --cov=ataraxis_data_structures --cov-config=pyproject.toml --cov-report=xml \
    --junitxml=reports/pytest.xml.{envname} -n logical --dist loadgroup

# Note: the 'xml' and 'html' commands run with '--fail-under=0' so that both reports are always written ('coverage.xml'
# in the project root and 'reports/coverage_html' for the html report). The trailing 'report' command applies the 100%
# coverage gate configured in the pyproject.toml file and prints the statements that remain uncovered. Every reporting
# command also combines any data files it finds, so all of them run with '--keep-combined' to preserve the per-version
# data files consumed by the 'combine' command. Without the flag, the first reporting command deletes those files and
# the task only succeeds once per test run.
[testenv:coverage]
skip_install = true
description =
    Merges the per-version JUnit XML reports into 'reports/pytest.xml' and combines test-coverage data from multiple
    test runs (for different python versions) into xml and html reports, then verifies that the combined data covers
    100% of the measured statements. The html report can be viewed by loading the 'reports/coverage_html/index.html'.
deps = ataraxis-automation==9.0.2
setenv = COVERAGE_FILE = reports/.coverage
depends = {py312, py313, py314}-test
commands =
    junitparser merge --glob reports/pytest.xml.* reports/pytest.xml
    coverage combine --keep
    coverage xml --fail-under=0 --keep-combined
    coverage html --fail-under=0 --keep-combined
    coverage report --keep-combined

[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'.
deps = ataraxis-automation==9.0.2
depends = uninstall
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 project's source code distribution (sdist) and binary distribution (wheel), clearing the 'dist'
    directory beforehand so that artifacts built for an earlier version cannot be carried into the upload task.
deps = ataraxis-automation==9.0.2
commands =
    python -c "import shutil; shutil.rmtree('dist', ignore_errors=True)"
    python -m build . --sdist
    python -m build . --wheel

# Note: use 'tox -e upload -- --replace-token' command to replace the token stored in the shared .pypirc file before
# uploading the project.
[testenv:upload]
skip_install = true
description =
    Uses twine to upload the wheel ('*.whl') and source ('*.tar.gz') distributions found inside the project's 'dist'
    directory to PyPI.
deps = ataraxis-automation==9.0.2
commands =
    automation-cli acquire-pypi-token {posargs:}
    automation-cli upload-project

# Note: use 'tox -e deploy -- --replace-token' command to replace the token stored in the shared .netlifyrc file, and
# 'tox -e deploy -- --replace-site' to replace the site identifier stored in the project's .netlify-site file, before
# deploying the documentation.
[testenv:deploy]
skip_install = true
description =
    Uploads the API documentation built by the 'docs' task to the project's Netlify site. Build the documentation with
    'tox -e docs' before calling this task.
deps = ataraxis-automation==9.0.2
commands =
    automation-cli acquire-netlify-token {posargs:}
    automation-cli deploy-docs

[testenv:install]
skip_install = true
deps = ataraxis-automation==9.0.2
depends =
    lint
    stubs
    {py312, py313, py314}-test
    coverage
    docs
    export
description = Builds and installs the project into its development mamba environment.
commands =
    automation-cli install-project --environment-name axds_dev {posargs:}

[testenv:uninstall]
skip_install = true
deps = ataraxis-automation==9.0.2
description = Uninstalls the project from its development mamba environment.
commands =
    automation-cli uninstall-project --environment-name axds_dev

[testenv:create]
skip_install = true
deps = ataraxis-automation==9.0.2
description =
    Creates the project's development mamba environment using the requested python version and installs runtime and
    development project dependencies extracted from the pyproject.toml file.
commands =
    automation-cli create-environment --environment-name axds_dev --python-version 3.14 {posargs:}

[testenv:remove]
skip_install = true
deps = ataraxis-automation==9.0.2
description = Removes the project's development mamba environment.
commands =
    automation-cli remove-environment --environment-name axds_dev

[testenv:provision]
skip_install = true
deps = ataraxis-automation==9.0.2
description =
    Provisions the project's development mamba environment by verifying that the new environment specification
    resolves, then removing and (re)creating the environment and installing the project dependencies into it.
commands =
    automation-cli provision-environment --environment-name axds_dev --python-version 3.14 {posargs:}

[testenv:export]
skip_install = true
deps = ataraxis-automation==9.0.2
depends = uninstall
description = Exports the project's development mamba environment to the 'envs' project directory as a .yml file.
commands =
    automation-cli export-environment --environment-name axds_dev

[testenv:import]
skip_install = true
deps = ataraxis-automation==9.0.2
description =
    Creates or updates the project's development mamba environment using the .yml file stored in the 'envs' project
    directory.
commands =
    automation-cli import-environment --environment-name axds_dev