From cbd26fcda323432eee7ca9fc7a4b97161508fa04 Mon Sep 17 00:00:00 2001 From: Skip Montanaro Date: Sat, 3 Feb 2024 08:42:36 -0600 Subject: [PATCH 1/8] Fix dangling references in test.rst Further cleanup related to #114770. --- Doc/library/test.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/Doc/library/test.rst b/Doc/library/test.rst index cad1023021a512..b390c40f6ea3ad 100644 --- a/Doc/library/test.rst +++ b/Doc/library/test.rst @@ -169,7 +169,7 @@ test.regrtest` used in previous Python versions still works. Running the script by itself automatically starts running all regression tests in the :mod:`test` package. It does this by finding all modules in the package whose name starts with ``test_``, importing them, and executing the function -:func:`test_main` if present or loading the tests via +:func:`!test_main` if present or loading the tests via unittest.TestLoader.loadTestsFromModule if ``test_main`` does not exist. The names of tests to execute may also be passed to the script. Specifying a single regression test (:program:`python -m test test_spam`) will minimize output and @@ -324,7 +324,7 @@ The :mod:`test.support` module defines the following constants: .. data:: Py_DEBUG - True if Python is built with the :c:macro:`Py_DEBUG` macro defined: if + True if Python is built with the :c:macro:`!Py_DEBUG` macro defined: if Python is :ref:`built in debug mode ` (:option:`./configure --with-pydebug <--with-pydebug>`). @@ -372,7 +372,7 @@ The :mod:`test.support` module defines the following constants: .. data:: MISSING_C_DOCSTRINGS Set to ``True`` if Python is built without docstrings (the - :c:macro:`WITH_DOC_STRINGS` macro is not defined). + :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. @@ -475,7 +475,7 @@ The :mod:`test.support` module defines the following functions: .. function:: with_pymalloc() - Return :const:`_testcapi.WITH_PYMALLOC`. + Return :const:`!_testcapi.WITH_PYMALLOC`. .. function:: requires(resource, msg=None) @@ -969,7 +969,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`. @@ -1087,12 +1087,12 @@ The :mod:`test.support.socket_helper` module provides support for socket tests. buildbot environment. This method raises an exception if the ``sock.family`` is :const:`~socket.AF_INET` and ``sock.type`` is :const:`~socket.SOCK_STREAM`, and the socket has - :const:`~socket.SO_REUSEADDR` or :const:`~socket.SO_REUSEPORT` set on it. + :const:`!SO_REUSEADDR` or :const:`!SO_REUSEPORT` set on it. Tests should never set these socket options for TCP/IP sockets. The only case for setting these options is testing multicasting via multiple UDP sockets. - Additionally, if the :const:`~socket.SO_EXCLUSIVEADDRUSE` socket option is + Additionally, if the :const:`!~socket.SO_EXCLUSIVEADDRUSE` socket option is available (i.e. on Windows), it will be set on the socket. This will prevent anyone else from binding to our host/port for the duration of the test. @@ -1141,7 +1141,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. @@ -1553,7 +1553,7 @@ 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 + 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 @@ -1716,7 +1716,7 @@ The :mod:`test.support.warnings_helper` module provides support for warnings tes In this case all warnings are caught and no errors are raised. - On entry to the context manager, a :class:`WarningRecorder` instance is + On entry to the context manager, a :class:`WarningsRecorder` 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 @@ -1725,7 +1725,7 @@ The :mod:`test.support.warnings_helper` module provides support for warnings tes 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 + The recorder object also has a :meth:`!reset` method, which clears the warnings list. The context manager is designed to be used like this:: From b9d12fda324424a75378ba6a583e028b9023d7d3 Mon Sep 17 00:00:00 2001 From: Skip Montanaro Date: Mon, 12 Feb 2024 11:54:04 -0600 Subject: [PATCH 2/8] add to test.rst change pr --- Doc/tools/.nitignore | 1 - 1 file changed, 1 deletion(-) diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index 7127f30f240ce7..b60abcbfb52441 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -63,7 +63,6 @@ Doc/library/ssl.rst Doc/library/stdtypes.rst Doc/library/subprocess.rst Doc/library/termios.rst -Doc/library/test.rst Doc/library/tkinter.rst Doc/library/tkinter.scrolledtext.rst Doc/library/tkinter.ttk.rst From 2d479c6154cf4898486393677ff4561c8b29b7b9 Mon Sep 17 00:00:00 2001 From: Skip Montanaro Date: Sat, 17 Feb 2024 13:48:22 -0600 Subject: [PATCH 3/8] minor nit - I think this phrase read better before --- Doc/library/test.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/test.rst b/Doc/library/test.rst index b390c40f6ea3ad..597d37357e6d99 100644 --- a/Doc/library/test.rst +++ b/Doc/library/test.rst @@ -324,7 +324,7 @@ The :mod:`test.support` module defines the following constants: .. data:: Py_DEBUG - True if Python is built with the :c:macro:`!Py_DEBUG` macro defined: if + True if Python was built with the :c:macro:`!Py_DEBUG` macro defined: if Python is :ref:`built in debug mode ` (:option:`./configure --with-pydebug <--with-pydebug>`). From f2252d06d62da546b81497ec7ed7e09cce07efa5 Mon Sep 17 00:00:00 2001 From: Skip Montanaro Date: Wed, 21 Feb 2024 18:26:17 -0600 Subject: [PATCH 4/8] restore Py_DEBUG ref --- Doc/library/test.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/test.rst b/Doc/library/test.rst index 597d37357e6d99..0acad70495cd60 100644 --- a/Doc/library/test.rst +++ b/Doc/library/test.rst @@ -324,8 +324,8 @@ The :mod:`test.support` module defines the following constants: .. data:: Py_DEBUG - True if Python was built with the :c:macro:`!Py_DEBUG` macro defined: if - Python is :ref:`built in debug mode ` + True if Python was built with the :c:macro:`Py_DEBUG` macro defined; + that is, if Python was :ref:`built in debug mode ` (:option:`./configure --with-pydebug <--with-pydebug>`). .. versionadded:: 3.12 From cccb427b9b81220545c8597a2edf353daf0bc31d Mon Sep 17 00:00:00 2001 From: Skip Montanaro Date: Thu, 22 Feb 2024 19:12:51 -0600 Subject: [PATCH 5/8] connect to the (undocumented) WarningsRecorder.reset method --- Doc/library/test.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/test.rst b/Doc/library/test.rst index 0acad70495cd60..8c63ca7c1adde1 100644 --- a/Doc/library/test.rst +++ b/Doc/library/test.rst @@ -1725,7 +1725,7 @@ The :mod:`test.support.warnings_helper` module provides support for warnings tes 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 + The recorder object also has a :meth:`~WarningsRecorder.reset` method, which clears the warnings list. The context manager is designed to be used like this:: From c23ac5453018621cbcc3b055cc02769b97bdea3a Mon Sep 17 00:00:00 2001 From: Skip Montanaro Date: Thu, 22 Feb 2024 19:21:58 -0600 Subject: [PATCH 6/8] correct reference to WarningsRecorder class --- Doc/library/test.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/test.rst b/Doc/library/test.rst index 8c63ca7c1adde1..2ef718ceaf12cd 100644 --- a/Doc/library/test.rst +++ b/Doc/library/test.rst @@ -1719,7 +1719,7 @@ The :mod:`test.support.warnings_helper` module provides support for warnings tes On entry to the context manager, a :class:`WarningsRecorder` 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 + :attr:`~WarningsRecorder.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 From b3acb266cc9ff9fe65ca95a8305bd475ed83bee0 Mon Sep 17 00:00:00 2001 From: Skip Montanaro Date: Thu, 22 Feb 2024 19:27:05 -0600 Subject: [PATCH 7/8] links are broken, display fully qualified attributes --- Doc/library/test.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/test.rst b/Doc/library/test.rst index 2ef718ceaf12cd..758f38576cd497 100644 --- a/Doc/library/test.rst +++ b/Doc/library/test.rst @@ -1719,13 +1719,13 @@ The :mod:`test.support.warnings_helper` module provides support for warnings tes On entry to the context manager, a :class:`WarningsRecorder` instance is returned. The underlying warnings list from :func:`~warnings.catch_warnings` is available via the recorder object's - :attr:`~WarningsRecorder.warnings` attribute. As a convenience, the attributes of the object + :attr:`WarningsRecorder.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:`~WarningsRecorder.reset` method, which clears the + The recorder object also has a :meth:`WarningsRecorder.reset` method, which clears the warnings list. The context manager is designed to be used like this:: From 38194c5be6012ae6f2bcaadb91367f07e4b1531e Mon Sep 17 00:00:00 2001 From: Skip Montanaro Date: Fri, 23 Feb 2024 19:22:14 -0600 Subject: [PATCH 8/8] Apply suggestions from code review Co-authored-by: C.A.M. Gerlach --- Doc/library/test.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/test.rst b/Doc/library/test.rst index 758f38576cd497..ae54e51be437fd 100644 --- a/Doc/library/test.rst +++ b/Doc/library/test.rst @@ -169,7 +169,7 @@ test.regrtest` used in previous Python versions still works. Running the script by itself automatically starts running all regression tests in the :mod:`test` package. It does this by finding all modules in the package whose name starts with ``test_``, importing them, and executing the function -:func:`!test_main` if present or loading the tests via +``test_main`` if present or loading the tests via unittest.TestLoader.loadTestsFromModule if ``test_main`` does not exist. The names of tests to execute may also be passed to the script. Specifying a single regression test (:program:`python -m test test_spam`) will minimize output and @@ -372,7 +372,7 @@ The :mod:`test.support` module defines the following constants: .. data:: MISSING_C_DOCSTRINGS Set to ``True`` if Python is built without docstrings (the - :c:macro:`!WITH_DOC_STRINGS` macro is not defined). + :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.