### Running Installations and Commands

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Demonstrates how to run installation commands and other external processes within a Nox session. It shows installing a build, configuring it, and performing an install operation.

```python
session.run(
    "cmake",
    "--build", build_dir,
    "--config", "Debug",
    "--target", "install",
    external=True,
)
session.install(".")
```

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

### Nox Session Examples

Source: https://github.com/wntrblm/nox/blob/main/README.md

Defines two example Nox sessions: 'tests' for running pytest and 'lint' for running flake8. These sessions demonstrate how to install dependencies and run commands within a Nox environment.

```python
import nox


@nox.session
def tests(session: nox.Session) -> None:
    session.install("pytest")
    session.run("pytest")

@nox.session
def lint(session: nox.Session) -> None:
    session.install("flake8")
    session.run("flake8", "--import-order-style", "google")
```

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

### Nox Parametrization Example

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

An introductory example of using `nox.parametrize` to run a session with different configurations, such as testing against different versions of a library like Django.

```python
@nox.session
@nox.parametrize("django", ["4.0", "4.1"])
def tests_with_django(session, django):
    session.install(f"django=={django}")
    session.install("pytest")
    session.run("pytest")

```

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

### Install Nox

Source: https://github.com/wntrblm/nox/blob/main/docs/index.rst

Instructions for installing Nox using pipx or pip.

```bash
pipx install nox
```

```bash
python3 -m pip install nox
```

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

### Install from Requirements File in Nox Session

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Installs dependencies from a `requirements.txt` file within a Nox session. This mirrors the `pip install -r requirements.txt` command.

```python
@nox.session
def tests(session):
    # same as pip install -r requirements.txt
    session.install("-r", "requirements.txt")
    ...
```

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

### Install Project in Nox Session

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Installs the current project (typically a Python package) within a Nox session. This is equivalent to `pip install .` and is useful for testing package installations.

```python
@nox.session
def tests(session):
    # same as pip install .
    session.install(".")
    ...
```

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

### Install Nox with Pip (User Site)

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Installs Nox to the user site directory using pip and Python 3. This avoids modifying the global Python installation.

```console
python3 -m pip install --user nox
```

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

### Install Nox with Pip

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Installs Nox globally using pip and Python 3. This is the standard method for installing Python packages.

```console
python3 -m pip install nox
```

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

### Nox Session Listing Example

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Shows the output of `nox --list` when a session is configured to run against multiple Python versions, demonstrating how Nox expands the session.

```console
Sessions defined in noxfile.py:

* test-3.10
* test-3.11
* test-3.12
```

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

### Basic Nox Session

Source: https://github.com/wntrblm/nox/blob/main/docs/config.rst

Defines a simple Nox session that installs Nox itself and runs a command. This is a foundational example for creating Nox tasks.

```python
@nox.session(python=False)
def tests(session):
    session.run("pip", "install", "nox")
```

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

### Basic Noxfile Session

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Defines a simple Nox session named 'lint' that installs the 'flake8' package and runs it against 'example.py'.

```python
import nox

@nox.session
def lint(session):
    session.install("flake8")
    session.run("flake8", "example.py")
```

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

### Installing Packages with Conda

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Demonstrates how to install packages into a Conda environment using `session.conda_install`, specifying channels for consistency.

```python
session.conda_install("pytest", channels=["conda-forge"])
```

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

### Install Nox with Pipx

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Installs Nox as a standalone application using pipx. Pipx is recommended for installing and running Python CLI applications.

```console
pipx install nox
```

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

### Running Nox Sessions

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Examples of how to run specific Nox sessions using the `--session` flag, including running all sessions matching a pattern or a single specific session.

```console
nox --sessions test
nox --sessions test-3.12
```

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

### Installing and Upgrading Nox

Source: https://github.com/wntrblm/nox/blob/main/docs/CONTRIBUTING.md

This command installs or upgrades Nox to the latest pre-release version. It's recommended to start with a known-good installation before running tests.

```shell
pip install --pre --upgrade nox
```

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

### Parametrized Session Example

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Demonstrates how to use the `nox.parametrize` decorator to run a session with different arguments. This allows for testing against multiple versions of a dependency, such as Django.

```python
@nox.parametrize("django", ["1.9", "2.0"])
def test(session, django):
    session.install(f"django=={django}")
    session.run("pytest")
```

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

### Installing and Upgrading Nox

Source: https://github.com/wntrblm/nox/blob/main/CONTRIBUTING.md

This command installs or upgrades Nox to the latest pre-release version. It's recommended to start with a known-good installation before running tests.

```shell
pip install --pre --upgrade nox
```

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

### Instant Dev Environment with Nox

Source: https://github.com/wntrblm/nox/blob/main/docs/cookbook.rst

Sets up a Python development environment by creating a virtual environment and installing project dependencies. It ensures the project is installed correctly with its development dependencies.

```python
import nox


# It's a good idea to keep your dev session out of the default list
# so it's not run twice accidentally
@nox.session(default=False)
def dev(session: nox.Session) -> None:
    """
    Set up a python development environment for the project at ".venv".
    """

    session.install("virtualenv")

    session.run("virtualenv", ".venv", silent=True)

    # Use the venv's interpreter to install the project along with
    # all it's dev dependencies, this ensures it's installed in the right way
    session.run(".venv/bin/pip", "install", "-e", ".[dev]", external=True)
```

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

### Nox Installation

Source: https://github.com/wntrblm/nox/blob/main/README.md

Provides commands for installing Nox using pipx and pip. It also mentions the option to install to the user site to avoid conflicts with the global Python installation.

```shell
pipx install nox
```

```shell
python3 -m pip install nox
```

```shell
python3 -m pip install --user nox
```

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

### Install Multiple Packages in Nox Session

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Installs multiple Python packages, including version-specific dependencies, within a Nox session. This is equivalent to `pip install pytest protobuf>3.0.0`.

```python
@nox.session
def tests(session):
    # same as pip install pytest protobuf>3.0.0
    session.install("pytest", "protobuf>3.0.0")
    ...
```

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

### Basic Noxfile Configuration

Source: https://github.com/wntrblm/nox/blob/main/docs/index.rst

A simple noxfile.py demonstrating how to define sessions for testing and linting. It installs dependencies and runs commands within isolated virtual environments.

```python
import nox

@nox.session
def tests(session):
    session.install('pytest')
    session.run('pytest')

@nox.session
def lint(session):
    session.install('flake8')
    session.run('flake8', '--import-order-style', 'google')
```

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

### Running Coverage Session

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

A Nox session that installs and runs the coverage tool. This is typically triggered by a notification from another session.

```python
@nox.session
def coverage(session):
    session.install("coverage")
    session.run("coverage")
```

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

### Setup Nox in GitHub Actions

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Configures Nox within a GitHub Actions workflow. It specifies the Nox action version and optionally the Python versions to use.

```yaml
# setup nox with all active CPython and PyPY versions provided by
# the GitHub Actions environment i.e. 
# python-versions: "3.8, 3.9, 3.10, 3.11, 3.12, pypy-3.8, pypy-3.9, pypy-3.10"
# Any Nox tag will work here
- uses: wntrblm/nox@2024.04.15

# setup nox only for a given list of python versions
# Limitations:
# - Version specifiers shall be supported by actions/setup-python
# - There can only be one "major.minor" per interpreter i.e. "3.12.0, 3.12.1" is invalid
# Any Nox tag will work here
- uses: wntrblm/nox@2024.04.15
  with:
      python-versions: "2.7, 3.5, 3.11, pypy-3.9"
```

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

### Running Tests with Pytest

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Shows how to install and run the pytest test runner within a Nox session. It covers basic execution and passing additional arguments like verbosity and specific test paths.

```python
@nox.session
def tests(session):
    session.install("pytest")
    session.run("pytest")
```

```python
@nox.session
def tests(session):
    session.install("pytest")
    session.run("pytest", "-v", "tests")
```

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

### Installing Pip Packages into Conda Environment

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Shows how to install pip packages into a Conda environment, emphasizing the use of `--no-deps` to prevent conflicts with Conda-installed packages.

```python
session.install("contexter", "--no-deps")
session.install("-e", ".", "--no-deps")
```

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

### Install Nox with Tox Conversion Support

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.rst

Installs or upgrades the Nox package with the necessary extra for converting tox.ini files.

```console
pip install --upgrade nox[tox_to_nox]
```

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

### Install Only Mode

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.rst

Instructs Nox to only execute installation commands (`session.install`) and skip all `session.run` commands. Useful for preparing environments or offline testing.

```python
@nox.session
def tests(session):
    session.install("pytest")
    session.install(".")
    session.run("pytest")
```

```console
nox --install-only
```

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

