Skip to content

Commit

Permalink
[3.8] bpo-38600: Change the mark up of NULL in the C API documentatio…
Browse files Browse the repository at this point in the history 
…n. (GH-16950) (GH-16999)

Replace all *NULL* with ``NULL``.
(cherry picked from commit 25fc088)
  • Loading branch information
@serhiy-storchaka
serhiy-storchaka committed Oct 30, 2019
1 parent dcb338e commit f2ba17b
Show file tree
Hide file tree
Showing 55 changed files with 723 additions and 723 deletions.
48 changes: 24 additions & 24 deletions Doc/c-api/arg.rst
View file
Expand Up @@ -50,7 +50,7 @@ Unless otherwise stated, buffers are not NUL-terminated.

Some formats require a read-only :term:`bytes-like object`, and set a
pointer instead of a buffer structure. They work by checking that
the object's :c:member:`PyBufferProcs.bf_releasebuffer` field is *NULL*,
the object's :c:member:`PyBufferProcs.bf_releasebuffer` field is ``NULL``,
which disallows mutable objects such as :class:`bytearray`.

.. note::
Expand Down Expand Up @@ -99,15 +99,15 @@ which disallows mutable objects such as :class:`bytearray`.

``z`` (:class:`str` or ``None``) [const char \*]
Like ``s``, but the Python object may also be ``None``, in which case the C
pointer is set to *NULL*.
pointer is set to ``NULL``.

``z*`` (:class:`str`, :term:`bytes-like object` or ``None``) [Py_buffer]
Like ``s*``, but the Python object may also be ``None``, in which case the
``buf`` member of the :c:type:`Py_buffer` structure is set to *NULL*.
``buf`` member of the :c:type:`Py_buffer` structure is set to ``NULL``.

``z#`` (:class:`str`, read-only :term:`bytes-like object` or ``None``) [const char \*, int]
Like ``s#``, but the Python object may also be ``None``, in which case the C
pointer is set to *NULL*.
pointer is set to ``NULL``.

``y`` (read-only :term:`bytes-like object`) [const char \*]
This format converts a bytes-like object to a C pointer to a character
Expand Down Expand Up @@ -166,15 +166,15 @@ which disallows mutable objects such as :class:`bytearray`.

``Z`` (:class:`str` or ``None``) [const Py_UNICODE \*]
Like ``u``, but the Python object may also be ``None``, in which case the
:c:type:`Py_UNICODE` pointer is set to *NULL*.
:c:type:`Py_UNICODE` pointer is set to ``NULL``.

.. deprecated-removed:: 3.3 4.0
Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
:c:func:`PyUnicode_AsWideCharString`.

``Z#`` (:class:`str` or ``None``) [const Py_UNICODE \*, int]
Like ``u#``, but the Python object may also be ``None``, in which case the
:c:type:`Py_UNICODE` pointer is set to *NULL*.
:c:type:`Py_UNICODE` pointer is set to ``NULL``.

.. deprecated-removed:: 3.3 4.0
Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
Expand All @@ -197,7 +197,7 @@ which disallows mutable objects such as :class:`bytearray`.

This format requires two arguments. The first is only used as input, and
must be a :c:type:`const char\*` which points to the name of an encoding as a
NUL-terminated string, or *NULL*, in which case ``'utf-8'`` encoding is used.
NUL-terminated string, or ``NULL``, in which case ``'utf-8'`` encoding is used.
An exception is raised if the named encoding is not known to Python. The
second argument must be a :c:type:`char\*\*`; the value of the pointer it
references will be set to a buffer with the contents of the argument text.
Expand All @@ -220,7 +220,7 @@ which disallows mutable objects such as :class:`bytearray`.

It requires three arguments. The first is only used as input, and must be a
:c:type:`const char\*` which points to the name of an encoding as a
NUL-terminated string, or *NULL*, in which case ``'utf-8'`` encoding is used.
NUL-terminated string, or ``NULL``, in which case ``'utf-8'`` encoding is used.
An exception is raised if the named encoding is not known to Python. The
second argument must be a :c:type:`char\*\*`; the value of the pointer it
references will be set to a buffer with the contents of the argument text.
Expand All @@ -230,12 +230,12 @@ which disallows mutable objects such as :class:`bytearray`.

There are two modes of operation:

If *\*buffer* points a *NULL* pointer, the function will allocate a buffer of
If *\*buffer* points a ``NULL`` pointer, the function will allocate a buffer of
the needed size, copy the encoded data into this buffer and set *\*buffer* to
reference the newly allocated storage. The caller is responsible for calling
:c:func:`PyMem_Free` to free the allocated buffer after usage.

