diff --git a/Doc/conf.py b/Doc/conf.py index 20971ec043bd1ab..9d24f2ff1146e05 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -214,6 +214,10 @@ ('c:macro', 'LONG_MIN'), # Standard C variables ('c:data', 'errno'), + # Platform-specific socket constants documented collectively as SO_*. + ('py:const', 'socket.SO_EXCLUSIVEADDRUSE'), + ('py:const', 'socket.SO_REUSEADDR'), + ('py:const', 'socket.SO_REUSEPORT'), # Standard environment variables ('envvar', 'BROWSER'), ('envvar', 'COLUMNS'), diff --git a/Doc/library/test.rst b/Doc/library/test.rst index b4809fdd66c1834..843142bcce15d20 100644 --- a/Doc/library/test.rst +++ b/Doc/library/test.rst @@ -506,7 +506,8 @@ The :mod:`!test.support` module defines the following functions: .. function:: with_pymalloc() - Return :const:`_testcapi.WITH_PYMALLOC`. + Return ``True`` if Python was built with :ref:`pymalloc ` enabled + and is not a :term:`free-threaded build`. .. function:: requires(resource, msg=None) @@ -1088,7 +1089,7 @@ The :mod:`!test.support` module defines the following functions: .. function:: skip_if_broken_multiprocessing_synchronize() - Skip tests if the :mod:`multiprocessing.synchronize` module is missing, if + Skip tests if the :mod:`!multiprocessing.synchronize` module is missing, if there is no available semaphore implementation, or if creating a lock raises an :exc:`OSError`. @@ -1260,7 +1261,7 @@ script execution tests. doesn't have an obvious home with Python's current home finding logic. Setting :envvar:`PYTHONHOME` is one way to get most of the testsuite to run - in that situation. :envvar:`PYTHONPATH` or :envvar:`PYTHONUSERSITE` are + in that situation. :envvar:`PYTHONPATH` or :envvar:`PYTHONNOUSERSITE` are other common environment variables that might impact whether or not the interpreter can start. @@ -1708,8 +1709,8 @@ The :mod:`!test.support.import_helper` module provides support for import tests. This function imports and returns a fresh copy of the named Python module by removing the named module from ``sys.modules`` before doing the import. - Note that unlike :func:`reload`, the original module is not affected by - this operation. + Note that unlike :func:`importlib.reload`, the original module is not + affected by this operation. *fresh* is an iterable of additional module names that are also removed from the ``sys.modules`` cache before doing the import. @@ -1871,17 +1872,10 @@ The :mod:`!test.support.warnings_helper` module provides support for warnings te In this case all warnings are caught and no errors are raised. - On entry to the context manager, a :class:`WarningRecorder` instance is - returned. The underlying warnings list from - :func:`~warnings.catch_warnings` is available via the recorder object's - :attr:`warnings` attribute. As a convenience, the attributes of the object - representing the most recent warning can also be accessed directly through - the recorder object (see example below). If no warning has been raised, - then any of the attributes that would otherwise be expected on an object - representing a warning will return ``None``. - - The recorder object also has a :meth:`reset` method, which clears the - warnings list. + On entry to the context manager, a :class:`WarningsRecorder` instance is + returned. The recorded warnings are available via its + :attr:`~WarningsRecorder.warnings` attribute, and its + :meth:`~WarningsRecorder.reset` method discards previously recorded warnings. The context manager is designed to be used like this:: @@ -1898,11 +1892,11 @@ The :mod:`!test.support.warnings_helper` module provides support for warnings te with check_warnings(quiet=True) as w: warnings.warn("foo") - assert str(w.args[0]) == "foo" + assert str(w.message) == "foo" warnings.warn("bar") - assert str(w.args[0]) == "bar" - assert str(w.warnings[0].args[0]) == "foo" - assert str(w.warnings[1].args[0]) == "bar" + assert str(w.message) == "bar" + assert str(w.warnings[0].message) == "foo" + assert str(w.warnings[1].message) == "bar" w.reset() assert len(w.warnings) == 0 @@ -1914,7 +1908,22 @@ The :mod:`!test.support.warnings_helper` module provides support for warnings te New optional arguments *filters* and *quiet*. -.. class:: WarningsRecorder() +.. class:: WarningsRecorder(warnings_list) + + Class used to record warnings for unit tests. Wraps the warnings list + returned by :func:`warnings.catch_warnings` when recording is enabled. + :func:`check_warnings` returns an instance of this class. + + As a convenience, the attributes of the object representing the most recent + warning can also be accessed directly through the recorder object. + If no warning has been raised since the recorder was created or last reset, + these attributes return ``None``. + + .. attribute:: warnings + + A list of warnings recorded since the recorder was created or last reset. + + .. method:: reset() - Class used to record warnings for unit tests. See documentation of - :func:`check_warnings` above for more details. + Discard previously recorded warnings from the recorder's view. + The underlying warnings list is not modified. diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index 77289370c77abee..04a40030ff23f1f 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -16,7 +16,6 @@ Doc/library/select.rst Doc/library/socket.rst Doc/library/ssl.rst Doc/library/termios.rst -Doc/library/test.rst Doc/library/urllib.parse.rst Doc/library/urllib.request.rst Doc/library/wsgiref.rst diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst index c36328ca6f79723..e77bbd33d80fc19 100644 --- a/Doc/using/configure.rst +++ b/Doc/using/configure.rst @@ -877,7 +877,12 @@ also be used to improve performance. Disable static documentation strings to reduce the memory footprint (enabled by default). Documentation strings defined in Python are not affected. - Don't define the ``WITH_DOC_STRINGS`` macro. + Don't define the :c:macro:`WITH_DOC_STRINGS` macro. + + .. c:macro:: WITH_DOC_STRINGS + + Define this macro to include static documentation strings in the build. + It is defined by default, unless :option:`--without-doc-strings` is used. See the ``PyDoc_STRVAR()`` macro.