### Run External Install Commands in Nox Session

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Executes external commands, such as build tools like 'cmake', within a Nox session to manage non-Python dependencies required during package installation. The `external=True` argument indicates that the command is not a Python package to be installed.

```python
@nox.session
def tests(session):
    ...
    session.run_install(
        "cmake", "-DCMAKE_BUILD_TYPE=Debug",
        "-S", libfoo_src_dir,
        "-B", build_dir,
        external=True,
    )
```

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

### Nox Session Expansion for Multiple Python Versions

Source: https://github.com/wntrblm/nox/blob/main/docs/config.rst

Example of a Noxfile that defines a session to run against multiple Python versions, and the resulting sessions listed by 'nox --list'.

```python
@nox.session(python=['2.7', '3.6', '3.7', '3.8', '3.9'])
def tests(session):
    pass
```

```console
Will produce these sessions:

    * tests-2.7
    * tests-3.6
    * tests-3.7
    * tests-3.8
    * tests-3.9
```

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

### Specify Nox Version Requirements

Source: https://github.com/wntrblm/nox/blob/main/docs/config.rst

This code snippet demonstrates how to specify minimum Nox version requirements in your Noxfile. If the installed Nox version does not meet the requirement, Nox will exit with an informative error message.

```python
import nox

nox.needs_version = ">=2019.5.30"

@nox.session(name="test")  # name argument was added in 2019.5.30
def pytest(session):
    session.run("pytest")
```

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

### Nox Session with Multiple Python Versions and Reuse

Source: https://github.com/wntrblm/nox/blob/main/docs/config.rst

Configures a Nox session to run with multiple Python versions ('2.7', '3.6') and enables virtual environment reuse across sessions. This optimizes build times by avoiding repeated environment setup.

```python
@nox.session(
    python=['2.7', '3.6'],
    reuse_venv=True)
def tests(session):
    pass
```

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

### Listing and Selecting Nox Sessions

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Explains how to use the '--list' and '--sessions' arguments to manage which Nox sessions are executed. It shows how to view available sessions and explicitly choose which ones to run.

```console
nox --list
```

```console
nox --list --sessions lint
```

```console
nox --sessions lint
```

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

### Nox Session Listing with Parametrization

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Shows the output of `nox --list` when a session is parametrized, illustrating how Nox expands a single session definition into multiple executable sessions based on the provided arguments.

```console
Sessions defined in noxfile.py:

* test(django='1.9')
* test(django='2.0')
```

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

### Using Mamba or Micromamba as Backend

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Explains that 'mamba' and 'micromamba' can also be used as values for `venv_backend` to leverage these faster package managers.

```python
@nox.session(venv_backend="mamba")
def test_mamba(session):
    ...

@nox.session(venv_backend="micromamba")
def test_micromamba(session):
    ...

```

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

### Loading Dependencies from PEP 723 Scripts

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Illustrates how to use nox.project.load_toml to load dependencies from a Python script that follows PEP 723. This is useful for preparing environments or running scripts directly.

```python
# /// script
# requires-python = ">=3.11"
# dependencies = [
#   "requests<3",
#   "rich",
# ]
# ///

import requests
from rich.pretty import pprint

resp = requests.get("https://peps.python.org/api/peps.json")
data = resp.json()
pprint([(k, v["title"]) for k, v in data.items()][:10])
```

```python
@nox.session
def peps(session):
    requirements = nox.project.load_toml("peps.py")["dependencies"]
    session.install(*requirements)
    session.run("peps.py")
```

```python
@nox.session
def peps(session):
    session.install_and_run_script("peps.py")
```

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

### Executing Sessions by Tag

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Demonstrates how to run Nox sessions based on their assigned tags. Running `nox -t style` executes all sessions tagged with 'style', while `nox -t fix` runs sessions tagged with 'fix'. Multiple tags can be combined.

```console
nox -t style
* black
* isort
* flake8

nox -t fix
* black
* isort
- flake8

nox -t style fix
* black
* isort
* flake8
```

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

### Nox Project Badge - Markdown

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Provides the Markdown code for embedding the official Nox project badge in a README file, linking to the Nox GitHub repository.

```markdown
[![Nox](https://img.shields.io/badge/%F0%9F%A6%8A-Nox-D85E00.svg)](https://github.com/wntrblm/nox)
```

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

### Parametrizing Nox Sessions with `nox.parametrize`

Source: https://github.com/wntrblm/nox/blob/main/docs/config.rst

