### Tox Quickstart Command for tox.ini Generation

Source: https://tox.wiki/en/latest/cli_interface

The `tox quickstart` command is a convenient script for generating a basic `tox.ini` configuration file. It accepts several options to customize the initial setup, including output formatting, error handling, and specifying the directory for the `tox.ini` file. This command simplifies the initial configuration process for new projects using tox.

```shell
# Generate a basic tox.ini file in the current directory
tox quickstart

# Generate tox.ini with colored output enabled
tox quickstart --colored yes

# Generate tox.ini with a specific stderr color
tox quickstart --stderr-color LIGHTGREEN_EX

# Generate tox.ini and dump after 60 seconds if it hangs
tox quickstart --exit-and-dump-after 60

# Generate tox.ini using a specific configuration file path
tox quickstart -c custom_tox.ini

# Generate tox.ini with a specified working directory
tox quickstart --workdir /path/to/tox_work/

# Generate tox.ini with a specified project root directory
tox quickstart --root /path/to/project/

# Generate tox.ini with increased verbosity
tox quickstart -v

# Generate tox.ini with decreased verbosity
tox quickstart -q

# Generate tox.ini and write results to a JSON file
tox quickstart --result-json q_results.json

# Generate tox.ini with a specific hash seed
tox quickstart --hashseed 98765

# Generate tox.ini specifying Python executables for discovery
tox quickstart --discover /usr/bin/python3.7

# Generate tox.ini to list dependencies
tox quickstart --list-dependencies

# Generate tox.ini to not list dependencies
tox quickstart --no-list-dependencies

# Generate tox.ini to show version information
tox quickstart --version

# Generate tox.ini disabling provision and outputting metadata to a file
tox quickstart --no-provision provision_info.json

# Generate tox.ini disabling recreation of provision environments
tox quickstart --no-recreate-provision

# Generate tox.ini and recreate environments
tox quickstart -r

# Generate tox.ini with configuration overrides
tox quickstart -x general_env:env_vars.DEBUG=True

# Generate tox.ini in a specific root directory
tox quickstart /path/to/project_root
```

--------------------------------

### Tox TOML Configuration Example

Source: https://tox.wiki/en/latest/_sources/user_guide.rst

Example of a tox configuration file in TOML format. It defines a list of environments to run ('format', '3.13'), and specifies settings for each environment, including dependencies, skip install flags, and commands to execute. It also demonstrates passing positional arguments.

```toml
env_list =  ["format", "3.13"]

[env.format]
description = "install black in a virtual environment and invoke it on the current folder"
deps = ["black==22.3.0"]
skip_install = true
commands = [[ "black", "." ]]

[env."3.13"]
description = "install pytest in a virtual environment and invoke it on the tests folder"
deps = [
    "pytest>=7",
    "pytest-sugar",
]
commands = [[ "pytest", "tests", { replace = "posargs", extend = true} ]]
```

--------------------------------

### Tox Configuration: TOML and INI Examples

Source: https://tox.wiki/en/latest/_sources/user_guide.rst

Provides example configurations for tox using both TOML and INI formats. These examples demonstrate how to specify requirements, environment lists, dependencies, and commands for different test environments like linting and type checking.

```toml
requires = ["tox>=4"]
env_list = ["lint", "type", "3.13", "3.12", "3.11"]

[env_run_base]
description = "run unit tests"
deps = [
    "pytest>=8",
    "pytest-sugar"
]
commands = [["pytest", { replace = "posargs", default = ["tests"], extend = true }]]

[env.lint]
description = "run linters"
skip_install = true
deps = ["black"]
commands = [["black", { replace = "posargs", default = ["."], extend = true} ]]

[env.type]
description = "run type checks"
deps = ["mypy"]
commands = [["mypy", { replace = "posargs", default = ["src", "tests"], extend = true} ]]
```

```ini
[tox]
requires =
    tox>=4
env_list = lint, type, 3.1{3,2,1}

[testenv]
description = run unit tests
deps =
    pytest>=8
    pytest-sugar
commands =
    pytest {posargs:tests}

[testenv:lint]
description = run linters
skip_install = true
deps =
    black
commands = black {posargs:.}

[testenv:type]
description = run type checks
deps =
    mypy
commands =
    mypy {posargs:src tests}
```

--------------------------------

