mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-18 15:51:23 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

[3.11] gh-95415: Make availability directive consistent (GH-95416) (GH-95438)

Browse source 
Co-authored-by: Christian Heimes <christian@python.org>
This commit is contained in:
Christian Heimes 2022-08-01 14:26:19 +02:00 • committed by GitHub
parent ad2872f5fd
commit 9af9ea28e7
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
17 changed files with 207 additions and 100 deletions
Download patch file Download diff file Expand all files Collapse all files

4
Doc/library/_thread.rst
View file

@ -140,7 +140,9 @@ This module defines the following constants and functions:
information (4 KiB pages are common; using multiples of 4096 for the stack size is information (4 KiB pages are common; using multiples of 4096 for the stack size is
the suggested approach in the absence of more specific information). the suggested approach in the absence of more specific information).
.. availability:: Windows, systems with POSIX threads. .. availability:: Windows, pthreads.
Unix platforms with POSIX threads support.
.. data:: TIMEOUT_MAX .. data:: TIMEOUT_MAX

2
Doc/library/codecs.rst
View file

@ -1530,7 +1530,7 @@ functions can be used directly if desired.
This module implements the ANSI codepage (CP_ACP). This module implements the ANSI codepage (CP_ACP).
.. availability:: Windows only. .. availability:: Windows.
.. versionchanged:: 3.3 .. versionchanged:: 3.3
Support any error handler. Support any error handler.

2
Doc/library/crypt.rst
View file

@ -36,7 +36,7 @@ the :manpage:`crypt(3)` routine in the running system. Therefore, any
extensions available on the current implementation will also be available on extensions available on the current implementation will also be available on
this module. this module.
.. availability:: Unix. Not available on VxWorks. .. availability:: Unix, not VxWorks.
Hashing Methods Hashing Methods
--------------- ---------------

4
Doc/library/intro.rst
View file

@ -60,3 +60,7 @@ Notes on availability
* If not separately noted, all functions that claim "Availability: Unix" are * If not separately noted, all functions that claim "Availability: Unix" are
supported on macOS, which builds on a Unix core. supported on macOS, which builds on a Unix core.
* If an availability note contains both a minimum Kernel version and a minimum
libc version, then both conditions must hold. For example a feature with note
*Availability: Linux >= 3.17 with glibc >= 2.27* requires both Linux 3.17 or
newer and glibc 2.27 or newer.

75
Doc/library/os.rst
View file

