cpython: 04065efd7747 (original) (raw)

Mercurial > cpython

changeset 104749:04065efd7747 3.5

Issue #28496: Mark up constants 0, 1 and -1 that denote return values or special input values as literal text. [#28496]

line wrap: on

line diff

--- a/Doc/c-api/arg.rst +++ b/Doc/c-api/arg.rst @@ -342,7 +342,7 @@ Other objects 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.

--- a/Doc/c-api/buffer.rst +++ b/Doc/c-api/buffer.rst @@ -156,7 +156,7 @@ a buffer, see :c:func:`PyObject_GetBuffe .. 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[](#l2.7)

•  If it is ``0``, :c:member:`~Py_buffer.buf` points to a single item representing[](#l2.8)
   a scalar. In this case, :c:member:`~Py_buffer.shape`, :c:member:`~Py_buffer.strides`[](#l2.9)
   and :c:member:`~Py_buffer.suboffsets` MUST be *NULL*.[](#l2.10)

@@ -427,7 +427,7 @@ Buffer-related functions .. 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 @@ Buffer-related functions 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 @@ Buffer-related functions

.. 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 @@ Buffer-related functions 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

--- a/Doc/c-api/capsule.rst +++ b/Doc/c-api/capsule.rst @@ -120,19 +120,19 @@ Refer to :ref:using-capsules for more 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 @@ Refer to :ref:using-capsules for more 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.

--- a/Doc/c-api/import.rst +++ b/Doc/c-api/import.rst @@ -185,10 +185,10 @@ Importing Modules 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.[](#l4.11)

•  Return value of ``-1`` upon failure.[](#l4.12)

.. c:function:: const char * PyImport_GetMagicTag()

--- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -44,8 +44,8 @@ Initializing and finalizing the interpre .. 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 @@ Process-wide parameters 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 @@ Process-wide parameters
  • 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 @@ Process-wide parameters .. note:: It is recommended that applications embedding the Python interpreter

•  for purposes other than executing a single script pass 0 as *updatepath*,[](#l5.36)

•  for purposes other than executing a single script pass ``0`` as *updatepath*,[](#l5.37)
   and update :data:`sys.path` themselves if desired.[](#l5.38)
   See `CVE-2008-5983 <https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2008-5983>`_.[](#l5.39)

@@ -371,14 +371,14 @@ Process-wide parameters .. 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 @@ with sub-interpreters:

.. 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 @@ pointer and a void pointer argument. .. 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 @@ pointer and a void pointer argument.
  • 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.

--- a/Doc/c-api/long.rst +++ b/Doc/c-api/long.rst @@ -232,7 +232,7 @@ All integers are implemented as "long" i 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 @@ All integers are implemented as "long" i 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)

--- a/Doc/c-api/number.rst +++ b/Doc/c-api/number.rst @@ -266,7 +266,7 @@ Number Protocol .. 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

--- a/Doc/c-api/set.rst +++ b/Doc/c-api/set.rst @@ -114,7 +114,7 @@ or :class:frozenset or instances of th .. 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 @@ or :class:frozenset or instances of th 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 @@ subtypes but not for instances of :class

.. 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

--- a/Doc/c-api/slice.rst +++ b/Doc/c-api/slice.rst @@ -32,9 +32,9 @@ Slice Objects 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 @@ Slice Objects 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*

--- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -290,7 +290,7 @@ definition with the same method name. 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).

--- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -1278,7 +1278,7 @@ Buffer Object Structures 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.[](#l11.7)

•   set :c:data:`view->obj` to *NULL* and return ``-1``.[](#l11.8)

(2) Fill in the requested fields. @@ -1286,7 +1286,7 @@ Buffer Object Structures (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 @@ Buffer Object Structures (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

--- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -102,7 +102,7 @@ access internal read-only data of Unicod .. 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 @@ the Python configuration.

.. 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 @@ wchar_t Support .. 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 @@ wchar_t Support 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 @@ They all return NULL or -1 if an e .. 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 @@ They all return NULL or -1 if an e .. c:function:: Py_ssize_t PyUnicode_Tailmatch(PyObject *str, PyObject *substr, [](#l12.109) 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, [](#l12.120) 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 @@ They all return NULL or -1 if an e 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 @@ They all return NULL or -1 if an e 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.