Skip to content

gh-77024: test.support: Improve documentation #92513

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
May 27, 2022
Merged

gh-77024: test.support: Improve documentation #92513

Changes from 3 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
81c870d
gh-77024: test.support: Improve documentation
JelleZijlstra May 8, 2022
41ed063
Feedback from Victor
JelleZijlstra May 23, 2022
ccadae6
Apply suggestions from code review
JelleZijlstra May 26, 2022
212e267
Update Doc/library/test.rst
JelleZijlstra May 26, 2022
66199b4
one more
JelleZijlstra May 26, 2022
36981dd
Apply suggestions from code review
JelleZijlstra May 27, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
108 changes: 67 additions & 41 deletions Doc/library/test.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -359,13 +359,19 @@ The :mod:`test.support` module defines the following constants:

.. data:: MISSING_C_DOCSTRINGS

Return ``True`` if running on CPython, not on Windows, and configuration
not set with ``WITH_DOC_STRINGS``.
Set to ``True`` if Python is built without docstrings (the
:c:macro:`WITH_DOC_STRINGS` macro is not defined).
See the :option:`configure --without-doc-strings <--without-doc-strings>` option.

See also the :data:`HAVE_DOCSTRINGS` variable.


.. data:: HAVE_DOCSTRINGS

Check for presence of docstrings.
Set to ``True`` if function docstrings are available.
See the :option:`python -OO <-O>` option, which strips docstrings of functions implemented in Python.

See also the :data:`MISSING_C_DOCSTRINGS` variable.


.. data:: TEST_HTTP_URL
Expand Down Expand Up @@ -423,11 +429,6 @@ The :mod:`test.support` module defines the following functions:
Used when tests are executed by :mod:`test.regrtest`.


.. function:: system_must_validate_cert(f)

Raise :exc:`unittest.SkipTest` on TLS certification validation failures.


.. function:: sortdict(dict)

Return a repr of *dict* with keys sorted.
Expand All @@ -445,12 +446,12 @@ The :mod:`test.support` module defines the following functions:

.. function:: match_test(test)

Match *test* to patterns set in :func:`set_match_tests`.
Determine whether *test* matches the patterns set in :func:`set_match_tests`.


.. function:: set_match_tests(patterns)
.. function:: set_match_tests(accept_patterns=None, ignore_patterns=None)

Define match test with regular expression *patterns*.
Define match patterns on test filenames and test method names for filtering tests.


.. function:: run_unittest(*classes)
Expand Down Expand Up @@ -490,7 +491,9 @@ The :mod:`test.support` module defines the following functions:
.. function:: check_impl_detail(**guards)

Use this check to guard CPython's implementation-specific tests or to
run them only on the implementations guarded by the arguments::
run them only on the implementations guarded by the arguments. This
function returns ``True`` or ``False`` depending on the host platform.
Example usage::

check_impl_detail() # Only on CPython (default).
check_impl_detail(jython=True) # Only on Jython.
Expand All @@ -509,7 +512,7 @@ The :mod:`test.support` module defines the following functions:
time the regrtest began.


.. function:: get_original_stdout
.. function:: get_original_stdout()

Return the original stdout set by :func:`record_original_stdout` or
``sys.stdout`` if it's not set.
Expand Down Expand Up @@ -554,7 +557,7 @@ The :mod:`test.support` module defines the following functions:

.. function:: disable_faulthandler()

A context manager that replaces ``sys.stderr`` with ``sys.__stderr__``.
A context manager that temporary disables :mod:`faulthandler`.


.. function:: gc_collect()
Expand All @@ -568,7 +571,7 @@ The :mod:`test.support` module defines the following functions:
.. function:: disable_gc()

A context manager that disables the garbage collector upon entry and
reenables it upon exit.
reenables it upon exit, if it was initially enabled.


.. function:: swap_attr(obj, attr, new_val)
Expand Down Expand Up @@ -642,14 +645,14 @@ The :mod:`test.support` module defines the following functions:

.. function:: calcobjsize(fmt)