Shows how to use the `nox.parametrize` decorator to create multiple sessions based on different parameter values, such as testing against different Django versions.

```python
@nox.session
@nox.parametrize('django', ['1.9', '2.0'])
def tests(session, django):
    session.install(f'django=={django}')
    session.run('pytest')
```

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

### Session with Description and Listing

Source: https://github.com/wntrblm/nox/blob/main/docs/config.rst

Shows how to add a docstring to a session for a description, which is displayed when listing sessions. The 'nox --list' command output is also shown.

```python
import nox

@nox.session
def tests(session):
    """Run the test suite."""
    session.run('pytest')
```

```console
$ nox --list
Available sessions:
* tests -> Run the test suite.
```

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

### Parametrized Session Requirements

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Illustrates how to use parametrized session names within the `requires` keyword. This allows for flexible dependency management across different Python versions.

```python
@nox.session(python=["3.10", "3.13"])
def tests(session):
    session.install("pytest")
    session.run("pytest")

@nox.session(python=["3.10", "3.13"], requires=["tests-{python}"])
def coverage(session):
    session.install("coverage")
    session.run("coverage")
```

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

### Error on External Run

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.rst

Causes Nox to fail a session if it attempts to run an external program not installed in the session's virtual environment, unless `external=True` is explicitly passed to `session.run`. Overrides the Noxfile setting `nox.options.error_on_external_run`.

```console
nox --error-on-external-run
```

```console
nox --no-error-on-external-run
```

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

### Queueing Test Coverage Session

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Demonstrates how to queue a test coverage session to run after another session. This is a common pattern for organizing test runs.

```python
session.notify("coverage")
```

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

### Parametrize Session with Dependencies and Python Versions

Source: https://github.com/wntrblm/nox/blob/main/docs/config.rst

Shows how to parametrize a session with both Python versions and dependency versions, excluding specific incompatible combinations.

```python
@nox.session
@nox.parametrize(
    "python,dependency",
    [
        (python, dependency)
        for python in ("3.10", "3.11", "3.12")
        for dependency in ("1.0", "2.0")
        if (python, dependency) != ("3.10", "2.0")
    ],
)
def tests(session, dependency):
    ...
```

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

### Nox Usage Commands

Source: https://github.com/wntrblm/nox/blob/main/README.md

Illustrates common Nox command-line interface commands for managing and running test sessions. This includes listing all sessions, running all sessions, and running a specific session.

```shell
nox -l/--list
```

```shell
nox
```

```shell
nox -s/--session test
```

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

### Enabling Script Mode for Generalized Runners

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Shows the necessary additions to a Noxfile to support running with generalized Python runners like `pipx run noxfile.py`. This involves a special comment block for dependencies and a standard `if __name__ == "__main__":` guard.

```python
# /// script
# dependencies = ["nox"]
# ///

if __name__ == "__main__":
    nox.main()
```

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

### Passing Positional Arguments with Notify

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Shows how to pass positional arguments to a notified session. The `prepare_thing` session runs a command and then notifies `consume_thing` with a specific path.

```python
@nox.session
def prepare_thing(session):
    thing_path = "./path/to/thing"
    session.run("prepare", "thing", thing_path)
    session.notify("consume_thing", posargs=[thing_path])

@nox.session
def consume_thing(session):
    # The 'consume' command has the arguments
    # sent to it from the 'prepare_thing' session
    session.run("consume", "thing", *session.posargs)
```

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

### Requiring Sessions

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Demonstrates how to specify that one Nox session must run before another using the `requires` keyword. This ensures a stable execution order.

```python
@nox.session
def tests(session):
    session.install("pytest")
    session.run("pytest")

@nox.session(requires=["tests"])
def coverage(session):
    session.install("coverage")
    session.run("coverage")
```

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

### Defining Default Sessions

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Shows how to configure Nox to run a specific set of sessions by default when the 'nox' command is invoked without any arguments. This can be done by setting the nox.options.sessions attribute.

```python
import nox

nox.options.sessions = ["lint", "test"]
```

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

### Session Tagging for Task Organization

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Illustrates how to assign tags to Nox sessions for better organization and selective execution. Multiple sessions can share the same tags, allowing for group execution.

```python
@nox.session(tags=["style", "fix"])
def black(session):
    session.install("black")
    session.run("black", "my_package")

@nox.session(tags=["style", "fix"])
def isort(session):
    session.install("isort")
    session.run("isort", "my_package")

@nox.session(tags=["style"])
def flake8(session):
    session.install("flake8")
    session.run("flake8", "my_package")
```

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

### Testing with Conda Backend

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Configures a Nox session to use Conda as its virtual environment backend, suitable for projects requiring Conda environments.

```python
@nox.session(venv_backend="conda")
def test(session):
    ...

```

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

### Stacked `nox.parametrize` Decorators

Source: https://github.com/wntrblm/nox/blob/main/docs/config.rst

Explains how to stack multiple `nox.parametrize` decorators to create sessions that are combinations of different parameter sets, like Django versions and database backends.

```python
@nox.session
@nox.parametrize('django', ['1.9', '2.0'])
@nox.parametrize('database', ['postgres', 'mysql'])
def tests(session, django, database):
    ...
```

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

### Running All Sessions

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.rst

Illustrates how to execute all defined sessions in the Noxfile.

```console
nox
```

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

### Automated Release Process with Nox

Source: https://github.com/wntrblm/nox/blob/main/docs/cookbook.rst

Automates the release process of an open-source project by creating and pushing new tags using bump2version. It prompts for confirmation before proceeding with the version bump and tag push.

```python
import argparse
import nox

@nox.session
def release(session: nox.Session) -> None:
    """
    Kicks off an automated release process by creating and pushing a new tag.

    Invokes bump2version with the posarg setting the version.

    Usage:
    $ nox -s release -- [major|minor|patch]
    """
    parser = argparse.ArgumentParser(description="Release a semver version.")
    parser.add_argument(
        "version",
        type=str,
        nargs=1,
        help="The type of semver release to make.",
        choices={"major", "minor", "patch"},
    )
    args: argparse.Namespace = parser.parse_args(args=session.posargs)
    version: str = args.version.pop()

    # If we get here, we should be good to go
    # Let's do a final check for safety
    confirm = input(
        f"You are about to bump the {version!r} version. Are you sure? [y/n]: "
    )

    # Abort on anything other than 'y'
    if confirm.lower().strip() != "y":
        session.error(f"You said no when prompted to bump the {version!r} version.")


    session.install("bump2version")

    session.log(f"Bumping the {version!r} version")
    session.run("bump2version", version)

    session.log("Pushing the new tag")
    session.run("git", "push", external=True)
    session.run("git", "push", "--tags", external=True)
```

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

### Running Nox Sessions

Source: https://github.com/wntrblm/nox/blob/main/docs/index.rst

Command to execute all defined sessions in the noxfile.py.

```bash
nox
```

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

### Listing Available Sessions

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.rst

Shows commands to list all available Nox sessions, including options for JSON output.

```console
nox -l
nox --list
nox --list-sessions
```

```console
nox --list --json
```

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

### Running Nox with Positional Arguments

Source: https://github.com/wntrblm/nox/blob/main/docs/config.rst

Demonstrates how to invoke Nox sessions with positional arguments from the command line. Arguments after '--' are passed to the session.

```console
nox -- test_c.py
```

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

### Nox Sessions with uv Sync

Source: https://github.com/wntrblm/nox/blob/main/docs/cookbook.rst

Defines Nox sessions that utilize the `nox-uv` package to synchronize dependencies using `uv sync`. It showcases how to specify dependency groups and run tests, type checks, and linting.

```python
#!/usr/bin/env -S uv run --script --quiet

# /// script
# dependencies = ["nox", "nox-uv"]
# ///

import nox
import nox_uv

nox.options.default_venv_backend = "uv"

@nox_uv.session(
    python=["3.10", "3.11", "3.12", "3.13"],
    uv_groups=["test"],
)
def test(s: nox.Session) -> None:
    """`uv sync` main dependencies and the `test` dependency group."""
    s.run("python", "-m", "pytest")

@nox_uv.session(uv_groups=["type_check"])
def type_check(s: nox.Session) -> None:
    """`uv sync` main dependencies and the `type_check` dependency group."""
    s.run("mypy", "src")

@nox_uv.session(uv_only_groups=["lint"])
def type_check(s: nox.Session) -> None:
    """`uv sync` only the `lint` dependency group."""
    s.run("ruff", "check", ".")
    s.run("ruff", "format", "--check", ".")


if __name__ == "__main__":
    nox.main()

```

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

### Nox Project Badge - reStructuredText

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Provides the reStructuredText code for embedding the official Nox project badge in documentation, linking to the Nox GitHub repository.

