[Python-checkins] [3.11] gh-106948: Docs: Disable links for C standard library functions, OS utility functions and system calls (#107062) (#107157)
erlend-aasland
webhook-mailer at python.org
Sun Jul 23 17:49:51 EDT 2023
https://github.com/python/cpython/commit/b3e600a632d018ce868bec0ef26116b8637fe8e0
commit: b3e600a632d018ce868bec0ef26116b8637fe8e0
branch: 3.11
author: Erlend E. Aasland <erlend at python.org>
committer: erlend-aasland <erlend.aasland at protonmail.com>
date: 2023-07-23T23:49:48+02:00
summary:
[3.11] gh-106948: Docs: Disable links for C standard library functions, OS utility functions and system calls (#107062) (#107157)
(cherry picked from commit b447e19e720e6781025432a40eb72b1cc93ac944)
Co-authored-by: Serhiy Storchaka <storchaka at gmail.com>
files:
M Doc/c-api/exceptions.rst
M Doc/c-api/sys.rst
M Doc/conf.py
M Doc/howto/instrumentation.rst
M Doc/library/mailbox.rst
M Doc/library/os.rst
M Doc/library/select.rst
M Doc/library/signal.rst
M Doc/whatsnew/2.6.rst
M Doc/whatsnew/2.7.rst
M Misc/NEWS.d/3.10.0a1.rst
diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst
index 5dad596f6197f..6ca53bd29f9e8 100644
--- a/Doc/c-api/exceptions.rst
+++ b/Doc/c-api/exceptions.rst
@@ -152,7 +152,7 @@ For convenience, some of these functions will always return a
This is a convenience function to raise an exception when a C library function
has returned an error and set the C variable :c:data:`errno`. It constructs a
tuple object whose first item is the integer :c:data:`errno` value and whose
- second item is the corresponding error message (gotten from :c:func:`strerror`),
+ second item is the corresponding error message (gotten from :c:func:`!strerror`),
and then calls ``PyErr_SetObject(type, object)``. On Unix, when the
:c:data:`errno` value is :c:macro:`EINTR`, indicating an interrupted system call,
this calls :c:func:`PyErr_CheckSignals`, and if that set the error indicator,
diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst
index 305a315549d15..57a36c038b592 100644
--- a/Doc/c-api/sys.rst
+++ b/Doc/c-api/sys.rst
@@ -104,7 +104,7 @@ Operating System Utilities
.. c:function:: PyOS_sighandler_t PyOS_getsig(int i)
Return the current signal handler for signal *i*. This is a thin wrapper around
- either :c:func:`sigaction` or :c:func:`signal`. Do not call those functions
+ either :c:func:`!sigaction` or :c:func:`!signal`. Do not call those functions
directly! :c:type:`PyOS_sighandler_t` is a typedef alias for :c:expr:`void
(\*)(int)`.
@@ -112,7 +112,7 @@ Operating System Utilities
.. c:function:: PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)
Set the signal handler for signal *i* to be *h*; return the old signal handler.
- This is a thin wrapper around either :c:func:`sigaction` or :c:func:`signal`. Do
+ This is a thin wrapper around either :c:func:`!sigaction` or :c:func:`!signal`. Do
not call those functions directly! :c:type:`PyOS_sighandler_t` is a typedef
alias for :c:expr:`void (\*)(int)`.
diff --git a/Doc/conf.py b/Doc/conf.py
index c082717efda72..28c35f2b0a234 100644
--- a/Doc/conf.py
+++ b/Doc/conf.py
@@ -72,6 +72,24 @@
exclude_patterns.append(venvdir + '/*')
nitpick_ignore = [
+ # Standard C functions
+ ('c:func', 'calloc'),
+ ('c:func', 'dlopen'),
+ ('c:func', 'exec'),
+ ('c:func', 'fcntl'),
+ ('c:func', 'fork'),
+ ('c:func', 'free'),
+ ('c:func', 'gmtime'),
+ ('c:func', 'localtime'),
+ ('c:func', 'main'),
+ ('c:func', 'malloc'),
+ ('c:func', 'printf'),
+ ('c:func', 'realloc'),
+ ('c:func', 'snprintf'),
+ ('c:func', 'sprintf'),
+ ('c:func', 'stat'),
+ ('c:func', 'system'),
+ ('c:func', 'vsnprintf'),
# Standard C types
('c:type', 'FILE'),
('c:type', '__int'),
diff --git a/Doc/howto/instrumentation.rst b/Doc/howto/instrumentation.rst
index 4ce15c69dac90..875f846aad005 100644
--- a/Doc/howto/instrumentation.rst
+++ b/Doc/howto/instrumentation.rst
@@ -292,11 +292,11 @@ Available static markers
.. object:: function__return(str filename, str funcname, int lineno)
- This marker is the converse of :c:func:`function__entry`, and indicates that
+ This marker is the converse of :c:func:`!function__entry`, and indicates that
execution of a Python function has ended (either via ``return``, or via an
exception). It is only triggered for pure-Python (bytecode) functions.
- The arguments are the same as for :c:func:`function__entry`
+ The arguments are the same as for :c:func:`!function__entry`
.. object:: line(str filename, str funcname, int lineno)
@@ -304,7 +304,7 @@ Available static markers
the equivalent of line-by-line tracing with a Python profiler. It is
not triggered within C functions.
- The arguments are the same as for :c:func:`function__entry`.
+ The arguments are the same as for :c:func:`!function__entry`.
.. object:: gc__start(int generation)
diff --git a/Doc/library/mailbox.rst b/Doc/library/mailbox.rst
index 56908dedea1b4..91df07d914cae 100644
--- a/Doc/library/mailbox.rst
+++ b/Doc/library/mailbox.rst
@@ -477,7 +477,7 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF.
unlock()
Three locking mechanisms are used---dot locking and, if available, the
- :c:func:`flock` and :c:func:`lockf` system calls.
+ :c:func:`!flock` and :c:func:`!lockf` system calls.
.. seealso::
@@ -588,7 +588,7 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF.
unlock()
Three locking mechanisms are used---dot locking and, if available, the
- :c:func:`flock` and :c:func:`lockf` system calls. For MH mailboxes, locking
+ :c:func:`!flock` and :c:func:`!lockf` system calls. For MH mailboxes, locking
the mailbox means locking the :file:`.mh_sequences` file and, only for the
duration of any operations that affect them, locking individual message
files.
@@ -686,7 +686,7 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF.
unlock()
Three locking mechanisms are used---dot locking and, if available, the
- :c:func:`flock` and :c:func:`lockf` system calls.
+ :c:func:`!flock` and :c:func:`!lockf` system calls.
.. seealso::
@@ -737,7 +737,7 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF.
unlock()
Three locking mechanisms are used---dot locking and, if available, the
- :c:func:`flock` and :c:func:`lockf` system calls.
+ :c:func:`!flock` and :c:func:`!lockf` system calls.
.. seealso::
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 9d6d02652db90..dcb4e7d3ab259 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -665,14 +665,14 @@ process and user.
.. function:: getsid(pid, /)
- Call the system call :c:func:`getsid`. See the Unix manual for the semantics.
+ Call the system call :c:func:`!getsid`. See the Unix manual for the semantics.
.. availability:: Unix, not Emscripten, not WASI.
.. function:: setsid()
- Call the system call :c:func:`setsid`. See the Unix manual for the semantics.
+ Call the system call :c:func:`!setsid`. See the Unix manual for the semantics.
.. availability:: Unix, not Emscripten, not WASI.
@@ -690,7 +690,7 @@ process and user.
.. function:: strerror(code, /)
Return the error message corresponding to the error code in *code*.
- On platforms where :c:func:`strerror` returns ``NULL`` when given an unknown
+ On platforms where :c:func:`!strerror` returns ``NULL`` when given an unknown
error number, :exc:`ValueError` is raised.
diff --git a/Doc/library/select.rst b/Doc/library/select.rst
index b0891b0c8f584..c2941e628d9d7 100644
--- a/Doc/library/select.rst
+++ b/Doc/library/select.rst
@@ -6,10 +6,10 @@
--------------
-This module provides access to the :c:func:`select` and :c:func:`poll` functions
-available in most operating systems, :c:func:`devpoll` available on
-Solaris and derivatives, :c:func:`epoll` available on Linux 2.5+ and
-:c:func:`kqueue` available on most BSD.
+This module provides access to the :c:func:`!select` and :c:func:`!poll` functions
+available in most operating systems, :c:func:`!devpoll` available on
+Solaris and derivatives, :c:func:`!epoll` available on Linux 2.5+ and
+:c:func:`!kqueue` available on most BSD.
Note that on Windows, it only works for sockets; on other operating systems,
it also works for other file types (in particular, on Unix, it works on pipes).
It cannot be used on regular files to determine whether a file has grown since
@@ -41,10 +41,10 @@ The module defines the following:
polling object; see section :ref:`devpoll-objects` below for the
methods supported by devpoll objects.
- :c:func:`devpoll` objects are linked to the number of file
+ :c:func:`!devpoll` objects are linked to the number of file
descriptors allowed at the time of instantiation. If your program
- reduces this value, :c:func:`devpoll` will fail. If your program
- increases this value, :c:func:`devpoll` may return an
+ reduces this value, :c:func:`!devpoll` will fail. If your program
+ increases this value, :c:func:`!devpoll` may return an
incomplete list of active file descriptors.
The new file descriptor is :ref:`non-inheritable <fd_inheritance>`.
@@ -62,7 +62,7 @@ The module defines the following:
*sizehint* informs epoll about the expected number of events to be
registered. It must be positive, or ``-1`` to use the default. It is only
- used on older systems where :c:func:`epoll_create1` is not available;
+ used on older systems where :c:func:`!epoll_create1` is not available;
otherwise it has no effect (though its value is still checked).
*flags* is deprecated and completely ignored. However, when supplied, its
@@ -117,7 +117,7 @@ The module defines the following:
.. function:: select(rlist, wlist, xlist[, timeout])
- This is a straightforward interface to the Unix :c:func:`select` system call.
+ This is a straightforward interface to the Unix :c:func:`!select` system call.
The first three arguments are iterables of 'waitable objects': either
integers representing file descriptors or objects with a parameterless method
named :meth:`~io.IOBase.fileno` returning such an integer:
@@ -154,7 +154,7 @@ The module defines the following:
.. index:: single: WinSock
File objects on Windows are not acceptable, but sockets are. On Windows,
- the underlying :c:func:`select` function is provided by the WinSock
+ the underlying :c:func:`!select` function is provided by the WinSock
library, and does not handle file descriptors that don't originate from
WinSock.
@@ -169,7 +169,7 @@ The module defines the following:
The minimum number of bytes which can be written without blocking to a pipe
when the pipe has been reported as ready for writing by :func:`~select.select`,
- :func:`poll` or another interface in this module. This doesn't apply
+ :func:`!poll` or another interface in this module. This doesn't apply
to other kind of file-like objects such as sockets.
This value is guaranteed by POSIX to be at least 512.
@@ -184,11 +184,11 @@ The module defines the following:
``/dev/poll`` Polling Objects
-----------------------------
-Solaris and derivatives have ``/dev/poll``. While :c:func:`select` is
-O(highest file descriptor) and :c:func:`poll` is O(number of file
+Solaris and derivatives have ``/dev/poll``. While :c:func:`!select` is
+O(highest file descriptor) and :c:func:`!poll` is O(number of file
descriptors), ``/dev/poll`` is O(active file descriptors).
-``/dev/poll`` behaviour is very close to the standard :c:func:`poll`
+``/dev/poll`` behaviour is very close to the standard :c:func:`!poll`
object.
@@ -222,7 +222,7 @@ object.
implement :meth:`!fileno`, so they can also be used as the argument.
*eventmask* is an optional bitmask describing the type of events you want to
- check for. The constants are the same that with :c:func:`poll`
+ check for. The constants are the same that with :c:func:`!poll`
object. The default value is a combination of the constants :const:`POLLIN`,
:const:`POLLPRI`, and :const:`POLLOUT`.
@@ -231,7 +231,7 @@ object.
Registering a file descriptor that's already registered is not an
error, but the result is undefined. The appropriate action is to
unregister or modify it first. This is an important difference
- compared with :c:func:`poll`.
+ compared with :c:func:`!poll`.
.. method:: devpoll.modify(fd[, eventmask])
@@ -376,13 +376,13 @@ Edge and Level Trigger Polling (epoll) Objects
Polling Objects
---------------
-The :c:func:`poll` system call, supported on most Unix systems, provides better
+The :c:func:`!poll` system call, supported on most Unix systems, provides better
scalability for network servers that service many, many clients at the same
-time. :c:func:`poll` scales better because the system call only requires listing
-the file descriptors of interest, while :c:func:`select` builds a bitmap, turns
+time. :c:func:`!poll` scales better because the system call only requires listing
+the file descriptors of interest, while :c:func:`!select` builds a bitmap, turns
on bits for the fds of interest, and then afterward the whole bitmap has to be
-linearly scanned again. :c:func:`select` is O(highest file descriptor), while
-:c:func:`poll` is O(number of file descriptors).
+linearly scanned again. :c:func:`!select` is O(highest file descriptor), while
+:c:func:`!poll` is O(number of file descriptors).
.. method:: poll.register(fd[, eventmask])
diff --git a/Doc/library/signal.rst b/Doc/library/signal.rst
index 523d1ac500136..e53315bee3ea3 100644
--- a/Doc/library/signal.rst
+++ b/Doc/library/signal.rst
@@ -562,7 +562,7 @@ The :mod:`signal` module defines the following functions:
Note that installing a signal handler with :func:`signal` will reset the
restart behaviour to interruptible by implicitly calling
- :c:func:`siginterrupt` with a true *flag* value for the given signal.
+ :c:func:`!siginterrupt` with a true *flag* value for the given signal.
.. function:: signal(signalnum, handler)
diff --git a/Doc/whatsnew/2.6.rst b/Doc/whatsnew/2.6.rst
index 72a273fdd8d12..2b8fa1546a588 100644
--- a/Doc/whatsnew/2.6.rst
+++ b/Doc/whatsnew/2.6.rst
@@ -2289,7 +2289,7 @@ changes, or look through the Subversion logs for all the details.
(Contributed by Raymond Hettinger; :issue:`1861`.)
* The :mod:`select` module now has wrapper functions
- for the Linux :c:func:`epoll` and BSD :c:func:`kqueue` system calls.
+ for the Linux :c:func:`!epoll` and BSD :c:func:`!kqueue` system calls.
:meth:`modify` method was added to the existing :class:`poll`
objects; ``pollobj.modify(fd, eventmask)`` takes a file descriptor
or file object and an event mask, modifying the recorded event mask
@@ -2328,7 +2328,7 @@ changes, or look through the Subversion logs for all the details.
one for reading and one for writing. The writable descriptor
will be passed to :func:`set_wakeup_fd`, and the readable descriptor
will be added to the list of descriptors monitored by the event loop via
- :c:func:`select` or :c:func:`poll`.
+ :c:func:`!select` or :c:func:`!poll`.
On receiving a signal, a byte will be written and the main event loop
will be woken up, avoiding the need to poll.
@@ -2982,7 +2982,7 @@ Changes to Python's build process and to the C API include:
* Python now must be compiled with C89 compilers (after 19
years!). This means that the Python source tree has dropped its
- own implementations of :c:func:`memmove` and :c:func:`strerror`, which
+ own implementations of :c:func:`!memmove` and :c:func:`!strerror`, which
are in the C89 standard library.
* Python 2.6 can be built with Microsoft Visual Studio 2008 (version
diff --git a/Doc/whatsnew/2.7.rst b/Doc/whatsnew/2.7.rst
index ba6aebafd59d9..09798ca82d261 100644
--- a/Doc/whatsnew/2.7.rst
+++ b/Doc/whatsnew/2.7.rst
@@ -355,7 +355,7 @@ added as a more powerful replacement for the
This means Python now supports three different modules for parsing
command-line arguments: :mod:`getopt`, :mod:`optparse`, and
:mod:`argparse`. The :mod:`getopt` module closely resembles the C
-library's :c:func:`getopt` function, so it remains useful if you're writing a
+library's :c:func:`!getopt` function, so it remains useful if you're writing a
Python prototype that will eventually be rewritten in C.
:mod:`optparse` becomes redundant, but there are no plans to remove it
because there are many scripts still using it, and there's no
diff --git a/Misc/NEWS.d/3.10.0a1.rst b/Misc/NEWS.d/3.10.0a1.rst
index 58e57a951ae60..2ef511c6e227e 100644
--- a/Misc/NEWS.d/3.10.0a1.rst
+++ b/Misc/NEWS.d/3.10.0a1.rst
@@ -228,8 +228,8 @@ format string in f-string and :meth:`str.format`.
.. section: Core and Builtins
The implementation of :func:`signal.siginterrupt` now uses
-:c:func:`sigaction` (if it is available in the system) instead of the
-deprecated :c:func:`siginterrupt`. Patch by Pablo Galindo.
+:c:func:`!sigaction` (if it is available in the system) instead of the
+deprecated :c:func:`!siginterrupt`. Patch by Pablo Galindo.
..
More information about the Python-checkins
mailing list