### Tox Configuration Example (TOML)

Source: https://tox.wiki/en/latest/user_guide

Example of a tox configuration file in TOML format. It specifies required tox version, environment list, and settings for base test environments, linting, and type checking. Dependencies and commands for each environment are defined.

```TOML
requires = ["tox>=4"]
env_list = ["lint", "type", "3.13", "3.12", "3.11"]

[env_run_base]
description = "run unit tests"
deps = [
    "pytest>=8",
    "pytest-sugar"
]
commands = [["pytest", { replace = "posargs", default = ["tests"], extend = true }]]

[env.lint]
description = "run linters"
skip_install = true
deps = ["black"]
commands = [["black", { replace = "posargs", default = ["."], extend = true} ]]

[env.type]
description = "run type checks"
deps = ["mypy"]
commands = [["mypy", { replace = "posargs", default = ["src", "tests"], extend = true} ]]
```

--------------------------------

### Tox Quickstart Options

Source: https://tox.wiki/en/latest/cli_interface

This section outlines the various command-line options available for configuring tox during project setup and execution. These options control aspects such as help messages, output coloring, error handling, configuration files, working directories, and dependency management.

```APIDOC
## Tox Quickstart Options

### Description
This section outlines the various command-line options available for configuring tox during project setup and execution. These options control aspects such as help messages, output coloring, error handling, configuration files, working directories, and dependency management.

### Options

- **`-h`, `--help`**: Show this help message and exit.
- **`--colored` `COLORED`**: Enable or disable colored output. Defaults to 'yes' unless TERM=dumb or NO_COLOR is defined.
- **`--stderr-color` `STDERR_COLOR`**: Set the color for stderr output. Use 'RESET' for terminal defaults. (default: `RED`)
- **`--exit-and-dump-after` `SECONDS`**: Dump tox threads after N seconds and exit if tox hangs. Set to 0 to disable. (default: `0`)
- **`-c FILE`, `--conf FILE`**: Specify a configuration file or folder for tox. If not specified, tox will discover one. (default: `None`)
- **`--workdir DIR`**: Set the tox working directory. If not specified, it defaults to the directory of the config file. (default: `{cwd}/.tox`)
- **`--root DIR`**: Set the project root directory. If not specified, it defaults to the directory of the config file. (default: `None`)
- **`--runner DEFAULT_RUNNER`**: Specify the tox run engine to use when not explicitly stated in tox environment configuration. (default: `virtualenv`)
- **`--result-json PATH`**: Write detailed information about commands and results to a JSON file. (default: `None`)
- **`--hashseed SEED`**: Set PYTHONHASHSEED before running commands. Defaults to a random integer. Passing `'notset'` suppresses this behavior. (default: `890220119`)
- **`--discover PATH`**: Specify Python executables to try first for Python discovery. (default: `[]`)
- **`--list-dependencies`**: List the dependencies installed during environment setup.
- **`--no-list-dependencies`**: Never list the dependencies installed during environment setup.
- **`--version`**: Show the program's and plugins' version numbers and exit.
- **`--no-provision [REQ_JSON]`**: Do not perform provision. If a path is provided, write provision metadata as JSON to it. (default: `False`)
- **`--no-recreate-provision`**: Do not recreate the provision tox environment if 'recreate' is set.
- **`-r`, `--recreate`**: Recreate the tox environments.
- **`-x OVERRIDE`, `--override OVERRIDE`**: Apply configuration overrides. Example: `-x testenv:pypy3.ignore_errors=True`. (default: `[]`)

### Verbosity Options

- **`-v`, `--verbose`**: Increase verbosity. (default: `2`)
- **`-q`, `--quiet`**: Decrease verbosity. (default: `0`)
```

--------------------------------

### Tox INI Configuration Example

Source: https://tox.wiki/en/latest/_sources/user_guide.rst

Example of a tox configuration file in INI format. It defines a list of environments to run ('format', '3.13'), and specifies settings for each environment, including dependencies, skip install flags, and commands to execute. It also demonstrates passing positional arguments.

```ini
[tox]
env_list =
    format
    3.13

[testenv:format]
description = install black in a virtual environment and invoke it on the current folder
deps = black==22.3.0
skip_install = true
commands = black .

[testenv:3.13]
description = install pytest in a virtual environment and invoke it on the tests folder
deps =
    pytest>=7
    pytest-sugar
commands = pytest tests {posargs}
```

