Add documentation.

python · serhiy-storchaka · Sep 2, 2023 · Sep 3, 2023 · Sep 3, 2023 · Sep 3, 2023
commit fe7fcd04ba1cbbff601c95faf341998a2bfddafb
diff --git a/Doc/library/test.rst b/Doc/library/test.rst
@@ -482,6 +482,8 @@ The :mod:`test.support` module defines the following functions:
    ``True`` if called by a function whose ``__name__`` is ``'__main__'``.
    Used when tests are executed by :mod:`test.regrtest`.
 
+   If called at the top level, sets label "requires_\ *resource*" on the module.
+
 
 .. function:: sortdict(dict)
 
@@ -498,16 +500,34 @@ The :mod:`test.support` module defines the following functions:
    rather than looking directly in the path directories.
 
 
+.. function:: mark(label, *, globals=None)
-.. function:: mark(label, *, globals=None)
+.. function:: mark(name, *, globals=None)
-.. function:: mark(label, *, globals=None)
+.. function:: mark(name, *, globals=None)
+
+   Add a label to tests.
-   Add a label to tests.
+   Add a mark to tests.
-   Add a label to tests.
+   Add a mark to tests.
+   The ``@mark('label')`` de
10000
corator adds a label to method or class.
+   ``test.support.mark('label', globals=globals())`` adds a label to the whole
+   module.
+
+   Many :mod:`test.support` decorators like :func:`requires_resource`,
+   :func:`~test.support.cpython_only` or :func:`bigmemtest` add labels
+   automatically.
+
+
 .. function:: match_test(test)
 
-   Determine whether *test* matches the patterns set in :func:`set_match_tests`.
+   Determine whether *test* matches the patterns set in :func:`set_match_tests`
+   and labels set in :func:`set_match_tests2`.
 
 
 .. function:: set_match_tests(accept_patterns=None, ignore_patterns=None)
 
    Define match patterns on test filenames and test method names for filtering tests.
 
 
+.. function:: set_match_tests2(accept_labels=None, ignore_labels=None)
+
+   Define labels on tests for filtering.
+
+
 .. function:: run_unittest(*classes)
 
    Execute :class:`unittest.TestCase` subclasses passed to the function. The
@@ -774,26 +794,31 @@ The :mod:`test.support` module defines the following functions:
 .. decorator:: requires_zlib
 
    Decorator for skipping tests if :mod:`zlib` doesn't exist.
+   Adds label "requires_zlib".
 
 
 .. decorator:: requires_gzip
 
    Decorator for skipping tests if :mod:`gzip` doesn't exist.
+   Adds label "requires_gzip".
 
 
 .. decorator:: requires_bz2
 
    Decorator for skipping tests if :mod:`bz2` doesn't exist.
+   Adds label "requires_bz2".
 
 
 .. decorator:: requires_lzma
 
    Decorator for skipping tests if :mod:`lzma` doesn't exist.
+   Adds label "requires_lzma".
 
 
 .. decorator:: requires_resource(resource)
 
    Decorator for skipping tests if *resource* is not available.
+   Adds label "requires_\ *resource*".
 
 
 .. decorator:: requires_docstrings
@@ -810,13 +835,16 @@ The :mod:`test.support` module defines the following functions:
 .. decorator:: cpython_only
 
    Decorator for tests only applicable to CPython.
+   Adds label "impl_detail_cpython".
 
 
 .. decorator:: impl_detail(msg=None, **guards)
 
    Decorator for invoking :func:`check_impl_detail` on *guards*.  If that
    returns ``False``, then uses *msg* as the reason for skipping the test.
-
+   For every keyword argument *implname* adds a label
+   "impl_detail_\ *implname*" if its value is true or
+   "impl_detail_no_\ *implname*" otherwise.
 
 .. decorator:: no_tracing
 
@@ -845,10 +873,13 @@ The :mod:`test.support` module defines the following functions:
    method may be less than the requested value.  If *dry_run* is ``False``, it
    means the test doesn't support dummy runs when ``-M`` is not specified.
 
+   Adds label "bigmemtest".
+
 
 .. decorator:: bigaddrspacetest
 
    Decorator for tests that fill the address space.
+   Adds label "bigaddrspacetest".
 
 
    .. function:: check_syntax_error(testcase, statement, errtext='', *, lineno=None, offset=None)
@@ -1630,6 +1661,8 @@ The :mod:`test.support.import_helper` module provides support for import tests.
    optional for others, set *required_on* to an iterable of platform prefixes
    which will be compared against :data:`sys.platform`.
 
+   If called at the top level, sets label "requires_\ *name*" on the module.
+
    .. versionadded:: 3.1
 
 

diff --git a/Lib/test/support/__init__.py b/Lib/test/support/__init__.py
@@ -527,7 +527,8 @@ def requires_debug_ranges(reason='requires co_positions / debug_ranges'):
 has_fork_support = hasattr(os, "fork") and not is_emscripten and not is_wasi
 
 def requires_fork():
-    return skipUnless(has_fork_support, "requires working os.fork()", label='requires_fork')
+    return skipUnless(has_fork_support, "requires working os.fork()",
+                      label='requires_fork')
 
 has_subprocess_support = not is_emscripten and not is_wasi
 

diff --git a/Misc/NEWS.d/next/Tests/2023-09-03-12-53-53.gh-issue-108828.zoWIyX.rst b/Misc/NEWS.d/next/Tests/2023-09-03-12-53-53.gh-issue-108828.zoWIyX.rst
@@ -0,0 +1,7 @@
+Add support of labels in tests. The ``@test.support.mark('label')``
+decorator adds a label to method or class. ``test.support.mark('label',
+globals=globals())`` adds a label to the whole module. Many
+:mod:`test.support` decorators like :func:`~test.support.requires_resource`,
+:func:`~test.support.cpython_only` or :func:`~test.support.bigmemtest` add
+labels automatically.  Tests which have or have not the specified label can
+be filtered by options ``--label`` and ``--no-label``.