Skip to content
Snippets Groups Projects
Unverified Commit 9912b3d9 authored by Miss Islington (bot)'s avatar Miss Islington (bot) Committed by GitHub
Browse files

gh-77024: test.support: Improve documentation (GH-92513)



This is a rework of GH-5774 on current main. I was a bit more
conservative in making changes than the original PR.

See @csabella's comments on issue GH-77024 and the discussion
on GH-5774 for explanations of several of the changes.

Co-authored-by: default avatarCheryl Sabella <cheryl.sabella@gmail.com>
Co-authored-by: default avatarAlex Waygood <Alex.Waygood@Gmail.com>
(cherry picked from commit 89951770)

Co-authored-by: default avatarJelle Zijlstra <jelle.zijlstra@gmail.com>
parent 93699420
No related branches found
No related tags found
No related merge requests found
...@@ -359,13 +359,19 @@ The :mod:`test.support` module defines the following constants: ...@@ -359,13 +359,19 @@ The :mod:`test.support` module defines the following constants:
.. data:: MISSING_C_DOCSTRINGS .. data:: MISSING_C_DOCSTRINGS
Return ``True`` if running on CPython, not on Windows, and configuration Set to ``True`` if Python is built without docstrings (the
not set with ``WITH_DOC_STRINGS``. :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 .. 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 .. data:: TEST_HTTP_URL
...@@ -423,11 +429,6 @@ The :mod:`test.support` module defines the following functions: ...@@ -423,11 +429,6 @@ The :mod:`test.support` module defines the following functions:
Used when tests are executed by :mod:`test.regrtest`. 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) .. function:: sortdict(dict)
Return a repr of *dict* with keys sorted. Return a repr of *dict* with keys sorted.
...@@ -445,12 +446,12 @@ The :mod:`test.support` module defines the following functions: ...@@ -445,12 +446,12 @@ The :mod:`test.support` module defines the following functions:
.. function:: match_test(test) .. 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) .. function:: run_unittest(*classes)
...@@ -490,7 +491,9 @@ The :mod:`test.support` module defines the following functions: ...@@ -490,7 +491,9 @@ The :mod:`test.support` module defines the following functions:
.. function:: check_impl_detail(**guards) .. function:: check_impl_detail(**guards)
Use this check to guard CPython's implementation-specific tests or to 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() # Only on CPython (default).
check_impl_detail(jython=True) # Only on Jython. check_impl_detail(jython=True) # Only on Jython.
...@@ -509,7 +512,7 @@ The :mod:`test.support` module defines the following functions: ...@@ -509,7 +512,7 @@ The :mod:`test.support` module defines the following functions:
time the regrtest began. time the regrtest began.
.. function:: get_original_stdout .. function:: get_original_stdout()
Return the original stdout set by :func:`record_original_stdout` or Return the original stdout set by :func:`record_original_stdout` or
``sys.stdout`` if it's not set. ``sys.stdout`` if it's not set.
...@@ -554,7 +557,7 @@ The :mod:`test.support` module defines the following functions: ...@@ -554,7 +557,7 @@ The :mod:`test.support` module defines the following functions:
.. function:: disable_faulthandler() .. function:: disable_faulthandler()
A context manager that replaces ``sys.stderr`` with ``sys.__stderr__``. A context manager that temporary disables :mod:`faulthandler`.
.. function:: gc_collect() .. function:: gc_collect()
...@@ -567,8 +570,8 @@ The :mod:`test.support` module defines the following functions: ...@@ -567,8 +570,8 @@ The :mod:`test.support` module defines the following functions:
.. function:: disable_gc() .. function:: disable_gc()
A context manager that disables the garbage collector upon entry and A context manager that disables the garbage collector on entry. On
reenables it upon exit. exit, the garbage collector is restored to its prior state.
.. function:: swap_attr(obj, attr, new_val) .. function:: swap_attr(obj, attr, new_val)
...@@ -633,14 +636,14 @@ The :mod:`test.support` module defines the following functions: ...@@ -633,14 +636,14 @@ The :mod:`test.support` module defines the following functions:
.. function:: calcobjsize(fmt) .. function:: calcobjsize(fmt)
Return :func:`struct.calcsize` for ``nP{fmt}0n`` or, if ``gettotalrefcount`` Return the size of the :c:type:`PyObject` whose structure members are
exists, ``2PnP{fmt}0P``. defined by *fmt*. The returned value includes the size of the Python object header and alignment.
.. function:: calcvobjsize(fmt) .. function:: calcvobjsize(fmt)
Return :func:`struct.calcsize` for ``nPn{fmt}0n`` or, if ``gettotalrefcount`` Return the size of the :c:type:`PyVarObject` whose structure members are
exists, ``2PnPn{fmt}0P``. defined by *fmt*. The returned value includes the size of the Python object header and alignment.
.. function:: checksizeof(test, o, size) .. function:: checksizeof(test, o, size)
...@@ -656,6 +659,11 @@ The :mod:`test.support` module defines the following functions: ...@@ -656,6 +659,11 @@ The :mod:`test.support` module defines the following functions:
have an associated comment identifying the relevant tracker issue. 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) .. decorator:: run_with_locale(catstr, *locales)
A decorator for running a function in a different locale, correctly A decorator for running a function in a different locale, correctly
...@@ -673,19 +681,19 @@ The :mod:`test.support` module defines the following functions: ...@@ -673,19 +681,19 @@ The :mod:`test.support` module defines the following functions:
.. decorator:: requires_freebsd_version(*min_version) .. decorator:: requires_freebsd_version(*min_version)
Decorator for the minimum version when running test on FreeBSD. If the 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:: requires_linux_version(*min_version)
Decorator for the minimum version when running test on Linux. If the 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:: requires_mac_version(*min_version)
Decorator for the minimum version when running test on macOS. If the 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 .. decorator:: requires_IEEE_754
...@@ -723,7 +731,7 @@ The :mod:`test.support` module defines the following functions: ...@@ -723,7 +731,7 @@ The :mod:`test.support` module defines the following functions:
Decorator for only running the test if :data:`HAVE_DOCSTRINGS`. Decorator for only running the test if :data:`HAVE_DOCSTRINGS`.
.. decorator:: cpython_only(test) .. decorator:: cpython_only
Decorator for tests only applicable to CPython. Decorator for tests only applicable to CPython.
...@@ -734,12 +742,12 @@ The :mod:`test.support` module defines the following functions: ...@@ -734,12 +742,12 @@ The :mod:`test.support` module defines the following functions:
returns ``False``, then uses *msg* as the reason for skipping the test. 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 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 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 not run the test if it is not run by CPython. Any trace function is unset
...@@ -762,10 +770,9 @@ The :mod:`test.support` module defines the following functions: ...@@ -762,10 +770,9 @@ The :mod:`test.support` module defines the following functions:
means the test doesn't support dummy runs when ``-M`` is not specified. 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 Decorator for tests that fill the address space.
wrap.
.. function:: check_syntax_error(testcase, statement, errtext='', *, lineno=None, offset=None) .. function:: check_syntax_error(testcase, statement, errtext='', *, lineno=None, offset=None)
...@@ -867,7 +874,7 @@ The :mod:`test.support` module defines the following functions: ...@@ -867,7 +874,7 @@ The :mod:`test.support` module defines the following functions:
.. function:: check_free_after_iterating(test, iter, cls, args=()) .. 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=[]) .. function:: missing_compiler_executable(cmd_names=[])
...@@ -958,6 +965,16 @@ The :mod:`test.support` module defines the following classes: ...@@ -958,6 +965,16 @@ The :mod:`test.support` module defines the following classes:
Class to save and restore signal handlers registered by the Python signal Class to save and restore signal handlers registered by the Python signal
handler. 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() .. class:: Matcher()
...@@ -1101,11 +1118,11 @@ script execution tests. ...@@ -1101,11 +1118,11 @@ script execution tests.
variables *env_vars* succeeds (``rc == 0``) and return a ``(return code, variables *env_vars* succeeds (``rc == 0``) and return a ``(return code,
stdout, stderr)`` tuple. stdout, stderr)`` tuple.
If the ``__cleanenv`` keyword is set, *env_vars* is used as a fresh If the *__cleanenv* keyword-only parameter is set, *env_vars* is used as a fresh
environment. environment.
Python is started in isolated mode (command line option ``-I``), Python is started in isolated mode (command line option ``-I``),
except if the ``__isolated`` keyword is set to ``False``. except if the *__isolated* keyword-only parameter is set to ``False``.
.. versionchanged:: 3.9 .. versionchanged:: 3.9
The function no longer strips whitespaces from *stderr*. The function no longer strips whitespaces from *stderr*.
...@@ -1216,15 +1233,17 @@ The :mod:`test.support.threading_helper` module provides support for threading t ...@@ -1216,15 +1233,17 @@ The :mod:`test.support.threading_helper` module provides support for threading t
is still alive after *timeout* seconds. 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. Decorator to ensure the threads are cleaned up even if the test fails.
.. function:: start_threads(threads, unlock=None) .. function:: start_threads(threads, unlock=None)
Context manager to start *threads*. It attempts to join the threads upon Context manager to start *threads*, which is a sequence of threads.
exit. *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) .. function:: threading_cleanup(*original_values)
...@@ -1306,7 +1325,10 @@ The :mod:`test.support.os_helper` module provides support for os tests. ...@@ -1306,7 +1325,10 @@ The :mod:`test.support.os_helper` module provides support for os tests.
.. data:: TESTFN_NONASCII .. 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.
.. data:: TESTFN_UNENCODABLE .. data:: TESTFN_UNENCODABLE
...@@ -1404,13 +1426,16 @@ The :mod:`test.support.os_helper` module provides support for os tests. ...@@ -1404,13 +1426,16 @@ The :mod:`test.support.os_helper` module provides support for os tests.
.. function:: rmdir(filename) .. function:: rmdir(filename)
Call :func:`os.rmdir` on *filename*. On Windows platforms, this is 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) .. function:: rmtree(path)
Call :func:`shutil.rmtree` on *path* or call :func:`os.lstat` and 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. this is wrapped with a wait loop that checks for the existence of the files.
...@@ -1457,7 +1482,8 @@ The :mod:`test.support.os_helper` module provides support for os tests. ...@@ -1457,7 +1482,8 @@ The :mod:`test.support.os_helper` module provides support for os tests.
.. function:: unlink(filename) .. 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. wrapped with a wait loop that checks for the existence of the file.
...@@ -1514,7 +1540,7 @@ The :mod:`test.support.import_helper` module provides support for import tests. ...@@ -1514,7 +1540,7 @@ The :mod:`test.support.import_helper` module provides support for import tests.
.. versionadded:: 3.1 .. 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 This function imports and returns the named module. Unlike a normal
import, this function raises :exc:`unittest.SkipTest` if the module import, this function raises :exc:`unittest.SkipTest` if the module
...@@ -1556,7 +1582,7 @@ The :mod:`test.support.import_helper` module provides support for import tests. ...@@ -1556,7 +1582,7 @@ 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 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 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'): with CleanImport('foo'):
importlib.import_module('foo') # New reference. importlib.import_module('foo') # New reference.
...@@ -1564,7 +1590,7 @@ The :mod:`test.support.import_helper` module provides support for import tests. ...@@ -1564,7 +1590,7 @@ The :mod:`test.support.import_helper` module provides support for import tests.
.. class:: DirsOnSysPath(*paths) .. 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 This makes a copy of :data:`sys.path`, appends any directories given
as positional arguments, then reverts :data:`sys.path` to the copied as positional arguments, then reverts :data:`sys.path` to the copied
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment