[Python-checkins] bpo-11233: Create availability directive for documentation (GH-9692)
Victor Stinner
webhook-mailer at python.org
Fri Oct 12 10:55:25 EDT 2018
https://github.com/python/cpython/commit/2d6097d027e0dd3debbabc702aa9c98d94ba32a3
commit: 2d6097d027e0dd3debbabc702aa9c98d94ba32a3
branch: master
author: Cheryl Sabella <cheryl.sabella at gmail.com>
committer: Victor Stinner <vstinner at redhat.com>
date: 2018-10-12T16:55:20+02:00
summary:
bpo-11233: Create availability directive for documentation (GH-9692)
Replace "Availability: xxx" with ".. availability:: xxx" in the doc.
Original patch by Georg Brandl.
Co-Authored-By: Georg Brandl <georg at python.org>
files:
A Misc/NEWS.d/next/Documentation/2018-10-03-20-39-25.bpo-11233.BX6Gen.rst
M Doc/c-api/exceptions.rst
M Doc/c-api/init.rst
M Doc/library/_thread.rst
M Doc/library/asyncio-eventloop.rst
M Doc/library/asyncio-policy.rst
M Doc/library/asyncio-stream.rst
M Doc/library/asyncore.rst
M Doc/library/codecs.rst
M Doc/library/hashlib.rst
M Doc/library/intro.rst
M Doc/library/mimetypes.rst
M Doc/library/os.path.rst
M Doc/library/os.rst
M Doc/library/resource.rst
M Doc/library/select.rst
M Doc/library/shutil.rst
M Doc/library/signal.rst
M Doc/library/socket.rst
M Doc/library/ssl.rst
M Doc/library/subprocess.rst
M Doc/library/sys.rst
M Doc/library/threading.rst
M Doc/library/time.rst
M Doc/tools/extensions/pyspecific.py
M Doc/tools/rstlint.py
M Doc/using/cmdline.rst
diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst
index 2bc1bd876a2f..dd1e026cb071 100644
--- a/Doc/c-api/exceptions.rst
+++ b/Doc/c-api/exceptions.rst
@@ -186,34 +186,42 @@ NULL pointer for use in a ``return`` statement.
then it constructs a tuple object whose first item is the *ierr* value and whose
second item is the corresponding error message (gotten from
:c:func:`FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError,
- object)``. This function always returns *NULL*. Availability: Windows.
+ object)``. This function always returns *NULL*.
+
+ .. availability:: Windows.
.. c:function:: PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)
Similar to :c:func:`PyErr_SetFromWindowsErr`, with an additional parameter
- specifying the exception type to be raised. Availability: Windows.
+ specifying the exception type to be raised.
+
+ .. availability:: Windows.
.. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)
Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, but the
filename is given as a C string. *filename* is decoded from the filesystem
- encoding (:func:`os.fsdecode`). Availability: Windows.
+ encoding (:func:`os.fsdecode`).
+
+ .. availability:: Windows.
.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename)
Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, with an
additional parameter specifying the exception type to be raised.
- Availability: Windows.
+
+ .. availability:: Windows.
.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenameObjects(PyObject *type, int ierr, PyObject *filename, PyObject *filename2)
Similar to :c:func:`PyErr_SetExcFromWindowsErrWithFilenameObject`,
but accepts a second filename object.
- Availability: Windows.
+
+ .. availability:: Windows.
.. versionadded:: 3.4
@@ -221,7 +229,9 @@ NULL pointer for use in a ``return`` statement.
.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, const char *filename)
Similar to :c:func:`PyErr_SetFromWindowsErrWithFilename`, with an additional
- parameter specifying the exception type to be raised. Availability: Windows.
+ parameter specifying the exception type to be raised.
+
+ .. availability:: Windows.
.. c:function:: PyObject* PyErr_SetImportError(PyObject *msg, PyObject *name, PyObject *path)
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index e51a2555f6ad..6b5290a7ebbb 100644
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -156,7 +156,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
See :pep:`529` for more details.
- Availability: Windows.
+ .. availability:: Windows.
.. c:var:: Py_LegacyWindowsStdioFlag
@@ -168,7 +168,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
See :pep:`528` for more details.
- Availability: Windows.
+ .. availability:: Windows.
.. c:var:: Py_NoSiteFlag
diff --git a/Doc/library/_thread.rst b/Doc/library/_thread.rst
index 67cb70944f4d..acffabf24bad 100644
--- a/Doc/library/_thread.rst
+++ b/Doc/library/_thread.rst
@@ -101,7 +101,8 @@ This module defines the following constants and functions:
memory page size - platform documentation should be referred to for more
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, systems with POSIX threads.
.. data:: TIMEOUT_MAX
diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
index 76c8ce9943ef..96f5e0b38a9f 100644
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -510,7 +510,7 @@ Opening network connections
See the documentation of the :meth:`loop.create_connection` method
for information about arguments to this method.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.7
@@ -630,7 +630,7 @@ Creating network servers
See the documentation of the :meth:`loop.create_server` method
for information about arguments to this method.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.7
@@ -979,7 +979,7 @@ Unix signals
Return ``True`` if the signal handler was removed, or ``False`` if
no handler was set for the given signal.
-Availability: Unix.
+ .. availability:: Unix.
.. seealso::
@@ -1423,14 +1423,14 @@ on all platforms.
asyncio.set_event_loop(loop)
- Availability: Unix, Windows.
+ .. availability:: Unix, Windows.
.. class:: ProactorEventLoop
An event loop for Windows that uses "I/O Completion Ports" (IOCP).
- Availability: Windows.
+ .. availability:: Windows.
.. seealso::
diff --git a/Doc/library/asyncio-policy.rst b/Doc/library/asyncio-policy.rst
index 560f8b3135e1..82c83822d4d3 100644
--- a/Doc/library/asyncio-policy.rst
+++ b/Doc/library/asyncio-policy.rst
@@ -107,7 +107,7 @@ asyncio ships with the following built-in policies:
An alternative event loop policy that uses the
:class:`SelectorEventLoop` event loop implementation.
- Availability: Windows.
+ .. availability:: Windows.
.. class:: WindowsProactorEventLoopPolicy
@@ -115,7 +115,7 @@ asyncio ships with the following built-in policies:
An alternative event loop policy that uses the
:class:`ProactorEventLoop` event loop implementation.
- Availability: Windows.
+ .. availability:: Windows.
Process Watchers
diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst
index 60aae16c6d4f..e686a6a1c4cd 100644
--- a/Doc/library/asyncio-stream.rst
+++ b/Doc/library/asyncio-stream.rst
@@ -114,7 +114,7 @@ and work with streams:
See also the documentation of :meth:`loop.create_unix_connection`.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.7
@@ -136,7 +136,7 @@ and work with streams:
See also the documentation of :meth:`loop.create_unix_server`.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.7
diff --git a/Doc/library/asyncore.rst b/Doc/library/asyncore.rst
index 11d36163e44a..a86518ebff27 100644
--- a/Doc/library/asyncore.rst
+++ b/Doc/library/asyncore.rst
@@ -273,14 +273,18 @@ any that have been added to the map during asynchronous service) is closed.
with an optional map argument and wraps it for use with the :c:func:`poll`
or :c:func:`loop` functions. If provided a file object or anything with a
:c:func:`fileno` method, that method will be called and passed to the
- :class:`file_wrapper` constructor. Availability: UNIX.
+ :class:`file_wrapper` constructor.
+
+ .. availability:: Unix.
.. class:: file_wrapper()
A file_wrapper takes an integer file descriptor and calls :func:`os.dup` to
duplicate the handle so that the original handle may be closed independently
of the file_wrapper. This class implements sufficient methods to emulate a
- socket for use by the :class:`file_dispatcher` class. Availability: UNIX.
+ socket for use by the :class:`file_dispatcher` class.
+
+ .. availability:: Unix.
.. _asyncore-example-1:
diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst
index 24008a0b3f00..b9c04c241a8b 100644
--- a/Doc/library/codecs.rst
+++ b/Doc/library/codecs.rst
@@ -1471,7 +1471,7 @@ functions can be used directly if desired.
Encode operand according to the ANSI codepage (CP_ACP).
-Availability: Windows only.
+.. availability:: Windows only.
.. versionchanged:: 3.3
Support any error handler.
diff --git a/Doc/library/hashlib.rst b/Doc/library/hashlib.rst
index 4a8d7058c68f..a16c7cd4d7cd 100644
--- a/Doc/library/hashlib.rst
+++ b/Doc/library/hashlib.rst
@@ -271,7 +271,7 @@ include a `salt <https://en.wikipedia.org/wiki/Salt_%28cryptography%29>`_.
factor and *maxmem* limits memory (OpenSSL 1.1.0 defaults to 32 MiB).
*dklen* is the length of the derived key.
- Availability: OpenSSL 1.1+
+ .. availability:: OpenSSL 1.1+.
.. versionadded:: 3.6
diff --git a/Doc/library/intro.rst b/Doc/library/intro.rst
index e3283cac9947..8567e4d1d089 100644
--- a/Doc/library/intro.rst
+++ b/Doc/library/intro.rst
@@ -47,3 +47,16 @@ this material.
Let the show begin!
+
+.. _availability:
+
+Notes on availability
+=====================
+
+* An "Availability: Unix" note means that this function is commonly found on
+ Unix systems. It does not make any claims about its existence on a specific
+ operating system.
+
+* If not separately noted, all functions that claim "Availability: Unix" are
+ supported on Mac OS X, which builds on a Unix core.
+
diff --git a/Doc/library/mimetypes.rst b/Doc/library/mimetypes.rst
index 973014abba59..5728407cb34c 100644
--- a/Doc/library/mimetypes.rst
+++ b/Doc/library/mimetypes.rst
@@ -260,7 +260,9 @@ than one MIME-type database; it provides an interface similar to the one of the
.. method:: MimeTypes.read_windows_registry(strict=True)
- Load MIME type information from the Windows registry. Availability: Windows.
+ Load MIME type information from the Windows registry.
+
+ .. availability:: Windows.
If *strict* is ``True``, information will be added to the list of standard
types, else to the list of non-standard types.
diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst
index 5a0b178b9d04..f68fe61c0c2c 100644
--- a/Doc/library/os.path.rst
+++ b/Doc/library/os.path.rst
@@ -93,7 +93,7 @@ the :mod:`glob` module.)
pathnames, or if *paths* is empty. Unlike :func:`commonprefix`, this
returns a valid path.
- Availability: Unix, Windows
+ .. availability:: Unix, Windows.
.. versionadded:: 3.5
@@ -357,7 +357,7 @@ the :mod:`glob` module.)
*start* defaults to :attr:`os.curdir`.
- Availability: Unix, Windows.
+ .. availability:: Unix, Windows.
.. versionchanged:: 3.6
Accepts a :term:`path-like object`.
@@ -369,7 +369,7 @@ the :mod:`glob` module.)
This is determined by the device number and i-node number and raises an
exception if an :func:`os.stat` call on either pathname fails.
- Availability: Unix, Windows.
+ .. availability:: Unix, Windows.
.. versionchanged:: 3.2
Added Windows support.
@@ -385,7 +385,7 @@ the :mod:`glob` module.)
Return ``True`` if the file descriptors *fp1* and *fp2* refer to the same file.
- Availability: Unix, Windows.
+ .. availability:: Unix, Windows.
.. versionchanged:: 3.2
Added Windows support.
@@ -401,7 +401,7 @@ the :mod:`glob` module.)
:func:`os.lstat`, or :func:`os.stat`. This function implements the
underlying comparison used by :func:`samefile` and :func:`sameopenfile`.
- Availability: Unix, Windows.
+ .. availability:: Unix, Windows.
.. versionchanged:: 3.4
Added Windows support.
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index bc8d5a8abbf3..75d473c00d5c 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -32,15 +32,6 @@ Notes on the availability of these functions:
objects, and result in an object of the same type, if a path or file name is
returned.
-* An "Availability: Unix" note means that this function is commonly found on
- Unix systems. It does not make any claims about its existence on a specific
- operating system.
-
-* If not separately noted, all functions that claim "Availability: Unix" are
- supported on Mac OS X, which builds on a Unix core.
-
-.. Availability notes get their own line and occur at the end of the function
-.. documentation.
.. note::
@@ -105,7 +96,7 @@ process and user.
Return the filename corresponding to the controlling terminal of the process.
- Availability: Unix.
+ .. availability:: Unix.
.. data:: environ
@@ -235,7 +226,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:: most flavors of Unix, Windows.
.. function:: getenvb(key, default=None)
@@ -246,7 +237,7 @@ process and user.
:func:`getenvb` is only available if :data:`supports_bytes_environ`
is True.
- Availability: most flavors of Unix.
+ .. availability:: most flavors of Unix.
.. versionadded:: 3.2
@@ -267,7 +258,7 @@ process and user.
Return the effective group id of the current process. This corresponds to the
"set id" bit on the file being executed in the current process.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: geteuid()
@@ -276,7 +267,7 @@ process and user.
Return the current process's effective user id.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: getgid()
@@ -285,7 +276,7 @@ process and user.
Return the real group id of the current process.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: getgrouplist(user, group)
@@ -294,7 +285,7 @@ process and user.
list, it is included; typically, *group* is specified as the group ID
field from the password record for *user*.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
@@ -303,7 +294,7 @@ process and user.
Return list of supplemental group ids associated with the current process.
- Availability: Unix.
+ .. availability:: Unix.
.. note::
@@ -331,7 +322,7 @@ process and user.
falls back to ``pwd.getpwuid(os.getuid())[0]`` to get the login name of the
current real user id.
- Availability: Unix, Windows.
+ .. availability:: Unix, Windows.
.. function:: getpgid(pid)
@@ -339,7 +330,7 @@ process and user.
Return the process group id of the process with process id *pid*. If *pid* is 0,
the process group id of the current process is returned.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: getpgrp()
@@ -347,7 +338,7 @@ process and user.
Return the id of the current process group.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: getpid()
@@ -365,7 +356,7 @@ process and user.
the id returned is the one of the init process (1), on Windows it is still
the same id, which may be already reused by another process.
- Availability: Unix, Windows.
+ .. availability:: Unix, Windows.
.. versionchanged:: 3.2
Added support for Windows.
@@ -383,7 +374,7 @@ process and user.
(respectively) the calling process, the process group of the calling process,
or the real user ID of the calling process.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
@@ -394,7 +385,7 @@ process and user.
Parameters for the :func:`getpriority` and :func:`setpriority` functions.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
@@ -404,7 +395,7 @@ process and user.
Return a tuple (ruid, euid, suid) denoting the current process's
real, effective, and saved user ids.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.2
@@ -414,7 +405,7 @@ process and user.
Return a tuple (rgid, egid, sgid) denoting the current process's
real, effective, and saved group ids.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.2
@@ -425,7 +416,7 @@ process and user.
Return the current process's real user id.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: initgroups(username, gid)
@@ -434,7 +425,7 @@ process and user.
the groups of which the specified username is a member, plus the specified
group id.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.2
@@ -447,7 +438,7 @@ process and user.
changes to the environment affect subprocesses started with :func:`os.system`,
:func:`popen` or :func:`fork` and :func:`execv`.
- Availability: most flavors of Unix, Windows.
+ .. availability:: most flavors of Unix, Windows.
.. note::
@@ -464,21 +455,21 @@ process and user.
Set the current process's effective group id.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: seteuid(euid)
Set the current process's effective user id.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: setgid(gid)
Set the current process' group id.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: setgroups(groups)
@@ -487,7 +478,7 @@ process and user.
*groups*. *groups* must be a sequence, and each element must be an integer
identifying a group. This operation is typically available only to the superuser.
- Availability: Unix.
+ .. availability:: Unix.
.. note:: On Mac OS X, the length of *groups* may not exceed the
system-defined maximum number of effective group ids, typically 16.
@@ -499,7 +490,7 @@ process and user.
Call the system call :c:func:`setpgrp` or ``setpgrp(0, 0)`` depending on
which version is implemented (if any). See the Unix manual for the semantics.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: setpgid(pid, pgrp)
@@ -508,7 +499,7 @@ process and user.
process with id *pid* to the process group with id *pgrp*. See the Unix manual
for the semantics.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: setpriority(which, who, priority)
@@ -525,7 +516,7 @@ process and user.
*priority* is a value in the range -20 to 19. The default priority is 0;
lower priorities cause more favorable scheduling.
- Availability: Unix
+ .. availability:: Unix.
.. versionadded:: 3.3
@@ -534,14 +525,14 @@ process and user.
Set the current process's real and effective group ids.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: setresgid(rgid, egid, sgid)
Set the current process's real, effective, and saved group ids.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.2
@@ -550,7 +541,7 @@ process and user.
Set the current process's real, effective, and saved user ids.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.2
@@ -559,21 +550,21 @@ process and user.
Set the current process's real and effective user ids.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: getsid(pid)
Call the system call :c:func:`getsid`. See the Unix manual for the semantics.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: setsid()
Call the system call :c:func:`setsid`. See the Unix manual for the semantics.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: setuid(uid)
@@ -582,7 +573,7 @@ process and user.
Set the current process's user id.
- Availability: Unix.
+ .. availability:: Unix.
.. placed in this section since it relates to errno.... a little weak
@@ -631,7 +622,7 @@ process and user.
:func:`socket.gethostname` or even
``socket.gethostbyaddr(socket.gethostname())``.
- Availability: recent flavors of Unix.
+ .. availability:: recent flavors of Unix.
.. versionchanged:: 3.3
Return type changed from a tuple to a tuple-like object
@@ -651,7 +642,7 @@ process and user.
calls to :func:`unsetenv` don't update ``os.environ``, so it is actually
preferable to delete items of ``os.environ``.
- Availability: most flavors of Unix, Windows.
+ .. availability:: most flavors of Unix, Windows.
.. _os-newstreams:
@@ -754,7 +745,7 @@ as internal buffering of data.
docs for :func:`chmod` for possible values of *mode*. As of Python 3.3, this
is equivalent to ``os.chmod(fd, mode)``.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: fchown(fd, uid, gid)
@@ -764,7 +755,7 @@ as internal buffering of data.
:func:`chown`. As of Python 3.3, this is equivalent to ``os.chown(fd, uid,
gid)``.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: fdatasync(fd)
@@ -772,7 +763,7 @@ as internal buffering of data.
Force write of file with filedescriptor *fd* to disk. Does not force update of
metadata.
- Availability: Unix.
+ .. availability:: Unix.
.. note::
This function is not available on MacOS.
@@ -795,7 +786,7 @@ as internal buffering of data.
As of Python 3.3, this is equivalent to ``os.pathconf(fd, name)``.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: fstat(fd)
@@ -816,7 +807,7 @@ as internal buffering of data.
file descriptor *fd*, like :func:`statvfs`. As of Python 3.3, this is
equivalent to ``os.statvfs(fd)``.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: fsync(fd)
@@ -828,7 +819,7 @@ as internal buffering of data.
``f.flush()``, and then do ``os.fsync(f.fileno())``, to ensure that all internal
buffers associated with *f* are written to disk.
- Availability: Unix, Windows.
+ .. availability:: Unix, Windows.
.. function:: ftruncate(fd, length)
@@ -837,7 +828,7 @@ as internal buffering of data.
most *length* bytes in size. As of Python 3.3, this is equivalent to
``os.truncate(fd, length)``.
- Availability: Unix, Windows.
+ .. availability:: Unix, Windows.
.. versionchanged:: 3.5
Added support for Windows
@@ -849,7 +840,7 @@ as internal buffering of data.
See also :func:`set_blocking` and :meth:`socket.socket.setblocking`.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.5
@@ -867,7 +858,7 @@ as internal buffering of data.
:data:`F_ULOCK` or :data:`F_TEST`.
*len* specifies the section of the file to lock.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
@@ -879,7 +870,7 @@ as internal buffering of data.
Flags that specify what action :func:`lockf` will take.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
@@ -1011,7 +1002,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:: some flavors of Unix.
.. versionchanged:: 3.4
The new file descriptors are now non-inheritable.
@@ -1023,7 +1014,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
reading and writing, respectively. The new file descriptor is
:ref:`non-inheritable <fd_inheritance>`.
- Availability: Unix, Windows.
+ .. availability:: Unix, Windows.
.. versionchanged:: 3.4
The new file descriptors are now non-inheritable.
@@ -1037,7 +1028,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:: some flavors of Unix.
.. versionadded:: 3.3
@@ -1047,7 +1038,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
Ensures that enough disk space is allocated for the file specified by *fd*
starting from *offset* and continuing for *len* bytes.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
@@ -1062,7 +1053,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
:data:`POSIX_FADV_RANDOM`, :data:`POSIX_FADV_NOREUSE`,
:data:`POSIX_FADV_WILLNEED` or :data:`POSIX_FADV_DONTNEED`.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
@@ -1077,7 +1068,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
Flags that can be used in *advice* in :func:`posix_fadvise` that specify
the access pattern that is likely to be used.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
@@ -1090,7 +1081,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
Return a bytestring containing the bytes read. If the end of the file
referred to by *fd* has been reached, an empty bytes object is returned.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
@@ -1116,8 +1107,8 @@ 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. Using flags requires Linux 4.6 or newer.
+ .. availability:: Linux 2.6.30 and newer, FreeBSD 6.0 and newer,
+ OpenBSD 2.7 and newer. Using flags requires Linux 4.6 or newer.
.. versionadded:: 3.7
@@ -1132,7 +1123,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 and newer.
.. versionadded:: 3.7
@@ -1146,7 +1137,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 and newer.
.. versionadded:: 3.7
@@ -1158,7 +1149,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
Return the number of bytes actually written.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
@@ -1184,8 +1175,8 @@ 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. Using flags requires Linux 4.7 or newer.
+ .. availability:: Linux 2.6.30 and newer, FreeBSD 6.0 and newer,
+ OpenBSD 2.7 and newer. Using flags requires Linux 4.7 or newer.
.. versionadded:: 3.7
@@ -1195,7 +1186,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` ``open(2)`` 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 and newer.
.. versionadded:: 3.7
@@ -1205,7 +1196,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` ``open(2)`` 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 and newer.
.. versionadded:: 3.7
@@ -1257,7 +1248,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
Cross-platform applications should not use *headers*, *trailers* and *flags*
arguments.
- Availability: Unix.
+ .. availability:: Unix.
.. note::
@@ -1274,7 +1265,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
See also :func:`get_blocking` and :meth:`socket.socket.setblocking`.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.5
@@ -1286,7 +1277,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
Parameters to the :func:`sendfile` function, if the implementation supports
them.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
@@ -1304,7 +1295,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
The operating system may set a limit (:func:`sysconf` value
``'SC_IOV_MAX'``) on the number of buffers that can be used.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
@@ -1314,7 +1305,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
Return the process group associated with the terminal given by *fd* (an open
file descriptor as returned by :func:`os.open`).
- Availability: Unix.
+ .. availability:: Unix.
.. function:: tcsetpgrp(fd, pg)
@@ -1322,7 +1313,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
Set the process group associated with the terminal given by *fd* (an open file
descriptor as returned by :func:`os.open`) to *pg*.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: ttyname(fd)
@@ -1331,7 +1322,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
file descriptor *fd*. If *fd* is not associated with a terminal device, an
exception is raised.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: write(fd, str)
@@ -1366,7 +1357,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
The operating system may set a limit (:func:`sysconf` value
``'SC_IOV_MAX'``) on the number of buffers that can be used.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
@@ -1393,7 +1384,7 @@ Querying the size of a terminal
should normally be used, ``os.get_terminal_size`` is the low-level
implementation.
- Availability: Unix, Windows.
+ .. availability:: Unix, Windows.
.. class:: terminal_size
@@ -1442,13 +1433,13 @@ streams are closed, and inheritable handles are only inherited if the
Get the "inheritable" flag of the specified handle (a boolean).
- Availability: Windows.
+ .. availability:: Windows.
.. function:: set_handle_inheritable(handle, inheritable)
Set the "inheritable" flag of the specified handle.
- Availability: Windows.
+ .. availability:: Windows.
.. _os-file-dir:
@@ -1603,7 +1594,7 @@ features:
This function can support :ref:`not following symlinks <follow_symlinks>`.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
The *follow_symlinks* argument.
@@ -1668,7 +1659,7 @@ features:
See :func:`shutil.chown` for a higher-level function that accepts names in
addition to numeric ids.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
Added support for specifying an open file descriptor for *path*,
@@ -1682,7 +1673,7 @@ features:
Change the root directory of the current process to *path*.
- Availability: Unix.
+ .. availability:: Unix.
.. versionchanged:: 3.6
Accepts a :term:`path-like object`.
@@ -1694,7 +1685,7 @@ features:
descriptor *fd*. The descriptor must refer to an opened directory, not an
open file. As of Python 3.3, this is equivalent to ``os.chdir(fd)``.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: getcwd()
@@ -1713,7 +1704,7 @@ features:
not follow symbolic links. As of Python 3.3, this is equivalent to
``os.chflags(path, flags, follow_symlinks=False)``.
- Availability: Unix.
+ .. availability:: Unix.
.. versionchanged:: 3.6
Accepts a :term:`path-like object`.
@@ -1726,7 +1717,7 @@ features:
for possible values of *mode*. As of Python 3.3, this is equivalent to
``os.chmod(path, mode, follow_symlinks=False)``.
- Availability: Unix.
+ .. availability:: Unix.
.. versionchanged:: 3.6
Accepts a :term:`path-like object`.
@@ -1737,7 +1728,7 @@ features:
function will not follow symbolic links. As of Python 3.3, this is equivalent
to ``os.chown(path, uid, gid, follow_symlinks=False)``.
- Availability: Unix.
+ .. availability:: Unix.
.. versionchanged:: 3.6
Accepts a :term:`path-like object`.
@@ -1751,7 +1742,7 @@ features:
supply :ref:`paths relative to directory descriptors <dir_fd>`, and :ref:`not
following symlinks <follow_symlinks>`.
- Availability: Unix, Windows.
+ .. availability:: Unix, Windows.
.. versionchanged:: 3.2
Added Windows support.
@@ -1909,7 +1900,7 @@ features:
FIFO for reading, and the client opens it for writing. Note that :func:`mkfifo`
doesn't open the FIFO --- it just creates the rendezvous point.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
The *dir_fd* argument.
@@ -1931,7 +1922,7 @@ features:
This function can also support :ref:`paths relative to directory descriptors
<dir_fd>`.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
The *dir_fd* argument.
@@ -1975,7 +1966,7 @@ features:
This function can support :ref:`specifying a file descriptor
<path_fd>`.
- Availability: Unix.
+ .. availability:: Unix.
.. versionchanged:: 3.6
Accepts a :term:`path-like object`.
@@ -1987,7 +1978,7 @@ features:
the integer values defined for those names by the host operating system. This
can be used to determine the set of names known to the system.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: readlink(path, *, dir_fd=None)
@@ -2005,7 +1996,7 @@ features:
This function can also support :ref:`paths relative to directory descriptors
<dir_fd>`.
- Availability: Unix, Windows
+ .. availability:: Unix, Windows.
.. versionchanged:: 3.2
Added support for Windows 6.0 (Vista) symbolic links.
@@ -2596,7 +2587,7 @@ features:
This function can support :ref:`specifying a file descriptor <path_fd>`.
- Availability: Unix.
+ .. availability:: Unix.
.. versionchanged:: 3.2
The :const:`ST_RDONLY` and :const:`ST_NOSUID` constants were added.
@@ -2726,7 +2717,7 @@ features:
:exc:`OSError` is raised when the function is called by an unprivileged
user.
- Availability: Unix, Windows.
+ .. availability:: Unix, Windows.
.. versionchanged:: 3.2
Added support for Windows 6.0 (Vista) symbolic links.
@@ -2743,7 +2734,7 @@ features:
Force write of everything to disk.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
@@ -2755,7 +2746,7 @@ features:
This function can support :ref:`specifying a file descriptor <path_fd>`.
- Availability: Unix, Windows.
+ .. availability:: Unix, Windows.
.. versionadded:: 3.3
@@ -2962,7 +2953,7 @@ features:
for name in dirs:
os.rmdir(name, dir_fd=rootfd)
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
@@ -3139,7 +3130,7 @@ to be ignored.
you can check whether or not it is available using :data:`os.supports_fd`.
If it is unavailable, using it will raise a :exc:`NotImplementedError`.
- Availability: Unix, Windows.
+ .. availability:: Unix, Windows.
.. versionadded:: 3.3
Added support for specifying an open file descriptor for *path*
@@ -3173,7 +3164,7 @@ written in Python, such as a mail server's external command delivery program.
Exit code that means no error occurred.
- Availability: Unix.
+ .. availability:: Unix.
.. data:: EX_USAGE
@@ -3181,49 +3172,49 @@ written in Python, such as a mail server's external command delivery program.
Exit code that means the command was used incorrectly, such as when the wrong
number of arguments are given.
- Availability: Unix.
+ .. availability:: Unix.
.. data:: EX_DATAERR
Exit code that means the input data was incorrect.
- Availability: Unix.
+ .. availability:: Unix.
.. data:: EX_NOINPUT
Exit code that means an input file did not exist or was not readable.
- Availability: Unix.
+ .. availability:: Unix.
.. data:: EX_NOUSER
Exit code that means a specified user did not exist.
- Availability: Unix.
+ .. availability:: Unix.
.. data:: EX_NOHOST
Exit code that means a specified host did not exist.
- Availability: Unix.
+ .. availability:: Unix.
.. data:: EX_UNAVAILABLE
Exit code that means that a required service is unavailable.
- Availability: Unix.
+ .. availability:: Unix.
.. data:: EX_SOFTWARE
Exit code that means an internal software error was detected.
- Availability: Unix.
+ .. availability:: Unix.
.. data:: EX_OSERR
@@ -3231,7 +3222,7 @@ written in Python, such as a mail server's external command delivery program.
Exit code that means an operating system error was detected, such as the
inability to fork or create a pipe.
- Availability: Unix.
+ .. availability:: Unix.
.. data:: EX_OSFILE
@@ -3239,21 +3230,21 @@ written in Python, such as a mail server's external command delivery program.
Exit code that means some system file did not exist, could not be opened, or had
some other kind of error.
- Availability: Unix.
+ .. availability:: Unix.
.. data:: EX_CANTCREAT
Exit code that means a user specified output file could not be created.
- Availability: Unix.
+ .. availability:: Unix.
.. data:: EX_IOERR
Exit code that means that an error occurred while doing I/O on some file.
- Availability: Unix.
+ .. availability:: Unix.
.. data:: EX_TEMPFAIL
@@ -3262,7 +3253,7 @@ written in Python, such as a mail server's external command delivery program.
that may not really be an error, such as a network connection that couldn't be
made during a retryable operation.
- Availability: Unix.
+ .. availability:: Unix.
.. data:: EX_PROTOCOL
@@ -3270,7 +3261,7 @@ written in Python, such as a mail server's external command delivery program.
Exit code that means that a protocol exchange was illegal, invalid, or not
understood.
- Availability: Unix.
+ .. availability:: Unix.
.. data:: EX_NOPERM
@@ -3278,21 +3269,21 @@ written in Python, such as a mail server's external command delivery program.
Exit code that means that there were insufficient permissions to perform the
operation (but not intended for file system problems).
- Availability: Unix.
+ .. availability:: Unix.
.. data:: EX_CONFIG
Exit code that means that some kind of configuration error occurred.
- Availability: Unix.
+ .. availability:: Unix.
.. data:: EX_NOTFOUND
Exit code that means something like "an entry was not found".
- Availability: Unix.
+ .. availability:: Unix.
.. function:: fork()
@@ -3307,7 +3298,7 @@ written in Python, such as a mail server's external command delivery program.
See :mod:`ssl` for applications that use the SSL module with fork().
- Availability: Unix.
+ .. availability:: Unix.
.. function:: forkpty()
@@ -3318,7 +3309,7 @@ written in Python, such as a mail server's external command delivery program.
master end of the pseudo-terminal. For a more portable approach, use the
:mod:`pty` module. If an error occurs :exc:`OSError` is raised.
- Availability: some flavors of Unix.
+ .. availability:: some flavors of Unix.
.. function:: kill(pid, sig)
@@ -3352,14 +3343,14 @@ written in Python, such as a mail server's external command delivery program.
Send the signal *sig* to the process group *pgid*.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: nice(increment)
Add *increment* to the process's "niceness". Return the new niceness.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: plock(op)
@@ -3367,7 +3358,7 @@ written in Python, such as a mail server's external command delivery program.
Lock program segments into memory. The value of *op* (defined in
``<sys/lock.h>``) determines which segments are locked.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: popen(cmd, mode='r', buffering=-1)
@@ -3496,7 +3487,7 @@ written in Python, such as a mail server's external command delivery program.
There is no way to unregister a function.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.7
@@ -3560,10 +3551,10 @@ written in Python, such as a mail server's external command delivery program.
L = ['cp', 'index.html', '/dev/null']
os.spawnvpe(os.P_WAIT, 'cp', L, os.environ)
- 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.
+ .. 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.
.. versionchanged:: 3.6
Accepts a :term:`path-like object`.
@@ -3577,7 +3568,7 @@ written in Python, such as a mail server's external command delivery program.
will return as soon as the new process has been created, with the process id as
the return value.
- Availability: Unix, Windows.
+ .. availability:: Unix, Windows.
.. data:: P_WAIT
@@ -3588,7 +3579,7 @@ written in Python, such as a mail server's external command delivery program.
of the process the run is successful, or ``-signal`` if a signal kills the
process.
- Availability: Unix, Windows.
+ .. availability:: Unix, Windows.
.. data:: P_DETACH
@@ -3600,7 +3591,7 @@ written in Python, such as a mail server's external command delivery program.
console of the calling process. If :const:`P_OVERLAY` is used, the current
process will be replaced; the :func:`spawn\* <spawnl>` function will not return.
- Availability: Windows.
+ .. availability:: Windows.
.. function:: startfile(path[, operation])
@@ -3629,7 +3620,7 @@ written in Python, such as a mail server's external command delivery program.
function is not resolved until this function is first called. If the function
cannot be resolved, :exc:`NotImplementedError` will be raised.
- Availability: Windows.
+ .. availability:: Windows.
.. function:: system(command)
@@ -3656,7 +3647,7 @@ written in Python, such as a mail server's external command delivery program.
to using this function. See the :ref:`subprocess-replacements` section in
the :mod:`subprocess` documentation for some helpful recipes.
- Availability: Unix, Windows.
+ .. availability:: Unix, Windows.
.. function:: times()
@@ -3679,7 +3670,7 @@ written in Python, such as a mail server's external command delivery program.
On Windows, only :attr:`user` and :attr:`system` are known; the other
attributes are zero.
- Availability: Unix, Windows.
+ .. availability:: Unix, Windows.
.. versionchanged:: 3.3
Return type changed from a tuple to a tuple-like object
@@ -3694,7 +3685,7 @@ written in Python, such as a mail server's external command delivery program.
number is zero); the high bit of the low byte is set if a core file was
produced.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: waitid(idtype, id, options)
@@ -3709,7 +3700,7 @@ written in Python, such as a mail server's external command delivery program.
:attr:`si_code` or ``None`` if :data:`WNOHANG` is specified and there are no
children in a waitable state.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
@@ -3720,7 +3711,7 @@ written in Python, such as a mail server's external command delivery program.
These are the possible values for *idtype* in :func:`waitid`. They affect
how *id* is interpreted.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
@@ -3731,7 +3722,7 @@ written in Python, such as a mail server's external command delivery program.
Flags that can be used in *options* in :func:`waitid` that specify what
child signal to wait for.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
@@ -3744,7 +3735,7 @@ written in Python, such as a mail server's external command delivery program.
These are the possible values for :attr:`si_code` in the result returned by
:func:`waitid`.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
@@ -3791,7 +3782,7 @@ written in Python, such as a mail server's external command delivery program.
option argument is the same as that provided to :func:`waitpid` and
:func:`wait4`.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: wait4(pid, options)
@@ -3802,7 +3793,7 @@ written in Python, such as a mail server's external command delivery program.
resource usage information. The arguments to :func:`wait4` are the same
as those provided to :func:`waitpid`.
- Availability: Unix.
+ .. availability:: Unix.
.. data:: WNOHANG
@@ -3810,7 +3801,7 @@ written in Python, such as a mail server's external command delivery program.
The option for :func:`waitpid` to return immediately if no child process status
is available immediately. The function returns ``(0, 0)`` in this case.
- Availability: Unix.
+ .. availability:: Unix.
.. data:: WCONTINUED
@@ -3818,7 +3809,7 @@ 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:: some Unix systems.
.. data:: WUNTRACED
@@ -3826,7 +3817,7 @@ 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 stopped but
their current state has not been reported since they were stopped.
- Availability: Unix.
+ .. availability:: Unix.
The following functions take a process status code as returned by
@@ -3838,7 +3829,7 @@ used to determine the disposition of a process.
Return ``True`` if a core dump was generated for the process, otherwise
return ``False``.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: WIFCONTINUED(status)
@@ -3846,7 +3837,7 @@ used to determine the disposition of a process.
Return ``True`` if the process has been continued from a job control stop,
otherwise return ``False``.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: WIFSTOPPED(status)
@@ -3854,7 +3845,7 @@ used to determine the disposition of a process.
Return ``True`` if the process has been stopped, otherwise return
``False``.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: WIFSIGNALED(status)
@@ -3862,7 +3853,7 @@ used to determine the disposition of a process.
Return ``True`` if the process exited due to a signal, otherwise return
``False``.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: WIFEXITED(status)
@@ -3870,7 +3861,7 @@ used to determine the disposition of a process.
Return ``True`` if the process exited using the :manpage:`exit(2)` system call,
otherwise return ``False``.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: WEXITSTATUS(status)
@@ -3878,21 +3869,21 @@ used to determine the disposition of a process.
If ``WIFEXITED(status)`` is true, return the integer parameter to the
:manpage:`exit(2)` system call. Otherwise, the return value is meaningless.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: WSTOPSIG(status)
Return the signal which caused the process to stop.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: WTERMSIG(status)
Return the signal which caused the process to exit.
- Availability: Unix.
+ .. availability:: Unix.
Interface to the scheduler
@@ -4038,7 +4029,7 @@ Miscellaneous System Information
included in ``confstr_names``, an :exc:`OSError` is raised with
:const:`errno.EINVAL` for the error number.
- Availability: Unix.
+ .. availability:: Unix.
.. data:: confstr_names
@@ -4047,7 +4038,7 @@ Miscellaneous System Information
defined for those names by the host operating system. This can be used to
determine the set of names known to the system.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: cpu_count()
@@ -4068,7 +4059,7 @@ Miscellaneous System Information
1, 5, and 15 minutes or raises :exc:`OSError` if the load average was
unobtainable.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: sysconf(name)
@@ -4078,7 +4069,7 @@ Miscellaneous System Information
the *name* parameter for :func:`confstr` apply here as well; the dictionary that
provides information on the known names is given by ``sysconf_names``.
- Availability: Unix.
+ .. availability:: Unix.
.. data:: sysconf_names
@@ -4087,7 +4078,7 @@ Miscellaneous System Information
defined for those names by the host operating system. This can be used to
determine the set of names known to the system.
- Availability: Unix.
+ .. availability:: Unix.
The following data values are used to support path manipulation operations. These
are defined for all platforms.
@@ -4199,7 +4190,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 and newer.
.. versionadded:: 3.6
diff --git a/Doc/library/resource.rst b/Doc/library/resource.rst
index bdfe5f6d4594..bd49c87f1d78 100644
--- a/Doc/library/resource.rst
+++ b/Doc/library/resource.rst
@@ -92,7 +92,7 @@ this module for those platforms.
:exc:`PermissionError` when the user doesn't have ``CAP_SYS_RESOURCE`` for
the process.
- Availability: Linux 2.6.36 or later with glibc 2.13 or later
+ .. availability:: Linux 2.6.36 or later with glibc 2.13 or later.
.. versionadded:: 3.4
@@ -178,7 +178,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 or later.
.. versionadded:: 3.4
@@ -187,7 +187,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 or later.
.. versionadded:: 3.4
@@ -196,7 +196,7 @@ platform.
The ceiling of the real-time priority.
- Availability: Linux 2.6.12 or later.
+ .. availability:: Linux 2.6.12 or later.
.. versionadded:: 3.4
@@ -206,7 +206,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 or later.
.. versionadded:: 3.4
@@ -215,7 +215,7 @@ platform.
The number of signals which the process may queue.
- Availability: Linux 2.6.8 or later.
+ .. availability:: Linux 2.6.8 or later.
.. versionadded:: 3.4
@@ -225,7 +225,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 9 or later.
.. versionadded:: 3.4
@@ -236,7 +236,7 @@ platform.
This limit is enforced only if bit 1 of the vm.overcommit sysctl is set.
Please see :manpage:`tuning(7)` for a complete description of this sysctl.
- Availability: FreeBSD 9 or later.
+ .. availability:: FreeBSD 9 or later.
.. versionadded:: 3.4
@@ -244,7 +244,7 @@ platform.
The maximum number of pseudo-terminals created by this user id.
- Availability: FreeBSD 9 or later.
+ .. availability:: FreeBSD 9 or later.
.. versionadded:: 3.4
diff --git a/Doc/library/select.rst b/Doc/library/select.rst
index 8feedaa4770c..f5b25db774f6 100644
--- a/Doc/library/select.rst
+++ b/Doc/library/select.rst
@@ -171,7 +171,9 @@ The module defines the following:
:func:`poll` or another interface in this module. This doesn't apply
to other kind of file-like objects such as sockets.
- This value is guaranteed by POSIX to be at least 512. Availability: Unix.
+ This value is guaranteed by POSIX to be at least 512.
+
+ .. availability:: Unix
.. versionadded:: 3.2
diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
index d8826277a46c..6b4ce14b5da1 100644
--- a/Doc/library/shutil.rst
+++ b/Doc/library/shutil.rst
@@ -351,7 +351,7 @@ Directory and files operations
.. versionchanged:: 3.8
On Windows, *path* can now be a file or directory.
- Availability: Unix, Windows.
+ .. availability:: Unix, Windows.
.. function:: chown(path, user=None, group=None)
@@ -362,7 +362,7 @@ Directory and files operations
See also :func:`os.chown`, the underlying function.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
diff --git a/Doc/library/signal.rst b/Doc/library/signal.rst
index bf07559c3d27..5c48c88f08df 100644
--- a/Doc/library/signal.rst
+++ b/Doc/library/signal.rst
@@ -106,7 +106,7 @@ The variables defined in the :mod:`signal` module are:
The signal corresponding to the :kbd:`Ctrl+C` keystroke event. This signal can
only be used with :func:`os.kill`.
- Availability: Windows.
+ .. availability:: Windows.
.. versionadded:: 3.2
@@ -116,7 +116,7 @@ The variables defined in the :mod:`signal` module are:
The signal corresponding to the :kbd:`Ctrl+Break` keystroke event. This signal can
only be used with :func:`os.kill`.
- Availability: Windows.
+ .. availability:: Windows.
.. versionadded:: 3.2
@@ -193,7 +193,9 @@ The :mod:`signal` module defines the following functions:
then the number of seconds before any previously set alarm was to have been
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. (See
- the Unix man page :manpage:`alarm(2)`.) Availability: Unix.
+ the Unix man page :manpage:`alarm(2)`.)
+
+ .. availability:: Unix.
.. function:: getsignal(signalnum)
@@ -252,8 +254,8 @@ The :mod:`signal` module defines the following functions:
If *signalnum* is 0, then no signal is sent, but error checking is still
performed; this can be used to check if the target thread is still running.
- 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`.
@@ -283,8 +285,8 @@ The :mod:`signal` module defines the following functions:
For example, ``signal.pthread_sigmask(signal.SIG_BLOCK, [])`` reads the
signal mask of the calling thread.
- Availability: Unix. See the man page :manpage:`sigprocmask(3)` and
- :manpage:`pthread_sigmask(3)` for further information.
+ .. availability:: Unix. See the man page :manpage:`sigprocmask(3)` and
+ :manpage:`pthread_sigmask(3)` for further information.
See also :func:`pause`, :func:`sigpending` and :func:`sigwait`.
@@ -309,13 +311,16 @@ The :mod:`signal` module defines the following functions:
The old values are returned as a tuple: (delay, interval).
Attempting to pass an invalid interval timer will cause an
- :exc:`ItimerError`. Availability: Unix.
+ :exc:`ItimerError`.
+
+ .. availability:: Unix.
.. function:: getitimer(which)
Returns current value of a given interval timer specified by *which*.
- Availability: Unix.
+
+ .. availability:: Unix.
.. function:: set_wakeup_fd(fd, *, warn_on_full_buffer=True)
@@ -365,8 +370,10 @@ The :mod:`signal` module defines the following functions:
Change system call restart behaviour: if *flag* is :const:`False`, system
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).
+ system calls will be interrupted. Returns nothing.
+
+ .. 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
@@ -405,8 +412,8 @@ 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`.
@@ -419,8 +426,8 @@ 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`.
@@ -444,8 +451,8 @@ 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`.
@@ -463,8 +470,8 @@ 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 bfb315f1875a..d466884d6135 100644
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -161,7 +161,7 @@ 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
@@ -169,7 +169,7 @@ 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 >= 4.8 QEMU >= 2.8 ESX >= 4.0 ESX Workstation >= 6.5.
.. versionadded:: 3.7
@@ -313,7 +313,7 @@ Constants
`Secure File Descriptor Handling <http://udrepper.livejournal.com/20407.html>`_
for a more thorough explanation.
- Availability: Linux >= 2.6.27.
+ .. availability:: Linux >= 2.6.27.
.. versionadded:: 3.2
@@ -361,7 +361,7 @@ Constants
Many constants of these forms, documented in the Linux documentation, are
also defined in the socket module.
- Availability: Linux >= 2.6.25.
+ .. availability:: Linux >= 2.6.25.
.. versionadded:: 3.3
@@ -372,7 +372,7 @@ Constants
Broadcast manager constants, documented in the Linux documentation, are also
defined in the socket module.
- Availability: Linux >= 2.6.25.
+ .. availability:: Linux >= 2.6.25.
.. versionadded:: 3.4
@@ -384,7 +384,7 @@ Constants
This constant is documented in the Linux documentation.
- Availability: Linux >= 3.6.
+ .. availability:: Linux >= 3.6.
.. versionadded:: 3.5
@@ -393,7 +393,7 @@ Constants
CAN_ISOTP, in the CAN protocol family, is the ISO-TP (ISO 15765-2) protocol.
ISO-TP constants, documented in the Linux documentation.
- Availability: Linux >= 2.6.25
+ .. availability:: Linux >= 2.6.25.
.. versionadded:: 3.7
@@ -405,7 +405,7 @@ Constants
Many constants of these forms, documented in the Linux documentation, are
also defined in the socket module.
- Availability: Linux >= 2.2.
+ .. availability:: Linux >= 2.2.
.. data:: AF_RDS
@@ -416,7 +416,7 @@ Constants
Many constants of these forms, documented in the Linux documentation, are
also defined in the socket module.
- Availability: Linux >= 2.6.30.
+ .. availability:: Linux >= 2.6.30.
.. versionadded:: 3.3
@@ -444,7 +444,7 @@ Constants
Constants for Linux Kernel cryptography.
- Availability: Linux >= 2.6.38.
+ .. availability:: Linux >= 2.6.38.
.. versionadded:: 3.6
@@ -456,13 +456,13 @@ Constants
Constants for Linux host/guest communication.
- Availability: Linux >= 4.8.
+ .. availability:: Linux >= 4.8.
.. versionadded:: 3.7
.. data:: AF_LINK
- Availability: BSD, OSX.
+ .. availability:: BSD, OSX.
.. versionadded:: 3.4
@@ -493,7 +493,7 @@ Constants
Constant for Qualcomm's IPC router protocol, used to communicate with
service providing remote processors.
- Availability: Linux >= 4.7.
+ .. availability:: Linux >= 4.7.
Functions
^^^^^^^^^
@@ -618,7 +618,7 @@ The following functions all create :ref:`socket objects <socket-objects>`.
Instantiate a socket from data obtained from the :meth:`socket.share`
method. The socket is assumed to be in blocking mode.
- Availability: Windows.
+ .. availability:: Windows.
.. versionadded:: 3.3
@@ -865,7 +865,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 (maybe not all platforms), Windows.
.. versionchanged:: 3.4
Windows support added
@@ -885,7 +885,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 (maybe not all platforms), Windows.
.. versionchanged:: 3.4
Windows support added
@@ -911,7 +911,7 @@ 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:: most Unix platforms, possibly others.
.. versionadded:: 3.3
@@ -932,7 +932,7 @@ 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:: most Unix platforms, possibly others.
.. versionadded:: 3.3
@@ -957,7 +957,7 @@ The :mod:`socket` module also offers various network-related services:
Set the machine's hostname to *name*. This will raise an
:exc:`OSError` if you don't have enough rights.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
@@ -968,7 +968,7 @@ The :mod:`socket` module also offers various network-related services:
(index int, name string) tuples.
:exc:`OSError` if the system call fails.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
@@ -979,7 +979,7 @@ The :mod:`socket` module also offers various network-related services:
interface name.
:exc:`OSError` if no interface with the given name exists.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
@@ -990,7 +990,7 @@ The :mod:`socket` module also offers various network-related services:
interface index number.
:exc:`OSError` if no interface with the given index exists.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
@@ -1317,7 +1317,7 @@ to sockets.
fds.fromstring(cmsg_data[:len(cmsg_data) - (len(cmsg_data) % fds.itemsize)])
return msg, list(fds)
- Availability: most Unix platforms, possibly others.
+ .. availability:: most Unix platforms, possibly others.
.. versionadded:: 3.3
@@ -1359,7 +1359,7 @@ 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:: most Unix platforms, possibly others.
.. versionadded:: 3.3
@@ -1463,7 +1463,7 @@ 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:: most Unix platforms, possibly others.
.. versionadded:: 3.3
@@ -1477,7 +1477,7 @@ to sockets.
Specialized version of :meth:`~socket.sendmsg` for :const:`AF_ALG` socket.
Set mode, IV, AEAD associated data length and flags for :const:`AF_ALG` socket.
- Availability: Linux >= 2.6.38
+ .. availability:: Linux >= 2.6.38.
.. versionadded:: 3.6
@@ -1578,7 +1578,7 @@ to sockets.
Once this method has been called, it is safe to close the socket since
the operating system has already duplicated it for the target process.
- Availability: Windows.
+ .. availability:: Windows.
.. versionadded:: 3.3
diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst
index 9dadc58b650c..5b0ef2e1d361 100644
--- a/Doc/library/ssl.rst
+++ b/Doc/library/ssl.rst
@@ -328,7 +328,7 @@ Random generation
See http://egd.sourceforge.net/ or http://prngd.sourceforge.net/ for sources
of entropy-gathering daemons.
- Availability: not available with LibreSSL and OpenSSL > 1.1.0
+ .. availability:: not available with LibreSSL and OpenSSL > 1.1.0.
.. function:: RAND_add(bytes, entropy)
@@ -460,8 +460,8 @@ 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`
+ .. availability:: LibreSSL ignores the environment vars
+ :attr:`openssl_cafile_env` and :attr:`openssl_capath_env`.
.. versionadded:: 3.4
@@ -484,7 +484,7 @@ Certificate handling
[(b'data...', 'x509_asn', {'1.3.6.1.5.5.7.3.1', '1.3.6.1.5.5.7.3.2'}),
(b'data...', 'x509_asn', True)]
- Availability: Windows.
+ .. availability:: Windows.
.. versionadded:: 3.4
@@ -499,7 +499,7 @@ Certificate handling
:const:`x509_asn` for X.509 ASN.1 data or :const:`pkcs_7_asn` for
PKCS#7 ASN.1 data.
- Availability: Windows.
+ .. availability:: Windows.
.. versionadded:: 3.4
@@ -1610,7 +1610,7 @@ to speed up repeated connections from the same clients.
'strength_bits': 128,
'symmetric': 'aes-128-gcm'}]
- Availability: OpenSSL 1.0.2+
+ .. availability:: OpenSSL 1.0.2+.
.. versionadded:: 3.6
diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
index aa889ed00b03..8f4377bb526f 100644
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -1330,7 +1330,7 @@ handling consistency are valid for these functions.
>>> subprocess.getstatusoutput('/bin/kill $$')
(-15, '')
- Availability: POSIX & Windows
+ .. availability:: POSIX & Windows.
.. versionchanged:: 3.3.4
Windows support was added.
@@ -1350,7 +1350,7 @@ handling consistency are valid for these functions.
>>> subprocess.getoutput('ls /bin/ls')
'/bin/ls'
- Availability: POSIX & Windows
+ .. availability:: POSIX & Windows.
.. versionchanged:: 3.3.4
Windows support added
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index cd43e541f13e..46d8db0230b8 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -161,7 +161,9 @@ always available.
.. data:: dllhandle
- Integer specifying the handle of the Python DLL. Availability: Windows.
+ Integer specifying the handle of the Python DLL.
+
+ .. availability:: Windows.
.. function:: displayhook(value)
@@ -477,7 +479,7 @@ always available.
Return the build time API version of Android as an integer.
- Availability: Android.
+ .. availability:: Android.
.. versionadded:: 3.7
@@ -501,7 +503,9 @@ always available.
Return the current value of the flags that are used for
:c:func:`dlopen` calls. Symbolic names for the flag values can be
found in the :mod:`os` module (``RTLD_xxx`` constants, e.g.
- :data:`os.RTLD_LAZY`). Availability: Unix.
+ :data:`os.RTLD_LAZY`).
+
+ .. availability:: Unix.
.. function:: getfilesystemencoding()
@@ -669,7 +673,7 @@ always available.
is being emulated for the process. It is intended for use in logging rather
than for feature detection.
- Availability: Windows.
+ .. availability:: Windows.
.. versionchanged:: 3.2
Changed to a named tuple and added *service_pack_minor*,
@@ -1094,7 +1098,7 @@ always available.
can be found in the :mod:`os` module (``RTLD_xxx`` constants, e.g.
:data:`os.RTLD_LAZY`).
- Availability: Unix.
+ .. availability:: Unix.
.. function:: setprofile(profilefunc)
@@ -1340,7 +1344,7 @@ always available.
This is equivalent to defining the :envvar:`PYTHONLEGACYWINDOWSFSENCODING`
environment variable before launching Python.
- Availability: Windows
+ .. availability:: Windows.
.. versionadded:: 3.6
See :pep:`529` for more details.
@@ -1486,7 +1490,9 @@ always available.
stored as string resource 1000 in the Python DLL. The value is normally the
first three characters of :const:`version`. It is provided in the :mod:`sys`
module for informational purposes; modifying this value has no effect on the
- registry keys used by Python. Availability: Windows.
+ registry keys used by Python.
+
+ .. availability:: Windows.
.. data:: _xoptions
diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst
index e6185c5b3a21..a9d5268dd2b8 100644
--- a/Doc/library/threading.rst
+++ b/Doc/library/threading.rst
@@ -100,7 +100,8 @@ This module defines the following functions:
memory page size - platform documentation should be referred to for more
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, systems with POSIX threads.
This module also defines the following constant:
diff --git a/Doc/library/time.rst b/Doc/library/time.rst
index 3eddc3f1ad3d..56f972c9d032 100644
--- a/Doc/library/time.rst
+++ b/Doc/library/time.rst
@@ -170,8 +170,8 @@ 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
@@ -180,7 +180,7 @@ Functions
Return the resolution (precision) of the specified clock *clk_id*. Refer to
:ref:`time-clock-id-constants` for a list of accepted values for *clk_id*.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
@@ -190,7 +190,7 @@ Functions
Return the time of the specified clock *clk_id*. Refer to
:ref:`time-clock-id-constants` for a list of accepted values for *clk_id*.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
@@ -199,7 +199,7 @@ Functions
Similar to :func:`clock_gettime` but return time as nanoseconds.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.7
@@ -209,7 +209,7 @@ Functions
Set the time of the specified clock *clk_id*. Currently,
:data:`CLOCK_REALTIME` is the only accepted value for *clk_id*.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
@@ -218,7 +218,7 @@ Functions
Similar to :func:`clock_settime` but set time with nanoseconds.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.7
@@ -617,8 +617,8 @@ Functions
returned value is undefined, so that only the difference between the results
of consecutive calls in the same thread is valid.
- Availability: Windows, Linux, Unix systems supporting
- ``CLOCK_THREAD_CPUTIME_ID``.
+ .. availability:: Windows, Linux, Unix systems supporting
+ ``CLOCK_THREAD_CPUTIME_ID``.
.. versionadded:: 3.7
@@ -647,7 +647,7 @@ Functions
nonzero if there is a time, past, present or future when daylight saving time
applies).
- Availability: Unix.
+ .. availability:: Unix.
.. note::
@@ -743,7 +743,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 or later.
.. versionadded:: 3.7
@@ -754,7 +754,7 @@ These constants are used as parameters for :func:`clock_getres` and
hardware source, and may give close to nanosecond resolution.
``CLOCK_HIGHRES`` is the nonadjustable, high-resolution clock.
- Availability: Solaris.
+ .. availability:: Solaris.
.. versionadded:: 3.3
@@ -764,7 +764,7 @@ These constants are used as parameters for :func:`clock_getres` and
Clock that cannot be set and represents monotonic time since some unspecified
starting point.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
@@ -783,7 +783,7 @@ These constants are used as parameters for :func:`clock_getres` and
High-resolution per-process timer from the CPU.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
@@ -792,7 +792,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 or later, OpenBSD.
.. versionadded:: 3.7
@@ -812,7 +812,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 or later.
.. versionadded:: 3.7
@@ -825,7 +825,7 @@ The following constant is the only parameter that can be sent to
System-wide real-time clock. Setting this clock requires appropriate
privileges.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
diff --git a/Doc/tools/extensions/pyspecific.py b/Doc/tools/extensions/pyspecific.py
index 8036daa7d1de..132920f130ad 100644
--- a/Doc/tools/extensions/pyspecific.py
+++ b/Doc/tools/extensions/pyspecific.py
@@ -131,6 +131,25 @@ def run(self):
return [pnode]
+# Support for documenting platform availability
+
+class Availability(Directive):
+
+ has_content = False
+ required_arguments = 1
+ optional_arguments = 0
+ final_argument_whitespace = True
+
+ def run(self):
+ pnode = nodes.paragraph(classes=['availability'])
+ n, m = self.state.inline_text(':ref:`Availability <availability>`: ',
+ self.lineno)
+ pnode.extend(n + m)
+ n, m = self.state.inline_text(self.arguments[0], self.lineno)
+ pnode.extend(n + m)
+ return [pnode]
+
+
# Support for documenting decorators
class PyDecoratorMixin(object):
@@ -401,6 +420,7 @@ def setup(app):
app.add_role('issue', issue_role)
app.add_role('source', source_role)
app.add_directive('impl-detail', ImplementationDetail)
+ app.add_directive('availability', Availability)
app.add_directive('deprecated-removed', DeprecatedRemoved)
app.add_builder(PydocTopicsBuilder)
app.add_builder(suspicious.CheckSuspiciousMarkupBuilder)
diff --git a/Doc/tools/rstlint.py b/Doc/tools/rstlint.py
index 2c1816eedf92..a3024d6734d2 100755
--- a/Doc/tools/rstlint.py
+++ b/Doc/tools/rstlint.py
@@ -27,17 +27,18 @@
'table', 'target-notes', 'tip', 'title', 'topic', 'unicode', 'warning',
# Sphinx and Python docs custom ones
'acks', 'attribute', 'autoattribute', 'autoclass', 'autodata',
- 'autoexception', 'autofunction', 'automethod', 'automodule', 'centered',
- 'cfunction', 'class', 'classmethod', 'cmacro', 'cmdoption', 'cmember',
- 'code-block', 'confval', 'cssclass', 'ctype', 'currentmodule', 'cvar',
- 'data', 'decorator', 'decoratormethod', 'deprecated-removed',
- 'deprecated(?!-removed)', 'describe', 'directive', 'doctest', 'envvar',
- 'event', 'exception', 'function', 'glossary', 'highlight', 'highlightlang',
- 'impl-detail', 'index', 'literalinclude', 'method', 'miscnews', 'module',
- 'moduleauthor', 'opcode', 'pdbcommand', 'productionlist',
- 'program', 'role', 'sectionauthor', 'seealso', 'sourcecode', 'staticmethod',
- 'tabularcolumns', 'testcode', 'testoutput', 'testsetup', 'toctree', 'todo',
- 'todolist', 'versionadded', 'versionchanged'
+ 'autoexception', 'autofunction', 'automethod', 'automodule',
+ 'availability', 'centered', 'cfunction', 'class', 'classmethod', 'cmacro',
+ 'cmdoption', 'cmember', 'code-block', 'confval', 'cssclass', 'ctype',
+ 'currentmodule', 'cvar', 'data', 'decorator', 'decoratormethod',
+ 'deprecated-removed', 'deprecated(?!-removed)', 'describe', 'directive',
+ 'doctest', 'envvar', 'event', 'exception', 'function', 'glossary',
+ 'highlight', 'highlightlang', 'impl-detail', 'index', 'literalinclude',
+ 'method', 'miscnews', 'module', 'moduleauthor', 'opcode', 'pdbcommand',
+ 'productionlist', 'program', 'role', 'sectionauthor', 'seealso',
+ 'sourcecode', 'staticmethod', 'tabularcolumns', 'testcode', 'testoutput',
+ 'testsetup', 'toctree', 'todo', 'todolist', 'versionadded',
+ 'versionchanged'
]
all_directives = '(' + '|'.join(directives) + ')'
diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
index b61df8a4b77d..bd3cdef57390 100644
--- a/Doc/using/cmdline.rst
+++ b/Doc/using/cmdline.rst
@@ -785,7 +785,7 @@ conflict.
This may also be enabled at runtime with
:func:`sys._enablelegacywindowsfsencoding()`.
- Availability: Windows
+ .. availability:: Windows.
.. versionadded:: 3.6
See :pep:`529` for more details.
@@ -799,7 +799,7 @@ conflict.
This variable is ignored if the standard streams are redirected (to files
or pipes) rather than referring to console buffers.
- Availability: Windows
+ .. availability:: Windows.
.. versionadded:: 3.6
@@ -850,7 +850,7 @@ conflict.
order to force the interpreter to use ``ASCII`` instead of ``UTF-8`` for
system interfaces.
- Availability: \*nix
+ .. availability:: \*nix.
.. versionadded:: 3.7
See :pep:`538` for more details.
@@ -911,7 +911,7 @@ conflict.
Also available as the :option:`-X` ``utf8`` option.
- Availability: \*nix
+ .. availability:: \*nix.
.. versionadded:: 3.7
See :pep:`540` for more details.
diff --git a/Misc/NEWS.d/next/Documentation/2018-10-03-20-39-25.bpo-11233.BX6Gen.rst b/Misc/NEWS.d/next/Documentation/2018-10-03-20-39-25.bpo-11233.BX6Gen.rst
new file mode 100644
index 000000000000..0637dd66e42c
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2018-10-03-20-39-25.bpo-11233.BX6Gen.rst
@@ -0,0 +1,2 @@
+Create availability directive for documentation. Original patch by Georg
+Brandl.
More information about the Python-checkins
mailing list