Skip to content

gh-101100: Fix dangling references in test.rst #114958

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

Open
wants to merge 9 commits into
base: main
Choose a base branch
from
+13 −14
Open

gh-101100: Fix dangling references in test.rst #114958

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
cbd26fc
Fix dangling references in test.rst
smontanaro Feb 3, 2024
b9d12fd
add to test.rst change pr
smontanaro Feb 12, 2024
a6cb747
Merge branch 'main' into patch-9
smontanaro Feb 16, 2024
2d479c6
minor nit - I think this phrase read better before
smontanaro Feb 17, 2024
f2252d0
restore Py_DEBUG ref
smontanaro Feb 22, 2024
cccb427
connect to the (undocumented) WarningsRecorder.reset method
smontanaro Feb 23, 2024
c23ac54
correct reference to WarningsRecorder class
smontanaro Feb 23, 2024
b3acb26
links are broken, display fully qualified attributes
smontanaro Feb 23, 2024
38194c5
Apply suggestions from code review
smontanaro Feb 24, 2024
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
26 changes: 13 additions & 13 deletions Doc/library/test.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -324,9 +324,9 @@ 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, that is, if
Python was :ref:`built in debug mode <debug-build>`.
True if Python was built with the :c:macro:`Py_DEBUG` macro defined;
that is, if Python was :ref:`built in debug mode <debug-build>`
(:option:`./configure --with-pydebug <--with-pydebug>`).

.. versionadded:: 3.12

Expand Down Expand Up @@ -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`.
Copy link
Member

Choose a reason for hiding this comment

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

This is a constant in an underscored name, test module, so it's not required to document it, but given the entire description of this function is "return ", which doesn't seem terribly useful if said constant is entirely undocumented, it seems worth at least briefly touching on what that actually means here (which the warning is a canary for).

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I'm guessing the reference must be suppressed in some other way, because no hyperlink shows up in the generated HTML (and no warning is emitted by Sphinx). You'll have to take this up with someone above my pay grade.



.. function:: requires(resource, msg=None)
Expand Down Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

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

This is an purposefully undocumented module, I'm guessing?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I couldn't begin to guess why it's undocumented. Maybe it's meant to be semantically identical to the relevant threading module synchronization primitives?

__all__ = [
    'Lock', 'RLock', 'Semaphore', 'BoundedSemaphore', 'Condition', 'Event'
    ]

I see this comment preceding an import which it suggests might fail:

# Try to import the mp.synchronize module cleanly, if it fails
# raise ImportError for platforms lacking a working sem_open implementation.
# See issue 3770

There is also a note about this possibility in the multiprocessing module documentation.

there is no available semaphore implementation, or if creating a lock raises
an :exc:`OSError`.

Expand Down Expand Up @@ -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.
Copy link
Member

@AlexWaygood AlexWaygood Feb 4, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

The better way to fix these two warnings would be to add documentation for these constants in the socket module docs, if that documentation doesn't already exist. Then we'll also be able to reference these constants in the docs for other modules, as will users of intersphinx outside of CPython

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Perhaps, but ISTR the socket module doc explicitly mentions a whole raft of constants as coming from the underlying C socket(2) implementation. That is presumably to keep from duplicating underlying canonical documentation and to avoid introducing mistakes (think platform dependencies).

I understand it would be great to have the Python library docs completely self-contained, but I don't think that's the best way to go in some cases.

Copy link
Member

Choose a reason for hiding this comment

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

Fair point, there are probably too many in the socket module for us to list them all out explicitly!

Copy link
Member

Choose a reason for hiding this comment

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

In that case, we should explicitly list them in conf.py as silenced with a comment explaining why, to avoid introducing noise here, making it easy to change the decision in the future, and ensuring we have a consistent central record of it.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Given that many of the possible constants are only given in the socket module doc as wildcards (e.g., SO_*) I don't think that will work unless you only want to list a known (small) subset.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

This stuff is really at the fringe between low-level Unix stuff and the relevant Python wrappers. According to Wikipedia, the first edition of Stevens' Unix Network Programming (the network programming bible when I was a wee lad) is 768 pages long. It's not at all clear to me that there's much to be gained by documenting a few socket options. It's not really going to flatten the socket programming learning curve much. Programmers will have to delve into the C socket documentation to do anything serious anyway.

Sorry about the soapbox.

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.
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -1716,16 +1716,16 @@ 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
: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:`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::
Expand Down
1 change: 0 additions & 1 deletion Doc/tools/.nitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,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
Expand Down
Loading