.. 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
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.
.. 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:: 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.
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.
.. 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:: disable_gc()
- A context manager that disables the garbage collector upon entry and
- reenables it upon exit.
+ A context manager that disables the garbage collector on entry. On
+ exit, the garbage collector is restored to its prior state.
.. function:: swap_attr(obj, attr, new_val)
.. 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*. The returned value includes the size of the Python object header and alignment.
.. function:: checksizeof(test, o, size)
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
.. 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
Decorator for only running the test if :data:`HAVE_DOCSTRINGS`.
-.. decorator:: cpython_only(test)
+.. decorator:: cpython_only
Decorator for tests only applicable to CPython.
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
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)
.. 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=[])
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()
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-only parameter 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-only parameter is set to ``False``.
.. versionchanged:: 3.9
The function no longer strips whitespaces from *stderr*.
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)
.. 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
.. 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.
.. 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.
.. 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
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
projects / thirdparty / Python / cpython.git / commitdiff
