Replace "Availability: xxx" with ".. availability:: xxx" in the doc.
Original patch by Georg Brandl.
Co-Authored-By: Georg Brandl <georg@python.org>
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
.. 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)
See :pep:`529` for more details.
- Availability: Windows.
+ .. availability:: Windows.
.. c:var:: Py_LegacyWindowsStdioFlag
See :pep:`528` for more details.
- Availability: Windows.
+ .. availability:: Windows.
.. c:var:: Py_NoSiteFlag
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
See the documentation of the :meth:`loop.create_connection` method
for information about arguments to this method.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.7
See the documentation of the :meth:`loop.create_server` method
for information about arguments to this method.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.7
Return ``True`` if the signal handler was removed, or ``False`` if
no handler was set for the given signal.
-Availability: Unix.
+ .. availability:: Unix.
.. seealso::
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::
An alternative event loop policy that uses the
:class:`SelectorEventLoop` event loop implementation.
- Availability: Windows.
+ .. availability:: Windows.
.. class:: WindowsProactorEventLoopPolicy
An alternative event loop policy that uses the
:class:`ProactorEventLoop` event loop implementation.
- Availability: Windows.
+ .. availability:: Windows.
Process Watchers
See also the documentation of :meth:`loop.create_unix_connection`.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.7
See also the documentation of :meth:`loop.create_unix_server`.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.7
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:
Encode operand according to the ANSI codepage (CP_ACP).
-Availability: Windows only.
+.. availability:: Windows only.
.. versionchanged:: 3.3
Support any error handler.
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
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.
+
.. 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.
pathnames, or if *paths* is empty. Unlike :func:`commonprefix`, this
returns a valid path.
- Availability: Unix, Windows
+ .. availability:: Unix, Windows.
.. versionadded:: 3.5
*start* defaults to :attr:`os.curdir`.
- Availability: Unix, Windows.
+ .. availability:: Unix, Windows.
.. versionchanged:: 3.6
Accepts a :term:`path-like object`.
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.
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.
: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.
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::
Return the filename corresponding to the controlling terminal of the process.
- Availability: Unix.
+ .. availability:: Unix.
.. data:: environ
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)
: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
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()
Return the current process's effective user id.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: getgid()
Return the real group id of the current process.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: getgrouplist(user, group)
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
Return list of supplemental group ids associated with the current process.
- Availability: Unix.
+ .. availability:: Unix.
.. note::
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)
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()
Return the id of the current process group.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: getpid()
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.
(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
Parameters for the :func:`getpriority` and :func:`setpriority` functions.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
Return a tuple (ruid, euid, suid) denoting the current process's
real, effective, and saved user ids.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.2
Return a tuple (rgid, egid, sgid) denoting the current process's
real, effective, and saved group ids.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.2
Return the current process's real user id.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: initgroups(username, gid)
the groups of which the specified username is a member, plus the specified
group id.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.2
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::
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)
*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.
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)
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)
*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
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
Set the current process's real, effective, and saved user ids.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.2
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)
Set the current process's user id.
- Availability: Unix.
+ .. availability:: Unix.
.. placed in this section since it relates to errno.... a little weak
: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
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:
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)
:func:`chown`. As of Python 3.3, this is equivalent to ``os.chown(fd, uid,
gid)``.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: fdatasync(fd)
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.
As of Python 3.3, this is equivalent to ``os.pathconf(fd, name)``.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: fstat(fd)
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)
``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)
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
See also :func:`set_blocking` and :meth:`socket.socket.setblocking`.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.5
:data:`F_ULOCK` or :data:`F_TEST`.
*len* specifies the section of the file to lock.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
Flags that specify what action :func:`lockf` will take.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
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.
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.
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
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
:data:`POSIX_FADV_RANDOM`, :data:`POSIX_FADV_NOREUSE`,
:data:`POSIX_FADV_WILLNEED` or :data:`POSIX_FADV_DONTNEED`.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
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
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
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
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
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
Return the number of bytes actually written.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
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
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
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
Cross-platform applications should not use *headers*, *trailers* and *flags*
arguments.
- Availability: Unix.
+ .. availability:: Unix.
.. note::
See also :func:`get_blocking` and :meth:`socket.socket.setblocking`.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.5
Parameters to the :func:`sendfile` function, if the implementation supports
them.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
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
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)
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)
file descriptor *fd*. If *fd* is not associated with a terminal device, an
exception is raised.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: write(fd, str)
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
should normally be used, ``os.get_terminal_size`` is the low-level
implementation.
- Availability: Unix, Windows.
+ .. availability:: Unix, Windows.
.. class:: terminal_size
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:
This function can support :ref:`not following symlinks <follow_symlinks>`.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
The *follow_symlinks* argument.
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*,
Change the root directory of the current process to *path*.
- Availability: Unix.
+ .. availability:: Unix.
.. versionchanged:: 3.6
Accepts a :term:`path-like object`.
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()
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`.
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`.
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`.
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.
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.
This function can also support :ref:`paths relative to directory descriptors
<dir_fd>`.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
The *dir_fd* argument.
This function can support :ref:`specifying a file descriptor
<path_fd>`.
- Availability: Unix.
+ .. availability:: Unix.
.. versionchanged:: 3.6
Accepts a :term:`path-like object`.
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)
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.
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.
: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.
Force write of everything to disk.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
This function can support :ref:`specifying a file descriptor <path_fd>`.
- Availability: Unix, Windows.
+ .. availability:: Unix, Windows.
.. versionadded:: 3.3
for name in dirs:
os.rmdir(name, dir_fd=rootfd)
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
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*
Exit code that means no error occurred.
- Availability: Unix.
+ .. availability:: Unix.
.. data:: EX_USAGE
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
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
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
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
Exit code that means that a protocol exchange was illegal, invalid, or not
understood.
- Availability: Unix.
+ .. availability:: Unix.
.. data:: EX_NOPERM
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()
See :mod:`ssl` for applications that use the SSL module with fork().
- Availability: Unix.
+ .. availability:: Unix.
.. function:: forkpty()
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)
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)
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)
There is no way to unregister a function.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.7
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`.
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
of the process the run is successful, or ``-signal`` if a signal kills the
process.
- Availability: Unix, Windows.
+ .. availability:: Unix, Windows.
.. data:: P_DETACH
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])
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)
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()
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
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)
: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
These are the possible values for *idtype* in :func:`waitid`. They affect
how *id* is interpreted.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
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
These are the possible values for :attr:`si_code` in the result returned by
:func:`waitid`.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
option argument is the same as that provided to :func:`waitpid` and
:func:`wait4`.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: wait4(pid, options)
resource usage information. The arguments to :func:`wait4` are the same
as those provided to :func:`waitpid`.
- Availability: Unix.
+ .. availability:: Unix.
.. data:: WNOHANG
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
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
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
Return ``True`` if a core dump was generated for the process, otherwise
return ``False``.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: WIFCONTINUED(status)
Return ``True`` if the process has been continued from a job control stop,
otherwise return ``False``.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: WIFSTOPPED(status)
Return ``True`` if the process has been stopped, otherwise return
``False``.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: WIFSIGNALED(status)
Return ``True`` if the process exited due to a signal, otherwise return
``False``.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: WIFEXITED(status)
Return ``True`` if the process exited using the :manpage:`exit(2)` system call,
otherwise return ``False``.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: WEXITSTATUS(status)
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
included in ``confstr_names``, an :exc:`OSError` is raised with
:const:`errno.EINVAL` for the error number.
- Availability: Unix.
+ .. availability:: Unix.
.. data:: confstr_names
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()
1, 5, and 15 minutes or raises :exc:`OSError` if the load average was
unobtainable.
- Availability: Unix.
+ .. availability:: Unix.
.. function:: sysconf(name)
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
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.
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
: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
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
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
The ceiling of the real-time priority.
- Availability: Linux 2.6.12 or later.
+ .. availability:: Linux 2.6.12 or later.
.. versionadded:: 3.4
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
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
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
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
The maximum number of pseudo-terminals created by this user id.
- Availability: FreeBSD 9 or later.
+ .. availability:: FreeBSD 9 or later.
.. versionadded:: 3.4
: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
.. 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)
See also :func:`os.chown`, the underlying function.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
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
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
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)
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`.
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`.
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)
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
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`.
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`.
: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`.
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`.
- *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
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
`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
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
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
This constant is documented in the Linux documentation.
- Availability: Linux >= 3.6.
+ .. availability:: Linux >= 3.6.
.. versionadded:: 3.5
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
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
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
Constants for Linux Kernel cryptography.
- Availability: Linux >= 2.6.38.
+ .. availability:: Linux >= 2.6.38.
.. versionadded:: 3.6
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
Constant for Qualcomm's IPC router protocol, used to communicate with
service providing remote processors.
- Availability: Linux >= 4.7.
+ .. availability:: Linux >= 4.7.
Functions
^^^^^^^^^
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
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
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
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
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
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
(index int, name string) tuples.
:exc:`OSError` if the system call fails.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
interface name.
:exc:`OSError` if no interface with the given name exists.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
interface index number.
:exc:`OSError` if no interface with the given index exists.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
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
>>> [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
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
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
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
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)
* :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
[(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
: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
'strength_bits': 128,
'symmetric': 'aes-128-gcm'}]
- Availability: OpenSSL 1.0.2+
+ .. availability:: OpenSSL 1.0.2+.
.. versionadded:: 3.6
>>> subprocess.getstatusoutput('/bin/kill $$')
(-15, '')
- Availability: POSIX & Windows
+ .. availability:: POSIX & Windows.
.. versionchanged:: 3.3.4
Windows support was added.
>>> subprocess.getoutput('ls /bin/ls')
'/bin/ls'
- Availability: POSIX & Windows
+ .. availability:: POSIX & Windows.
.. versionchanged:: 3.3.4
Windows support added
.. 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)
Return the build time API version of Android as an integer.
- Availability: Android.
+ .. availability:: Android.
.. versionadded:: 3.7
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()
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*,
can be found in the :mod:`os` module (``RTLD_xxx`` constants, e.g.
:data:`os.RTLD_LAZY`).
- Availability: Unix.
+ .. availability:: Unix.
.. function:: setprofile(profilefunc)
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.
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
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:
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
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
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
Similar to :func:`clock_gettime` but return time as nanoseconds.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.7
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
Similar to :func:`clock_settime` but set time with nanoseconds.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.7
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
nonzero if there is a time, past, present or future when daylight saving time
applies).
- Availability: Unix.
+ .. availability:: Unix.
.. note::
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
hardware source, and may give close to nanosecond resolution.
``CLOCK_HIGHRES`` is the nonadjustable, high-resolution clock.
- Availability: Solaris.
+ .. availability:: Solaris.
.. versionadded:: 3.3
Clock that cannot be set and represents monotonic time since some unspecified
starting point.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
High-resolution per-process timer from the CPU.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
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
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
System-wide real-time clock. Setting this clock requires appropriate
privileges.
- Availability: Unix.
+ .. availability:: Unix.
.. versionadded:: 3.3
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):
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)
'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) + ')'
This may also be enabled at runtime with
:func:`sys._enablelegacywindowsfsencoding()`.
- Availability: Windows
+ .. availability:: Windows.
.. versionadded:: 3.6
See :pep:`529` for more details.
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
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.
Also available as the :option:`-X` ``utf8`` option.
- Availability: \*nix
+ .. availability:: \*nix.
.. versionadded:: 3.7
See :pep:`540` for more details.
--- /dev/null
+Create availability directive for documentation. Original patch by Georg
+Brandl.
projects / python / commitdiff