--------------------------------

### Tox Configuration Example (INI)

Source: https://tox.wiki/en/latest/user_guide

Example of a tox configuration file in INI format. It defines the global tox settings, including required version and environment list, followed by configurations for a default test environment and specific environments for linting and type checking.

```INI
[tox]
requires =
    tox>=4
env_list = lint, type, 3.1{3,2,1}

[testenv]
description = run unit tests
deps =
    pytest>=8
    pytest-sugar
commands =
    pytest {posargs:tests}

[testenv:lint]
description = run linters
skip_install = true
deps =
    black
commands = black {posargs:.}

[testenv:type]
description = run type checks
deps =
    mypy
commands =
    mypy {posargs:src tests}
```

--------------------------------

### TOML Example for deps in Tox

Source: https://tox.wiki/en/latest/config

This TOML example shows how to specify Python dependencies for a Tox environment using the 'deps' option. It includes direct package installations, requirement files, and constraint files.

```toml
[tool.tox.env_run_base]
deps = [
  "pytest>=8",
  "-r requirements.txt",
  "-c constraints.txt",
]

```

--------------------------------

### Python Example for extras in Tox

Source: https://tox.wiki/en/latest/config

This Python code snippet shows how to specify extra dependencies for a Tox environment using the 'extras' option. This is analogous to specifying extras in a pip install command.

```python
extras = ["testing"]

```

--------------------------------

### tox quickstart Command

Source: https://tox.wiki/en/latest/cli_interface

The `tox quickstart` command helps create a basic `tox.ini` configuration file for Python projects.

```APIDOC
## tox quickstart Command

The `tox quickstart` command helps create a basic `tox.ini` configuration file for Python projects.

### Usage
```bash
tox quickstart [-h] [--colored {yes,no}]
               [--stderr-color {BLACK,BLUE,CYAN,GREEN,LIGHTBLACK_EX,LIGHTBLUE_EX,LIGHTCYAN_EX,LIGHTGREEN_EX,LIGHTMAGENTA_EX,LIGHTRED_EX,LIGHTWHITE_EX,LIGHTYELLOW_EX,MAGENTA,RED,RESET,WHITE,YELLOW}]
               [--exit-and-dump-after seconds] [-c file] [--workdir dir] [--root dir]
               [--runner {virtualenv}] [-v | -q] [--result-json path] [--hashseed SEED]
               [--discover path [path ...]] [--list-dependencies | --no-list-dependencies]
               [--version] [--no-provision [REQ_JSON]] [--no-recreate-provision] [-r]
               [-x OVERRIDE]
               [root]
```

### Positional Arguments

- **`root`**: The folder where the `tox.ini` file will be created. (default: `{cwd}`)

```

--------------------------------

### Install tox using pip

Source: https://tox.wiki/en/latest/installation

Installs tox using pip, the standard Python package installer. This method can install tox directly into the user's site-packages or a global interpreter. Use with caution, especially if the Python installation is managed by the OS or another package manager. Requires pip version 9.0.0 or higher for wheel installations and 18.0.0 or higher for sdist installations.

```bash
python -m pip install --user tox
python -m tox --help

```

--------------------------------

### setup.cfg Configuration Example

Source: https://tox.wiki/en/latest/config

Example of a setup.cfg file used for tox configuration. It mirrors the structure of tox.ini, with core settings under [tox:tox] and environment settings under [testenv] and [testenv:{env_name}].

```INI
[tox:tox]
requires =
    tox >= 4.0
env_list =
    3.14t
    3.14
    3.13
    3.12
    type

[testenv]
deps = pytest
commands = pytest tests

[testenv:type]
deps = mypy
commands = mypy src

```

--------------------------------

### Tox Environment Reuse Example (Discouraged)

Source: https://tox.wiki/en/latest/_sources/upgrading.rst

Presents an example of Tox configuration that might have allowed environment reuse in version 3, which is now unsupported and can lead to incorrect results. The example shows distinct dependencies for environments 'a' and 'b'.

```ini
[testenv]
envdir = .tox/venv

[testenv:a]
deps = pytest>7

[testenv:b]
deps = pytest<7
```

--------------------------------

### Dockerfile to Extend Tox Image

