summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--Doc/library/_thread.rst4
-rw-r--r--Doc/library/codecs.rst2
-rw-r--r--Doc/library/crypt.rst2
-rw-r--r--Doc/library/intro.rst4
-rw-r--r--Doc/library/os.rst77
-rw-r--r--Doc/library/pipes.rst2
-rw-r--r--Doc/library/resource.rst20
-rw-r--r--Doc/library/signal.rst56
-rw-r--r--Doc/library/socket.rst44
-rw-r--r--Doc/library/ssl.rst3
-rw-r--r--Doc/library/subprocess.rst4
-rw-r--r--Doc/library/sys.rst2
-rw-r--r--Doc/library/threading.rst6
-rw-r--r--Doc/library/time.rst21
-rw-r--r--Doc/tools/extensions/pyspecific.py58
-rw-r--r--Doc/using/cmdline.rst2
-rw-r--r--Misc/NEWS.d/next/Documentation/2022-07-29-09-04-02.gh-issue-95415.LKTyw6.rst2
17 files changed, 208 insertions, 101 deletions
diff --git a/Doc/library/_thread.rst b/Doc/library/_thread.rst
index 75b3834b9a..d61ce90393 100644
--- a/Doc/library/_thread.rst
+++ b/Doc/library/_thread.rst
@@ -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
diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst
index d131408175..4a665f2254 100644
--- a/Doc/library/codecs.rst
+++ b/Doc/library/codecs.rst
@@ -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.
diff --git a/Doc/library/crypt.rst b/Doc/library/crypt.rst
index efba4236bc..f585bbcbc1 100644
--- a/Doc/library/crypt.rst
+++ b/Doc/library/crypt.rst
@@ -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
---------------
diff --git a/Doc/library/intro.rst b/Doc/library/intro.rst
index 5bb33b9c10..120b174dc3 100644
--- a/Doc/library/intro.rst
+++ b/Doc/library/intro.rst
@@ -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.
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 4639a8b4af..d3500d5a1b 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -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
@@ -824,7 +824,7 @@ as internal buffering of data.
It will always copy no bytes and return 0 as if the file was empty
because of a known Linux kernel issue.
- .. availability:: Linux kernel >= 4.5 or glibc >= 2.27.
+ .. availability:: Linux >= 4.5 with glibc >= 2.27.
.. versionadded:: 3.8
@@ -1164,7 +1164,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.
@@ -1190,7 +1190,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
@@ -1269,9 +1269,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
@@ -1286,7 +1286,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
@@ -1300,7 +1300,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
@@ -1339,9 +1339,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
@@ -1351,7 +1351,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
@@ -1361,7 +1361,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
@@ -1375,7 +1375,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
@@ -1495,7 +1495,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
@@ -3334,7 +3334,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
@@ -3359,8 +3359,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
@@ -3412,7 +3413,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
@@ -3421,7 +3422,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
@@ -3430,7 +3431,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
@@ -3438,7 +3439,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
@@ -3447,7 +3448,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
@@ -3456,7 +3457,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
@@ -3861,7 +3862,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)
@@ -3917,7 +3918,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
.. data:: PIDFD_NONBLOCK
@@ -3927,7 +3928,7 @@ written in Python, such as a mail server's external command delivery program.
then an attempt to wait on the file descriptor using :manpage:`waitid(2)`
will immediately return the error :data:`~errno.EAGAIN` rather than blocking.
- .. availability:: Linux 5.10+
+ .. availability:: Linux >= 5.10
.. versionadded:: 3.12
@@ -4077,7 +4078,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, \
@@ -4177,7 +4180,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.
@@ -4381,7 +4386,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
@@ -4523,7 +4528,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
@@ -4929,7 +4936,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
diff --git a/Doc/library/pipes.rst b/Doc/library/pipes.rst
index 245dd0d252..471ae0dbc9 100644
--- a/Doc/library/pipes.rst
+++ b/Doc/library/pipes.rst
@@ -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:
diff --git a/Doc/library/resource.rst b/Doc/library/resource.rst
index 67e9b44fe4..7c9c5a0819 100644
--- a/Doc/library/resource.rst
+++ b/Doc/library/resource.rst
@@ -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
diff --git a/Doc/library/signal.rst b/Doc/library/signal.rst
index d850639d24..72b8f03fc1 100644
--- a/Doc/library/signal.rst
+++ b/Doc/library/signal.rst
@@ -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`.
diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index 84b6d797dd..8eb254ce89 100644
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -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
@@ -1080,7 +1084,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
@@ -1100,7 +1104,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
@@ -1126,7 +1130,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
@@ -1147,7 +1153,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
@@ -1246,7 +1254,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
@@ -1257,7 +1268,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
@@ -1592,7 +1606,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
@@ -1634,7 +1650,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
@@ -1740,7 +1758,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
diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst
index 19225c85ff..e6e9a08e0a 100644
--- a/Doc/library/ssl.rst
+++ b/Doc/library/ssl.rst
@@ -410,9 +410,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)
diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
index 0a996feb22..fae81f8ac2 100644
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -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
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index 62b3673c74..e7ad6a6c67 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -338,7 +338,7 @@ always available.
| | memory support. |
+-----------------------------+----------------------------------------------+
- .. availability:: WebAssembly Emscripten platform (*wasm32-emscripten*).
+ .. availability:: Emscripten.
.. versionadded:: 3.11
diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst
index 58e4ad786f..8e69c2c404 100644
--- a/Doc/library/threading.rst
+++ b/Doc/library/threading.rst
@@ -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
diff --git a/Doc/library/time.rst b/Doc/library/time.rst
index be17fa68eb..9f23a6fc7d 100644
--- a/Doc/library/time.rst
+++ b/Doc/library/time.rst
@@ -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
diff --git a/Doc/tools/extensions/pyspecific.py b/Doc/tools/extensions/pyspecific.py
index 8ac0028cc4..20c372e249 100644
--- a/Doc/tools/extensions/pyspecific.py
+++ b/Doc/tools/extensions/pyspecific.py
@@ -134,11 +134,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],
@@ -147,8 +158,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
diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
index bc92e0e44b..2d376ec7b4 100644
--- a/Doc/using/cmdline.rst
+++ b/Doc/using/cmdline.rst
@@ -981,7 +981,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.
diff --git a/Misc/NEWS.d/next/Documentation/2022-07-29-09-04-02.gh-issue-95415.LKTyw6.rst b/Misc/NEWS.d/next/Documentation/2022-07-29-09-04-02.gh-issue-95415.LKTyw6.rst
new file mode 100644
index 0000000000..ece36bc4d1
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2022-07-29-09-04-02.gh-issue-95415.LKTyw6.rst
@@ -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.
View Lorry Controller Status