mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-17 23:31:09 +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
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

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).
.. availability:: Windows only.
.. availability:: Windows.
.. versionchanged:: 3.3
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
this module.
.. availability:: Unix. Not available on VxWorks.
.. availability:: Unix, not VxWorks.
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
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
would like to use a different encoding.
.. availability:: most flavors of Unix, Windows.
.. availability:: Unix, Windows.
.. function:: getenvb(key, default=None)
@ -316,7 +316,7 @@ process and user.
:func:`getenvb` is only available if :data:`supports_bytes_environ`
is ``True``.
.. availability:: most flavors of Unix.
.. availability:: Unix.
.. versionadded:: 3.2
@ -706,7 +706,7 @@ process and user.
:func:`socket.gethostname` or even
``socket.gethostbyaddr(socket.gethostname())``.
.. availability:: recent flavors of Unix.
.. availability:: Unix.
.. versionchanged:: 3.3
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
amount requested.
.. availability:: Linux kernel >= 4.5 or glibc >= 2.27.
.. availability:: Linux >= 4.5 with glibc >= 2.27.
.. 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
portable approach, use the :mod:`pty` module.
.. availability:: some flavors of Unix.
.. availability:: Unix.
.. versionchanged:: 3.4
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,
respectively.
.. availability:: some flavors of Unix.
.. availability:: Unix.
.. 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`.
.. availability:: Linux 2.6.30 and newer, FreeBSD 6.0 and newer,
OpenBSD 2.7 and newer, AIX 7.1 and newer. Using flags requires
Linux 4.6 or newer.
.. availability:: Linux >= 2.6.30, FreeBSD >= 6.0, OpenBSD >= 2.7, AIX >= 7.1.
Using flags requires Linux >= 4.6.
.. 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
:data:`errno.EAGAIN`.
.. availability:: Linux 4.14 and newer.
.. availability:: Linux >= 4.14.
.. 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
using the :data:`O_DIRECT` flag.
.. availability:: Linux 4.6 and newer.
.. availability:: Linux >= 4.6.
.. 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`.
.. availability:: Linux 2.6.30 and newer, FreeBSD 6.0 and newer,
OpenBSD 2.7 and newer, AIX 7.1 and newer. Using flags requires
Linux 4.7 or newer.
.. availability:: Linux >= 2.6.30, FreeBSD >= 6.0, OpenBSD >= 2.7, AIX >= 7.1.
Using flags requires Linux >= 4.6.
.. 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.
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
@ -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.
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
@ -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
``-1``, the current file *offset* is updated.
.. availability:: Linux 4.16 and newer.
.. availability:: Linux >= 4.16.
.. 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
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
@ -3320,7 +3320,7 @@ features:
the file descriptor, and as such multiple files can have the same name
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
@ -3345,8 +3345,9 @@ features:
These flags can be passed to :func:`memfd_create`.
.. availability:: Linux 3.17 or newer with glibc 2.27 or newer. The
``MFD_HUGE*`` flags are only available since Linux 4.14.
.. availability:: Linux >= 3.17 with glibc >= 2.27
The ``MFD_HUGE*`` flags are only available since Linux 4.14.
.. versionadded:: 3.8
@ -3398,7 +3399,7 @@ features:
finally:
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
@ -3407,7 +3408,7 @@ features:
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`.
.. availability:: See :func:`eventfd`
.. availability:: Linux >= 2.6.27
.. versionadded:: 3.10
@ -3416,7 +3417,7 @@ features:
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`.
.. availability:: See :func:`eventfd`
.. availability:: Linux >= 2.6.27
.. versionadded:: 3.10
@ -3424,7 +3425,7 @@ features:
Set close-on-exec flag for new :func:`eventfd` file descriptor.
.. availability:: See :func:`eventfd`
.. availability:: Linux >= 2.6.27
.. versionadded:: 3.10
@ -3433,7 +3434,7 @@ features:
Set :const:`O_NONBLOCK` status flag for new :func:`eventfd` file
descriptor.
.. availability:: See :func:`eventfd`
.. availability:: Linux >= 2.6.27
.. versionadded:: 3.10
@ -3442,7 +3443,7 @@ features:
Provide semaphore-like semantics for reads from a :func:`eventfd` file
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
@ -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
(:exc:`RuntimeError` is raised).
.. availability:: some flavors of Unix.
.. availability:: Unix.
.. 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.
.. availability:: Linux 5.3+
.. availability:: Linux >= 5.3
.. versionadded:: 3.9
@ -4054,7 +4055,9 @@ written in Python, such as a mail server's external command delivery program.
.. 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, \
@ -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
.. 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
:func:`spawnve` are not thread-safe on Windows; we advise you to use the
: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
descriptor that refers to a process.
.. availability:: Linux 5.4+
.. availability:: Linux >= 5.4
.. 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
from a job control stop since their status was last reported.
.. availability:: some Unix systems.
.. availability:: Unix.
Some Unix systems.
.. data:: WUNTRACED
@ -4906,7 +4913,7 @@ Random numbers
See also the `Linux getrandom() manual page
<http://man7.org/linux/man-pages/man2/getrandom.2.html>`_.
.. availability:: Linux 3.17 and newer.
.. availability:: Linux >= 3.17.
.. 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
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:

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
.. 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
@ -185,7 +185,7 @@ platform.
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
@ -194,7 +194,7 @@ platform.
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
@ -203,7 +203,7 @@ platform.
The ceiling of the real-time priority.
.. availability:: Linux 2.6.12 or later.
.. availability:: Linux >= 2.6.12.
.. versionadded:: 3.4
@ -213,7 +213,7 @@ platform.
The time limit (in microseconds) on CPU time that a process can spend
under real-time scheduling without making a blocking syscall.
.. availability:: Linux 2.6.25 or later.
.. availability:: Linux >= 2.6.25.
.. versionadded:: 3.4
@ -222,7 +222,7 @@ platform.
The number of signals which the process may queue.
.. availability:: Linux 2.6.8 or later.
.. availability:: Linux >= 2.6.8.
.. versionadded:: 3.4
@ -232,7 +232,7 @@ platform.
This limits the amount of network memory, and hence the amount of mbufs,
that this user may hold at any time.
.. availability:: FreeBSD 9 or later.
.. availability:: FreeBSD.
.. versionadded:: 3.4
@ -245,7 +245,7 @@ platform.
`tuning(7) <https://www.freebsd.org/cgi/man.cgi?query=tuning&sektion=7>`__
for a complete description of this sysctl.
.. availability:: FreeBSD 9 or later.
.. availability:: FreeBSD.
.. versionadded:: 3.4
@ -253,7 +253,7 @@ platform.
The maximum number of pseudo-terminals created by this user id.
.. availability:: FreeBSD 9 or later.
.. availability:: FreeBSD.
.. versionadded:: 3.4
@ -261,7 +261,7 @@ platform.
The maximum number of kqueues this user id is allowed to create.
.. availability:: FreeBSD 11 or later.
.. availability:: FreeBSD >= 11.
.. versionadded:: 3.10