Source: https://tox.wiki/en/latest/_sources/faq.rst

A Dockerfile example to create a derivative Tox image. It switches to root to install additional packages like specific Python versions, then switches back to the 'tox' user.

```Dockerfile
FROM 31z4/tox

USER root

RUN set -eux; \
    apt-get update; \
    DEBIAN_FRONTEND=noninteractive \
    apt-get install -y --no-install-recommends \
        python3.12; \
    rm -rf /var/lib/apt/lists/*

USER tox
```

--------------------------------

### Tox Installer API

Source: https://tox.wiki/en/latest/_sources/plugins_api.rst

This section details the Tox installer API, responsible for installing packages.

```APIDOC
## Tox Installer API

### Description
Provides the `Installer` class for managing package installations within Tox environments.

### Class
- **Installer** (`tox.tox_env.installer.Installer`): Handles the installation of packages.
```

--------------------------------

### TOML Configuration for tox Auto-provisioning

Source: https://tox.wiki/en/latest/_sources/user_guide.rst

Example of specifying 'requires' dependencies for tox auto-provisioning using TOML format. This ensures that the specified tox and plugin versions are met, creating a meta environment if necessary.

```toml
requires = ["tox>=4", "tox-uv>=1"]
```

--------------------------------

### tox.ini Configuration Example

Source: https://tox.wiki/en/latest/config

Example of a tox.ini file, demonstrating core configuration in the [tox] section and environment-specific configurations in [testenv] and [testenv:{env_name}] sections. It specifies dependencies and commands for different test environments.

```INI
[tox]
requires =
    tox >= 4.20
env_list =
    3.14t
    3.14
    3.13
    3.12
    type

[testenv]
deps = pytest
commands = pytest tests

[testenv:type]
deps = mypy
commands = mypy src

```

--------------------------------

### Control tox run-parallel Packaging and Installation

Source: https://tox.wiki/en/latest/cli_interface

Manage how tox packages and installs project dependencies. Options allow skipping packaging, installing a specific package, developing in place, and controlling package recreation.

```bash
# Only perform packaging activity
tox run-parallel --pkg-only

# Install a specific package instead of packaging
tox run-parallel --installpkg dist/my_package.whl

# Install package in development mode
tox run-parallel --develop

# Do not recreate packaging tox environment(s)
tox run-parallel --no-recreate-pkg

# Skip package installation for this run
tox run-parallel --skip-pkg-install
```

--------------------------------

### Tox User Configuration Example (INI)

Source: https://tox.wiki/en/latest/_sources/config.rst

Demonstrates how to set user-level configuration for Tox using an INI file. This allows overriding default values for CLI commands. The example shows how to enable skipping missing interpreters.

```ini
[tox]
skip_missing_interpreters = true
```

--------------------------------

### Tox Configuration: INI Format

Source: https://tox.wiki/en/latest/user_guide

This INI configuration achieves the same goals as the TOML example, defining 'format' and '3.13' test environments. It details dependencies, execution commands, and how to handle dynamic arguments passed to the commands. The 'env_list' property dictates the default environments.

```ini
[tox]
env_list =
    format
    3.13

[testenv:format]
description = install black in a virtual environment and invoke it on the current folder
deps = black==22.3.0
skip_install = true
commands = black .

[testenv:3.13]
description = install pytest in a virtual environment and invoke it on the tests folder
deps =
    pytest>=7
    pytest-sugar
commands = pytest tests {posargs}

```

--------------------------------

### Installer Abstract Class for Package Installation

Source: https://tox.wiki/en/latest/plugins_api

Abstract base class for package installers in tox environments. It defines abstract methods for checking installed packages and performing the actual installation process with specified arguments and sections.

```python
import abc
from typing import Generic, TypeVar, Any

T = TypeVar('T')

class _tox.tox_env.installer.Installer(abc.ABC, Generic[T]):
    """Abstract base class for package installers."""

    @abc.abstractmethod
    def _installed(self) -> Any:
        """Returns a list of installed packages (JSON dump-able)."""
        pass

    @abc.abstractmethod
    def _install(self, _arguments_: list[str], _section_: str, _of_type_: str) -> None:
        """Installs packages with given arguments and section."""
        pass
```

--------------------------------

### Install Tox with uv

Source: https://tox.wiki/en/latest/_sources/installation.rst