If *\*buffer* points to a non-*NULL* pointer (an already allocated buffer),
If *\*buffer* points to a non-``NULL`` pointer (an already allocated buffer),
:c:func:`PyArg_ParseTuple` will use this location as the buffer and interpret the
initial value of *\*buffer_length* as the buffer size. It will then copy the
encoded data into the buffer and NUL-terminate it. If the buffer is not large
Expand Down Expand Up @@ -317,7 +317,7 @@ Other objects
``O`` (object) [PyObject \*]
Store a Python object (without any conversion) in a C object pointer. The C
program thus receives the actual object that was passed. The object's reference
count is not increased. The pointer stored is not *NULL*.
count is not increased. The pointer stored is not ``NULL``.

``O!`` (object) [*typeobject*, PyObject \*]
Store a Python object in a C object pointer. This is similar to ``O``, but
Expand Down Expand Up @@ -437,7 +437,7 @@ API Functions
Parse the parameters of a function that takes both positional and keyword
parameters into local variables. The *keywords* argument is a
*NULL*-terminated array of keyword parameter names. Empty names denote
``NULL``-terminated array of keyword parameter names. Empty names denote
:ref:`positional-only parameters <positional-only_parameter>`.
Returns true on success; on failure, it returns false and raises the
appropriate exception.
Expand Down Expand Up @@ -520,8 +520,8 @@ Building values
Create a new value based on a format string similar to those accepted by the
:c:func:`PyArg_Parse\*` family of functions and a sequence of values. Returns
the value or *NULL* in the case of an error; an exception will be raised if
*NULL* is returned.
the value or ``NULL`` in the case of an error; an exception will be raised if
``NULL`` is returned.
:c:func:`Py_BuildValue` does not always build a tuple. It builds a tuple only if
its format string contains two or more format units. If the format string is
Expand All @@ -547,20 +547,20 @@ Building values
``s`` (:class:`str` or ``None``) [const char \*]
Convert a null-terminated C string to a Python :class:`str` object using ``'utf-8'``
encoding. If the C string pointer is *NULL*, ``None`` is used.
encoding. If the C string pointer is ``NULL``, ``None`` is used.
``s#`` (:class:`str` or ``None``) [const char \*, int]
Convert a C string and its length to a Python :class:`str` object using ``'utf-8'``
encoding. If the C string pointer is *NULL*, the length is ignored and
encoding. If the C string pointer is ``NULL``, the length is ignored and
``None`` is returned.
``y`` (:class:`bytes`) [const char \*]
This converts a C string to a Python :class:`bytes` object. If the C
string pointer is *NULL*, ``None`` is returned.
string pointer is ``NULL``, ``None`` is returned.
``y#`` (:class:`bytes`) [const char \*, int]
This converts a C string and its lengths to a Python object. If the C
string pointer is *NULL*, ``None`` is returned.
string pointer is ``NULL``, ``None`` is returned.
``z`` (:class:`str` or ``None``) [const char \*]
Same as ``s``.
Expand All @@ -570,12 +570,12 @@ Building values
``u`` (:class:`str`) [const wchar_t \*]
Convert a null-terminated :c:type:`wchar_t` buffer of Unicode (UTF-16 or UCS-4)
data to a Python Unicode object. If the Unicode buffer pointer is *NULL*,
data to a Python Unicode object. If the Unicode buffer pointer is ``NULL``,
``None`` is returned.
``u#`` (:class:`str`) [const wchar_t \*, int]
Convert a Unicode (UTF-16 or UCS-4) data buffer and its length to a Python
Unicode object. If the Unicode buffer pointer is *NULL*, the length is ignored
Unicode object. If the Unicode buffer pointer is ``NULL``, the length is ignored
and ``None`` is returned.
``U`` (:class:`str` or ``None``) [const char \*]
Expand Down Expand Up @@ -636,9 +636,9 @@ Building values
``O`` (object) [PyObject \*]
Pass a Python object untouched (except for its reference count, which is
incremented by one). If the object passed in is a *NULL* pointer, it is assumed
incremented by one). If the object passed in is a ``NULL`` pointer, it is assumed
that this was caused because the call producing the argument found an error and
set an exception. Therefore, :c:func:`Py_BuildValue` will return *NULL* but won't
set an exception. Therefore, :c:func:`Py_BuildValue` will return ``NULL`` but won't
raise an exception. If no exception has been raised yet, :exc:`SystemError` is
set.
Expand All @@ -653,7 +653,7 @@ Building values
``O&`` (object) [*converter*, *anything*]
Convert *anything* to a Python object through a *converter* function. The
function is called with *anything* (which should be compatible with :c:type:`void
\*`) as its argument and should return a "new" Python object, or *NULL* if an
\*`) as its argument and should return a "new" Python object, or ``NULL`` if an
error occurred.
``(items)`` (:class:`tuple`) [*matching-items*]
Expand All @@ -668,7 +668,7 @@ Building values
respectively.
If there is an error in the format string, the :exc:`SystemError` exception is
set and *NULL* returned.
set and ``NULL`` returned.
.. c:function:: PyObject* Py_VaBuildValue(const char *format, va_list vargs)
Expand Down
22 changes: 11 additions & 11 deletions Doc/c-api/buffer.rst
View file
Expand Up @@ -102,13 +102,13 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
.. c:member:: void \*obj
A new reference to the exporting object. The reference is owned by
the consumer and automatically decremented and set to *NULL* by
the consumer and automatically decremented and set to ``NULL`` by
:c:func:`PyBuffer_Release`. The field is the equivalent of the return
value of any standard C-API function.

As a special case, for *temporary* buffers that are wrapped by
:c:func:`PyMemoryView_FromBuffer` or :c:func:`PyBuffer_FillInfo`
this field is *NULL*. In general, exporting objects MUST NOT
this field is ``NULL``. In general, exporting objects MUST NOT
use this scheme.

.. c:member:: Py_ssize_t len
Expand All @@ -134,21 +134,21 @@ a buffer, see :c:func:`PyObject_GetBuffer`.

Important exception: If a consumer requests a buffer without the
:c:macro:`PyBUF_FORMAT` flag, :c:member:`~Py_buffer.format` will
be set to *NULL*, but :c:member:`~Py_buffer.itemsize` still has
be set to ``NULL``, but :c:member:`~Py_buffer.itemsize` still has
the value for the original format.

If :c:member:`~Py_buffer.shape` is present, the equality
``product(shape) * itemsize == len`` still holds and the consumer
can use :c:member:`~Py_buffer.itemsize` to navigate the buffer.

If :c:member:`~Py_buffer.shape` is *NULL* as a result of a :c:macro:`PyBUF_SIMPLE`
If :c:member:`~Py_buffer.shape` is ``NULL`` as a result of a :c:macro:`PyBUF_SIMPLE`
or a :c:macro:`PyBUF_WRITABLE` request, the consumer must disregard
:c:member:`~Py_buffer.itemsize` and assume ``itemsize == 1``.

.. c:member:: const char \*format
A *NUL* terminated string in :mod:`struct` module style syntax describing
the contents of a single item. If this is *NULL*, ``"B"`` (unsigned bytes)
the contents of a single item. If this is ``NULL``, ``"B"`` (unsigned bytes)
is assumed.

This field is controlled by the :c:macro:`PyBUF_FORMAT` flag.
Expand All @@ -158,7 +158,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
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
a scalar. In this case, :c:member:`~Py_buffer.shape`, :c:member:`~Py_buffer.strides`
and :c:member:`~Py_buffer.suboffsets` MUST be *NULL*.
and :c:member:`~Py_buffer.suboffsets` MUST be ``NULL``.

The macro :c:macro:`PyBUF_MAX_NDIM` limits the maximum number of dimensions
to 64. Exporters MUST respect this limit, consumers of multi-dimensional
Expand Down Expand Up @@ -248,7 +248,7 @@ readonly, format
.. c:macro:: PyBUF_FORMAT
Controls the :c:member:`~Py_buffer.format` field. If set, this field MUST
be filled in correctly. Otherwise, this field MUST be *NULL*.
be filled in correctly. Otherwise, this field MUST be ``NULL``.


:c:macro:`PyBUF_WRITABLE` can be \|'d to any of the flags in the next section.
Expand Down Expand Up @@ -349,9 +349,9 @@ The logical structure of NumPy-style arrays is defined by :c:member:`~Py_buffer.

