Skip to content

Commit 25fc088

Browse files
serhiy-storchakaserhiy-storchaka
authored
bpo-38600: Change the mark up of NULL in the C API documentation. (pythonGH-16950)
Replace all *NULL* with ``NULL``.
1 parent da6ce58 commit 25fc088

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

55 files changed

+728
-728
lines changed

‎Doc/c-api/arg.rst‎

Lines changed: 24 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ Unless otherwise stated, buffers are not NUL-terminated.
5050

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

5656
.. note::
@@ -99,15 +99,15 @@ which disallows mutable objects such as :class:`bytearray`.
9999

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

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

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

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

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

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

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

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

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

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

231231
There are two modes of operation:
232232

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

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

322322
``O!`` (object) [*typeobject*, PyObject \*]
323323
Store a Python object in a C object pointer. This is similar to ``O``, but
@@ -437,7 +437,7 @@ API Functions
437437
438438
Parse the parameters of a function that takes both positional and keyword
439439
parameters into local variables. The *keywords* argument is a
440-
*NULL*-terminated array of keyword parameter names. Empty names denote
440+
``NULL``-terminated array of keyword parameter names. Empty names denote
441441
:ref:`positional-only parameters <positional-only_parameter>`.
442442
Returns true on success; on failure, it returns false and raises the
443443
appropriate exception.
@@ -520,8 +520,8 @@ Building values
520520
521521
Create a new value based on a format string similar to those accepted by the
522522
:c:func:`PyArg_Parse\*` family of functions and a sequence of values. Returns
523-
the value or *NULL* in the case of an error; an exception will be raised if
524-
*NULL* is returned.
523+
the value or ``NULL`` in the case of an error; an exception will be raised if
524+
``NULL`` is returned.
525525
526526
:c:func:`Py_BuildValue` does not always build a tuple. It builds a tuple only if
527527
its format string contains two or more format units. If the format string is
@@ -547,20 +547,20 @@ Building values
547547
548548
``s`` (:class:`str` or ``None``) [const char \*]
549549
Convert a null-terminated C string to a Python :class:`str` object using ``'utf-8'``
550-
encoding. If the C string pointer is *NULL*, ``None`` is used.
550+
encoding. If the C string pointer is ``NULL``, ``None`` is used.
551551
552552
``s#`` (:class:`str` or ``None``) [const char \*, int]
553553
Convert a C string and its length to a Python :class:`str` object using ``'utf-8'``
554-
encoding. If the C string pointer is *NULL*, the length is ignored and
554+
encoding. If the C string pointer is ``NULL``, the length is ignored and
555555
``None`` is returned.
556556
557557
``y`` (:class:`bytes`) [const char \*]
558558
This converts a C string to a Python :class:`bytes` object. If the C
559-
string pointer is *NULL*, ``None`` is returned.
559+
string pointer is ``NULL``, ``None`` is returned.
560560
561561
``y#`` (:class:`bytes`) [const char \*, int]
562562
This converts a C string and its lengths to a Python object. If the C
563-
string pointer is *NULL*, ``None`` is returned.
563+
string pointer is ``NULL``, ``None`` is returned.
564564
565565
``z`` (:class:`str` or ``None``) [const char \*]
566566
Same as ``s``.
@@ -570,12 +570,12 @@ Building values
570570
571571
``u`` (:class:`str`) [const wchar_t \*]
572572
Convert a null-terminated :c:type:`wchar_t` buffer of Unicode (UTF-16 or UCS-4)
573-
data to a Python Unicode object. If the Unicode buffer pointer is *NULL*,
573+
data to a Python Unicode object. If the Unicode buffer pointer is ``NULL``,
574574
``None`` is returned.
575575
576576
``u#`` (:class:`str`) [const wchar_t \*, int]
577577
Convert a Unicode (UTF-16 or UCS-4) data buffer and its length to a Python
578-
Unicode object. If the Unicode buffer pointer is *NULL*, the length is ignored
578+
Unicode object. If the Unicode buffer pointer is ``NULL``, the length is ignored
579579
and ``None`` is returned.
580580
581581
``U`` (:class:`str` or ``None``) [const char \*]
@@ -636,9 +636,9 @@ Building values
636636
637637
``O`` (object) [PyObject \*]
638638
Pass a Python object untouched (except for its reference count, which is
639-
incremented by one). If the object passed in is a *NULL* pointer, it is assumed
639+
incremented by one). If the object passed in is a ``NULL`` pointer, it is assumed
640640
that this was caused because the call producing the argument found an error and
641-
set an exception. Therefore, :c:func:`Py_BuildValue` will return *NULL* but won't
641+
set an exception. Therefore, :c:func:`Py_BuildValue` will return ``NULL`` but won't
642642
raise an exception. If no exception has been raised yet, :exc:`SystemError` is
643643
set.
644644
@@ -653,7 +653,7 @@ Building values
653653
``O&`` (object) [*converter*, *anything*]
654654
Convert *anything* to a Python object through a *converter* function. The
655655
function is called with *anything* (which should be compatible with :c:type:`void
656-
\*`) as its argument and should return a "new" Python object, or *NULL* if an
656+
\*`) as its argument and should return a "new" Python object, or ``NULL`` if an
657657
error occurred.
658658
659659
``(items)`` (:class:`tuple`) [*matching-items*]
@@ -668,7 +668,7 @@ Building values
668668
respectively.
669669
670670
If there is an error in the format string, the :exc:`SystemError` exception is
671-
set and *NULL* returned.
671+
set and ``NULL`` returned.
672672
673673
.. c:function:: PyObject* Py_VaBuildValue(const char *format, va_list vargs)
674674

‎Doc/c-api/buffer.rst‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -102,13 +102,13 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
102102
.. c:member:: void \*obj
103103
104104
A new reference to the exporting object. The reference is owned by
105-
the consumer and automatically decremented and set to *NULL* by
105+
the consumer and automatically decremented and set to ``NULL`` by
106106
:c:func:`PyBuffer_Release`. The field is the equivalent of the return
107107
value of any standard C-API function.
108108

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

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

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

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

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

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

154154
This field is controlled by the :c:macro:`PyBUF_FORMAT` flag.
@@ -158,7 +158,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`.
158158
The number of dimensions the memory represents as an n-dimensional array.
159159
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`
161-
and :c:member:`~Py_buffer.suboffsets` MUST be *NULL*.
161+
and :c:member:`~Py_buffer.suboffsets` MUST be ``NULL``.
162162

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

253253

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

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

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

@@ -438,7 +438,7 @@ Buffer-related functions
438438
439439
Send a request to *exporter* to fill in *view* as specified by *flags*.
440440
If the exporter cannot provide a buffer of the exact type, it MUST raise
441-
:c:data:`PyExc_BufferError`, set :c:member:`view->obj` to *NULL* and
441+
:c:data:`PyExc_BufferError`, set :c:member:`view->obj` to ``NULL`` and
442442
return ``-1``.
443443
444444
On success, fill in *view*, set :c:member:`view->obj` to a new reference
@@ -518,7 +518,7 @@ Buffer-related functions
518518
519519
On success, set :c:member:`view->obj` to a new reference to *exporter* and
520520
return 0. Otherwise, raise :c:data:`PyExc_BufferError`, set
521-
:c:member:`view->obj` to *NULL* and return ``-1``;
521+
:c:member:`view->obj` to ``NULL`` and return ``-1``;
522522
523523
If this function is used as part of a :ref:`getbufferproc <buffer-structs>`,
524524
*exporter* MUST be set to the exporting object and *flags* must be passed

‎Doc/c-api/bytearray.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ Direct API functions
4848
.. c:function:: PyObject* PyByteArray_FromStringAndSize(const char *string, Py_ssize_t len)
4949
5050
Create a new bytearray object from *string* and its length, *len*. On
51-
failure, *NULL* is returned.
51+
failure, ``NULL`` is returned.
5252
5353
5454
.. c:function:: PyObject* PyByteArray_Concat(PyObject *a, PyObject *b)
@@ -58,13 +58,13 @@ Direct API functions
5858
5959
.. c:function:: Py_ssize_t PyByteArray_Size(PyObject *bytearray)
6060
61-
Return the size of *bytearray* after checking for a *NULL* pointer.
61+
Return the size of *bytearray* after checking for a ``NULL`` pointer.
6262
6363
6464
.. c:function:: char* PyByteArray_AsString(PyObject *bytearray)
6565
6666
Return the contents of *bytearray* as a char array after checking for a
67-
*NULL* pointer. The returned array always has an extra
67+
``NULL`` pointer. The returned array always has an extra
6868
null byte appended.
6969
7070

‎Doc/c-api/bytes.rst‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -37,14 +37,14 @@ called with a non-bytes parameter.
3737
.. c:function:: PyObject* PyBytes_FromString(const char *v)
3838
3939
Return a new bytes object with a copy of the string *v* as value on success,
40-
and *NULL* on failure. The parameter *v* must not be *NULL*; it will not be
40+
and ``NULL`` on failure. The parameter *v* must not be ``NULL``; it will not be
4141
checked.
4242
4343
4444
.. c:function:: PyObject* PyBytes_FromStringAndSize(const char *v, Py_ssize_t len)
4545
4646
Return a new bytes object with a copy of the string *v* as value and length
47-
*len* on success, and *NULL* on failure. If *v* is *NULL*, the contents of
47+
*len* on success, and ``NULL`` on failure. If *v* is ``NULL``, the contents of
4848
the bytes object are uninitialized.
4949
5050
@@ -145,7 +145,7 @@ called with a non-bytes parameter.
145145
whether there are any other null bytes. The data must not be
146146
modified in any way, unless the object was just created using
147147
``PyBytes_FromStringAndSize(NULL, size)``. It must not be deallocated. If
148-
*o* is not a bytes object at all, :c:func:`PyBytes_AsString` returns *NULL*
148+
*o* is not a bytes object at all, :c:func:`PyBytes_AsString` returns ``NULL``
149149
and raises :exc:`TypeError`.
150150
151151
@@ -159,7 +159,7 @@ called with a non-bytes parameter.
159159
Return the null-terminated contents of the object *obj*
160160
through the output variables *buffer* and *length*.
161161
162-
If *length* is *NULL*, the bytes object
162+
If *length* is ``NULL``, the bytes object
163163
may not contain embedded null bytes;
164164
if it does, the function returns ``-1`` and a :exc:`ValueError` is raised.
165165
@@ -181,7 +181,7 @@ called with a non-bytes parameter.
181181
appended to *bytes*; the caller will own the new reference. The reference to
182182
the old value of *bytes* will be stolen. If the new object cannot be
183183
created, the old reference to *bytes* will still be discarded and the value
184-
of *\*bytes* will be set to *NULL*; the appropriate exception will be set.
184+
of *\*bytes* will be set to ``NULL``; the appropriate exception will be set.
185185
186186
187187
.. c:function:: void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)
@@ -201,5 +201,5 @@ called with a non-bytes parameter.
201201
desired. On success, *\*bytes* holds the resized bytes object and ``0`` is
202202
returned; the address in *\*bytes* may differ from its input value. If the
203203
reallocation fails, the original bytes object at *\*bytes* is deallocated,
204-
*\*bytes* is set to *NULL*, :exc:`MemoryError` is set, and ``-1`` is
204+
*\*bytes* is set to ``NULL``, :exc:`MemoryError` is set, and ``-1`` is
205205
returned.

0 commit comments

Comments
 (0)