[3.11] pythongh-95415: Make availability directive consistent (python…

…GH-95416). (cherry picked from commit f81a6c5) Co-authored-by: Christian Heimes <[email protected]>
/ · Jul 29, 2022 · a4dcbe5 · a4dcbe5
1 parent 30ca691
commit a4dcbe5
Show file tree

Hide file tree

Showing 17 changed files with 207 additions and 100 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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,15 +3417,15 @@ 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
 
 .. data:: EFD_CLOEXEC
 
    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
 

diff --git 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: