Issue #28496: Mark up constants 0, 1 and -1 that denote return values or · python/cpython@1ecf7d2 · GitHub
Skip to content

Commit 1ecf7d2

Browse files
serhiy-storchakaserhiy-storchaka
committed
Issue #28496: Mark up constants 0, 1 and -1 that denote return values or
special input values as literal text.
1 parent b29cee4 commit 1ecf7d2

12 files changed

Lines changed: 64 additions & 64 deletions

File tree

‎Doc/c-api/arg.rst‎

Lines changed: 1 addition & 1 deletion

‎Doc/c-api/buffer.rst‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -156,7 +156,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
156156
.. c:member:: int ndim
157157
158158
The number of dimensions the memory represents as an n-dimensional array.
159-
If it is 0, :c:member:`~Py_buffer.buf` points to a single item representing
159+
If it is ``0``, :c:member:`~Py_buffer.buf` points to a single item representing
160160
a scalar. In this case, :c:member:`~Py_buffer.shape`, :c:member:`~Py_buffer.strides`
161161
and :c:member:`~Py_buffer.suboffsets` MUST be *NULL*.
162162

@@ -427,7 +427,7 @@ Buffer-related functions
427427

428428
.. c:function:: int PyObject_CheckBuffer(PyObject *obj)
429429
430-
Return 1 if *obj* supports the buffer interface otherwise 0. When 1 is
430+
Return ``1`` if *obj* supports the buffer interface otherwise ``0``. When ``1`` is
431431
returned, it doesn't guarantee that :c:func:`PyObject_GetBuffer` will
432432
succeed.
433433
@@ -437,7 +437,7 @@ Buffer-related functions
437437
Send a request to *exporter* to fill in *view* as specified by *flags*.
438438
If the exporter cannot provide a buffer of the exact type, it MUST raise
439439
:c:data:`PyExc_BufferError`, set :c:member:`view->obj` to *NULL* and
440-
return -1.
440+
return ``-1``.
441441
442442
On success, fill in *view*, set :c:member:`view->obj` to a new reference
443443
to *exporter* and return 0. In the case of chained buffer providers
@@ -468,9 +468,9 @@ Buffer-related functions
468468
469469
.. c:function:: int PyBuffer_IsContiguous(Py_buffer *view, char order)
470470
471-
Return 1 if the memory defined by the *view* is C-style (*order* is
471+
Return ``1`` if the memory defined by the *view* is C-style (*order* is
472472
``'C'``) or Fortran-style (*order* is ``'F'``) :term:`contiguous` or either one
473-
(*order* is ``'A'``). Return 0 otherwise.
473+
(*order* is ``'A'``). Return ``0`` otherwise.
474474
475475
476476
.. c:function:: void PyBuffer_FillContiguousStrides(int ndim, Py_ssize_t *shape, Py_ssize_t *strides, Py_ssize_t itemsize, char order)
@@ -492,7 +492,7 @@ Buffer-related functions
492492
493493
On success, set :c:member:`view->obj` to a new reference to *exporter* and
494494
return 0. Otherwise, raise :c:data:`PyExc_BufferError`, set
495-
:c:member:`view->obj` to *NULL* and return -1;
495+
:c:member:`view->obj` to *NULL* and return ``-1``;
496496
497497
If this function is used as part of a :ref:`getbufferproc <buffer-structs>`,
498498
*exporter* MUST be set to the exporting object and *flags* must be passed

‎Doc/c-api/capsule.rst‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -120,31 +120,31 @@ Refer to :ref:`using-capsules` for more information on using these objects.
120120
guaranteed to succeed.
121121
122122
Return a nonzero value if the object is valid and matches the name passed in.
123-
Return 0 otherwise. This function will not fail.
123+
Return ``0`` otherwise. This function will not fail.
124124
125125
.. c:function:: int PyCapsule_SetContext(PyObject *capsule, void *context)
126126
127127
Set the context pointer inside *capsule* to *context*.
128128
129-
Return 0 on success. Return nonzero and set an exception on failure.
129+
Return ``0`` on success. Return nonzero and set an exception on failure.
130130
131131
.. c:function:: int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)
132132
133133
Set the destructor inside *capsule* to *destructor*.
134134
135-
Return 0 on success. Return nonzero and set an exception on failure.
135+
Return ``0`` on success. Return nonzero and set an exception on failure.
136136
137137
.. c:function:: int PyCapsule_SetName(PyObject *capsule, const char *name)
138138
139139
Set the name inside *capsule* to *name*. If non-*NULL*, the name must
140140
outlive the capsule. If the previous *name* stored in the capsule was not
141141
*NULL*, no attempt is made to free it.
142142
143-
Return 0 on success. Return nonzero and set an exception on failure.
143+
Return ``0`` on success. Return nonzero and set an exception on failure.
144144
145145
.. c:function:: int PyCapsule_SetPointer(PyObject *capsule, void *pointer)
146146
147147
Set the void pointer inside *capsule* to *pointer*. The pointer may not be
148148
*NULL*.
149149
150-
Return 0 on success. Return nonzero and set an exception on failure.
150+
Return ``0`` on success. Return nonzero and set an exception on failure.