Return :func:`struct.calcsize` for ``nP{fmt}0n`` or, if ``gettotalrefcount``
exists, ``2PnP{fmt}0P``.
Return the size of the :c:type:`PyObject` whose structure members are
defined by *fmt*. The returned value includes the size of the Python object header and alignment.


.. function:: calcvobjsize(fmt)

Return :func:`struct.calcsize` for ``nPn{fmt}0n`` or, if ``gettotalrefcount``
exists, ``2PnPn{fmt}0P``.
Return the size of the :c:type:`PyVarObject` whose structure members are
defined by *fmt* including the Python object header and alignment.


.. function:: checksizeof(test, o, size)
Expand All @@ -665,6 +668,11 @@ The :mod:`test.support` module defines the following functions:
have an associated comment identifying the relevant tracker issue.


.. function:: system_must_validate_cert(f)

A decorator that skips the decorated test on TLS certification validation failures.


.. decorator:: run_with_locale(catstr, *locales)

A decorator for running a function in a different locale, correctly
Expand All @@ -682,19 +690,19 @@ The :mod:`test.support` module defines the following functions:
.. decorator:: requires_freebsd_version(*min_version)

Decorator for the minimum version when running test on FreeBSD. If the
FreeBSD version is less than the minimum, raise :exc:`unittest.SkipTest`.
FreeBSD version is less than the minimum, the test is skipped.


.. decorator:: requires_linux_version(*min_version)

Decorator for the minimum version when running test on Linux. If the
Linux version is less than the minimum, raise :exc:`unittest.SkipTest`.
Linux version is less than the minimum, the test is skipped.


.. decorator:: requires_mac_version(*min_version)

Decorator for the minimum version when running test on macOS. If the
macOS version is less than the minimum, raise :exc:`unittest.SkipTest`.
macOS version is less than the minimum, the test is skipped.


.. decorator:: requires_IEEE_754
Expand Down Expand Up @@ -732,7 +740,7 @@ The :mod:`test.support` module defines the following functions:
Decorator for only running the test if :data:`HAVE_DOCSTRINGS`.


.. decorator:: cpython_only(test)
.. decorator:: cpython_only

Decorator for tests only applicable to CPython.

Expand All @@ -743,12 +751,12 @@ The :mod:`test.support` module defines the following functions:
returns ``False``, then uses *msg* as the reason for skipping the test.


.. decorator:: no_tracing(func)
.. decorator:: no_tracing

Decorator to temporarily turn off tracing for the duration of the test.


.. decorator:: refcount_test(test)
.. decorator:: refcount_test

Decorator for tests which involve reference counting. The decorator does
not run the test if it is not run by CPython. Any trace function is unset
Expand All @@ -771,10 +779,9 @@ The :mod:`test.support` module defines the following functions:
means the test doesn't support dummy runs when ``-M`` is not specified.


.. decorator:: bigaddrspacetest(f)
.. decorator:: bigaddrspacetest

Decorator for tests that fill the address space. *f* is the function to
wrap.
Decorator for tests that fill the address space.


.. function:: check_syntax_error(testcase, statement, errtext='', *, lineno=None, offset=None)
Expand Down Expand Up @@ -876,7 +883,7 @@ The :mod:`test.support` module defines the following functions:

.. function:: check_free_after_iterating(test, iter, cls, args=())

Assert that *iter* is deallocated after iterating.
Assert instances of *cls* are deallocated after iterating.


.. function:: missing_compiler_executable(cmd_names=[])
Expand Down Expand Up @@ -967,6 +974,16 @@ The :mod:`test.support` module defines the following classes:
Class to save and restore signal handlers registered by the Python signal
handler.

.. method:: save(self)

Save the signal handlers to a dictionary mapping signal numbers to the
current signal handler.

.. method:: restore(self)

Set the signal numbers from the :meth:`save` dictionary to the saved
handler.


.. class:: Matcher()

Expand Down Expand Up @@ -1110,11 +1127,11 @@ script execution tests.
variables *env_vars* succeeds (``rc == 0``) and return a ``(return code,
stdout, stderr)`` tuple.

If the ``__cleanenv`` keyword is set, *env_vars* is used as a fresh
If the *__cleanenv* keyword is set, *env_vars* is used as a fresh
environment.

