# Configuration & API

## Noxfile

Nox looks for configuration in a file named noxfile.py by default. You can specify a different file using the `--noxfile` argument when running `nox`.

## Defining sessions

`session`(func=None, python=None, py=None, reuse_venv=None, name=None)

  Designate the decorated function as a session.

Nox sessions are configured via standard Python functions that are decorated with `@nox.session`. For example:

    import nox

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

You can also configure sessions to run against multiple Python versions as described in Configuring a session’s virtualenv and parametrize sessions as described in parametrized sessions.

## Session description

You can add a description to your session using a docstring. The first line will be shown when listing the sessions. For example:

    import nox

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

The `nox --list` command will show:

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

## Session name

By default Nox uses the decorated function’s name as the session name. This works wonderfully for the vast majority of projects, however, if you need to you can customize the session’s name by using the `name` argument to `@nox.session`. For example:

    import nox

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

The `nox --list` command will show:

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

And you can tell `nox` to run the session using the custom name:

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

## Configuring a session’s virtualenv

By default, Nox will create a new virtualenv for each session using the same interpreter that Nox uses. If you installed Nox using Python 3.6, Nox will use Python 3.6 by default for all of your sessions.

You can tell Nox to use a different Python interpreter/version by specifying the `python` argument (or its alias `py`) to `@nox.session`:

    @nox.session(python='2.7')
    def tests(session):
        pass

You can also tell Nox to run your session against multiple Python interpreters. Nox will create a separate virtualenv and run the session for each interpreter you specify. For example, this session will run twice - once for Python 2.7 and once for Python 3.6:

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

When you provide a version number, Nox automatically prepends python to determine the name of the executable. However, Nox also accepts the full executable name. If you want to test using pypy, for example:

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

When collecting your sessions, Nox will create a separate session for each interpreter. You can see these sesions when running `nox --list`. For example this Noxfile:

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

Will produce these sessions:

    * tests-2.7
    * tests-3.5
    * tests-3.6
    * tests-3.7

Note that this expansion happens before parameterization occurs, so you can still parametrize sessions with multiple interpreters.

If you want to disable virtualenv creation altogether, you can set `python` to `False`:

    @nox.session(python=False)
    def tests(session):
        pass

Finally you can also specify that the virtualenv should always be reused instead of recreated every time:

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

## Passing arguments into sessions

Often it’s useful to pass arguments into your test session. Here’s a quick example that demonstrates how to use arguments to run tests against a particular file:

    @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)

Now you if you run:

    nox

Then nox will run:

    pytest test_a.py test_b.py

But if you run:

    nox -- test_c.py

Then nox will run:

    pytest test_c.py

## Parametrizing sessions

Session arguments can be parametrized with the `nox.parametrize()` decorator. Here’s a typical example of parametrizing the Django version to install:

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

When you run `nox`, it will create a two distinct sessions:

    $ nox
    nox > Running session tests(django='1.9')
    nox > pip install django==1.9
    ...
    nox > Running session tests(djano='2.0')
    nox > pip install django==2.0

`nox.parametrize()` has an interface and usage intentionally similar to pytest’s parametrize.

`parametrize`(arg_names, arg_values_list, ids=None)

  Parametrize a session.

  Add new invocations to the underlying session function using the list of `arg_values_list` for the given `arg_names`. Parametrization is performed during session discovery and each invocation appears as a separate session to nox.

  Parameters:

  - arg_names (Sequence[str]) – A list of argument names.
  - arg_values_list (Sequence[Union[Any, Tuple]]) – The list of argument values determines how often a session is invoked with different argument values. If only one argument names was specified then this is a simple list of values, for example `[1, 2, 3]`. If N argument names were specified, this must be a list of N-tuples, where each tuple-element specifies a value for its respective argument name, for example `[(1, 'a'), (2, 'b')]`.
  - ids (Sequence[str]) – Optional sequence of test IDs to use for the parametrized arguments.

You can also stack the decorator to produce sessions that are a combination of the arguments, for example:

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

If you run `nox --list`, you’ll see that this generates the following set of sessions:

    * tests(django='1.9', database='postgres')
    * tests(django='2.0', database='mysql')
    * tests(django='1.9', database='postgres')
    * tests(django='2.0', database='mysql')

If you only want to run one of the parametrized sessions, see Specifying parametrized sessions.

## Giving friendly names to parametrized sessions

The automatically generated names for parametrized sessions, such as `tests(django='1.9', database='postgres')`, can be long and unwieldy to work with even with using keyword filtering. You can give parametrized sessions custom IDs to help in this scenario. These two examples are equivalent:

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

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

When running `nox --list` you’ll see their new IDs:

    * tests(old)
    * tests(new)

And you can run them with `nox --sessions "tests(old)"` and so on.

This works with stacked parameterizations as well. The IDs are combined during the combination. For example:

    @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):
        ...

Produces these sessions when running `nox --list`:

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

## The session object

Nox will call your session functions with a an instance of the `Session` class.

## Modifying Nox’s behavior in the Noxfile

Nox has various command line arguments that can be used to modify its behavior. Some of these can also be specified in the Noxfile using `nox.options`. For example, if you wanted to store Nox’s virtualenvs in a different directory without needing to pass it into `nox` every time:

    import nox

    nox.options.envdir = ".cache"

    @nox.session
    def tests(session):
        ...

Or, if you wanted to provide a set of sessions that are run by default:

    import nox

    nox.options.sessions = ["lint", "tests-3.6"]

    ...

The following options can be specified in the Noxfile:

- `nox.options.envdir` is equivalent to specifying –envdir.
- `nox.options.sessions` is equivalent to specifying -s or –sessions.
- `nox.options.keywords` is equivalent to specifying -k or –keywords.
- `nox.options.reuse_existing_virtualenvs` is equivalent to specifying –reuse-existing-virtualenvs. You can force this off by specifying `--no-reuse-existing-virtualenvs` during invocation.
- `nox.options.stop_on_first_error` is equivalent to specifying –stop-on-first-error. You can force this off by specifying `--no-stop-on-first-error` during invocation.
- `nox.options.error_on_missing_interpreters` is equivalent to specifying –error-on-missing-interpreters. You can force this off by specifying `--no-error-on-missing-interpreters` during invocation.
- `nox.options.error_on_external_run` is equivalent to specifying –error-on-external-run. You can force this off by specifying `--no-error-on-external-run` during invocation.
- `nox.options.report` is equivalent to specifying –report.

When invoking `nox`, any options specified on the command line take precedence over the options specified in the Noxfile. If either `--sessions` or `--keywords` is specified on the command line, both options specified in the Noxfile will be ignored.