@ -301,7 +301,7 @@ process and user.
and ``'surrogateescape'`` error handler. Use :func:`os.getenvb` if you and ``'surrogateescape'`` error handler. Use :func:`os.getenvb` if you
would like to use a different encoding. would like to use a different encoding.
.. availability:: most flavors of Unix, Windows. .. availability:: Unix, Windows.
.. function:: getenvb(key, default=None) .. function:: getenvb(key, default=None)
@ -316,7 +316,7 @@ process and user.
:func:`getenvb` is only available if :data:`supports_bytes_environ` :func:`getenvb` is only available if :data:`supports_bytes_environ`
is ``True``. is ``True``.
.. availability:: most flavors of Unix. .. availability:: Unix.
.. versionadded:: 3.2 .. versionadded:: 3.2
@ -706,7 +706,7 @@ process and user.
:func:`socket.gethostname` or even :func:`socket.gethostname` or even
``socket.gethostbyaddr(socket.gethostname())``. ``socket.gethostbyaddr(socket.gethostname())``.
.. availability:: recent flavors of Unix. .. availability:: Unix.
.. versionchanged:: 3.3 .. versionchanged:: 3.3
Return type changed from a tuple to a tuple-like object Return type changed from a tuple to a tuple-like object
@ -810,7 +810,7 @@ as internal buffering of data.
The return value is the amount of bytes copied. This could be less than the The return value is the amount of bytes copied. This could be less than the
amount requested. amount requested.
.. availability:: Linux kernel >= 4.5 or glibc >= 2.27. .. availability:: Linux >= 4.5 with glibc >= 2.27.
.. versionadded:: 3.8 .. versionadded:: 3.8
@ -1150,7 +1150,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
descriptors are :ref:`non-inheritable <fd_inheritance>`. For a (slightly) more descriptors are :ref:`non-inheritable <fd_inheritance>`. For a (slightly) more
portable approach, use the :mod:`pty` module. portable approach, use the :mod:`pty` module.
.. availability:: some flavors of Unix. .. availability:: Unix.
.. versionchanged:: 3.4 .. versionchanged:: 3.4
The new file descriptors are now non-inheritable. The new file descriptors are now non-inheritable.
@ -1176,7 +1176,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
Return a pair of file descriptors ``(r, w)`` usable for reading and writing, Return a pair of file descriptors ``(r, w)`` usable for reading and writing,
respectively. respectively.
.. availability:: some flavors of Unix. .. availability:: Unix.
.. versionadded:: 3.3 .. versionadded:: 3.3
@ -1255,9 +1255,9 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
Combine the functionality of :func:`os.readv` and :func:`os.pread`. Combine the functionality of :func:`os.readv` and :func:`os.pread`.
.. availability:: Linux 2.6.30 and newer, FreeBSD 6.0 and newer, .. availability:: Linux >= 2.6.30, FreeBSD >= 6.0, OpenBSD >= 2.7, AIX >= 7.1.
OpenBSD 2.7 and newer, AIX 7.1 and newer. Using flags requires
Linux 4.6 or newer. Using flags requires Linux >= 4.6.
.. versionadded:: 3.7 .. versionadded:: 3.7
@ -1272,7 +1272,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
If no bytes were read, it will return ``-1`` and set errno to If no bytes were read, it will return ``-1`` and set errno to
:data:`errno.EAGAIN`. :data:`errno.EAGAIN`.
.. availability:: Linux 4.14 and newer. .. availability:: Linux >= 4.14.
.. versionadded:: 3.7 .. versionadded:: 3.7
@ -1286,7 +1286,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
Currently, on Linux, this feature is usable only on a file descriptor opened Currently, on Linux, this feature is usable only on a file descriptor opened
using the :data:`O_DIRECT` flag. using the :data:`O_DIRECT` flag.
.. availability:: Linux 4.6 and newer. .. availability:: Linux >= 4.6.
.. versionadded:: 3.7 .. versionadded:: 3.7
@ -1325,9 +1325,9 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
Combine the functionality of :func:`os.writev` and :func:`os.pwrite`. Combine the functionality of :func:`os.writev` and :func:`os.pwrite`.
.. availability:: Linux 2.6.30 and newer, FreeBSD 6.0 and newer, .. availability:: Linux >= 2.6.30, FreeBSD >= 6.0, OpenBSD >= 2.7, AIX >= 7.1.
OpenBSD 2.7 and newer, AIX 7.1 and newer. Using flags requires
Linux 4.7 or newer. Using flags requires Linux >= 4.6.
.. versionadded:: 3.7 .. versionadded:: 3.7
@ -1337,7 +1337,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
Provide a per-write equivalent of the :data:`O_DSYNC` :func:`os.open` flag. Provide a per-write equivalent of the :data:`O_DSYNC` :func:`os.open` flag.
This flag effect applies only to the data range written by the system call. This flag effect applies only to the data range written by the system call.
.. availability:: Linux 4.7 and newer. .. availability:: Linux >= 4.7.
.. versionadded:: 3.7 .. versionadded:: 3.7
@ -1347,7 +1347,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
Provide a per-write equivalent of the :data:`O_SYNC` :func:`os.open` flag. Provide a per-write equivalent of the :data:`O_SYNC` :func:`os.open` flag.
This flag effect applies only to the data range written by the system call. This flag effect applies only to the data range written by the system call.
.. availability:: Linux 4.7 and newer. .. availability:: Linux >= 4.7.
.. versionadded:: 3.7 .. versionadded:: 3.7
@ -1361,7 +1361,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
appended to the end of the file. However, if the *offset* argument is appended to the end of the file. However, if the *offset* argument is
``-1``, the current file *offset* is updated. ``-1``, the current file *offset* is updated.
.. availability:: Linux 4.16 and newer. .. availability:: Linux >= 4.16.
.. versionadded:: 3.10 .. versionadded:: 3.10
@ -1481,7 +1481,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
make sense to block because there are no writers connected to the write end make sense to block because there are no writers connected to the write end
of the pipe. of the pipe.
.. availability:: Linux kernel >= 2.6.17 and glibc >= 2.5 .. availability:: Linux >= 2.6.17 with glibc >= 2.5
.. versionadded:: 3.10 .. versionadded:: 3.10
@ -3320,7 +3320,7 @@ features:
the file descriptor, and as such multiple files can have the same name the file descriptor, and as such multiple files can have the same name
without any side effects. without any side effects.
.. availability:: Linux 3.17 or newer with glibc 2.27 or newer. .. availability:: Linux >= 3.17 with glibc >= 2.27.
.. versionadded:: 3.8 .. versionadded:: 3.8
@ -3345,8 +3345,9 @@ features:
These flags can be passed to :func:`memfd_create`. These flags can be passed to :func:`memfd_create`.
.. availability:: Linux 3.17 or newer with glibc 2.27 or newer. The .. availability:: Linux >= 3.17 with glibc >= 2.27
``MFD_HUGE*`` flags are only available since Linux 4.14.
The ``MFD_HUGE*`` flags are only available since Linux 4.14.
.. versionadded:: 3.8 .. versionadded:: 3.8
@ -3398,7 +3399,7 @@ features:
finally: finally:
os.close(fd) os.close(fd)
.. availability:: Linux 2.6.27 or newer with glibc 2.8 or newer. .. availability:: Linux >= 2.6.27 with glibc >= 2.8
.. versionadded:: 3.10 .. versionadded:: 3.10
@ -3407,7 +3408,7 @@ features:
Read value from an :func:`eventfd` file descriptor and return a 64 bit Read value from an :func:`eventfd` file descriptor and return a 64 bit
unsigned int. The function does not verify that *fd* is an :func:`eventfd`. unsigned int. The function does not verify that *fd* is an :func:`eventfd`.
.. availability:: See :func:`eventfd` .. availability:: Linux >= 2.6.27
.. versionadded:: 3.10 .. versionadded:: 3.10
@ -3416,7 +3417,7 @@ features:
Add value to an :func:`eventfd` file descriptor. *value* must be a 64 bit Add value to an :func:`eventfd` file descriptor. *value* must be a 64 bit
unsigned int. The function does not verify that *fd* is an :func:`eventfd`. unsigned int. The function does not verify that *fd* is an :func:`eventfd`.
.. availability:: See :func:`eventfd` .. availability:: Linux >= 2.6.27
.. versionadded:: 3.10 .. versionadded:: 3.10
@ -3424,7 +3425,7 @@ features:
Set close-on-exec flag for new :func:`eventfd` file descriptor. Set close-on-exec flag for new :func:`eventfd` file descriptor.
.. availability:: See :func:`eventfd` .. availability:: Linux >= 2.6.27
.. versionadded:: 3.10 .. versionadded:: 3.10
@ -3433,7 +3434,7 @@ features:
Set :const:`O_NONBLOCK` status flag for new :func:`eventfd` file Set :const:`O_NONBLOCK` status flag for new :func:`eventfd` file
descriptor. descriptor.
.. availability:: See :func:`eventfd` .. availability:: Linux >= 2.6.27
.. versionadded:: 3.10 .. versionadded:: 3.10
@ -3442,7 +3443,7 @@ features:
Provide semaphore-like semantics for reads from a :func:`eventfd` file Provide semaphore-like semantics for reads from a :func:`eventfd` file
descriptor. On read the internal counter is decremented by one. descriptor. On read the internal counter is decremented by one.
.. availability:: Linux 2.6.30 or newer with glibc 2.8 or newer. .. availability:: Linux >= 2.6.30
.. versionadded:: 3.10 .. versionadded:: 3.10
@ -3847,7 +3848,7 @@ written in Python, such as a mail server's external command delivery program.
Calling ``forkpty()`` in a subinterpreter is no longer supported Calling ``forkpty()`` in a subinterpreter is no longer supported
(:exc:`RuntimeError` is raised). (:exc:`RuntimeError` is raised).
.. availability:: some flavors of Unix. .. availability:: Unix.
.. function:: kill(pid, sig) .. function:: kill(pid, sig)
@ -3904,7 +3905,7 @@ written in Python, such as a mail server's external command delivery program.
See the :manpage:`pidfd_open(2)` man page for more details. See the :manpage:`pidfd_open(2)` man page for more details.
.. availability:: Linux 5.3+ .. availability:: Linux >= 5.3
.. versionadded:: 3.9 .. versionadded:: 3.9
@ -4054,7 +4055,9 @@ written in Python, such as a mail server's external command delivery program.
.. versionadded:: 3.8 .. versionadded:: 3.8
.. availability:: See :func:`posix_spawn` documentation. .. availability:: POSIX
See :func:`posix_spawn` documentation.
.. function:: register_at_fork(*, before=None, after_in_parent=None, \ .. function:: register_at_fork(*, before=None, after_in_parent=None, \
@ -4154,7 +4157,9 @@ written in Python, such as a mail server's external command delivery program.
.. audit-event:: os.spawn mode,path,args,env os.spawnl .. audit-event:: os.spawn mode,path,args,env os.spawnl
.. availability:: Unix, Windows. :func:`spawnlp`, :func:`spawnlpe`, :func:`spawnvp` .. availability:: Unix, Windows.
:func:`spawnlp`, :func:`spawnlpe`, :func:`spawnvp`
and :func:`spawnvpe` are not available on Windows. :func:`spawnle` and and :func:`spawnvpe` are not available on Windows. :func:`spawnle` and
:func:`spawnve` are not thread-safe on Windows; we advise you to use the :func:`spawnve` are not thread-safe on Windows; we advise you to use the
:mod:`subprocess` module instead. :mod:`subprocess` module instead.
@ -4358,7 +4363,7 @@ written in Python, such as a mail server's external command delivery program.
This is a Linux-specific *idtype* that indicates that *id* is a file This is a Linux-specific *idtype* that indicates that *id* is a file
descriptor that refers to a process. descriptor that refers to a process.
.. availability:: Linux 5.4+ .. availability:: Linux >= 5.4
.. versionadded:: 3.9 .. versionadded:: 3.9
@ -4500,7 +4505,9 @@ written in Python, such as a mail server's external command delivery program.
This option causes child processes to be reported if they have been continued This option causes child processes to be reported if they have been continued
from a job control stop since their status was last reported. from a job control stop since their status was last reported.
.. availability:: some Unix systems. .. availability:: Unix.
Some Unix systems.
.. data:: WUNTRACED .. data:: WUNTRACED
@ -4906,7 +4913,7 @@ Random numbers
See also the `Linux getrandom() manual page See also the `Linux getrandom() manual page
<http://man7.org/linux/man-pages/man2/getrandom.2.html>`_. <http://man7.org/linux/man-pages/man2/getrandom.2.html>`_.
.. availability:: Linux 3.17 and newer. .. availability:: Linux >= 3.17.
.. versionadded:: 3.6 .. versionadded:: 3.6

2
Doc/library/pipes.rst
View file

@ -23,7 +23,7 @@ The :mod:`pipes` module defines a class to abstract the concept of a *pipeline*
Because the module uses :program:`/bin/sh` command lines, a POSIX or compatible Because the module uses :program:`/bin/sh` command lines, a POSIX or compatible
shell for :func:`os.system` and :func:`os.popen` is required. shell for :func:`os.system` and :func:`os.popen` is required.
.. availability:: Unix. Not available on VxWorks. .. availability:: Unix, not VxWorks.
The :mod:`pipes` module defines the following class: The :mod:`pipes` module defines the following class:

20
Doc/library/resource.rst
View file

@ -99,7 +99,7 @@ this module for those platforms.
.. audit-event:: resource.prlimit pid,resource,limits resource.prlimit .. audit-event:: resource.prlimit pid,resource,limits resource.prlimit
.. availability:: Linux 2.6.36 or later with glibc 2.13 or later. .. availability:: Linux >= 2.6.36 with glibc >= 2.13.
.. versionadded:: 3.4 .. versionadded:: 3.4
@ -185,7 +185,7 @@ platform.
The number of bytes that can be allocated for POSIX message queues. The number of bytes that can be allocated for POSIX message queues.
.. availability:: Linux 2.6.8 or later. .. availability:: Linux >= 2.6.8.
.. versionadded:: 3.4 .. versionadded:: 3.4
@ -194,7 +194,7 @@ platform.
The ceiling for the process's nice level (calculated as 20 - rlim_cur). The ceiling for the process's nice level (calculated as 20 - rlim_cur).
.. availability:: Linux 2.6.12 or later. .. availability:: Linux >= 2.6.12.
.. versionadded:: 3.4 .. versionadded:: 3.4
@ -203,7 +203,7 @@ platform.
The ceiling of the real-time priority. The ceiling of the real-time priority.
.. availability:: Linux 2.6.12 or later. .. availability:: Linux >= 2.6.12.
.. versionadded:: 3.4 .. versionadded:: 3.4
@ -213,7 +213,7 @@ platform.
The time limit (in microseconds) on CPU time that a process can spend The time limit (in microseconds) on CPU time that a process can spend
under real-time scheduling without making a blocking syscall. under real-time scheduling without making a blocking syscall.
.. availability:: Linux 2.6.25 or later. .. availability:: Linux >= 2.6.25.
.. versionadded:: 3.4 .. versionadded:: 3.4
@ -222,7 +222,7 @@ platform.
The number of signals which the process may queue. The number of signals which the process may queue.
.. availability:: Linux 2.6.8 or later. .. availability:: Linux >= 2.6.8.
.. versionadded:: 3.4 .. versionadded:: 3.4
@ -232,7 +232,7 @@ platform.
This limits the amount of network memory, and hence the amount of mbufs, This limits the amount of network memory, and hence the amount of mbufs,
that this user may hold at any time. that this user may hold at any time.
.. availability:: FreeBSD 9 or later. .. availability:: FreeBSD.
.. versionadded:: 3.4 .. versionadded:: 3.4
@ -245,7 +245,7 @@ platform.
`tuning(7) <https://www.freebsd.org/cgi/man.cgi?query=tuning&sektion=7>`__ `tuning(7) <https://www.freebsd.org/cgi/man.cgi?query=tuning&sektion=7>`__
for a complete description of this sysctl. for a complete description of this sysctl.
.. availability:: FreeBSD 9 or later. .. availability:: FreeBSD.
.. versionadded:: 3.4 .. versionadded:: 3.4
@ -253,7 +253,7 @@ platform.
The maximum number of pseudo-terminals created by this user id. The maximum number of pseudo-terminals created by this user id.
.. availability:: FreeBSD 9 or later. .. availability:: FreeBSD.
.. versionadded:: 3.4 .. versionadded:: 3.4
@ -261,7 +261,7 @@ platform.
The maximum number of kqueues this user id is allowed to create. The maximum number of kqueues this user id is allowed to create.
.. availability:: FreeBSD 11 or later. .. availability:: FreeBSD >= 11.
.. versionadded:: 3.10 .. versionadded:: 3.10

54
Doc/library/signal.rst
View file

@ -95,7 +95,9 @@ The signal module defines three enums:
:class:`enum.IntEnum` collection the constants :const:`SIG_BLOCK`, :const:`SIG_UNBLOCK` and :const:`SIG_SETMASK`. :class:`enum.IntEnum` collection the constants :const:`SIG_BLOCK`, :const:`SIG_UNBLOCK` and :const:`SIG_SETMASK`.
Availability: Unix. See the man page :manpage:`sigprocmask(2)` and .. availability:: Unix.
See the man page :manpage:`sigprocmask(2)` and
:manpage:`pthread_sigmask(3)` for further information. :manpage:`pthread_sigmask(3)` for further information.
.. versionadded:: 3.5 .. versionadded:: 3.5
@ -205,7 +207,9 @@ The variables defined in the :mod:`signal` module are:
Stack fault on coprocessor. The Linux kernel does not raise this signal: it Stack fault on coprocessor. The Linux kernel does not raise this signal: it
can only be raised in user space. can only be raised in user space.
.. availability:: Linux, on architectures where the signal is available. See .. availability:: Linux.
On architectures where the signal is available. See
the man page :manpage:`signal(7)` for further information. the man page :manpage:`signal(7)` for further information.
.. versionadded:: 3.11 .. versionadded:: 3.11
@ -337,8 +341,9 @@ The :mod:`signal` module defines the following functions:
delivered. If *time* is zero, no alarm is scheduled, and any scheduled alarm is delivered. If *time* is zero, no alarm is scheduled, and any scheduled alarm is
canceled. If the return value is zero, no alarm is currently scheduled. canceled. If the return value is zero, no alarm is currently scheduled.
.. availability:: Unix. See the man page :manpage:`alarm(2)` for further .. availability:: Unix.
information.
See the man page :manpage:`alarm(2)` for further information.
.. function:: getsignal(signalnum) .. function:: getsignal(signalnum)
@ -375,8 +380,9 @@ The :mod:`signal` module defines the following functions:
Cause the process to sleep until a signal is received; the appropriate handler Cause the process to sleep until a signal is received; the appropriate handler
will then be called. Returns nothing. will then be called. Returns nothing.
.. availability:: Unix. See the man page :manpage:`signal(2)` for further .. availability:: Unix.
information.
See the man page :manpage:`signal(2)` for further information.
See also :func:`sigwait`, :func:`sigwaitinfo`, :func:`sigtimedwait` and See also :func:`sigwait`, :func:`sigwaitinfo`, :func:`sigtimedwait` and
:func:`sigpending`. :func:`sigpending`.
@ -398,7 +404,7 @@ The :mod:`signal` module defines the following functions:
See the :manpage:`pidfd_send_signal(2)` man page for more information. See the :manpage:`pidfd_send_signal(2)` man page for more information.
.. availability:: Linux 5.1+ .. availability:: Linux >= 5.1
.. versionadded:: 3.9 .. versionadded:: 3.9
@ -421,8 +427,9 @@ The :mod:`signal` module defines the following functions:
.. audit-event:: signal.pthread_kill thread_id,signalnum signal.pthread_kill .. audit-event:: signal.pthread_kill thread_id,signalnum signal.pthread_kill
.. availability:: Unix. See the man page :manpage:`pthread_kill(3)` for further .. availability:: Unix.
information.
See the man page :manpage:`pthread_kill(3)` for further information.
See also :func:`os.kill`. See also :func:`os.kill`.
@ -454,7 +461,9 @@ The :mod:`signal` module defines the following functions:
:data:`SIGKILL` and :data:`SIGSTOP` cannot be blocked. :data:`SIGKILL` and :data:`SIGSTOP` cannot be blocked.
.. availability:: Unix. See the man page :manpage:`sigprocmask(2)` and .. availability:: Unix.
See the man page :manpage:`sigprocmask(2)` and
:manpage:`pthread_sigmask(3)` for further information. :manpage:`pthread_sigmask(3)` for further information.
See also :func:`pause`, :func:`sigpending` and :func:`sigwait`. See also :func:`pause`, :func:`sigpending` and :func:`sigwait`.
@ -542,8 +551,9 @@ The :mod:`signal` module defines the following functions:
calls will be restarted when interrupted by signal *signalnum*, otherwise calls will be restarted when interrupted by signal *signalnum*, otherwise
system calls will be interrupted. Returns nothing. system calls will be interrupted. Returns nothing.
.. availability:: Unix. See the man page :manpage:`siginterrupt(3)` .. availability:: Unix.
for further information.
See the man page :manpage:`siginterrupt(3)` for further information.
Note that installing a signal handler with :func:`signal` will reset the Note that installing a signal handler with :func:`signal` will reset the
restart behaviour to interruptible by implicitly calling restart behaviour to interruptible by implicitly calling
@ -583,8 +593,9 @@ The :mod:`signal` module defines the following functions:
thread (i.e., the signals which have been raised while blocked). Return the thread (i.e., the signals which have been raised while blocked). Return the
set of the pending signals. set of the pending signals.
.. availability:: Unix. See the man page :manpage:`sigpending(2)` for further .. availability:: Unix.
information.
See the man page :manpage:`sigpending(2)` for further information.
See also :func:`pause`, :func:`pthread_sigmask` and :func:`sigwait`. See also :func:`pause`, :func:`pthread_sigmask` and :func:`sigwait`.
@ -597,8 +608,9 @@ The :mod:`signal` module defines the following functions:
signals specified in the signal set *sigset*. The function accepts the signal signals specified in the signal set *sigset*. The function accepts the signal
(removes it from the pending list of signals), and returns the signal number. (removes it from the pending list of signals), and returns the signal number.
.. availability:: Unix. See the man page :manpage:`sigwait(3)` for further .. availability:: Unix.
information.
See the man page :manpage:`sigwait(3)` for further information.
See also :func:`pause`, :func:`pthread_sigmask`, :func:`sigpending`, See also :func:`pause`, :func:`pthread_sigmask`, :func:`sigpending`,
:func:`sigwaitinfo` and :func:`sigtimedwait`. :func:`sigwaitinfo` and :func:`sigtimedwait`.
@ -622,8 +634,9 @@ The :mod:`signal` module defines the following functions:
:attr:`si_errno`, :attr:`si_pid`, :attr:`si_uid`, :attr:`si_status`, :attr:`si_errno`, :attr:`si_pid`, :attr:`si_uid`, :attr:`si_status`,
:attr:`si_band`. :attr:`si_band`.
.. availability:: Unix. See the man page :manpage:`sigwaitinfo(2)` for further .. availability:: Unix.
information.
See the man page :manpage:`sigwaitinfo(2)` for further information.
See also :func:`pause`, :func:`sigwait` and :func:`sigtimedwait`. See also :func:`pause`, :func:`sigwait` and :func:`sigtimedwait`.
@ -641,8 +654,9 @@ The :mod:`signal` module defines the following functions:
specifying a timeout. If *timeout* is specified as :const:`0`, a poll is specifying a timeout. If *timeout* is specified as :const:`0`, a poll is
performed. Returns :const:`None` if a timeout occurs. performed. Returns :const:`None` if a timeout occurs.
.. availability:: Unix. See the man page :manpage:`sigtimedwait(2)` for further .. availability:: Unix.
information.
See the man page :manpage:`sigtimedwait(2)` for further information.
See also :func:`pause`, :func:`sigwait` and :func:`sigwaitinfo`. See also :func:`pause`, :func:`sigwait` and :func:`sigwaitinfo`.

44
Doc/library/socket.rst
View file

@ -165,7 +165,9 @@ created. Socket addresses are represented as follows:
- *feat* and *mask* are unsigned 32bit integers. - *feat* and *mask* are unsigned 32bit integers.
.. availability:: Linux 2.6.38, some algorithm types require more recent Kernels. .. availability:: Linux >= 2.6.38.
Some algorithm types require more recent Kernels.
.. versionadded:: 3.6 .. versionadded:: 3.6
@ -173,7 +175,9 @@ created. Socket addresses are represented as follows:
their hosts. The sockets are represented as a ``(CID, port)`` tuple their hosts. The sockets are represented as a ``(CID, port)`` tuple
where the context ID or CID and port are integers. where the context ID or CID and port are integers.
.. availability:: Linux >= 4.8 QEMU >= 2.8 ESX >= 4.0 ESX Workstation >= 6.5. .. availability:: Linux >= 3.9
See :manpage:`vsock(7)`
.. versionadded:: 3.7 .. versionadded:: 3.7
@ -221,7 +225,7 @@ created. Socket addresses are represented as follows:
``socket(AF_INET, SOCK_DGRAM, IPPROTO_UDPLITE)`` for IPv4 or ``socket(AF_INET, SOCK_DGRAM, IPPROTO_UDPLITE)`` for IPv4 or
``socket(AF_INET6, SOCK_DGRAM, IPPROTO_UDPLITE)`` for IPv6. ``socket(AF_INET6, SOCK_DGRAM, IPPROTO_UDPLITE)`` for IPv6.
.. availability:: Linux >= 2.6.20, FreeBSD >= 10.1-RELEASE .. availability:: Linux >= 2.6.20, FreeBSD >= 10.1
.. versionadded:: 3.9 .. versionadded:: 3.9
@ -1033,7 +1037,7 @@ The :mod:`socket` module also offers various network-related services:
both the value of *address_family* and the underlying implementation of both the value of *address_family* and the underlying implementation of
:c:func:`inet_pton`. :c:func:`inet_pton`.
.. availability:: Unix (maybe not all platforms), Windows. .. availability:: Unix, Windows.
.. versionchanged:: 3.4 .. versionchanged:: 3.4
Windows support added Windows support added
@ -1053,7 +1057,7 @@ The :mod:`socket` module also offers various network-related services:
length for the specified address family, :exc:`ValueError` will be raised. length for the specified address family, :exc:`ValueError` will be raised.
:exc:`OSError` is raised for errors from the call to :func:`inet_ntop`. :exc:`OSError` is raised for errors from the call to :func:`inet_ntop`.
.. availability:: Unix (maybe not all platforms), Windows. .. availability:: Unix, Windows.
.. versionchanged:: 3.4 .. versionchanged:: 3.4
Windows support added Windows support added
@ -1079,7 +1083,9 @@ The :mod:`socket` module also offers various network-related services:
buffer. Raises :exc:`OverflowError` if *length* is outside the buffer. Raises :exc:`OverflowError` if *length* is outside the
permissible range of values. permissible range of values.
.. availability:: most Unix platforms, possibly others. .. availability:: Unix.
Most Unix platforms.
.. versionadded:: 3.3 .. versionadded:: 3.3
@ -1100,7 +1106,9 @@ The :mod:`socket` module also offers various network-related services:
amount of ancillary data that can be received, since additional amount of ancillary data that can be received, since additional
data may be able to fit into the padding area. data may be able to fit into the padding area.
.. availability:: most Unix platforms, possibly others. .. availability:: Unix.
most Unix platforms.
.. versionadded:: 3.3 .. versionadded:: 3.3
@ -1199,7 +1207,10 @@ The :mod:`socket` module also offers various network-related services:
The *fds* parameter is a sequence of file descriptors. The *fds* parameter is a sequence of file descriptors.
Consult :meth:`sendmsg` for the documentation of these parameters. Consult :meth:`sendmsg` for the documentation of these parameters.
.. availability:: Unix supporting :meth:`~socket.sendmsg` and :const:`SCM_RIGHTS` mechanism. .. availability:: Unix.
Unix platforms supporting :meth:`~socket.sendmsg`
and :const:`SCM_RIGHTS` mechanism.
.. versionadded:: 3.9 .. versionadded:: 3.9
@ -1210,7 +1221,10 @@ The :mod:`socket` module also offers various network-related services:
Return ``(msg, list(fds), flags, addr)``. Return ``(msg, list(fds), flags, addr)``.
Consult :meth:`recvmsg` for the documentation of these parameters. Consult :meth:`recvmsg` for the documentation of these parameters.
.. availability:: Unix supporting :meth:`~socket.recvmsg` and :const:`SCM_RIGHTS` mechanism. .. availability:: Unix.
Unix platforms supporting :meth:`~socket.sendmsg`
and :const:`SCM_RIGHTS` mechanism.
.. versionadded:: 3.9 .. versionadded:: 3.9
@ -1545,7 +1559,9 @@ to sockets.
fds.frombytes(cmsg_data[:len(cmsg_data) - (len(cmsg_data) % fds.itemsize)]) fds.frombytes(cmsg_data[:len(cmsg_data) - (len(cmsg_data) % fds.itemsize)])
return msg, list(fds) return msg, list(fds)
.. availability:: most Unix platforms, possibly others. .. availability:: Unix.
Most Unix platforms.
.. versionadded:: 3.3 .. versionadded:: 3.3
@ -1587,7 +1603,9 @@ to sockets.
>>> [b1, b2, b3] >>> [b1, b2, b3]
[bytearray(b'Mary'), bytearray(b'01 had a 9'), bytearray(b'little lamb---')] [bytearray(b'Mary'), bytearray(b'01 had a 9'), bytearray(b'little lamb---')]
.. availability:: most Unix platforms, possibly others. .. availability:: Unix.
Most Unix platforms.
.. versionadded:: 3.3 .. versionadded:: 3.3
@ -1693,7 +1711,9 @@ to sockets.
def send_fds(sock, msg, fds): def send_fds(sock, msg, fds):
return sock.sendmsg([msg], [(socket.SOL_SOCKET, socket.SCM_RIGHTS, array.array("i", fds))]) return sock.sendmsg([msg], [(socket.SOL_SOCKET, socket.SCM_RIGHTS, array.array("i", fds))])
.. availability:: most Unix platforms, possibly others. .. availability:: Unix.
Most Unix platforms.
.. audit-event:: socket.sendmsg self,address socket.socket.sendmsg .. audit-event:: socket.sendmsg self,address socket.socket.sendmsg

3
Doc/library/ssl.rst
View file

@ -474,9 +474,6 @@ Certificate handling
* :attr:`openssl_capath_env` - OpenSSL's environment key that points to a capath, * :attr:`openssl_capath_env` - OpenSSL's environment key that points to a capath,
* :attr:`openssl_capath` - hard coded path to a capath directory * :attr:`openssl_capath` - hard coded path to a capath directory
.. availability:: LibreSSL ignores the environment vars
:attr:`openssl_cafile_env` and :attr:`openssl_capath_env`.
.. versionadded:: 3.4 .. versionadded:: 3.4
.. function:: enum_certificates(store_name) .. function:: enum_certificates(store_name)

4
Doc/library/subprocess.rst
View file

@ -1473,7 +1473,7 @@ handling consistency are valid for these functions.
>>> subprocess.getstatusoutput('/bin/kill $$') >>> subprocess.getstatusoutput('/bin/kill $$')
(-15, '') (-15, '')
.. availability:: POSIX & Windows. .. availability:: Unix, Windows.
.. versionchanged:: 3.3.4 .. versionchanged:: 3.3.4
Windows support was added. Windows support was added.
@ -1495,7 +1495,7 @@ handling consistency are valid for these functions.
>>> subprocess.getoutput('ls /bin/ls') >>> subprocess.getoutput('ls /bin/ls')
'/bin/ls' '/bin/ls'
.. availability:: POSIX & Windows. .. availability:: Unix, Windows.
.. versionchanged:: 3.3.4 .. versionchanged:: 3.3.4
Windows support added Windows support added

2
Doc/library/sys.rst
View file

@ -338,7 +338,7 @@ always available.
| | memory support. | | | memory support. |
+-----------------------------+----------------------------------------------+ +-----------------------------+----------------------------------------------+
.. availability:: WebAssembly Emscripten platform (*wasm32-emscripten*). .. availability:: Emscripten.
.. versionadded:: 3.11 .. versionadded:: 3.11

6
Doc/library/threading.rst
View file

@ -192,7 +192,9 @@ This module defines the following functions:
information (4 KiB pages are common; using multiples of 4096 for the stack size is information (4 KiB pages are common; using multiples of 4096 for the stack size is
the suggested approach in the absence of more specific information). the suggested approach in the absence of more specific information).
.. availability:: Windows, systems with POSIX threads. .. availability:: Windows, pthreads.
Unix platforms with POSIX threads support.
This module also defines the following constant: This module also defines the following constant:
@ -429,7 +431,7 @@ since it is impossible to detect the termination of alien threads.
system-wide) from the time the thread is created until the thread system-wide) from the time the thread is created until the thread
has been terminated. has been terminated.
.. availability:: Requires :func:`get_native_id` function. .. availability:: Windows, FreeBSD, Linux, macOS, OpenBSD, NetBSD, AIX, DragonFlyBSD.
.. versionadded:: 3.8 .. versionadded:: 3.8

