From 41179d5ff4ffbfc5bdba8a3f860a866b0509cf63 Mon Sep 17 00:00:00 2001 From: Ran Benita Date: Sat, 29 Nov 2025 01:07:47 +0200 Subject: [PATCH 1/2] doc: use builtin `confval` directive Since version 7.4, Sphinx had a standard `confval` directive: https://www.sphinx-doc.org/en/master/usage/domains/standard.html#directive-confval So we can drop our custom one. --- changelog/14012.packaging.rst | 1 + doc/en/conf.py | 7 ------- doc/en/requirements.txt | 2 +- 3 files changed, 2 insertions(+), 8 deletions(-) create mode 100644 changelog/14012.packaging.rst diff --git a/changelog/14012.packaging.rst b/changelog/14012.packaging.rst new file mode 100644 index 00000000000..da0b3e974e9 --- /dev/null +++ b/changelog/14012.packaging.rst @@ -0,0 +1 @@ +Sphinx>=7.4 is now required to build the documentation. diff --git a/doc/en/conf.py b/doc/en/conf.py index 81156493131..bb6b22c6e6d 100644 --- a/doc/en/conf.py +++ b/doc/en/conf.py @@ -279,13 +279,6 @@ def setup(app: sphinx.application.Sphinx) -> None: indextemplate="pair: %s; fixture", ) - app.add_object_type( - "confval", - "confval", - objname="configuration value", - indextemplate="pair: %s; configuration value", - ) - app.add_object_type( "globalvar", "globalvar", diff --git a/doc/en/requirements.txt b/doc/en/requirements.txt index fcaaee695c9..eb6d74ae6ac 100644 --- a/doc/en/requirements.txt +++ b/doc/en/requirements.txt @@ -2,7 +2,7 @@ pluggy>=1.5.0 pygments-pytest>=2.5.0 sphinx-removed-in>=0.2.0 -sphinx>=7 +sphinx>=7.4 sphinxcontrib-trio sphinxcontrib-svg2pdfconverter furo From b47e4e1ae985be804259bf0cf2addc60ace13a87 Mon Sep 17 00:00:00 2001 From: Ran Benita Date: Sat, 29 Nov 2025 01:28:32 +0200 Subject: [PATCH 2/2] doc: make use of `confval`'s `type' and `default` options Seems good to have it in a structured form. --- changelog/14012.doc.rst | 1 + doc/en/reference/reference.rst | 196 ++++++++++++++++++++------------- 2 files changed, 122 insertions(+), 75 deletions(-) create mode 100644 changelog/14012.doc.rst diff --git a/changelog/14012.doc.rst b/changelog/14012.doc.rst new file mode 100644 index 00000000000..95942e4a86f --- /dev/null +++ b/changelog/14012.doc.rst @@ -0,0 +1 @@ +The :ref:`ini options ref` section of the API Reference now specified the type and default value of every configuration option. diff --git a/doc/en/reference/reference.rst b/doc/en/reference/reference.rst index 57415a18cc1..8049b1ffbf9 100644 --- a/doc/en/reference/reference.rst +++ b/doc/en/reference/reference.rst @@ -1329,6 +1329,7 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: addopts + :type: ``list[str]`` Add the specified ``OPTS`` to the set of command line arguments as if they had been specified by the user. Example: if you have this configuration file content: @@ -1345,19 +1346,20 @@ passed multiple times. The expected format is ``name=value``. For example:: pytest --maxfail=2 -rf test_hello.py - Default is to add no options. - .. confval:: cache_dir + :type: ``str`` + :default: ``".pytest_cache"`` - Sets the directory where the cache plugin's content is stored. Default directory is - ``.pytest_cache`` which is created in :ref:`rootdir `. Directory may be - relative or absolute path. If setting relative path, then directory is created + Sets the directory where the cache plugin's content is stored. + Directory may be relative or absolute path. If setting relative path, then directory is created relative to :ref:`rootdir `. Additionally, a path may contain environment variables, that will be expanded. For more information about cache plugin please refer to :ref:`cache_provider`. .. confval:: collect_imported_tests + :type: ``bool`` + :default: ``true`` .. versionadded:: 8.4 @@ -1378,8 +1380,6 @@ passed multiple times. The expected format is ``name=value``. For example:: [pytest] collect_imported_tests = false - Default: ``true`` - pytest traditionally collects classes/functions in the test module namespace even if they are imported from another file. For example: @@ -1401,9 +1401,11 @@ passed multiple times. The expected format is ``name=value``. For example:: Set ``collected_imported_tests`` to ``false`` in the configuration file prevents that. .. confval:: consider_namespace_packages + :type: ``bool`` + :default: ``false`` Controls if pytest should attempt to identify `namespace packages `__ - when collecting Python modules. Default is ``False``. + when collecting Python modules. Set to ``True`` if the package you are testing is part of a namespace package. Namespace packages are also supported as :option:`--pyargs` target. @@ -1414,6 +1416,8 @@ passed multiple times. The expected format is ``name=value``. For example:: .. versionadded:: 8.1 .. confval:: console_output_style + :type: ``str`` + :default: ``"progress"`` Sets the console output style while running tests: @@ -1423,7 +1427,7 @@ passed multiple times. The expected format is ``name=value``. For example:: * ``count``: like progress, but shows progress as the number of tests completed instead of a percent. * ``times``: show tests duration. - The default is ``progress``, but you can fallback to ``classic`` if you prefer or + You can fallback to ``classic`` if you prefer or the new mode is causing unexpected problems: .. tab:: toml @@ -1442,6 +1446,8 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: disable_test_id_escaping_and_forfeit_all_rights_to_community_support + :type: ``bool`` + :default: ``false`` .. versionadded:: 4.4 @@ -1469,31 +1475,30 @@ passed multiple times. The expected format is ``name=value``. For example:: even bugs depending on the OS used and plugins currently installed, so use it at your own risk. - Default: ``False``. - See :ref:`parametrizemark`. .. confval:: doctest_encoding - - + :type: ``str`` + :default: ``"utf-8"`` Default encoding to use to decode text files with docstrings. :ref:`See how pytest handles doctests `. .. confval:: doctest_optionflags + :type: ``list[str]`` One or more doctest flag names from the standard ``doctest`` module. :ref:`See how pytest handles doctests `. .. confval:: empty_parameter_set_mark - - + :type: ``str`` + :default: ``"skip"`` Allows to pick the action for empty parametersets in parameterization - * ``skip`` skips tests with an empty parameterset (default) + * ``skip`` skips tests with an empty parameterset * ``xfail`` marks tests with an empty parameterset as xfail(run=False) * ``fail_at_collect`` raises an exception if parametrize collects an empty parameter set @@ -1518,6 +1523,8 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: enable_assertion_pass_hook + :type: ``bool`` + :default: ``false`` Enables the :hook:`pytest_assertion_pass` hook. Make sure to delete any previously generated ``.pyc`` cache files. @@ -1538,14 +1545,14 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: faulthandler_exit_on_timeout + :type: ``bool`` + :default: ``false`` Exit the pytest process after the per-test timeout is reached by passing `exit=True` to the :func:`faulthandler.dump_traceback_later` function. This is particularly useful to avoid wasting CI resources for test suites that are prone to putting the main Python interpreter into a deadlock state. - This option is set to 'false' by default. - .. tab:: toml .. code-block:: toml @@ -1565,6 +1572,8 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: faulthandler_timeout + :type: ``float`` + :default: ``0`` (disabled) Dumps the tracebacks of all threads if a test takes longer than ``X`` seconds to run (including fixture setup and teardown). Implemented using the :func:`faulthandler.dump_traceback_later` function, @@ -1589,6 +1598,7 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: filterwarnings + :type: ``list[str]`` Sets a list of filters and actions that should be taken for matched warnings. By default all warnings emitted during the test session @@ -1621,12 +1631,14 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: junit_duration_report + :type: ``str`` + :default: ``"total"`` .. versionadded:: 4.1 Configures how durations are recorded into the JUnit XML report: - * ``total`` (the default): duration times reported include setup, call, and teardown times. + * ``total``: duration times reported include setup, call, and teardown times. * ``call``: duration times reported include only call times, excluding setup and teardown. .. tab:: toml @@ -1645,6 +1657,8 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: junit_family + :type: ``str`` + :default: ``"xunit2"`` .. versionadded:: 4.2 .. versionchanged:: 6.1 @@ -1653,7 +1667,7 @@ passed multiple times. The expected format is ``name=value``. For example:: Configures the format of the generated JUnit XML file. The possible options are: * ``xunit1`` (or ``legacy``): produces old style output, compatible with the xunit 1.0 format. - * ``xunit2``: produces `xunit 2.0 style output `__, which should be more compatible with latest Jenkins versions. **This is the default**. + * ``xunit2``: produces `xunit 2.0 style output `__, which should be more compatible with latest Jenkins versions. .. tab:: toml @@ -1671,11 +1685,13 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: junit_log_passing_tests + :type: ``bool`` + :default: ``true`` .. versionadded:: 4.6 If ``junit_logging != "no"``, configures if the captured output should be written - to the JUnit XML file for **passing** tests. Default is ``True``. + to the JUnit XML file for **passing** tests. .. tab:: toml @@ -1693,6 +1709,8 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: junit_logging + :type: ``str`` + :default: ``"no"`` .. versionadded:: 3.5 .. versionchanged:: 5.4 @@ -1705,7 +1723,7 @@ passed multiple times. The expected format is ``name=value``. For example:: * ``system-err``: write captured ``stderr`` contents. * ``out-err``: write both captured ``stdout`` and ``stderr`` contents. * ``all``: write captured ``logging``, ``stdout`` and ``stderr`` contents. - * ``no`` (the default): no captured output is written. + * ``no``: no captured output is written. .. tab:: toml @@ -1723,6 +1741,8 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: junit_suite_name + :type: ``str`` + :default: ``"pytest"`` To set the name of the root test suite xml item, you can configure the ``junit_suite_name`` option in your config file: @@ -1741,6 +1761,8 @@ passed multiple times. The expected format is ``name=value``. For example:: junit_suite_name = my_suite .. confval:: log_auto_indent + :type: ``str`` + :default: ``"false"`` Allow selective auto-indentation of multiline log messages. @@ -1749,16 +1771,16 @@ passed multiple times. The expected format is ``name=value``. For example:: auto-indentation behavior for all logging. ``[value]`` can be: - * True or "On" - Dynamically auto-indent multiline log messages - * False or "Off" or 0 - Do not auto-indent multiline log messages (the default behavior) - * [positive integer] - auto-indent multiline log messages by [value] spaces + * "True" or "On" - Dynamically auto-indent multiline log messages + * "False" or "Off" or "0" - Do not auto-indent multiline log messages + * "[positive integer]" - auto-indent multiline log messages by [value] spaces .. tab:: toml .. code-block:: toml [pytest] - log_auto_indent = false + log_auto_indent = "false" .. tab:: ini @@ -1773,9 +1795,10 @@ passed multiple times. The expected format is ``name=value``. For example:: on the command line or in the config. .. confval:: log_cli + :type: ``bool`` + :default: ``false`` Enable log display during test run (also known as :ref:`"live logging" `). - The default is ``False``. .. tab:: toml @@ -1792,8 +1815,8 @@ passed multiple times. The expected format is ``name=value``. For example:: log_cli = true .. confval:: log_cli_date_format - - + :type: ``str`` + :default: Fallback to ``log_date_format`` Sets a :py:func:`time.strftime`-compatible string that will be used when formatting dates for live logging. @@ -1814,8 +1837,8 @@ passed multiple times. The expected format is ``name=value``. For example:: For more information, see :ref:`live_logs`. .. confval:: log_cli_format - - + :type: ``str`` + :default: Fallback to ``log_format`` Sets a :py:mod:`logging`-compatible string used to format live logging messages. @@ -1837,8 +1860,8 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: log_cli_level - - + :type: ``str`` + :default: Fallback to ``log_level`` Sets the minimum log message level that should be captured for live logging. The integer value or the names of the levels can be used. @@ -1861,8 +1884,8 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: log_date_format - - + :type: ``str`` + :default: ``"%H:%M:%S"`` Sets a :py:func:`time.strftime`-compatible string that will be used when formatting dates for logging capture. @@ -1884,8 +1907,7 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: log_file - - + :type: ``str`` Sets a file name relative to the current working directory where log messages should be written to, in addition to the other logging facilities that are active. @@ -1908,8 +1930,8 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: log_file_date_format - - + :type: ``str`` + :default: Fallback to ``log_date_format`` Sets a :py:func:`time.strftime`-compatible string that will be used when formatting dates for the logging file. @@ -1930,8 +1952,8 @@ passed multiple times. The expected format is ``name=value``. For example:: For more information, see :ref:`logging`. .. confval:: log_file_format - - + :type: ``str`` + :default: Fallback to ``log_format`` Sets a :py:mod:`logging`-compatible string used to format logging messages redirected to the logging file. @@ -1952,11 +1974,11 @@ passed multiple times. The expected format is ``name=value``. For example:: For more information, see :ref:`logging`. .. confval:: log_file_level + :type: ``str`` + :default: Fallback to ``log_level`` - - - Sets the minimum log message level that should be captured for the logging file. The integer value or - the names of the levels can be used. + Sets the minimum log message level that should be captured for the logging file. + The integer value (as a string) or the name of the level can be used. .. tab:: toml @@ -1976,9 +1998,11 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: log_file_mode + :type: ``str`` + :default: ``"w"`` Sets the mode that the logging file is opened with. - The options are ``"w"`` to recreate the file (the default) or ``"a"`` to append to the file. + The options are ``"w"`` to recreate the file or ``"a"`` to append to the file. .. tab:: toml @@ -1998,8 +2022,8 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: log_format - - + :type: ``str`` + :default: ``%(levelname)-8s %(name)s:%(filename)s:%(lineno)d %(message)s`` Sets a :py:mod:`logging`-compatible string used to format captured logging messages. @@ -2021,11 +2045,12 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: log_level + :type: ``str`` - - - Sets the minimum log message level that should be captured for logging capture. The integer value or - the names of the levels can be used. + Sets the minimum log message level that should be captured for logging + capture. Not set by default, so it depends on the root/parent log handler's + effective level, where it is ``"WARNING"`` by default. The integer value (as + a string) or the names of the levels can be used. .. tab:: toml @@ -2045,6 +2070,7 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: markers + :type: ``list[str]`` When the :confval:`strict_markers` configuration option is set, only known markers - defined in code by core pytest or some plugin - are allowed. @@ -2073,6 +2099,7 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: minversion + :type: ``str`` Specifies a minimal pytest version required for running tests. @@ -2092,6 +2119,8 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: norecursedirs + :type: ``list[str]`` + :default: ``["*.egg", ".*", "_darcs", "build", "CVS", "dist", "node_modules", "venv", "{arch}"]`` Set the directory basename patterns to avoid when recursing for test discovery. The individual (fnmatch-style) patterns are @@ -2103,8 +2132,6 @@ passed multiple times. The expected format is ``name=value``. For example:: [seq] matches any character in seq [!seq] matches any char not in seq - Default patterns are ``'*.egg'``, ``'.*'``, ``'_darcs'``, ``'build'``, - ``'CVS'``, ``'dist'``, ``'node_modules'``, ``'venv'``, ``'{arch}'``. Setting a ``norecursedirs`` replaces the default. Here is an example of how to avoid certain directories: @@ -2136,6 +2163,8 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: python_classes + :type: ``list[str]`` + :default: ``["Test"]`` One or more name prefixes or glob-style patterns determining which classes are considered for test collection. Search for multiple glob patterns by @@ -2163,6 +2192,8 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: python_files + :type: ``list[str]`` + :default: ``["test_*.py", "*_test.py"]`` One or more Glob-style file patterns determining which python files are considered as test modules. Search for multiple glob patterns by @@ -2192,11 +2223,11 @@ passed multiple times. The expected format is ``name=value``. For example:: check_*.py example_*.py - By default, files matching ``test_*.py`` and ``*_test.py`` will be considered - test modules. .. confval:: python_functions + :type: ``list[str]`` + :default: ``["test"]`` One or more name prefixes or glob-patterns determining which test functions and methods are considered tests. Search for multiple glob patterns by @@ -2226,6 +2257,7 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: pythonpath + :type: ``list[str]`` Sets list of directories that should be added to the python search path. Directories will be added to the head of :data:`sys.path`. @@ -2250,6 +2282,7 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: required_plugins + :type: ``list[str]`` A space separated list of plugins that must be present for pytest to run. Plugins can be listed with or without version specifiers directly following @@ -2272,6 +2305,8 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: strict + :type: ``bool`` + :default: ``false`` If set to ``true``, enable "strict mode", which enables the following options: @@ -2307,6 +2342,8 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: strict_config + :type: ``bool`` + :default: ``false`` If set to ``true``, any warnings encountered while parsing the ``pytest`` section of the configuration file will raise errors. @@ -2328,6 +2365,8 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: strict_markers + :type: ``bool`` + :default: ``false`` If set to ``true``, markers not registered in the ``markers`` section of the configuration file will raise errors. @@ -2349,10 +2388,12 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: strict_parametrization_ids + :type: ``bool`` + :default: ``false`` If set to ``true``, pytest emits an error if it detects non-unique parameter set IDs. - If not set (the default), pytest automatically handles this by adding `0`, `1`, ... to duplicate IDs, + If not set, pytest automatically handles this by adding `0`, `1`, ... to duplicate IDs, making them unique. .. tab:: toml @@ -2399,6 +2440,8 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: strict_xfail + :type: ``bool`` + :default: ``false`` If set to ``true``, tests marked with ``@pytest.mark.xfail`` that actually succeed will by default fail the test suite. @@ -2426,6 +2469,7 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: testpaths + :type: ``list[str]`` Sets list of directories that should be searched for tests when no specific directories, files or test ids are given in the command line when @@ -2463,8 +2507,10 @@ passed multiple times. The expected format is ``name=value``. For example:: pytest testing doc .. confval:: tmp_path_retention_count + :type: ``str`` + :default: ``"3"`` - How many sessions should we keep the `tmp_path` directories, + How many sessions should pytest keep the `tmp_path` directories, according to :confval:`tmp_path_retention_policy`. .. tab:: toml @@ -2481,12 +2527,10 @@ passed multiple times. The expected format is ``name=value``. For example:: [pytest] tmp_path_retention_count = 3 - Default: ``3`` - .. confval:: tmp_path_retention_policy - - + :type: ``str`` + :default: ``"all"`` Controls which directories created by the `tmp_path` fixture are kept around, based on test outcome. @@ -2509,10 +2553,10 @@ passed multiple times. The expected format is ``name=value``. For example:: [pytest] tmp_path_retention_policy = all - Default: ``all`` - .. confval:: truncation_limit_chars + :type: ``int`` + :default: ``640`` Controls maximum number of characters to truncate assertion message contents. @@ -2534,16 +2578,16 @@ passed multiple times. The expected format is ``name=value``. For example:: pytest truncates the assert messages to a certain limit by default to prevent comparison with large data to overload the console output. - Default: ``640`` - .. note:: If pytest detects it is :ref:`running on CI `, truncation is disabled automatically. .. confval:: truncation_limit_lines + :type: ``int`` + :default: ``8`` - Controls maximum number of linesto truncate assertion message contents. + Controls maximum number of lines to truncate assertion message contents. Setting value to ``0`` disables the lines limit for truncation. @@ -2563,14 +2607,13 @@ passed multiple times. The expected format is ``name=value``. For example:: pytest truncates the assert messages to a certain limit by default to prevent comparison with large data to overload the console output. - Default: ``8`` - .. note:: If pytest detects it is :ref:`running on CI `, truncation is disabled automatically. .. confval:: usefixtures + :type: ``list[str]`` List of fixtures that will be applied to all test functions; this is semantically the same to apply the ``@pytest.mark.usefixtures`` marker to all test functions. @@ -2593,6 +2636,8 @@ passed multiple times. The expected format is ``name=value``. For example:: .. confval:: verbosity_assertions + :type: ``str`` + :default: ``"auto"`` Set a verbosity level specifically for assertion related output, overriding the application wide level. @@ -2610,11 +2655,12 @@ passed multiple times. The expected format is ``name=value``. For example:: [pytest] verbosity_assertions = 2 - If not set, defaults to application wide verbosity level (via the :option:`-v` command-line option). A special value of - ``"auto"`` can be used to explicitly use the global verbosity level. + A special value of ``"auto"`` can be used to explicitly use the global verbosity level. .. confval:: verbosity_subtests + :type: ``str`` + :default: ``"auto"`` Set the verbosity level specifically for **passed** subtests. @@ -2635,13 +2681,14 @@ passed multiple times. The expected format is ``name=value``. For example:: A value of ``1`` or higher will show output for **passed** subtests (**failed** subtests are always reported). Passed subtests output can be suppressed with the value ``0``, which overwrites the :option:`-v` command-line option. - If not set, defaults to application wide verbosity level (via the :option:`-v` command-line option). A special value of - ``"auto"`` can be used to explicitly use the global verbosity level. + A special value of ``"auto"`` can be used to explicitly use the global verbosity level. See also: :ref:`subtests`. .. confval:: verbosity_test_cases + :type: ``str`` + :default: ``"auto"`` Set a verbosity level specifically for test case execution related output, overriding the application wide level. @@ -2659,8 +2706,7 @@ passed multiple times. The expected format is ``name=value``. For example:: [pytest] verbosity_test_cases = 2 - If not set, defaults to application wide verbosity level (via the :option:`-v` command-line option). A special value of - ``"auto"`` can be used to explicitly use the global verbosity level. + A special value of ``"auto"`` can be used to explicitly use the global verbosity level. .. _`command-line-flags`: