Skip to content

[3.7] bpo-38600: Change the mark up of NULL in the C API documentation. (GH-16950) #17000

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
serhiy-storchaka merged 1 commit into from
Oct 30, 2019
Merged

[3.7] bpo-38600: Change the mark up of NULL in the C API documentation. (GH-16950) #17000

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 24 additions & 24 deletions Doc/c-api/arg.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
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
Open in desktop
Original file line number Diff line number Diff line change
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
Open in desktop
Original file line number Diff line number Diff line change
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
Open in desktop
Original file line number Diff line number Diff line change
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.
Loading