[Python-checkins] cpython (3.5): Issue #28496: Mark up constants 0, 1 and -1 that denote return values or
serhiy.storchaka
python-checkins at python.org
Thu Oct 27 14:43:17 EDT 2016
https://hg.python.org/cpython/rev/04065efd7747
changeset: 104749:04065efd7747
branch: 3.5
parent: 104743:bea48e72cae5
user: Serhiy Storchaka <storchaka at gmail.com>
date: Thu Oct 27 21:41:19 2016 +0300
summary:
Issue #28496: Mark up constants 0, 1 and -1 that denote return values or
special input values as literal text.
files:
Doc/c-api/arg.rst | 2 +-
Doc/c-api/buffer.rst | 12 +++---
Doc/c-api/capsule.rst | 10 ++--
Doc/c-api/import.rst | 4 +-
Doc/c-api/init.rst | 24 +++++++-------
Doc/c-api/long.rst | 4 +-
Doc/c-api/number.rst | 2 +-
Doc/c-api/set.rst | 8 ++--
Doc/c-api/slice.rst | 6 +-
Doc/c-api/structures.rst | 2 +-
Doc/c-api/typeobj.rst | 6 +-
Doc/c-api/unicode.rst | 48 ++++++++++++++--------------
12 files changed, 64 insertions(+), 64 deletions(-)
diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst
--- a/Doc/c-api/arg.rst
+++ b/Doc/c-api/arg.rst
@@ -342,7 +342,7 @@
``p`` (:class:`bool`) [int]
Tests the value passed in for truth (a boolean **p**\ redicate) and converts
the result to its equivalent C true/false integer value.
- Sets the int to 1 if the expression was true and 0 if it was false.
+ Sets the int to ``1`` if the expression was true and ``0`` if it was false.
This accepts any valid Python value. See :ref:`truth` for more
information about how Python tests values for truth.
diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst
--- a/Doc/c-api/buffer.rst
+++ b/Doc/c-api/buffer.rst
@@ -156,7 +156,7 @@
.. c:member:: int ndim
The number of dimensions the memory represents as an n-dimensional array.
- If it is 0, :c:member:`~Py_buffer.buf` points to a single item representing
+ If it is ``0``, :c:member:`~Py_buffer.buf` points to a single item representing
a scalar. In this case, :c:member:`~Py_buffer.shape`, :c:member:`~Py_buffer.strides`
and :c:member:`~Py_buffer.suboffsets` MUST be *NULL*.
@@ -427,7 +427,7 @@
.. c:function:: int PyObject_CheckBuffer(PyObject *obj)
- Return 1 if *obj* supports the buffer interface otherwise 0. When 1 is
+ Return ``1`` if *obj* supports the buffer interface otherwise ``0``. When ``1`` is
returned, it doesn't guarantee that :c:func:`PyObject_GetBuffer` will
succeed.
@@ -437,7 +437,7 @@
Send a request to *exporter* to fill in *view* as specified by *flags*.
If the exporter cannot provide a buffer of the exact type, it MUST raise
:c:data:`PyExc_BufferError`, set :c:member:`view->obj` to *NULL* and
- return -1.
+ return ``-1``.
On success, fill in *view*, set :c:member:`view->obj` to a new reference
to *exporter* and return 0. In the case of chained buffer providers
@@ -468,9 +468,9 @@
.. c:function:: int PyBuffer_IsContiguous(Py_buffer *view, char order)
- Return 1 if the memory defined by the *view* is C-style (*order* is
+ Return ``1`` if the memory defined by the *view* is C-style (*order* is
``'C'``) or Fortran-style (*order* is ``'F'``) :term:`contiguous` or either one
- (*order* is ``'A'``). Return 0 otherwise.
+ (*order* is ``'A'``). Return ``0`` otherwise.
.. 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 @@
On success, set :c:member:`view->obj` to a new reference to *exporter* and
return 0. Otherwise, raise :c:data:`PyExc_BufferError`, set
- :c:member:`view->obj` to *NULL* and return -1;
+ :c:member:`view->obj` to *NULL* and return ``-1``;
If this function is used as part of a :ref:`getbufferproc <buffer-structs>`,
*exporter* MUST be set to the exporting object and *flags* must be passed
diff --git a/Doc/c-api/capsule.rst b/Doc/c-api/capsule.rst
--- a/Doc/c-api/capsule.rst
+++ b/Doc/c-api/capsule.rst
@@ -120,19 +120,19 @@
guaranteed to succeed.
Return a nonzero value if the object is valid and matches the name passed in.
- Return 0 otherwise. This function will not fail.
+ Return ``0`` otherwise. This function will not fail.
.. c:function:: int PyCapsule_SetContext(PyObject *capsule, void *context)
Set the context pointer inside *capsule* to *context*.
- Return 0 on success. Return nonzero and set an exception on failure.
+ Return ``0`` on success. Return nonzero and set an exception on failure.
.. c:function:: int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)
Set the destructor inside *capsule* to *destructor*.
- Return 0 on success. Return nonzero and set an exception on failure.
+ Return ``0`` on success. Return nonzero and set an exception on failure.
.. c:function:: int PyCapsule_SetName(PyObject *capsule, const char *name)
@@ -140,11 +140,11 @@
outlive the capsule. If the previous *name* stored in the capsule was not
*NULL*, no attempt is made to free it.
- Return 0 on success. Return nonzero and set an exception on failure.
+ Return ``0`` on success. Return nonzero and set an exception on failure.
.. c:function:: int PyCapsule_SetPointer(PyObject *capsule, void *pointer)
Set the void pointer inside *capsule* to *pointer*. The pointer may not be
*NULL*.
- Return 0 on success. Return nonzero and set an exception on failure.
+ Return ``0`` on success. Return nonzero and set an exception on failure.
diff --git a/Doc/c-api/import.rst b/Doc/c-api/import.rst
--- a/Doc/c-api/import.rst
+++ b/Doc/c-api/import.rst
@@ -185,10 +185,10 @@
Return the magic number for Python bytecode files (a.k.a. :file:`.pyc` file).
The magic number should be present in the first four bytes of the bytecode
- file, in little-endian byte order. Returns -1 on error.
+ file, in little-endian byte order. Returns ``-1`` on error.
.. versionchanged:: 3.3
- Return value of -1 upon failure.
+ Return value of ``-1`` upon failure.
.. c:function:: const char * PyImport_GetMagicTag()
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -44,8 +44,8 @@
.. c:function:: void Py_InitializeEx(int initsigs)
- This function works like :c:func:`Py_Initialize` if *initsigs* is 1. If
- *initsigs* is 0, it skips initialization registration of signal handlers, which
+ This function works like :c:func:`Py_Initialize` if *initsigs* is ``1``. If
+ *initsigs* is ``0``, it skips initialization registration of signal handlers, which
might be useful when Python is embedded.
@@ -114,7 +114,7 @@
If :c:func:`Py_Finalize` is called, this function will need to be called
again in order to affect subsequent calls to :c:func:`Py_Initialize`.
- Returns 0 if successful, a nonzero value on error (e.g. calling after the
+ Returns ``0`` if successful, a nonzero value on error (e.g. calling after the
interpreter has already been initialized).
.. versionadded:: 3.4
@@ -349,7 +349,7 @@
- If the name of an existing script is passed in ``argv[0]``, the absolute
path of the directory where the script is located is prepended to
:data:`sys.path`.
- - Otherwise (that is, if *argc* is 0 or ``argv[0]`` doesn't point
+ - Otherwise (that is, if *argc* is ``0`` or ``argv[0]`` doesn't point
to an existing file name), an empty string is prepended to
:data:`sys.path`, which is the same as prepending the current working
directory (``"."``).
@@ -359,7 +359,7 @@
.. note::
It is recommended that applications embedding the Python interpreter
- for purposes other than executing a single script pass 0 as *updatepath*,
+ for purposes other than executing a single script pass ``0`` as *updatepath*,
and update :data:`sys.path` themselves if desired.
See `CVE-2008-5983 <https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2008-5983>`_.
@@ -371,14 +371,14 @@
.. versionadded:: 3.1.3
- .. XXX impl. doesn't seem consistent in allowing 0/NULL for the params;
+ .. XXX impl. doesn't seem consistent in allowing ``0``/``NULL`` for the params;
check w/ Guido.
.. c:function:: void PySys_SetArgv(int argc, wchar_t **argv)
This function works like :c:func:`PySys_SetArgvEx` with *updatepath* set
- to 1 unless the :program:`python` interpreter was started with the
+ to ``1`` unless the :program:`python` interpreter was started with the
:option:`-I`.
Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
@@ -718,10 +718,10 @@
.. c:function:: int PyGILState_Check()
- Return 1 if the current thread is holding the GIL and 0 otherwise.
+ Return ``1`` if the current thread is holding the GIL and ``0`` otherwise.
This function can be called from any thread at any time.
Only if it has had its Python thread state initialized and currently is
- holding the GIL will it return 1.
+ holding the GIL will it return ``1``.
This is mainly a helper/diagnostic function. It can be useful
for example in callback contexts or memory allocation functions when
knowing that the GIL is locked can allow the caller to perform sensitive
@@ -991,8 +991,8 @@
.. index:: single: Py_AddPendingCall()
Schedule a function to be called from the main interpreter thread. On
- success, 0 is returned and *func* is queued for being called in the
- main thread. On failure, -1 is returned without setting any exception.
+ success, ``0`` is returned and *func* is queued for being called in the
+ main thread. On failure, ``-1`` is returned without setting any exception.
When successfully queued, *func* will be *eventually* called from the
main interpreter thread with the argument *arg*. It will be called
@@ -1003,7 +1003,7 @@
* with the main thread holding the :term:`global interpreter lock`
(*func* can therefore use the full C API).
- *func* must return 0 on success, or -1 on failure with an exception
+ *func* must return ``0`` on success, or ``-1`` on failure with an exception
set. *func* won't be interrupted to perform another asynchronous
notification recursively, but it can still be interrupted to switch
threads if the global interpreter lock is released.
diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst
--- a/Doc/c-api/long.rst
+++ b/Doc/c-api/long.rst
@@ -232,7 +232,7 @@
method (if present) to convert it to a :c:type:`PyLongObject`.
If the value of *obj* is out of range for an :c:type:`unsigned long`,
- return the reduction of that value modulo :const:`ULONG_MAX + 1`.
+ return the reduction of that value modulo ``ULONG_MAX + 1``.
.. c:function:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *obj)
@@ -242,7 +242,7 @@
method (if present) to convert it to a :c:type:`PyLongObject`.
If the value of *obj* is out of range for an :c:type:`unsigned long long`,
- return the reduction of that value modulo :const:`PY_ULLONG_MAX + 1`.
+ return the reduction of that value modulo ``PY_ULLONG_MAX + 1``.
.. c:function:: double PyLong_AsDouble(PyObject *pylong)
diff --git a/Doc/c-api/number.rst b/Doc/c-api/number.rst
--- a/Doc/c-api/number.rst
+++ b/Doc/c-api/number.rst
@@ -266,7 +266,7 @@
.. c:function:: Py_ssize_t PyNumber_AsSsize_t(PyObject *o, PyObject *exc)
Returns *o* converted to a Py_ssize_t value if *o* can be interpreted as an
- integer. If the call fails, an exception is raised and -1 is returned.
+ integer. If the call fails, an exception is raised and ``-1`` is returned.
If *o* can be converted to a Python int but the attempt to
convert to a Py_ssize_t value would raise an :exc:`OverflowError`, then the
diff --git a/Doc/c-api/set.rst b/Doc/c-api/set.rst
--- a/Doc/c-api/set.rst
+++ b/Doc/c-api/set.rst
@@ -114,7 +114,7 @@
.. c:function:: int PySet_Contains(PyObject *anyset, PyObject *key)
- Return 1 if found, 0 if not found, and -1 if an error is encountered. Unlike
+ Return ``1`` if found, ``0`` if not found, and ``-1`` if an error is encountered. Unlike
the Python :meth:`__contains__` method, this function does not automatically
convert unhashable sets into temporary frozensets. Raise a :exc:`TypeError` if
the *key* is unhashable. Raise :exc:`PyExc_SystemError` if *anyset* is not a
@@ -125,8 +125,8 @@
Add *key* to a :class:`set` instance. Also works with :class:`frozenset`
instances (like :c:func:`PyTuple_SetItem` it can be used to fill-in the values
- of brand new frozensets before they are exposed to other code). Return 0 on
- success or -1 on failure. Raise a :exc:`TypeError` if the *key* is
+ of brand new frozensets before they are exposed to other code). Return ``0`` on
+ success or ``-1`` on failure. Raise a :exc:`TypeError` if the *key* is
unhashable. Raise a :exc:`MemoryError` if there is no room to grow. Raise a
:exc:`SystemError` if *set* is not an instance of :class:`set` or its
subtype.
@@ -138,7 +138,7 @@
.. c:function:: int PySet_Discard(PyObject *set, PyObject *key)
- Return 1 if found and removed, 0 if not found (no action taken), and -1 if an
+ Return ``1`` if found and removed, ``0`` if not found (no action taken), and ``-1`` if an
error is encountered. Does not raise :exc:`KeyError` for missing keys. Raise a
:exc:`TypeError` if the *key* is unhashable. Unlike the Python :meth:`~set.discard`
method, this function does not automatically convert unhashable sets into
diff --git a/Doc/c-api/slice.rst b/Doc/c-api/slice.rst
--- a/Doc/c-api/slice.rst
+++ b/Doc/c-api/slice.rst
@@ -32,9 +32,9 @@
assuming a sequence of length *length*. Treats indices greater than
*length* as errors.
- Returns 0 on success and -1 on error with no exception set (unless one of
+ Returns ``0`` on success and ``-1`` on error with no exception set (unless one of
the indices was not :const:`None` and failed to be converted to an integer,
- in which case -1 is returned with an exception set).
+ in which case ``-1`` is returned with an exception set).
You probably do not want to use this function.
@@ -51,7 +51,7 @@
of bounds indices are clipped in a manner consistent with the handling of
normal slices.
- Returns 0 on success and -1 on error with exception set.
+ Returns ``0`` on success and ``-1`` on error with exception set.
.. versionchanged:: 3.2
The parameter type for the *slice* parameter was ``PySliceObject*``
diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst
--- a/Doc/c-api/structures.rst
+++ b/Doc/c-api/structures.rst
@@ -290,7 +290,7 @@
handles use of the :keyword:`del` statement on that attribute more correctly
than :c:macro:`T_OBJECT`.
- :attr:`flags` can be 0 for write and read access or :c:macro:`READONLY` for
+ :attr:`flags` can be ``0`` for write and read access or :c:macro:`READONLY` for
read-only access. Using :c:macro:`T_STRING` for :attr:`type` implies
:c:macro:`READONLY`. Only :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX`
members can be deleted. (They are set to *NULL*).
diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -1278,7 +1278,7 @@
steps:
(1) Check if the request can be met. If not, raise :c:data:`PyExc_BufferError`,
- set :c:data:`view->obj` to *NULL* and return -1.
+ set :c:data:`view->obj` to *NULL* and return ``-1``.
(2) Fill in the requested fields.
@@ -1286,7 +1286,7 @@
(4) Set :c:data:`view->obj` to *exporter* and increment :c:data:`view->obj`.
- (5) Return 0.
+ (5) Return ``0``.
If *exporter* is part of a chain or tree of buffer providers, two main
schemes can be used:
@@ -1329,7 +1329,7 @@
(1) Decrement an internal counter for the number of exports.
- (2) If the counter is 0, free all memory associated with *view*.
+ (2) If the counter is ``0``, free all memory associated with *view*.
The exporter MUST use the :c:member:`~Py_buffer.internal` field to keep
track of buffer-specific resources. This field is guaranteed to remain
diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -102,7 +102,7 @@
.. XXX expand on when it is not required
- Returns 0 on success and -1 with an exception set on failure, which in
+ Returns ``0`` on success and ``-1`` with an exception set on failure, which in
particular happens if memory allocation fails.
.. versionadded:: 3.3
@@ -255,57 +255,57 @@
.. c:function:: int Py_UNICODE_ISSPACE(Py_UNICODE ch)
- Return 1 or 0 depending on whether *ch* is a whitespace character.
+ Return ``1`` or ``0`` depending on whether *ch* is a whitespace character.
.. c:function:: int Py_UNICODE_ISLOWER(Py_UNICODE ch)
- Return 1 or 0 depending on whether *ch* is a lowercase character.
+ Return ``1`` or ``0`` depending on whether *ch* is a lowercase character.
.. c:function:: int Py_UNICODE_ISUPPER(Py_UNICODE ch)
- Return 1 or 0 depending on whether *ch* is an uppercase character.
+ Return ``1`` or ``0`` depending on whether *ch* is an uppercase character.
.. c:function:: int Py_UNICODE_ISTITLE(Py_UNICODE ch)
- Return 1 or 0 depending on whether *ch* is a titlecase character.
+ Return ``1`` or ``0`` depending on whether *ch* is a titlecase character.
.. c:function:: int Py_UNICODE_ISLINEBREAK(Py_UNICODE ch)
- Return 1 or 0 depending on whether *ch* is a linebreak character.
+ Return ``1`` or ``0`` depending on whether *ch* is a linebreak character.
.. c:function:: int Py_UNICODE_ISDECIMAL(Py_UNICODE ch)
- Return 1 or 0 depending on whether *ch* is a decimal character.
+ Return ``1`` or ``0`` depending on whether *ch* is a decimal character.
.. c:function:: int Py_UNICODE_ISDIGIT(Py_UNICODE ch)
- Return 1 or 0 depending on whether *ch* is a digit character.
+ Return ``1`` or ``0`` depending on whether *ch* is a digit character.
.. c:function:: int Py_UNICODE_ISNUMERIC(Py_UNICODE ch)
- Return 1 or 0 depending on whether *ch* is a numeric character.
+ Return ``1`` or ``0`` depending on whether *ch* is a numeric character.
.. c:function:: int Py_UNICODE_ISALPHA(Py_UNICODE ch)
- Return 1 or 0 depending on whether *ch* is an alphabetic character.
+ Return ``1`` or ``0`` depending on whether *ch* is an alphabetic character.
.. c:function:: int Py_UNICODE_ISALNUM(Py_UNICODE ch)
- Return 1 or 0 depending on whether *ch* is an alphanumeric character.
+ Return ``1`` or ``0`` depending on whether *ch* is an alphanumeric character.
.. c:function:: int Py_UNICODE_ISPRINTABLE(Py_UNICODE ch)
- Return 1 or 0 depending on whether *ch* is a printable character.
+ Return ``1`` or ``0`` depending on whether *ch* is a printable character.
Nonprintable characters are those characters defined in the Unicode character
database as "Other" or "Separator", excepting the ASCII space (0x20) which is
considered printable. (Note that printable characters in this context are
@@ -903,7 +903,7 @@
.. c:function:: PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size)
Create a Unicode object from the :c:type:`wchar_t` buffer *w* of the given *size*.
- Passing -1 as the *size* indicates that the function must itself compute the length,
+ Passing ``-1`` as the *size* indicates that the function must itself compute the length,
using wcslen.
Return *NULL* on failure.
@@ -913,7 +913,7 @@
Copy the Unicode object contents into the :c:type:`wchar_t` buffer *w*. At most
*size* :c:type:`wchar_t` characters are copied (excluding a possibly trailing
null termination character). Return the number of :c:type:`wchar_t` characters
- copied or -1 in case of an error. Note that the resulting :c:type:`wchar_t*`
+ copied or ``-1`` in case of an error. Note that the resulting :c:type:`wchar_t*`
string may or may not be null-terminated. It is the responsibility of the caller
to make sure that the :c:type:`wchar_t*` string is null-terminated in case this is
required by the application. Also, note that the :c:type:`wchar_t*` string
@@ -1561,7 +1561,7 @@
.. c:function:: PyObject* PyUnicode_Splitlines(PyObject *s, int keepend)
Split a Unicode string at line breaks, returning a list of Unicode strings.
- CRLF is considered to be one line break. If *keepend* is 0, the Line break
+ CRLF is considered to be one line break. If *keepend* is ``0``, the Line break
characters are not included in the resulting strings.
@@ -1591,16 +1591,16 @@
.. c:function:: Py_ssize_t PyUnicode_Tailmatch(PyObject *str, PyObject *substr, \
Py_ssize_t start, Py_ssize_t end, int direction)
- Return 1 if *substr* matches ``str[start:end]`` at the given tail end
- (*direction* == -1 means to do a prefix match, *direction* == 1 a suffix match),
- 0 otherwise. Return ``-1`` if an error occurred.
+ Return ``1`` if *substr* matches ``str[start:end]`` at the given tail end
+ (*direction* == ``-1`` means to do a prefix match, *direction* == ``1`` a suffix match),
+ ``0`` otherwise. Return ``-1`` if an error occurred.
.. c:function:: Py_ssize_t PyUnicode_Find(PyObject *str, PyObject *substr, \
Py_ssize_t start, Py_ssize_t end, int direction)
Return the first position of *substr* in ``str[start:end]`` using the given
- *direction* (*direction* == 1 means to do a forward search, *direction* == -1 a
+ *direction* (*direction* == ``1`` means to do a forward search, *direction* == ``-1`` a
backward search). The return value is the index of the first match; a value of
``-1`` indicates that no match was found, and ``-2`` indicates that an error
occurred and an exception has been set.
@@ -1610,8 +1610,8 @@
Py_ssize_t start, Py_ssize_t end, int direction)
Return the first position of the character *ch* in ``str[start:end]`` using
- the given *direction* (*direction* == 1 means to do a forward search,
- *direction* == -1 a backward search). The return value is the index of the
+ the given *direction* (*direction* == ``1`` means to do a forward search,
+ *direction* == ``-1`` a backward search). The return value is the index of the
first match; a value of ``-1`` indicates that no match was found, and ``-2``
indicates that an error occurred and an exception has been set.
@@ -1629,19 +1629,19 @@
PyObject *replstr, Py_ssize_t maxcount)
Replace at most *maxcount* occurrences of *substr* in *str* with *replstr* and
- return the resulting Unicode object. *maxcount* == -1 means replace all
+ return the resulting Unicode object. *maxcount* == ``-1`` means replace all
occurrences.
.. c:function:: int PyUnicode_Compare(PyObject *left, PyObject *right)
- Compare two strings and return -1, 0, 1 for less than, equal, and greater than,
+ Compare two strings and return ``-1``, ``0``, ``1`` for less than, equal, and greater than,
respectively.
.. c:function:: int PyUnicode_CompareWithASCIIString(PyObject *uni, const char *string)
- Compare a unicode object, *uni*, with *string* and return -1, 0, 1 for less
+ Compare a unicode object, *uni*, with *string* and return ``-1``, ``0``, ``1`` for less
than, equal, and greater than, respectively. It is best to pass only
ASCII-encoded strings, but the function interprets the input string as
ISO-8859-1 if it contains non-ASCII characters.
--
Repository URL: https://hg.python.org/cpython
More information about the Python-checkins
mailing list