Skip to content

bpo-11233: Create availability directive for documentation #9692

New issue

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

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

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Oct 12, 2018
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 16 additions & 6 deletions Doc/c-api/exceptions.rst
Original file line number Diff line number Diff line change
Expand Up @@ -186,42 +186,52 @@ 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


.. 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)
Expand Down
4 changes: 2 additions & 2 deletions Doc/c-api/init.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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

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

Expand Down
3 changes: 2 additions & 1 deletion Doc/library/_thread.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
10 changes: 5 additions & 5 deletions Doc/library/asyncio-eventloop.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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

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

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

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

Expand Down
4 changes: 2 additions & 2 deletions Doc/library/asyncio-policy.rst
Original file line number Diff line number Diff line change
Expand Up @@ -107,15 +107,15 @@ 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

An alternative event loop policy that uses the
:class:`ProactorEventLoop` event loop implementation.

Availability: Windows.
.. availability:: Windows.


Process Watchers
Expand Down
4 changes: 2 additions & 2 deletions Doc/library/asyncio-stream.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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

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

Expand Down
8 changes: 6 additions & 2 deletions Doc/library/asyncore.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion Doc/library/codecs.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion Doc/library/hashlib.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
13 changes: 13 additions & 0 deletions Doc/library/intro.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.

4 changes: 3 additions & 1 deletion Doc/library/mimetypes.rst
Original file line number Diff line number Diff line change
Expand Up @@ -255,7 +255,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.
Expand Down
10 changes: 5 additions & 5 deletions Doc/library/os.path.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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

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