Installs the tox tool using uv, a Python package installer. This method is recommended for isolated environments. It requires uv to be installed beforehand as per its documentation. The output is the tox command line interface.

```bash
# install uv per https://docs.astral.sh/uv/#getting-started
uv tool install tox
tox --help
```

--------------------------------

### tox.toml Native TOML Configuration Example

Source: https://tox.wiki/en/latest/config

Example of native TOML configuration in a dedicated tox.toml file. This format is equivalent to the pyproject.toml native TOML configuration but does not require the [tool.tox] sub-table.

```TOML
requires = ["tox>=4.19"]
env_list = ["3.14t", "3.14", "3.13", "3.12", "type"]

[env_run_base]
description = "Run test under {base_python}"
commands = [["pytest"]]

[env.type]
description = "run type check on code base"
deps = ["mypy==1.18.2", "types-cachetools>=5.5.0.20240820", "types-chardet>=5.0.4.6"]
commands = [["mypy", "src{/}tox"], ["mypy", "tests"]]

```

--------------------------------

### Tox Quickstart Verbosity Options

Source: https://tox.wiki/en/latest/cli_interface

Controls the level of detail in tox output. Use '-v' to increase verbosity for more detailed logs or '-q' to decrease it for more concise output.

```bash
# -v, --verbose: Increase verbosity (default: 2).
# -q, --quiet: Decrease verbosity (default: 0).
```

--------------------------------

### pyproject.toml Native TOML Configuration Example

Source: https://tox.wiki/en/latest/config

Example of native TOML configuration for tox within a pyproject.toml file. It utilizes the [tool.tox] table for core settings and [tool.tox.env.{env_name}], [tool.tox.env_run_base], and [tool.tox.env_pkg_base] for environment-specific configurations.

```TOML
[tool.tox]
requires = ["tox>=4.19"]
env_list = ["3.14t", "3.14", "3.13", "3.12", "type"]

[tool.tox.env_run_base]
description = "Run test under {base_python}"
commands = [["pytest"]]

[tool.tox.env.type]
description = "run type check on code base"
deps = ["mypy==1.18.2", "types-cachetools>=5.5.0.20240820", "types-chardet>=5.0.4.6"]
commands = [["mypy", "src{/}tox"], ["mypy", "tests"]]

```

--------------------------------

### pyproject.toml INI Configuration Example

Source: https://tox.wiki/en/latest/config

Example of configuring tox within a pyproject.toml file using the legacy_tox_ini key under the [tool.tox] table. This allows INI-formatted configuration to be embedded within the TOML file.

```TOML
[tool.tox]
legacy_tox_ini = """
    [tox]
    requires =
        tox >= 4.0
    env_list =
        py310
        py39
        type

    [testenv]
    deps = pytest
    commands = pytest tests

    [testenv:type]
    deps = mypy
    commands = mypy src
"""

```

--------------------------------

### Specify Dependencies and Constraints in TOML

Source: https://tox.wiki/en/latest/_sources/config.rst

Example of how to specify dependencies and constraint files within a TOML configuration file for tox. It demonstrates the use of '-r' for requirements files and '-c' for constraint files.

```toml
[tool.tox.env_run_base]
deps = [
  "pytest>=8",
  "-r requirements.txt",
  "-c constraints.txt",
]
```

--------------------------------

### Configure Editable Install Mode in Tox (PEP 660)

Source: https://tox.wiki/en/latest/_sources/upgrading.rst

Illustrates how to configure tox for editable installs using PEP 660. It shows the default behavior, fallback mechanisms ('editable-legacy'), and the standardized method using 'package = editable' with appropriate dependency versions.

```ini
[testenv:dev]
package = editable-legacy
```

```ini
[testenv:dev]
deps = setuptools>=64
package = editable
```

--------------------------------

### Tox Quickstart Command-Line Options

Source: https://tox.wiki/en/latest/cli_interface

Lists and describes the available command-line flags for configuring and controlling tox builds. These options cover aspects like configuration files, working directories, output formatting, debugging, and environment recreation.

