From 8805c1f8d12c8ab98a0776a9f60d229cba6dfe69 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. --- doc/en/conf.py | 7 ------- 1 file changed, 7 deletions(-) diff --git a/doc/en/conf.py b/doc/en/conf.py index 81cb9086703..25dc526c4da 100644 --- a/doc/en/conf.py +++ b/doc/en/conf.py @@ -283,13 +283,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", From eb8249abedb7761e494b660fd72773db62b6206c 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, 121 insertions(+), 76 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 4e5c7cfd644..c1df110e822 100644 --- a/doc/en/reference/reference.rst +++ b/doc/en/reference/reference.rst @@ -1330,6 +1330,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: @@ -1346,19 +1347,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 @@ -1379,8 +1381,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: @@ -1402,9 +1402,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. @@ -1415,6 +1417,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: @@ -1424,7 +1428,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 @@ -1443,6 +1447,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 @@ -1470,31 +1476,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 @@ -1519,6 +1524,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. @@ -1539,14 +1546,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 @@ -1566,6 +1573,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. Note in TOML the integer must be quoted, as there is no support @@ -1864,8 +1887,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. @@ -1887,8 +1910,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. @@ -1911,8 +1933,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. @@ -1933,8 +1955,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. @@ -1955,12 +1977,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. Note in TOML the integer must be quoted, as there is no support - for config parameters of mixed type. + Sets the minimum log message level that should be captured for the logging file. + The integer value (in TOML, as a string) or the names of the levels can be used. .. tab:: toml @@ -1982,9 +2003,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 @@ -2004,8 +2027,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. @@ -2027,12 +2050,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. Note in TOML the integer must be quoted, as there is no support - for config parameters of mixed type. + 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 (in TOML, as a string) or the names of the levels can be used. .. tab:: toml @@ -2054,6 +2077,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. @@ -2082,6 +2106,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. @@ -2101,6 +2126,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 @@ -2112,8 +2139,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: @@ -2145,6 +2170,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 @@ -2172,6 +2199,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 @@ -2201,11 +2230,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 @@ -2235,6 +2264,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`. @@ -2259,6 +2289,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 @@ -2281,6 +2312,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: @@ -2316,6 +2349,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. @@ -2337,6 +2372,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. @@ -2358,10 +2395,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 @@ -2408,6 +2447,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. @@ -2435,6 +2476,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 @@ -2472,8 +2514,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 @@ -2490,12 +2534,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. @@ -2518,10 +2560,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. @@ -2543,14 +2585,14 @@ 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 lines to truncate assertion message contents. @@ -2572,14 +2614,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. @@ -2602,6 +2643,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. @@ -2619,11 +2662,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. @@ -2644,13 +2688,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. @@ -2668,8 +2713,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`: