Skip to content

Commit b248a8c

Browse files
csabellavstinner
csabella
authored and
vstinner
committed
[3.7] bpo-11233: Create availability directive for documentation (GH-9692) (GH-9830)
Replace "Availability: xxx" with ".. availability:: xxx" in the doc. Original patch by Georg Brandl. Co-Authored-By: Georg Brandl <georg@python.org> (cherry picked from commit 2d6097d) Co-authored-by: Cheryl Sabella <cheryl.sabella@gmail.com>
1 parent c804a59 commit b248a8c

27 files changed

Lines changed: 349 additions & 289 deletions

‎Doc/c-api/exceptions.rst‎

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -186,42 +186,52 @@ NULL pointer for use in a ``return`` statement.
186186
then it constructs a tuple object whose first item is the *ierr* value and whose
187187
second item is the corresponding error message (gotten from
188188
:c:func:`FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError,
189-
object)``. This function always returns *NULL*. Availability: Windows.
189+
object)``. This function always returns *NULL*.
190+
191+
.. availability:: Windows.
190192
191193
192194
.. c:function:: PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)
193195
194196
Similar to :c:func:`PyErr_SetFromWindowsErr`, with an additional parameter
195-
specifying the exception type to be raised. Availability: Windows.
197+
specifying the exception type to be raised.
198+
199+
.. availability:: Windows.
196200
197201
198202
.. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)
199203
200204
Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, but the
201205
filename is given as a C string. *filename* is decoded from the filesystem
202-
encoding (:func:`os.fsdecode`). Availability: Windows.
206+
encoding (:func:`os.fsdecode`).
207+
208+
.. availability:: Windows.
203209
204210
205211
.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename)
206212
207213
Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, with an
208214
additional parameter specifying the exception type to be raised.
209-
Availability: Windows.
215+
216+
.. availability:: Windows.
210217
211218
212219
.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenameObjects(PyObject *type, int ierr, PyObject *filename, PyObject *filename2)
213220
214221
Similar to :c:func:`PyErr_SetExcFromWindowsErrWithFilenameObject`,
215222
but accepts a second filename object.
216-
Availability: Windows.
223+
224+
.. availability:: Windows.
217225
218226
.. versionadded:: 3.4
219227
220228
221229
.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, const char *filename)
222230
223231
Similar to :c:func:`PyErr_SetFromWindowsErrWithFilename`, with an additional
224-
parameter specifying the exception type to be raised. Availability: Windows.
232+
parameter specifying the exception type to be raised.
233+
234+
.. availability:: Windows.
225235
226236
227237
.. c:function:: PyObject* PyErr_SetImportError(PyObject *msg, PyObject *name, PyObject *path)

‎Doc/c-api/init.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -156,7 +156,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
156156

157157
See :pep:`529` for more details.
158158

159-
Availability: Windows.
159+
.. availability:: Windows.
160160

161161
.. c:var:: Py_LegacyWindowsStdioFlag
162162
@@ -168,7 +168,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
168168

169169
See :pep:`528` for more details.
170170

171-
Availability: Windows.
171+
.. availability:: Windows.
172172

173173
.. c:var:: Py_NoSiteFlag
174174

‎Doc/library/_thread.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -101,7 +101,8 @@ This module defines the following constants and functions:
101101
memory page size - platform documentation should be referred to for more
102102
information (4 KiB pages are common; using multiples of 4096 for the stack size is
103103
the suggested approach in the absence of more specific information).
104-
Availability: Windows, systems with POSIX threads.
104+
105+
.. availability:: Windows, systems with POSIX threads.
105106

106107

107108
.. data:: TIMEOUT_MAX

‎Doc/library/asyncio-eventloop.rst‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -504,7 +504,7 @@ Opening network connections
504504
See the documentation of the :meth:`loop.create_connection` method
505505
for information about arguments to this method.
506506

507-
Availability: Unix.
507+
.. availability:: Unix.
508508

509509
.. versionadded:: 3.7
510510

@@ -624,7 +624,7 @@ Creating network servers
624624
See the documentation of the :meth:`loop.create_server` method
625625
for information about arguments to this method.
626626

627-
Availability: Unix.
627+
.. availability:: Unix.
628628

629629
.. versionadded:: 3.7
630630

@@ -973,7 +973,7 @@ Unix signals
973973
Return ``True`` if the signal handler was removed, or ``False`` if
974974
no handler was set for the given signal.
975975

976-
Availability: Unix.
976+
.. availability:: Unix.
977977

978978
.. seealso::
979979

@@ -1417,14 +1417,14 @@ on all platforms.
14171417
asyncio.set_event_loop(loop)
14181418

14191419

1420-
Availability: Unix, Windows.
1420+
.. availability:: Unix, Windows.
14211421

14221422

14231423
.. class:: ProactorEventLoop
14241424

14251425
An event loop for Windows that uses "I/O Completion Ports" (IOCP).
14261426

1427-
Availability: Windows.
1427+
.. availability:: Windows.
14281428

14291429
An example how to use :class:`ProactorEventLoop` on Windows::
14301430

‎Doc/library/asyncio-policy.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -103,7 +103,7 @@ asyncio ships with the following built-in policies:
103103
An alternative event loop policy that uses the
104104
:class:`ProactorEventLoop` event loop implementation.
105105

106-
Availability: Windows.
106+
.. availability:: Windows.
107107

108108

109109
Process Watchers

‎Doc/library/asyncio-stream.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -115,7 +115,7 @@ and work with streams:
115115

116116
See also the documentation of :meth:`loop.create_unix_connection`.
117117

118-
Availability: Unix.
118+
.. availability:: Unix.
119119

120120
.. versionadded:: 3.7
121121

@@ -137,7 +137,7 @@ and work with streams:
137137

138138
See also the documentation of :meth:`loop.create_unix_server`.
139139

140-
Availability: Unix.
140+
.. availability:: Unix.
141141

142142
.. versionadded:: 3.7
143143

‎Doc/library/asyncore.rst‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -273,14 +273,18 @@ any that have been added to the map during asynchronous service) is closed.
273273
with an optional map argument and wraps it for use with the :c:func:`poll`
274274
or :c:func:`loop` functions. If provided a file object or anything with a
275275
:c:func:`fileno` method, that method will be called and passed to the
276-
:class:`file_wrapper` constructor. Availability: UNIX.
276+
:class:`file_wrapper` constructor.
277+
278+
.. availability:: Unix.
277279

278280
.. class:: file_wrapper()
279281

280282
A file_wrapper takes an integer file descriptor and calls :func:`os.dup` to
281283
duplicate the handle so that the original handle may be closed independently
282284
of the file_wrapper. This class implements sufficient methods to emulate a
283-
socket for use by the :class:`file_dispatcher` class. Availability: UNIX.
285+
socket for use by the :class:`file_dispatcher` class.
286+
287+
.. availability:: Unix.
284288

285289

286290
.. _asyncore-example-1:

‎Doc/library/codecs.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1471,7 +1471,7 @@ functions can be used directly if desired.
14711471

14721472
Encode operand according to the ANSI codepage (CP_ACP).
14731473

1474-
Availability: Windows only.
1474+
.. availability:: Windows only.
14751475

14761476
.. versionchanged:: 3.3
14771477
Support any error handler.

‎Doc/library/hashlib.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -271,7 +271,7 @@ include a `salt <https://en.wikipedia.org/wiki/Salt_%28cryptography%29>`_.
271271
factor and *maxmem* limits memory (OpenSSL 1.1.0 defaults to 32 MiB).
272272
*dklen* is the length of the derived key.
273273

274-
Availability: OpenSSL 1.1+
274+
.. availability:: OpenSSL 1.1+.
275275

276276
.. versionadded:: 3.6
277277

‎Doc/library/intro.rst‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,3 +47,16 @@ this material.
4747

4848
Let the show begin!
4949

50+
51+
.. _availability:
52+
53+
Notes on availability
54+
=====================
55+
56+
* An "Availability: Unix" note means that this function is commonly found on
57+
Unix systems. It does not make any claims about its existence on a specific
58+
operating system.
59+
60+
* If not separately noted, all functions that claim "Availability: Unix" are
61+
supported on Mac OS X, which builds on a Unix core.
62+

0 commit comments

Comments
 (0)