diff --git a/Doc/library/_thread.rst b/Doc/library/_thread.rst index 75b3834b9a339c..d61ce9039349db 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 d131408175fd16..4a665f2254f8a6 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 efba4236bcbccc..f585bbcbc18b8e 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 5bb33b9c10cc03..120b174dc3b1e7 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 4639a8b4afe593..d3500d5a1b3298 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 `_ on Windo descriptors are :ref:`non-inheritable `. 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 `_ 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 `_ 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 `_ 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 `_ 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 `_ 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 `_ 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 `_ 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 `_ 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 `_ 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 `_. - .. 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 245dd0d2520881..471ae0dbc9768a 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 67e9b44fe48c46..7c9c5a0819b0a7 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) `__ 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 d850639d242abe..72b8f03fc16df7 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 84b6d797ddc013..8eb254ce898e12 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 19225c85ff7624..e6e9a08e0a7197 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 0a996feb22cef7..fae81f8ac28ff4 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 62b3673c747f21..e7ad6a6c67bd19 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 58e4ad786fe17f..8e69c2c404f63a 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 be17fa68eb7b58..9f23a6fc7d5341 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 8ac0028cc4f412..20c372e2495697 100644 --- a/Doc/tools/extensions/pyspecific.py +++ b/Doc/tools/extensions/pyspecific.py @@ -134,11 +134,22 @@ def run(self): 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 `: ' pnode = nodes.paragraph(availability_ref + self.arguments[0], @@ -147,8 +158,53 @@ def run(self): 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 bc92e0e44b9b29..2d376ec7b40fd0 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 00000000000000..ece36bc4d1cedb --- /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.