21
Doc/library/time.rst
View file

@ -144,8 +144,10 @@ Functions
Passing an invalid or expired *thread_id* may result in Passing an invalid or expired *thread_id* may result in
undefined behavior, such as segmentation fault. undefined behavior, such as segmentation fault.
.. availability:: Unix (see the man page for :manpage:`pthread_getcpuclockid(3)` for .. availability:: Unix
further information).
See the man page for :manpage:`pthread_getcpuclockid(3)` for
further information.
.. versionadded:: 3.7 .. versionadded:: 3.7
@ -651,8 +653,9 @@ Functions
Use :func:`thread_time_ns` to avoid the precision loss caused by the Use :func:`thread_time_ns` to avoid the precision loss caused by the
:class:`float` type. :class:`float` type.
.. availability:: Windows, Linux, Unix systems supporting .. availability:: Linux, Unix, Windows.
``CLOCK_THREAD_CPUTIME_ID``.
Unix systems supporting ``CLOCK_THREAD_CPUTIME_ID``.
.. versionadded:: 3.7 .. versionadded:: 3.7
@ -770,7 +773,7 @@ These constants are used as parameters for :func:`clock_getres` and
have discontinuities if the time is changed using ``settimeofday()`` or have discontinuities if the time is changed using ``settimeofday()`` or
similar. similar.
.. availability:: Linux 2.6.39 or later. .. availability:: Linux >= 2.6.39.
.. versionadded:: 3.7 .. versionadded:: 3.7
@ -801,7 +804,7 @@ These constants are used as parameters for :func:`clock_getres` and
Similar to :data:`CLOCK_MONOTONIC`, but provides access to a raw Similar to :data:`CLOCK_MONOTONIC`, but provides access to a raw
hardware-based time that is not subject to NTP adjustments. hardware-based time that is not subject to NTP adjustments.
.. availability:: Linux 2.6.28 and newer, macOS 10.12 and newer. .. availability:: Linux >= 2.6.28, macOS >= 10.12.
.. versionadded:: 3.3 .. versionadded:: 3.3
@ -819,7 +822,7 @@ These constants are used as parameters for :func:`clock_getres` and
High-resolution per-process timer from the CPU. High-resolution per-process timer from the CPU.
.. availability:: FreeBSD, NetBSD 7 or later, OpenBSD. .. availability:: FreeBSD, NetBSD >= 7, OpenBSD.
.. versionadded:: 3.7 .. versionadded:: 3.7
@ -849,7 +852,7 @@ These constants are used as parameters for :func:`clock_getres` and
suspended, providing accurate uptime measurement, both absolute and suspended, providing accurate uptime measurement, both absolute and
interval. interval.
.. availability:: FreeBSD, OpenBSD 5.5 or later. .. availability:: FreeBSD, OpenBSD >= 5.5.
.. versionadded:: 3.7 .. versionadded:: 3.7
@ -860,7 +863,7 @@ These constants are used as parameters for :func:`clock_getres` and
point, unaffected by frequency or time adjustments and not incremented while point, unaffected by frequency or time adjustments and not incremented while
the system is asleep. the system is asleep.
.. availability:: macOS 10.12 and newer. .. availability:: macOS >= 10.12.
.. versionadded:: 3.8 .. versionadded:: 3.8