```rst
.. image:: https://img.shields.io/badge/%F0%9F%A6%8A-Nox-D85E00.svg
   :alt: Nox
   :target: https://github.com/wntrblm/nox
```

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

### Deprecated session.install() Usage

Source: https://github.com/wntrblm/nox/blob/main/docs/config.rst

Notes that using session.install() without a virtualenv is deprecated and suggests using session.run() with pip instead for modifying the global environment.

```python
# Use session.run() and pip instead of session.install() without a virtualenv
# Example:
# session.run('pip', 'install', 'some-package')
```

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

### Listing All Available Nox Sessions

Source: https://github.com/wntrblm/nox/blob/main/docs/CONTRIBUTING.md

This command lists all the available sessions that can be run within Nox. It's useful for understanding the project's testing and development workflows.

```shell
nox --list-sessions
```

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

### Listing All Available Nox Sessions

Source: https://github.com/wntrblm/nox/blob/main/CONTRIBUTING.md

This command lists all the available sessions that can be run within Nox. It's useful for understanding the project's testing and development workflows.

```shell
nox --list-sessions
```

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

### Define a Basic Nox Session

Source: https://github.com/wntrblm/nox/blob/main/docs/config.rst

Demonstrates how to define a Nox session using the @nox.session decorator. This session runs the 'pytest' command.

```python
import nox

@nox.session
def tests(session):
    session.run('pytest')
```

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

### Nox Session with Chained Virtualenv Backends

Source: https://github.com/wntrblm/nox/blob/main/docs/config.rst

Demonstrates chaining multiple virtual environment backends (e.g., 'uv|virtualenv'). Nox will attempt to use the backends in the order specified, falling back to the next if the previous is unavailable.

```python
# Example of chaining: uv|virtualenv or micromamba|mamba|conda
```

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

### Nox Invocation

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.rst

Demonstrates the basic ways to invoke Nox, either directly or through the Python interpreter.

```console
nox
```

```console
python3 -m nox
```

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

### List Sessions

Source: https://github.com/wntrblm/nox/blob/main/docs/config.rst

Displays the available sessions that Nox can run, often used to see parametrized session combinations.

```console
* tests(psql, old)
* tests(mysql, old)
* tests(psql, new)
* tests(mysql, new)
```

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

### Running Parametrized Sessions

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.rst

Explains how to run specific parametrized versions of a Nox session.

```python
@nox.parametrize('django', ['1.9', '2.0'])
def tests(session, django):
    ...

```

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

### Running Commands with Environment Variables

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Demonstrates how to pass environment variables to commands executed within a Nox session. This is useful for configuring the behavior of the executed program, such as setting a debug mode.

```python
@nox.session
def tests(session):
    session.install("pytest")
    session.run(
        "pytest",
        env={
            "FLASK_DEBUG": "1"
        }
    )
```

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

### Configure Session with Custom Python Executables

Source: https://github.com/wntrblm/nox/blob/main/docs/config.rst

Illustrates configuring a session to use specific Python executables, including non-standard ones like 'pypy-6.0'.

```python
@nox.session(python=['2.7', '3.6', 'pypy-6.0'])
def tests(session):
    pass
```

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

### Testing Against Multiple Python Versions

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Configures a Nox session to run against several Python interpreter versions. Nox automatically expands this into multiple distinct sessions.

```python
@nox.session(python=["3.10", "3.11", "3.12"])
def test(session):
    ...

```

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

### Virtual Environment Backend Fallback

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.rst

Shows how to configure a fallback mechanism for virtual environment backends.

```console
nox -db "uv|virtualenv"
nox -db "micromamba|mamba|conda"
```

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

### Parametrize Session Python

Source: https://github.com/wntrblm/nox/blob/main/docs/config.rst

Demonstrates two equivalent ways to parametrize a Nox session with different Python interpreters using the @nox.session decorator.

```python
@nox.session
@nox.parametrize("python", ["3.10", "3.11", "3.12"])
def tests(session):
    ...
```

```python
@nox.session(python=["3.10", "3.11", "3.12"])
def tests(session):
    ...
```

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

### Combined Custom IDs for Stacked Parametrizations

Source: https://github.com/wntrblm/nox/blob/main/docs/config.rst

Illustrates how custom IDs work with stacked `nox.parametrize` decorators, showing how IDs are combined to create unique identifiers for each generated session.

