diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 01e8ae03a2..2a06f14359 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,3 +1,7 @@ +--- +default_language_version: + # force all unspecified python hooks to run python3 + python: python3 repos: - repo: https://github.com/psf/black rev: 19.10b0 @@ -6,13 +10,13 @@ repos: args: [--safe] language_version: python3.8 - repo: https://github.com/asottile/blacken-docs - rev: v1.3.0 + rev: v1.6.0 hooks: - id: blacken-docs - additional_dependencies: [black==19.3b0] + additional_dependencies: [black==19.10b0] language_version: python3.8 - repo: https://github.com/asottile/seed-isort-config - rev: v1.9.3 + rev: v2.1.1 hooks: - id: seed-isort-config args: [--application-directories, "src:."] @@ -21,21 +25,21 @@ repos: hooks: - id: isort - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v2.4.0 + rev: v2.5.0 hooks: - id: trailing-whitespace - id: end-of-file-fixer - id: check-yaml - id: debug-statements - id: flake8 - additional_dependencies: ["flake8-bugbear == 19.8.0"] + additional_dependencies: ["flake8-bugbear == 20.1.4"] language_version: python3.8 - repo: https://github.com/asottile/pyupgrade - rev: v1.25.1 + rev: v2.3.0 hooks: - id: pyupgrade - repo: https://github.com/pre-commit/pygrep-hooks - rev: v1.4.2 + rev: v1.5.1 hooks: - id: rst-backticks - repo: local diff --git a/docs/changelog/1423.bugfix.rst b/docs/changelog/1423.bugfix.rst index 155591e5ac..5cc043e048 100644 --- a/docs/changelog/1423.bugfix.rst +++ b/docs/changelog/1423.bugfix.rst @@ -1 +1 @@ -Respect attempts to change `PATH` via `setenv`. - by :user:`aklajnert` +Respect attempts to change ``PATH`` via ``setenv`` - by :user:`aklajnert`. diff --git a/docs/changelog/1573.doc.rst b/docs/changelog/1573.doc.rst new file mode 100644 index 0000000000..2dddf509d0 --- /dev/null +++ b/docs/changelog/1573.doc.rst @@ -0,0 +1 @@ +Improve documentation about config by adding tox environment description at start - by :user:`stephenfin`. diff --git a/docs/config.rst b/docs/config.rst index c159a50868..9ea4ecdff6 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -189,23 +189,50 @@ by using the ``tox:jenkins`` section: commands = ... # override settings for the jenkins context -tox environment settings ------------------------- +tox environments +---------------- -Test environments are defined by a: +Test environments are defined under the ``testenv`` section and individual +``testenv:NAME`` sections, where ``NAME`` is the name of a specific +environment. .. code-block:: ini + [testenv] + commands = ... + [testenv:NAME] commands = ... -section. The ``NAME`` will be the name of the virtual environment. -Defaults for each setting in this section are looked up in the:: +Settings defined in the top-level ``testenv`` section are automatically +inherited by individual environments unless overridden. Test environment names +can consist of alphanumeric characters and dashes; for example: +``py38-django30``. The name will be split on dashes into multiple factors, +meaning ``py38-django30`` will be split into two factors: ``py38`` and +``django30``. *tox* defines a number of default factors, which correspond to +various versions and implementations of Python and provide default values for +:conf:`basepython`: + +- ``pyNM``: configures ``basepython = pythonN.M`` +- ``pyN``: configures ``basepython = pythonN`` +- ``py``: configures ``basepython = python`` +- ``pypyN``: configures ``basepython = pypyN`` +- ``pypy``: configures ``basepython = pypy`` +- ``jythonN``: configures ``basepython = jythonN`` +- ``jython``: configures ``basepython = jython`` + +It is also possible to define what's know as *generative names*, where an +individual section maps to multiple environments; for example: +``py{37,38}-django{30,31}``, which would generate four environments, each +consisting of two factors a piece: ``py37-django30`` (``py37``, ``django30``), +``py37-django31`` (``py37``, ``django31``), ``py38-django30`` (``py38``, +``django30``), and ``py38-django31`` (``py38``, ``django31``). Combined, these +features provide the ability to write very concise ``tox.ini`` files and is +discussed further `below `__. - [testenv] - commands = ... -``testenv`` default section. +tox environment settings +------------------------ Complete list of settings that you can put into ``testenv*`` sections: @@ -755,6 +782,8 @@ You can put default values in one section and reference them in others to avoid {[base]deps} +.. _generating-environments: + Generating environments, conditional settings --------------------------------------------- @@ -793,7 +822,7 @@ Let's go through this step by step. .. _generative-envlist: Generative envlist -+++++++++++++++++++++++ +++++++++++++++++++ :: @@ -856,9 +885,10 @@ but still want to take advantage of factor-conditional settings. Factors and factor-conditional settings ++++++++++++++++++++++++++++++++++++++++ -Parts of an environment name delimited by hyphens are called factors and can -be used to set values conditionally. In list settings such as ``deps`` or -``commands`` you can freely intermix optional lines with unconditional ones: +As discussed previously, parts of an environment name delimited by hyphens are +called factors and can be used to set values conditionally. In list settings +such as ``deps`` or ``commands`` you can freely intermix optional lines with +unconditional ones: .. code-block:: ini @@ -908,6 +938,7 @@ special case for a combination of factors. Here is how you do it: py{27,36}-sqlite: mock # mocking sqlite in python 2.x & 3.6 !py34-sqlite: mock # mocking sqlite, except in python 3.4 sqlite-!py34: mock # (same as the line above) + !py34,!py36: enum34 # use if neither py34 nor py36 are in the env name Take a look at the first ``deps`` line. It shows how you can special case something for a combination of factors, by just hyphenating the combining diff --git a/tox.ini b/tox.ini index 4e4f52b15d..207d1fe330 100644 --- a/tox.ini +++ b/tox.ini @@ -72,7 +72,7 @@ passenv = PROGRAMDATA PRE_COMMIT_HOME extras = lint -deps = pre-commit >= 1.14.4, < 2 +deps = pre-commit>=2, <3 skip_install = True commands = pre-commit run --all-files --show-diff-on-failure {posargs} python -c 'import pathlib; print("hint: run \{\} install to add checks as pre-commit hook".format(pathlib.Path(r"{envdir}") / "bin" / "pre-commit"))'