If ``ndim == 0``, the memory location pointed to by :c:member:`~Py_buffer.buf` is
interpreted as a scalar of size :c:member:`~Py_buffer.itemsize`. In that case,
both :c:member:`~Py_buffer.shape` and :c:member:`~Py_buffer.strides` are *NULL*.
both :c:member:`~Py_buffer.shape` and :c:member:`~Py_buffer.strides` are ``NULL``.

If :c:member:`~Py_buffer.strides` is *NULL*, the array is interpreted as
If :c:member:`~Py_buffer.strides` is ``NULL``, the array is interpreted as
a standard n-dimensional C-array. Otherwise, the consumer must access an
n-dimensional array as follows:

Expand Down Expand Up @@ -438,7 +438,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
:c:data:`PyExc_BufferError`, set :c:member:`view->obj` to ``NULL`` and
return ``-1``.
On success, fill in *view*, set :c:member:`view->obj` to a new reference
Expand Down Expand Up @@ -516,7 +516,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
Expand Down
6 changes: 3 additions & 3 deletions Doc/c-api/bytearray.rst
View file
Expand Up @@ -48,7 +48,7 @@ Direct API functions
.. c:function:: PyObject* PyByteArray_FromStringAndSize(const char *string, Py_ssize_t len)
Create a new bytearray object from *string* and its length, *len*. On
failure, *NULL* is returned.
failure, ``NULL`` is returned.
.. c:function:: PyObject* PyByteArray_Concat(PyObject *a, PyObject *b)
Expand All @@ -58,13 +58,13 @@ Direct API functions
.. c:function:: Py_ssize_t PyByteArray_Size(PyObject *bytearray)
Return the size of *bytearray* after checking for a *NULL* pointer.
Return the size of *bytearray* after checking for a ``NULL`` pointer.
.. c:function:: char* PyByteArray_AsString(PyObject *bytearray)
Return the contents of *bytearray* as a char array after checking for a
*NULL* pointer. The returned array always has an extra
``NULL`` pointer. The returned array always has an extra
null byte appended.
Expand Down
12 changes: 6 additions & 6 deletions Doc/c-api/bytes.rst
View file
Expand Up @@ -37,14 +37,14 @@ called with a non-bytes parameter.
.. c:function:: PyObject* PyBytes_FromString(const char *v)
Return a new bytes object with a copy of the string *v* as value on success,
and *NULL* on failure. The parameter *v* must not be *NULL*; it will not be
and ``NULL`` on failure. The parameter *v* must not be ``NULL``; it will not be
checked.
.. c:function:: PyObject* PyBytes_FromStringAndSize(const char *v, Py_ssize_t len)
Return a new bytes object with a copy of the string *v* as value and length
*len* on success, and *NULL* on failure. If *v* is *NULL*, the contents of
*len* on success, and ``NULL`` on failure. If *v* is ``NULL``, the contents of
the bytes object are uninitialized.
Expand Down Expand Up @@ -145,7 +145,7 @@ called with a non-bytes parameter.
whether there are any other null bytes. The data must not be
modified in any way, unless the object was just created using
``PyBytes_FromStringAndSize(NULL, size)``. It must not be deallocated. If
*o* is not a bytes object at all, :c:func:`PyBytes_AsString` returns *NULL*
*o* is not a bytes object at all, :c:func:`PyBytes_AsString` returns ``NULL``
and raises :exc:`TypeError`.
Expand All @@ -159,7 +159,7 @@ called with a non-bytes parameter.
Return the null-terminated contents of the object *obj*
through the output variables *buffer* and *length*.
If *length* is *NULL*, the bytes object
If *length* is ``NULL``, the bytes object
may not contain embedded null bytes;
if it does, the function returns ``-1`` and a :exc:`ValueError` is raised.
Expand All @@ -181,7 +181,7 @@ called with a non-bytes parameter.
appended to *bytes*; the caller will own the new reference. The reference to
the old value of *bytes* will be stolen. If the new object cannot be
created, the old reference to *bytes* will still be discarded and the value
of *\*bytes* will be set to *NULL*; the appropriate exception will be set.
of *\*bytes* will be set to ``NULL``; the appropriate exception will be set.
.. c:function:: void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)
Expand All @@ -201,5 +201,5 @@ called with a non-bytes parameter.
desired. On success, *\*bytes* holds the resized bytes object and ``0`` is
returned; the address in *\*bytes* may differ from its input value. If the
reallocation fails, the original bytes object at *\*bytes* is deallocated,
*\*bytes* is set to *NULL*, :exc:`MemoryError` is set, and ``-1`` is
*\*bytes* is set to ``NULL``, :exc:`MemoryError` is set, and ``-1`` is
returned.

0 comments on commit f2ba17b

Please sign in to comment.