‎Doc/c-api/import.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -185,10 +185,10 @@ Importing Modules
185185
186186
Return the magic number for Python bytecode files (a.k.a. :file:`.pyc` file).
187187
The magic number should be present in the first four bytes of the bytecode
188-
file, in little-endian byte order. Returns -1 on error.
188+
file, in little-endian byte order. Returns ``-1`` on error.
189189
190190
.. versionchanged:: 3.3
191-
Return value of -1 upon failure.
191+
Return value of ``-1`` upon failure.
192192
193193
194194
.. c:function:: const char * PyImport_GetMagicTag()

‎Doc/c-api/init.rst‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -44,8 +44,8 @@ Initializing and finalizing the interpreter
4444

4545
.. c:function:: void Py_InitializeEx(int initsigs)
4646
47-
This function works like :c:func:`Py_Initialize` if *initsigs* is 1. If
48-
*initsigs* is 0, it skips initialization registration of signal handlers, which
47+
This function works like :c:func:`Py_Initialize` if *initsigs* is ``1``. If
48+
*initsigs* is ``0``, it skips initialization registration of signal handlers, which
4949
might be useful when Python is embedded.
5050
5151
@@ -114,7 +114,7 @@ Process-wide parameters
114114
If :c:func:`Py_Finalize` is called, this function will need to be called
115115
again in order to affect subsequent calls to :c:func:`Py_Initialize`.
116116
117-
Returns 0 if successful, a nonzero value on error (e.g. calling after the
117+
Returns ``0`` if successful, a nonzero value on error (e.g. calling after the
118118
interpreter has already been initialized).
119119
120120
.. versionadded:: 3.4
@@ -349,7 +349,7 @@ Process-wide parameters
349349
- If the name of an existing script is passed in ``argv[0]``, the absolute
350350
path of the directory where the script is located is prepended to
351351
:data:`sys.path`.
352-
- Otherwise (that is, if *argc* is 0 or ``argv[0]`` doesn't point
352+
- Otherwise (that is, if *argc* is ``0`` or ``argv[0]`` doesn't point
353353
to an existing file name), an empty string is prepended to
354354
:data:`sys.path`, which is the same as prepending the current working
355355
directory (``"."``).
@@ -359,7 +359,7 @@ Process-wide parameters
359359

360360
.. note::
361361
It is recommended that applications embedding the Python interpreter
362-
for purposes other than executing a single script pass 0 as *updatepath*,
362+
for purposes other than executing a single script pass ``0`` as *updatepath*,
363363
and update :data:`sys.path` themselves if desired.
364364
See `CVE-2008-5983 <https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2008-5983>`_.
365365

@@ -371,14 +371,14 @@ Process-wide parameters
371371

372372
.. versionadded:: 3.1.3
373373

374-
.. XXX impl. doesn't seem consistent in allowing 0/NULL for the params;
374+
.. XXX impl. doesn't seem consistent in allowing ``0``/``NULL`` for the params;
375375
check w/ Guido.
376376
377377
378378
.. c:function:: void PySys_SetArgv(int argc, wchar_t **argv)
379379
380380
This function works like :c:func:`PySys_SetArgvEx` with *updatepath* set
381-
to 1 unless the :program:`python` interpreter was started with the
381+
to ``1`` unless the :program:`python` interpreter was started with the
382382
:option:`-I`.
383383
384384
Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
@@ -718,10 +718,10 @@ with sub-interpreters:
718718
719719
.. c:function:: int PyGILState_Check()
720720
721-
Return 1 if the current thread is holding the GIL and 0 otherwise.
721+
Return ``1`` if the current thread is holding the GIL and ``0`` otherwise.
722722
This function can be called from any thread at any time.
723723
Only if it has had its Python thread state initialized and currently is
724-
holding the GIL will it return 1.
724+
holding the GIL will it return ``1``.
725725
This is mainly a helper/diagnostic function. It can be useful
726726
for example in callback contexts or memory allocation functions when
727727
knowing that the GIL is locked can allow the caller to perform sensitive
@@ -991,8 +991,8 @@ pointer and a void pointer argument.
991991
.. index:: single: Py_AddPendingCall()
992992
993993
Schedule a function to be called from the main interpreter thread. On
994-
success, 0 is returned and *func* is queued for being called in the
995-
main thread. On failure, -1 is returned without setting any exception.
994+
success, ``0`` is returned and *func* is queued for being called in the
995+
main thread. On failure, ``-1`` is returned without setting any exception.
996996
997997
When successfully queued, *func* will be *eventually* called from the
998998
main interpreter thread with the argument *arg*. It will be called
@@ -1003,7 +1003,7 @@ pointer and a void pointer argument.
10031003
* with the main thread holding the :term:`global interpreter lock`
10041004
(*func* can therefore use the full C API).
10051005
1006-
*func* must return 0 on success, or -1 on failure with an exception
1006+
*func* must return ``0`` on success, or ``-1`` on failure with an exception
10071007
set. *func* won't be interrupted to perform another asynchronous
10081008
notification recursively, but it can still be interrupted to switch
10091009
threads if the global interpreter lock is released.

‎Doc/c-api/long.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -232,7 +232,7 @@ All integers are implemented as "long" integer objects of arbitrary size.
232232
method (if present) to convert it to a :c:type:`PyLongObject`.
233233
234234
If the value of *obj* is out of range for an :c:type:`unsigned long`,
235-
return the reduction of that value modulo :const:`ULONG_MAX + 1`.
235+
return the reduction of that value modulo ``ULONG_MAX + 1``.
236236
237237
238238
.. c:function:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *obj)
@@ -242,7 +242,7 @@ All integers are implemented as "long" integer objects of arbitrary size.
242242
method (if present) to convert it to a :c:type:`PyLongObject`.
243243
244244
If the value of *obj* is out of range for an :c:type:`unsigned long long`,
245-
return the reduction of that value modulo :const:`PY_ULLONG_MAX + 1`.
245+
return the reduction of that value modulo ``PY_ULLONG_MAX + 1``.
246246
247247
248248
.. c:function:: double PyLong_AsDouble(PyObject *pylong)

‎Doc/c-api/number.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -266,7 +266,7 @@ Number Protocol
266266
.. c:function:: Py_ssize_t PyNumber_AsSsize_t(PyObject *o, PyObject *exc)
267267
268268
Returns *o* converted to a Py_ssize_t value if *o* can be interpreted as an
269-
integer. If the call fails, an exception is raised and -1 is returned.
269+
integer. If the call fails, an exception is raised and ``-1`` is returned.
270270
271271
If *o* can be converted to a Python int but the attempt to
272272
convert to a Py_ssize_t value would raise an :exc:`OverflowError`, then the

‎Doc/c-api/set.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -114,7 +114,7 @@ or :class:`frozenset` or instances of their subtypes.
114114
115115
.. c:function:: int PySet_Contains(PyObject *anyset, PyObject *key)
116116
117-
Return 1 if found, 0 if not found, and -1 if an error is encountered. Unlike
117+
Return ``1`` if found, ``0`` if not found, and ``-1`` if an error is encountered. Unlike
118118
the Python :meth:`__contains__` method, this function does not automatically
119119
convert unhashable sets into temporary frozensets. Raise a :exc:`TypeError` if
120120
the *key* is unhashable. Raise :exc:`PyExc_SystemError` if *anyset* is not a
@@ -125,8 +125,8 @@ or :class:`frozenset` or instances of their subtypes.
125125
126126
Add *key* to a :class:`set` instance. Also works with :class:`frozenset`
127127
instances (like :c:func:`PyTuple_SetItem` it can be used to fill-in the values
128-
of brand new frozensets before they are exposed to other code). Return 0 on
129-
success or -1 on failure. Raise a :exc:`TypeError` if the *key* is
128+
of brand new frozensets before they are exposed to other code). Return ``0`` on
129+
success or ``-1`` on failure. Raise a :exc:`TypeError` if the *key* is
130130
unhashable. Raise a :exc:`MemoryError` if there is no room to grow. Raise a
131131
:exc:`SystemError` if *set* is not an instance of :class:`set` or its
132132
subtype.
@@ -138,7 +138,7 @@ subtypes but not for instances of :class:`frozenset` or its subtypes.
138138
139139
.. c:function:: int PySet_Discard(PyObject *set, PyObject *key)
140140
141-
Return 1 if found and removed, 0 if not found (no action taken), and -1 if an
141+
Return ``1`` if found and removed, ``0`` if not found (no action taken), and ``-1`` if an
142142
error is encountered. Does not raise :exc:`KeyError` for missing keys. Raise a
143143
:exc:`TypeError` if the *key* is unhashable. Unlike the Python :meth:`~set.discard`
144144
method, this function does not automatically convert unhashable sets into

‎Doc/c-api/slice.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -32,9 +32,9 @@ Slice Objects
3232
assuming a sequence of length *length*. Treats indices greater than
3333
*length* as errors.
3434
35-
Returns 0 on success and -1 on error with no exception set (unless one of
35+
Returns ``0`` on success and ``-1`` on error with no exception set (unless one of
3636
the indices was not :const:`None` and failed to be converted to an integer,
37-
in which case -1 is returned with an exception set).
37+
in which case ``-1`` is returned with an exception set).
3838
3939
You probably do not want to use this function.
4040
@@ -51,7 +51,7 @@ Slice Objects
5151
of bounds indices are clipped in a manner consistent with the handling of
5252
normal slices.
5353
54-
Returns 0 on success and -1 on error with exception set.
54+
Returns ``0`` on success and ``-1`` on error with exception set.
5555
5656
.. versionchanged:: 3.2
5757
The parameter type for the *slice* parameter was ``PySliceObject*``

‎Doc/c-api/structures.rst‎

Lines changed: 1 addition & 1 deletion

0 commit comments

Comments
 (0)