```bash
# General Options:
# -h, --help: Show this help message and exit.
# --colored COLORED: Whether to enrich output with colors (default: yes, unless TERM=dumb or NO_COLOR is defined).
# --stderr-color STDERR_COLOR: Color for stderr output (default: RED).
# --exit-and-dump-after SECONDS: Dump tox threads after N seconds and exit (default: 0, disabled).
# -c FILE, --conf FILE: Configuration file/folder for tox (default: None).
# --workdir DIR: Tox working directory (default: {cwd}/.tox).
# --root DIR: Project root directory (default: None).
# --runner DEFAULT_RUNNER: Tox run engine (default: virtualenv).
# --result-json PATH: Write a JSON file with command results (default: None).
# --hashseed SEED: Set PYTHONHASHSEED before running commands (default: random).
# --discover PATH: Python executables for discovery (default: []).
# --list-dependencies: List dependencies installed during environment setup.
# --no-list-dependencies: Never list dependencies installed during environment setup.
# --version: Show program and plugin versions and exit.
# --no-provision REQ_JSON: Do not perform provision, fail if path provided (default: False).
# --no-recreate-provision: Do not recreate provision tox environment.
# -r, --recreate: Recreate tox environments.
# -x OVERRIDE, --override OVERRIDE: Configuration override(s) (default: []).
```

--------------------------------

### Tox Configuration for TOML Environments

Source: https://tox.wiki/en/latest/_sources/user_guide.rst

Example TOML configuration for a tox environment named 'unit'. It specifies dependencies ('pytest') and the commands to run ('pytest'). This configuration is used to define specific test environments within a tox setup.

```toml
[env.unit]
deps = [ "pytest" ]
commands = [[ "pytest" ]]
```

--------------------------------

### Tox Configuration for Centralized Packaging Settings

Source: https://tox.wiki/en/latest/upgrading

Shows how to define common packaging settings in a '[pkgenv]' section and inherit them in specific packaging environments like '.pkg-cpython311' and 'magic', allowing for overrides.

```TOML
[pkgenv]
pass_env =
    PKG_CONFIG
    PKG_CONFIG_PATH
    PKG_CONFIG_SYSROOT_DIR

[testenv:.pkg-cpython311]
pass_env =
    {[pkgenv]pass_env}
    IS_311 = yes

[testenv:magic]
package = sdist
pass_env = {[pkgenv]pass_env}  # sdist install builds wheel -> need packaging settings

```

--------------------------------

### Build documentation with Sphinx using tox

Source: https://tox.wiki/en/latest/faq

This tox configuration defines a 'docs' test environment to build project documentation using Sphinx. It specifies Python 3.10, installs Sphinx, and executes the sphinx-build command. A Python command is included to print the link to the generated documentation.

```TOML
[testenv:docs]
description = build documentation
basepython = python3.10
deps =
  sphinx>=4
commands =
  sphinx-build -d "{envtmpdir}{/}doctree" docs "{toxworkdir}{/}docs_out" --color -b html
  python -c 'print(r"documentation available under file://{toxworkdir}{/}docs_out{/}index.html")'

```

--------------------------------

### Build and deploy documentation with mkdocs using tox

Source: https://tox.wiki/en/latest/faq

This tox configuration sets up two environments for documentation management with mkdocs. 'docs' runs a development server for working on documentation, while 'docs-deploy' builds fresh documentation and deploys it. It utilizes config substitution to avoid duplication.

```TOML
[testenv:docs]
description = Run a development server for working on documentation
deps =
  mkdocs>=1.3
  mkdocs-material
commands =
  mkdocs build --clean
  python -c 'print("###### Starting local server. Press Control+C to stop server ")'
  mkdocs serve -a localhost:8080

[testenv:docs-deploy]
description = built fresh docs and deploy them
deps = {[testenv:docs]deps}
commands = mkdocs gh-deploy --clean

```

--------------------------------

### Forcing tox Environment Recreation

Source: https://tox.wiki/en/latest/_sources/user_guide.rst

Command to force a fresh start for tox environments by passing the '-r' flag to the 'run' command. This is useful for troubleshooting when stale environments cause errors.

```bash
tox run -e py310 -r
```

--------------------------------

### Build Documentation Locally with Tox

Source: https://tox.wiki/en/latest/_sources/development.rst

Builds the project's documentation locally using Sphinx. This command utilizes the 'docs' environment within Tox.

```shell
tox -e docs
```

--------------------------------

### INI Configuration for tox Auto-provisioning

Source: https://tox.wiki/en/latest/_sources/user_guide.rst