Python is started in isolated mode (command line option ``-I``),
except if the ``__isolated`` keyword is set to ``False``.
except if the *__isolated* keyword is set to ``False``.

.. versionchanged:: 3.9
The function no longer strips whitespaces from *stderr*.
Expand Down Expand Up @@ -1225,15 +1242,17 @@ The :mod:`test.support.threading_helper` module provides support for threading t
is still alive after *timeout* seconds.


.. decorator:: reap_threads(func)
.. decorator:: reap_threads

Decorator to ensure the threads are cleaned up even if the test fails.


.. function:: start_threads(threads, unlock=None)

Context manager to start *threads*. It attempts to join the threads upon
exit.
Context manager to start *threads*, which is a sequence of threads.
*unlock* is a function called after the threads are started, even if an
exception was raised; an example would be :meth:`threading.Event.set`.
``start_threads`` will attempt to join the started threads upon exit.


.. function:: threading_cleanup(*original_values)
Expand Down Expand Up @@ -1315,7 +1334,10 @@ The :mod:`test.support.os_helper` module provides support for os tests.

.. data:: TESTFN_NONASCII

Set to a filename containing the :data:`FS_NONASCII` character.
Set to a filename containing the :data:`FS_NONASCII` character, if it exists.
This guarantees that if the filename exists, it can be encoded and decoded
with the default filesystem encoding. This allows tests that require a
non-ASCII filename to be easily skipped on platforms where they can't work.
Comment on lines +1337 to +1340
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This currently feels like it leads with the implementation, and finishes with why it's useful ("This allows tests that require a non-ASCII filename to be easily skipped on platforms where they can't work"). The other way around might be better.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see your point, but I feel like the current sequence is more in line with the surrounding TESTFN_* paragraphs.



.. data:: TESTFN_UNENCODABLE
Expand Down Expand Up @@ -1413,13 +1435,16 @@ The :mod:`test.support.os_helper` module provides support for os tests.
.. function:: rmdir(filename)

Call :func:`os.rmdir` on *filename*. On Windows platforms, this is
wrapped with a wait loop that checks for the existence of the file.
wrapped with a wait loop that checks for the existence of the file,
which is needed due to antivirus programs that can hold files open and prevent
deletion.


.. function:: rmtree(path)

Call :func:`shutil.rmtree` on *path* or call :func:`os.lstat` and
:func:`os.rmdir` to remove a path and its contents. On Windows platforms,
:func:`os.rmdir` to remove a path and its contents. As with :func:`rmdir`,
on Windows platforms
this is wrapped with a wait loop that checks for the existence of the files.


Expand Down Expand Up @@ -1466,7 +1491,8 @@ The :mod:`test.support.os_helper` module provides support for os tests.

.. function:: unlink(filename)

Call :func:`os.unlink` on *filename*. On Windows platforms, this is
Call :func:`os.unlink` on *filename*. As with :func:`rmdir`,
on Windows platforms, this is
wrapped with a wait loop that checks for the existence of the file.


Expand Down Expand Up @@ -1523,7 +1549,7 @@ The :mod:`test.support.import_helper` module provides support for import tests.
.. versionadded:: 3.1


.. function:: import_module(name, deprecated=False, *, required_on())
.. function:: import_module(name, deprecated=False, *, required_on=())

This function imports and returns the named module. Unlike a normal
import, this function raises :exc:`unittest.SkipTest` if the module
Expand Down Expand Up @@ -1565,15 +1591,15 @@ The :mod:`test.support.import_helper` module provides support for import tests.

A context manager to force import to return a new module reference. This
is useful for testing module-level behaviors, such as the emission of a
DeprecationWarning on import. Example usage::
:exc:`DeprecationWarning` on import. Example usage::

with CleanImport('foo'):
importlib.import_module('foo') # New reference.


.. class:: DirsOnSysPath(*paths)

A context manager to temporarily add directories to sys.path.
A context manager to temporarily add directories to :data:`sys.path`.

This makes a copy of :data:`sys.path`, appends any directories given
as positional arguments, then reverts :data:`sys.path` to the copied
Expand Down