```python
@nox.session
@nox.parametrize(
    'django',
    ['1.9', '2.0'],
    ids=["old", "new"])
@nox.parametrize(
    'database',
    ['postgres', 'mysql'],
    ids=["psql", "mysql"])
def tests(session, django, database):
    ...
```

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

### Listing Parametrized Sessions with Custom IDs

Source: https://github.com/wntrblm/nox/blob/main/docs/config.rst

Shows the output of `nox --list` when custom IDs are used for parametrized sessions, highlighting how the custom IDs replace the default generated names.

```console
* tests(old)
* tests(new)
```

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

### Specifying Parametrized Session Arguments

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.rst

Demonstrates how to target specific parametrized arguments for a session.

```console
nox --session "tests(django='1.9')"
nox --session "tests(django='2.0')"
```

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

### Running Specific Parametrized Sessions

Source: https://github.com/wntrblm/nox/blob/main/docs/config.rst

Explains how to run a specific parametrized session using its custom ID via the `--sessions` flag.

```console
nox --sessions "tests(old)"
```

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

### Accessing Selected Virtual Environment Backend

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.rst

Demonstrates how to check the currently selected virtual environment backend within a Nox session.

```python
session.venv_backend
```

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

### Custom IDs for Parametrized Nox Sessions

Source: https://github.com/wntrblm/nox/blob/main/docs/config.rst

Demonstrates how to assign custom, human-readable IDs to parametrized sessions using the `ids` argument in `nox.parametrize`, making them easier to reference and manage.

```python
@nox.session
@nox.parametrize('django',
    ['1.9', '2.0'],
    ids=['old', 'new'])
def tests(session, django):
    ...
```

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

### Nox Session with uv Lockfile

Source: https://github.com/wntrblm/nox/blob/main/docs/cookbook.rst

Runs tests using a Nox session configured with the 'uv' backend for dependency management. It synchronizes dependencies using 'uv sync' before executing tests with pytest.

```python
@nox.session(venv_backend="uv")
def tests(session: nox.Session) -> None:
    """
    Run the unit and regular tests.
    """
    session.run_install(
        "uv",
        "sync",
        "--extra=test",
        "--no-default-extras",
        f"--python={session.virtualenv.location}",
        env={"UV_PROJECT_ENVIRONMENT": session.virtualenv.location},
    )
    session.run("pytest", *session.posargs)
```

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

### Noxfile Configuration Options

Source: https://github.com/wntrblm/nox/blob/main/docs/config.rst

This section outlines the various options that can be set within a Noxfile to control Nox's behavior. These options often mirror command-line arguments and affect session selection, environment management, and error handling.

```APIDOC
nox.options.envdir
  Equivalent to: --envdir
  Description: Specifies the directory where virtual environments are stored.

nox.options.sessions
  Equivalent to: -s or --sessions
  Description: Defines the sessions to run. If empty and no sessions are provided on the command line, available sessions are listed.

nox.options.pythons
  Equivalent to: -p or --pythons
  Description: Specifies the Python interpreters to use for sessions.

nox.options.keywords
  Equivalent to: -k or --keywords
  Description: Filters sessions based on keywords.

nox.options.tags
  Equivalent to: -t or --tags
  Description: Filters sessions based on tags.

nox.options.default_venv_backend
  Equivalent to: -db or --default-venv-backend
  Description: Sets the default virtual environment backend.

nox.options.force_venv_backend
  Equivalent to: -fb or --force-venv-backend
  Description: Forces the use of a specific virtual environment backend.

nox.options.reuse_venv
  Equivalent to: --reuse-venv
  Description: Enables reuse of existing virtual environments. Preferred over reuse_existing_virtualenvs.

nox.options.reuse_existing_virtualenvs
  Equivalent to: --reuse-existing-virtualenvs
  Description: Enables reuse of existing virtual environments. Can be forced off with --no-reuse-existing-virtualenvs. Alias for nox.options.reuse_venv=yes|no.

nox.options.stop_on_first_error
  Equivalent to: --stop-on-first-error
  Description: Stops execution on the first encountered error. Can be forced off with --no-stop-on-first-error.

nox.options.error_on_missing_interpreters
  Equivalent to: --error-on-missing-interpreters
  Description: Raises an error if required Python interpreters are missing. Can be forced off with --no-error-on-missing-interpreters.

nox.options.error_on_external_run
  Equivalent to: --error-on-external-run
  Description: Raises an error when external commands are run. Can be forced off with --no-error-on-external-run.

nox.options.report
  Equivalent to: --report
  Description: Specifies a file to which a report of the session execution should be written.
```

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

### Nox Session with Custom Virtualenv Parameters

Source: https://github.com/wntrblm/nox/blob/main/docs/config.rst

Allows passing custom parameters to the virtual environment creation process, such as '--no-download' to prevent downloading packages during venv creation.

```python
@nox.session(venv_params=['--no-download'])
def tests(session):
    pass
```

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

### Changing Default Virtual Environment Backend

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.rst

Illustrates how to set the default virtual environment backend for Nox sessions using CLI options or environment variables.

```console
nox -db conda
nox --default-venv-backend conda
```

```console
NOX_DEFAULT_VENV_BACKEND=conda
```

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

### Filtering Sessions by Keywords and Tags

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.rst

Shows how to use pytest-style keywords and tags to filter which sessions are executed.

```console
nox -k "not lint"
nox -k "tests and not lint"
nox -k "not my_tag"
nox -t "my_tag" "my_other_tag"
```

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

### Accessing Selected Virtualenv Backend

Source: https://github.com/wntrblm/nox/blob/main/docs/config.rst

Shows how to retrieve the name of the virtual environment backend that Nox selected for the current session using `session.venv_backend`.

```python
session.venv_backend
```

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

### Notifying Other Sessions

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Illustrates how to use the session.notify function to trigger other Nox sessions from within a running session. This allows for chaining or coordinating different tasks.

```python
@nox.session
def tests(session):
    session.install("pytest")
    session.run("pytest")
    session.notify("lint")
```

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

### Configure Session for Multiple Python Versions

Source: https://github.com/wntrblm/nox/blob/main/docs/config.rst

Shows how to configure a session to run against multiple Python interpreters. Nox creates a separate virtualenv and runs the session for each specified interpreter.

```python
@nox.session(python=['2.7', '3.6'])
def tests(session):
    pass
```

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

### Filtering Sessions by Python Version

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.rst

Demonstrates how to select sessions to run with specific Python versions using CLI arguments or environment variables.

```console
nox --python 3.12
nox -p 3.11 3.12
```

```console
NOXPYTHON=3.12 nox
NOXPYTHON=3.11,3.12 nox
```

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

### Passing Positional Arguments to Nox Sessions

Source: https://github.com/wntrblm/nox/blob/main/docs/config.rst

Illustrates how to pass positional arguments (`session.posargs`) into a Nox session, enabling dynamic behavior like specifying test files to run.

```python
@nox.session
def test(session):
    session.install('pytest')

    if session.posargs:
        test_files = session.posargs
    else:
        test_files = ['test_a.py', 'test_b.py']

    session.run('pytest', *test_files)
```

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

### Assign Tags to Parametrized Sessions (Method 1)

Source: https://github.com/wntrblm/nox/blob/main/docs/config.rst

Assigns tags to parametrized sessions using separate @nox.parametrize decorators for each parameter, providing tags as lists.

```python
@nox.session
@nox.parametrize('dependency',
    ['1.0', '2.0'],
    tags=[['old'], ['new']])
@nox.parametrize('database'
    ['postgres', 'mysql'],
    tags=[['psql'], ['mysql']])
def tests(session, dependency, database):
    ...
```

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

### Specifying Sessions by Name

Source: https://github.com/wntrblm/nox/blob/main/docs/usage.rst

Provides methods to run specific Nox sessions using CLI options or environment variables.

```console
nox --session tests
nox -s lint tests
nox -e lint
```

```console
NOXSESSION=tests nox
NOXSESSION=lint nox
NOXSESSION=lint,tests nox
```

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

### Testing Against a Single Python Version

Source: https://github.com/wntrblm/nox/blob/main/docs/tutorial.rst

Configures a Nox session to run exclusively against a specific Python interpreter version.

```python
@nox.session(python="3.12")
def test(session):
    ...

```

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

### Custom Session Name

Source: https://github.com/wntrblm/nox/blob/main/docs/config.rst

Illustrates how to customize a session's name using the 'name' argument in the @nox.session decorator. It shows how to run the session with the custom name.

```python
import nox

@nox.session(name="custom-name")
def a_very_long_function_name(session):
    print("Hello!")
```

```console
$ nox --list
Available sessions:
* custom-name
```

```console
$ nox --session "custom-name"
Hello!
```