Example of specifying 'requires' dependencies for tox auto-provisioning using INI format. This ensures that the specified tox and plugin versions are met, creating a meta environment if necessary.

```ini
[tox]
requires =
    tox>=4
    tox-uv>=1
```

--------------------------------

### Build and Deploy Documentation with MkDocs using Tox

Source: https://tox.wiki/en/latest/_sources/faq.rst

Manages documentation build and deployment using MkDocs. It defines separate tox environments for development server and deployment, leveraging config substitution for dependency reuse.

```ini
[testenv:docs]
description = Run a development server for working on documentation
deps =
  mkdocs>=1.3
  mkdocs-material
commands =
  mkdocs build --clean
  python -c 'print("###### Starting local server. Press Control+C to stop server ######")'
  mkdocs serve -a localhost:8080

[testenv:docs-deploy]
description = built fresh docs and deploy them
deps = {[testenv:docs]deps}
commands = mkdocs gh-deploy --clean
```

--------------------------------

### Tox Configuration for Packaging Environment Settings

Source: https://tox.wiki/en/latest/upgrading

Defines specific settings for packaging environments, including '.pkg' for source distributions and '.pkg-cpython311' for wheels, demonstrating how to pass environment variables.

```TOML
[testenv:.pkg]
pass_env =
    PKG_CONFIG
    PKG_CONFIG_PATH
    PKG_CONFIG_SYSROOT_DIR

[testenv:.pkg-cpython311]
pass_env =
    PKG_CONFIG
    PKG_CONFIG_PATH
    PKG_CONFIG_SYSROOT_DIR

```

--------------------------------

### Tox Configuration using setup.cfg

Source: https://tox.wiki/en/latest/_sources/config.rst

Similar to tox.ini, this uses the [tox:tox] section for core settings and [testenv:{env_name}] for environment specifics. The [testenv] section provides base configuration for run environments.

```ini
[tox:tox]
requires =
    tox >= 4.0
env_list =
    3.14t
    3.14
    3.13
    3.12
    type

[testenv]
deps = pytest
commands = pytest tests

[testenv:type]
deps = mypy
commands = mypy src
```

--------------------------------

### Tox Configuration for INI Environments

Source: https://tox.wiki/en/latest/_sources/user_guide.rst

Example INI configuration for a tox test environment named 'unit'. It lists the dependency 'pytest' and the command 'pytest' to be executed within this environment. This format is an alternative to TOML for defining tox environments.

```ini
[testenv:unit]
deps = pytest
commands = pytest
```

--------------------------------

### Bash Example of Tox Parallel Mode Summary

Source: https://tox.wiki/en/latest/_sources/user_guide.rst

Shows the summary output after Tox completes its parallel execution. This includes the status of each environment (succeeded/failed) and a final congratulatory message, offering a concise overview of the run's outcome.

```bash
✔ OK py39 in 9.533 seconds
✔ OK py310 in 9.96 seconds
✔ OK coverage in 2.0 seconds
___________________________ summary ______________________________________________________
  py310: commands succeeded
  py39: commands succeeded
  coverage: commands succeeded
  congratulations :)

```

--------------------------------

### Tox List Options for Configuration and Behavior

Source: https://tox.wiki/en/latest/cli_interface

This section details command-line options for configuring tox's behavior, including output formatting, file paths, environment management, and debugging. Options like --colored, --conf, and --recreate control how tox operates.

```bash
# Show help message
tox -h

# Enable colored output
tox --colored yes

# Set stderr color to RED
tox --stderr-color RED

# Dump threads after 10 seconds and exit
tox --exit-and-dump-after 10

# Use a specific configuration file
tox -c tox.ini

# Set a custom working directory
tox --workdir .tox-custom

# Set the project root directory
tox --root /path/to/project

# Use 'virtualenv' as the runner
tox --runner virtualenv

# Write detailed results to a JSON file
tox --result-json results.json

# Set a specific hash seed for Python
tox --hashseed 12345

# Specify Python executables for discovery
tox --discover /usr/bin/python3.9 /usr/bin/python3.10

# List dependencies
tox --list-dependencies

# Do not list dependencies
tox --no-list-dependencies

# Do not show descriptions
tox --no-desc

# Show version information
tox --version

# Do not perform provision and write metadata to a JSON file
tox --no-provision provision.json

# Do not recreate provision tox environment
tox --no-recreate-provision

# Recreate tox environments
tox -r

# Override a configuration setting
tox -x "testenv:pypy3.ignore_errors=True"
```