56
Doc/library/signal.rst
View file

@ -95,8 +95,10 @@ The signal module defines three enums:
: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
:manpage:`pthread_sigmask(3)` for further information.
.. availability:: Unix.
See the man page :manpage:`sigprocmask(2)` and
:manpage:`pthread_sigmask(3)` for further information.
.. 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
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.
.. 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
canceled. If the return value is zero, no alarm is currently scheduled.
.. availability:: Unix. See the man page :manpage:`alarm(2)` for further
information.
.. availability:: Unix.
See the man page :manpage:`alarm(2)` for further information.
.. 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
will then be called. Returns nothing.
.. availability:: Unix. See the man page :manpage:`signal(2)` for further
information.
.. availability:: Unix.
See the man page :manpage:`signal(2)` for further information.
See also :func:`sigwait`, :func:`sigwaitinfo`, :func:`sigtimedwait` and
: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.
.. availability:: Linux 5.1+
.. availability:: Linux >= 5.1
.. 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
.. availability:: Unix. See the man page :manpage:`pthread_kill(3)` for further
information.
.. availability:: Unix.
See the man page :manpage:`pthread_kill(3)` for further information.
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.
.. 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.
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
system calls will be interrupted. Returns nothing.
.. availability:: Unix. See the man page :manpage:`siginterrupt(3)`
for further information.
.. availability:: Unix.
See the man page :manpage:`siginterrupt(3)` for further information.
Note that installing a signal handler with :func:`signal` will reset the
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
set of the pending signals.
.. availability:: Unix. See the man page :manpage:`sigpending(2)` for further
information.
.. availability:: Unix.
See the man page :manpage:`sigpending(2)` for further information.
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
(removes it from the pending list of signals), and returns the signal number.
.. availability:: Unix. See the man page :manpage:`sigwait(3)` for further
information.
.. availability:: Unix.
See the man page :manpage:`sigwait(3)` for further information.
See also :func:`pause`, :func:`pthread_sigmask`, :func:`sigpending`,
: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_band`.
.. availability:: Unix. See the man page :manpage:`sigwaitinfo(2)` for further
information.
.. availability:: Unix.
See the man page :manpage:`sigwaitinfo(2)` for further information.
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
performed. Returns :const:`None` if a timeout occurs.
.. availability:: Unix. See the man page :manpage:`sigtimedwait(2)` for further
information.
.. availability:: Unix.
See the man page :manpage:`sigtimedwait(2)` for further information.
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.
.. 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
@ -173,7 +175,9 @@ created. Socket addresses are represented as follows:
their hosts. The sockets are represented as a ``(CID, port)`` tuple
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
@ -221,7 +225,7 @@ created. Socket addresses are represented as follows:
``socket(AF_INET, SOCK_DGRAM, IPPROTO_UDPLITE)`` for IPv4 or
``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
@ -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
:c:func:`inet_pton`.
.. availability:: Unix (maybe not all platforms), Windows.
.. availability:: Unix, Windows.
.. versionchanged:: 3.4
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.
: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
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
permissible range of values.
.. availability:: most Unix platforms, possibly others.
.. availability:: Unix.
Most Unix platforms.
.. 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
data may be able to fit into the padding area.
.. availability:: most Unix platforms, possibly others.
.. availability:: Unix.
most Unix platforms.
.. 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.
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
@ -1210,7 +1221,10 @@ The :mod:`socket` module also offers various network-related services:
Return ``(msg, list(fds), flags, addr)``.
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
@ -1545,7 +1559,9 @@ to sockets.
fds.frombytes(cmsg_data[:len(cmsg_data) - (len(cmsg_data) % fds.itemsize)])
return msg, list(fds)
.. availability:: most Unix platforms, possibly others.
.. availability:: Unix.
Most Unix platforms.
.. versionadded:: 3.3
@ -1587,7 +1603,9 @@ to sockets.
>>> [b1, b2, b3]
[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
@ -1693,7 +1711,9 @@ to sockets.
def send_fds(sock, msg, 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

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

2
Doc/library/sys.rst
View file

@ -338,7 +338,7 @@ always available.
| | memory support. |
+-----------------------------+----------------------------------------------+
.. availability:: WebAssembly Emscripten platform (*wasm32-emscripten*).
.. availability:: Emscripten.
.. 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
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:
@ -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
has been terminated.
.. availability:: Requires :func:`get_native_id` function.
.. availability:: Windows, FreeBSD, Linux, macOS, OpenBSD, NetBSD, AIX, DragonFlyBSD.
.. 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
undefined behavior, such as segmentation fault.
.. availability:: Unix (see the man page for :manpage:`pthread_getcpuclockid(3)` for
further information).
.. availability:: Unix
See the man page for :manpage:`pthread_getcpuclockid(3)` for
further information.
.. versionadded:: 3.7
@ -651,8 +653,9 @@ Functions
Use :func:`thread_time_ns` to avoid the precision loss caused by the
:class:`float` type.
.. availability:: Windows, Linux, Unix systems supporting
``CLOCK_THREAD_CPUTIME_ID``.
.. availability:: Linux, Unix, Windows.
Unix systems supporting ``CLOCK_THREAD_CPUTIME_ID``.
.. 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
similar.
.. availability:: Linux 2.6.39 or later.
.. availability:: Linux >= 2.6.39.
.. 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
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
@ -819,7 +822,7 @@ These constants are used as parameters for :func:`clock_getres` and
High-resolution per-process timer from the CPU.
.. availability:: FreeBSD, NetBSD 7 or later, OpenBSD.
.. availability:: FreeBSD, NetBSD >= 7, OpenBSD.
.. 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
interval.
.. availability:: FreeBSD, OpenBSD 5.5 or later.
.. availability:: FreeBSD, OpenBSD >= 5.5.
.. 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
the system is asleep.
.. availability:: macOS 10.12 and newer.
.. availability:: macOS >= 10.12.
.. versionadded:: 3.8

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

@ -135,11 +135,22 @@ class ImplementationDetail(Directive):
class Availability(Directive):
has_content = False
has_content = True
required_arguments = 1
optional_arguments = 0
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):
availability_ref = ':ref:`Availability <availability>`: '
pnode = nodes.paragraph(availability_ref + self.arguments[0],
@ -148,8 +159,53 @@ class Availability(Directive):
pnode.extend(n + m)
n, m = self.state.inline_text(self.arguments[0], self.lineno)
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]
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

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
system interfaces.
.. availability:: \*nix.
.. availability:: Unix.
.. versionadded:: 3.7
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.