58
Doc/tools/extensions/pyspecific.py
View file

@ -135,11 +135,22 @@ class ImplementationDetail(Directive):
class Availability(Directive): class Availability(Directive):
has_content = False has_content = True
required_arguments = 1 required_arguments = 1
optional_arguments = 0 optional_arguments = 0
final_argument_whitespace = True final_argument_whitespace = True
# known platform, libc, and threading implementations
known_platforms = frozenset({
"AIX", "Android", "BSD", "DragonFlyBSD", "Emscripten", "FreeBSD",
"Linux", "NetBSD", "OpenBSD", "POSIX", "Solaris", "Unix", "VxWorks",
"WASI", "Windows", "macOS",
# libc
"BSD libc", "glibc", "musl",
# POSIX platforms with pthreads
"pthreads",
})
def run(self): def run(self):
availability_ref = ':ref:`Availability <availability>`: ' availability_ref = ':ref:`Availability <availability>`: '
pnode = nodes.paragraph(availability_ref + self.arguments[0], pnode = nodes.paragraph(availability_ref + self.arguments[0],
@ -148,8 +159,53 @@ class Availability(Directive):
pnode.extend(n + m) pnode.extend(n + m)
n, m = self.state.inline_text(self.arguments[0], self.lineno) n, m = self.state.inline_text(self.arguments[0], self.lineno)
pnode.extend(n + m) pnode.extend(n + m)
if self.content:
content = " " + " ".join(self.content)
n, m = self.state.inline_text(content, self.content_offset)
pnode.extend(n + m)
self.parse_platforms()
return [pnode] return [pnode]
def parse_platforms(self):
"""Parse platform information from arguments
Arguments is a comma-separated string of platforms. A platform may
be prefixed with "not " to indicate that a feature is not available.
Example::
.. availability:: Windows, Linux >= 4.2, not Emscripten, not WASI
Arguments like "Linux >= 3.17 with glibc >= 2.27" are currently not
parsed into separate tokens.
"""
platforms = {}
for arg in self.arguments[0].rstrip(".").split(","):
arg = arg.strip()
platform, _, version = arg.partition(" >= ")
if platform.startswith("not "):
version = False
platform = platform[4:]
elif not version:
version = True
platforms[platform] = version
unknown = set(platforms).difference(self.known_platforms)
if unknown:
cls = type(self)
logger = logging.getLogger(cls.__qualname__)
logger.warn(
f"Unknown platform(s) or syntax '{' '.join(sorted(unknown))}' "
f"in '.. availability:: {self.arguments[0]}', see "
f"{__file__}:{cls.__qualname__}.known_platforms for a set "
"known platforms."
)
return platforms
# Support for documenting audit event # Support for documenting audit event

2
Doc/using/cmdline.rst
View file

@ -975,7 +975,7 @@ conflict.
order to force the interpreter to use ``ASCII`` instead of ``UTF-8`` for order to force the interpreter to use ``ASCII`` instead of ``UTF-8`` for
system interfaces. system interfaces.
.. availability:: \*nix. .. availability:: Unix.
.. versionadded:: 3.7 .. versionadded:: 3.7
See :pep:`538` for more details. See :pep:`538` for more details.

2
Misc/NEWS.d/next/Documentation/2022-07-29-09-04-02.gh-issue-95415.LKTyw6.rst Normal file
View file

@ -0,0 +1,2 @@
Use consistent syntax for platform availability. The directive now supports
a content body and emits a warning when it encounters an unknown platform.