Skip to content

gh-95415: Make availability directive consistent (GH-95416) #95416

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Jul 29, 2022
Merged

gh-95415: Make availability directive consistent (GH-95416) #95416

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a3a9bb0
gh-95415: Make availability directive consistent
tiran Jul 29, 2022
1e6b8cf
whitespace
tiran Jul 29, 2022
0b36a35
Better warning, clarify OS + libc availability
tiran Jul 29, 2022
f94a7cd
with glibc
tiran Jul 29, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion Doc/library/_thread.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion Doc/library/codecs.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion Doc/library/crypt.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
---------------
Expand Down
4 changes: 4 additions & 0 deletions Doc/library/intro.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
77 changes: 42 additions & 35 deletions Doc/library/os.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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

Expand Down Expand Up @@ -706,7 +706,7 @@ process and user.
:func:`socket.gethostname` or even
``socket.gethostbyaddr(socket.gethostname())``.

.. availability:: recent flavors of Unix.
.. availability:: Unix.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should these get a note like Might not be available on less recent flavors of Unix. or Might not be available on some flavors of Unix.? Even better would be to be more specific (e.g. Not available on Unix flavors that ...).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

uname is available on all Unix-like platforms that we support. It was standardized in IEEE Std 1003.1-2001, https://pubs.opengroup.org/onlinepubs/009604599/functions/uname.html . Every POSIX-like OS released in the last 20 years should have it.


.. versionchanged:: 3.3
Return type changed from a tuple to a tuple-like object
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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.
Expand All @@ -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

Expand Down Expand Up @@ -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

Expand All @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -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

Expand All @@ -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

Expand All @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -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

Expand All @@ -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

Expand All @@ -3430,15 +3431,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

Expand All @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand All @@ -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


Expand Down Expand Up @@ -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, \
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion Doc/library/pipes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
Loading