--------------------------------

### Tox Configuration: TOML Format

Source: https://tox.wiki/en/latest/user_guide

This TOML configuration defines two test environments, 'format' and '3.13', for a project. It specifies dependencies, installation behavior, and commands to be executed within each environment. The 'env_list' setting indicates which environments should run by default.

```toml
env_list =  ["format", "3.13"]

[env.format]
description = "install black in a virtual environment and invoke it on the current folder"
deps = ["black==22.3.0"]
skip_install = true
commands = [[ "black", "." ]]

[env."3.13"]
description = "install pytest in a virtual environment and invoke it on the tests folder"
deps = [
    "pytest>=7",
    "pytest-sugar",
]
commands = [[ "pytest", "tests", { replace = "posargs", extend = true} ]]

```

--------------------------------

### Bash Example of Tox Parallel Mode Progress

Source: https://tox.wiki/en/latest/_sources/user_guide.rst

Illustrates the output format and progress indicator when Tox is running environments in parallel mode. It shows the spinner, the number of active environments, and their names, providing visual feedback during long-running processes.

```bash
⠹ [2] py310 | py39

```

--------------------------------

### Build Documentation with Tox

Source: https://tox.wiki/en/latest/development

Command to build the project's documentation locally using Tox. The documentation is generated using Sphinx and written in reStructuredText. The output is placed in the `.tox/docs_out` folder.

```shell
tox -e docs

```

--------------------------------

### Tox Test Environment Configuration (INI)

Source: https://tox.wiki/en/latest/user_guide

INI configuration for tox test environments. It shows the setup for the default test environment ('testenv') and specific environments ('testenv:lint', 'testenv:type'), detailing their descriptions, dependencies, and commands to be executed.

```INI
[testenv]
description = run unit tests
deps =
    pytest>=8
    pytest-sugar
commands =
    pytest {posargs:tests}

[testenv:lint]
description = run linters
skip_install = true
deps =
    black
commands = black {posargs:.}

[testenv:type]
description = run type checks
deps =
    mypy
commands =
    mypy {posargs:src tests}
```

--------------------------------

### Conditional Settings in Tox INI Files

Source: https://tox.wiki/en/latest/config

Details how to apply configuration settings conditionally within `tox.ini`. Lines starting with environment names (comma-separated) followed by a colon will only be applied if the current tox environment matches one of the specified names. This allows for environment-specific dependency installations or configurations.

```INI
[testenv]
deps =
   pip
   format: black
   py310,py39: pytest

```

--------------------------------

### Tox Configuration for Universal Wheel Builds

Source: https://tox.wiki/en/latest/upgrading

Configures Tox to use a single packaging environment ('.pkg') for building universal wheels, simplifying the build process by avoiding multiple build environments.

```TOML
[testenv]
package = wheel
wheel_build_env = .pkg

```

--------------------------------

### Install Tox with pip

Source: https://tox.wiki/en/latest/_sources/installation.rst

Installs the tox tool using pip, Python's package installer. This method can install tox as a user package. Caution is advised when using system-managed Python installations, as pip might cause inconsistencies. Requires pip version 9.0.0 or higher for wheel installations.

```bash
python -m pip install --user tox
python -m tox --help
```

--------------------------------

### Tox Configuration Example with Environment Name Conflict

Source: https://tox.wiki/en/latest/_sources/upgrading.rst

Demonstrates a Tox configuration where an environment name ('list') conflicts with a Tox 4 subcommand. This highlights parsing ambiguity and the recommended solution of using the 'run' subcommand to explicitly target environments.

```ini
[tox]
env_list = py39,py310

[testenv]
commands =
    python -c 'print("hi")'

[testenv:list]
commands =
    python -c 'print("a, b, c")'
```

--------------------------------

### Install Tox with pipx

Source: https://tox.wiki/en/latest/_sources/installation.rst

Installs the tox tool using pipx, a tool for installing and running Python applications in isolated environments. This method ensures that tox does not interfere with other system packages. It requires pipx to be installed first.

```bash
python -m pip install pipx-in-pipx --user
pipx install tox
tox --help
```