bpo-38600: Change the mark up of NULL in the C API documentation. (GH-16950)
Replace all *NULL* with ``NULL``.
diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index a150a9c..0359f5e 100644
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -236,7 +236,7 @@
.. versionchanged:: 3.3
This macro is now inefficient -- because in many cases the
:c:type:`Py_UNICODE` representation does not exist and needs to be created
- -- and can fail (return *NULL* with an exception set). Try to port the
+ -- and can fail (return ``NULL`` with an exception set). Try to port the
code to use the new :c:func:`PyUnicode_nBYTE_DATA` macros or use
:c:func:`PyUnicode_WRITE` or :c:func:`PyUnicode_READ`.
@@ -413,11 +413,11 @@
Create a Unicode object from the char buffer *u*. The bytes will be
interpreted as being UTF-8 encoded. The buffer is copied into the new
- object. If the buffer is not *NULL*, the return value might be a shared
+ object. If the buffer is not ``NULL``, the return value might be a shared
object, i.e. modification of the data is not allowed.
- If *u* is *NULL*, this function behaves like :c:func:`PyUnicode_FromUnicode`
- with the buffer set to *NULL*. This usage is deprecated in favor of
+ If *u* is ``NULL``, this function behaves like :c:func:`PyUnicode_FromUnicode`
+ with the buffer set to ``NULL``. This usage is deprecated in favor of
:c:func:`PyUnicode_New`.
@@ -443,82 +443,82 @@
.. tabularcolumns:: |l|l|L|
- +-------------------+---------------------+--------------------------------+
- | Format Characters | Type | Comment |
- +===================+=====================+================================+
- | :attr:`%%` | *n/a* | The literal % character. |
- +-------------------+---------------------+--------------------------------+
- | :attr:`%c` | int | A single character, |
- | | | represented as a C int. |
- +-------------------+---------------------+--------------------------------+
- | :attr:`%d` | int | Equivalent to |
- | | | ``printf("%d")``. [1]_ |
- +-------------------+---------------------+--------------------------------+
- | :attr:`%u` | unsigned int | Equivalent to |
- | | | ``printf("%u")``. [1]_ |
- +-------------------+---------------------+--------------------------------+
- | :attr:`%ld` | long | Equivalent to |
- | | | ``printf("%ld")``. [1]_ |
- +-------------------+---------------------+--------------------------------+
- | :attr:`%li` | long | Equivalent to |
- | | | ``printf("%li")``. [1]_ |
- +-------------------+---------------------+--------------------------------+
- | :attr:`%lu` | unsigned long | Equivalent to |
- | | | ``printf("%lu")``. [1]_ |
- +-------------------+---------------------+--------------------------------+
- | :attr:`%lld` | long long | Equivalent to |
- | | | ``printf("%lld")``. [1]_ |
- +-------------------+---------------------+--------------------------------+
- | :attr:`%lli` | long long | Equivalent to |
- | | | ``printf("%lli")``. [1]_ |
- +-------------------+---------------------+--------------------------------+
- | :attr:`%llu` | unsigned long long | Equivalent to |
- | | | ``printf("%llu")``. [1]_ |
- +-------------------+---------------------+--------------------------------+
- | :attr:`%zd` | Py_ssize_t | Equivalent to |
- | | | ``printf("%zd")``. [1]_ |
- +-------------------+---------------------+--------------------------------+
- | :attr:`%zi` | Py_ssize_t | Equivalent to |
- | | | ``printf("%zi")``. [1]_ |
- +-------------------+---------------------+--------------------------------+
- | :attr:`%zu` | size_t | Equivalent to |
- | | | ``printf("%zu")``. [1]_ |
- +-------------------+---------------------+--------------------------------+
- | :attr:`%i` | int | Equivalent to |
- | | | ``printf("%i")``. [1]_ |
- +-------------------+---------------------+--------------------------------+
- | :attr:`%x` | int | Equivalent to |
- | | | ``printf("%x")``. [1]_ |
- +-------------------+---------------------+--------------------------------+
- | :attr:`%s` | const char\* | A null-terminated C character |
- | | | array. |
- +-------------------+---------------------+--------------------------------+
- | :attr:`%p` | const void\* | The hex representation of a C |
- | | | pointer. Mostly equivalent to |
- | | | ``printf("%p")`` except that |
- | | | it is guaranteed to start with |
- | | | the literal ``0x`` regardless |
- | | | of what the platform's |
- | | | ``printf`` yields. |
- +-------------------+---------------------+--------------------------------+
- | :attr:`%A` | PyObject\* | The result of calling |
- | | | :func:`ascii`. |
- +-------------------+---------------------+--------------------------------+
- | :attr:`%U` | PyObject\* | A Unicode object. |
- +-------------------+---------------------+--------------------------------+
- | :attr:`%V` | PyObject\*, | A Unicode object (which may be |
- | | const char\* | *NULL*) and a null-terminated |
- | | | C character array as a second |
- | | | parameter (which will be used, |
- | | | if the first parameter is |
- | | | *NULL*). |
- +-------------------+---------------------+--------------------------------+
- | :attr:`%S` | PyObject\* | The result of calling |
- | | | :c:func:`PyObject_Str`. |
- +-------------------+---------------------+--------------------------------+
- | :attr:`%R` | PyObject\* | The result of calling |
- | | | :c:func:`PyObject_Repr`. |
- +-------------------+---------------------+--------------------------------+
+ +-------------------+---------------------+----------------------------------+
+ | Format Characters | Type | Comment |
+ +===================+=====================+==================================+
+ | :attr:`%%` | *n/a* | The literal % character. |
+ +-------------------+---------------------+----------------------------------+
+ | :attr:`%c` | int | A single character, |
+ | | | represented as a C int. |
+ +-------------------+---------------------+----------------------------------+
+ | :attr:`%d` | int | Equivalent to |
+ | | | ``printf("%d")``. [1]_ |
+ +-------------------+---------------------+----------------------------------+
+ | :attr:`%u` | unsigned int | Equivalent to |
+ | | | ``printf("%u")``. [1]_ |
+ +-------------------+---------------------+----------------------------------+
+ | :attr:`%ld` | long | Equivalent to |
+ | | | ``printf("%ld")``. [1]_ |
+ +-------------------+---------------------+----------------------------------+
+ | :attr:`%li` | long | Equivalent to |
+ | | | ``printf("%li")``. [1]_ |
+ +-------------------+---------------------+----------------------------------+
+ | :attr:`%lu` | unsigned long | Equivalent to |
+ | | | ``printf("%lu")``. [1]_ |
+ +-------------------+---------------------+----------------------------------+
+ | :attr:`%lld` | long long | Equivalent to |
+ | | | ``printf("%lld")``. [1]_ |
+ +-------------------+---------------------+----------------------------------+
+ | :attr:`%lli` | long long | Equivalent to |
+ | | | ``printf("%lli")``. [1]_ |
+ +-------------------+---------------------+----------------------------------+
+ | :attr:`%llu` | unsigned long long | Equivalent to |
+ | | | ``printf("%llu")``. [1]_ |
+ +-------------------+---------------------+----------------------------------+
+ | :attr:`%zd` | Py_ssize_t | Equivalent to |
+ | | | ``printf("%zd")``. [1]_ |
+ +-------------------+---------------------+----------------------------------+
+ | :attr:`%zi` | Py_ssize_t | Equivalent to |
+ | | | ``printf("%zi")``. [1]_ |
+ +-------------------+---------------------+----------------------------------+
+ | :attr:`%zu` | size_t | Equivalent to |
+ | | | ``printf("%zu")``. [1]_ |
+ +-------------------+---------------------+----------------------------------+
+ | :attr:`%i` | int | Equivalent to |
+ | | | ``printf("%i")``. [1]_ |
+ +-------------------+---------------------+----------------------------------+
+ | :attr:`%x` | int | Equivalent to |
+ | | | ``printf("%x")``. [1]_ |
+ +-------------------+---------------------+----------------------------------+
+ | :attr:`%s` | const char\* | A null-terminated C character |
+ | | | array. |
+ +-------------------+---------------------+----------------------------------+
+ | :attr:`%p` | const void\* | The hex representation of a C |
+ | | | pointer. Mostly equivalent to |
+ | | | ``printf("%p")`` except that |
+ | | | it is guaranteed to start with |
+ | | | the literal ``0x`` regardless |
+ | | | of what the platform's |
+ | | | ``printf`` yields. |
+ +-------------------+---------------------+----------------------------------+
+ | :attr:`%A` | PyObject\* | The result of calling |
+ | | | :func:`ascii`. |
+ +-------------------+---------------------+----------------------------------+
+ | :attr:`%U` | PyObject\* | A Unicode object. |
+ +-------------------+---------------------+----------------------------------+
+ | :attr:`%V` | PyObject\*, | A Unicode object (which may be |
+ | | const char\* | ``NULL``) and a null-terminated |
+ | | | C character array as a second |
+ | | | parameter (which will be used, |
+ | | | if the first parameter is |
+ | | | ``NULL``). |
+ +-------------------+---------------------+----------------------------------+
+ | :attr:`%S` | PyObject\* | The result of calling |
+ | | | :c:func:`PyObject_Str`. |
+ +-------------------+---------------------+----------------------------------+
+ | :attr:`%R` | PyObject\* | The result of calling |
+ | | | :c:func:`PyObject_Repr`. |
+ +-------------------+---------------------+----------------------------------+
An unrecognized format character causes all the rest of the format string to be
copied as-is to the result string, and any extra arguments discarded.
@@ -558,13 +558,13 @@
:class:`bytes`, :class:`bytearray` and other
:term:`bytes-like objects <bytes-like object>`
are decoded according to the given *encoding* and using the error handling
- defined by *errors*. Both can be *NULL* to have the interface use the default
+ defined by *errors*. Both can be ``NULL`` to have the interface use the default
values (see :ref:`builtincodecs` for details).
All other objects, including Unicode objects, cause a :exc:`TypeError` to be
set.
- The API returns *NULL* if there was an error. The caller is responsible for
+ The API returns ``NULL`` if there was an error. The caller is responsible for
decref'ing the returned objects.
@@ -640,7 +640,7 @@
Py_ssize_t buflen, int copy_null)
Copy the string *u* into a UCS4 buffer, including a null character, if
- *copy_null* is set. Returns *NULL* and sets an exception on error (in
+ *copy_null* is set. Returns ``NULL`` and sets an exception on error (in
particular, a :exc:`SystemError` if *buflen* is smaller than the length of
*u*). *buffer* is returned on success.
@@ -650,7 +650,7 @@
.. c:function:: Py_UCS4* PyUnicode_AsUCS4Copy(PyObject *u)
Copy the string *u* into a new UCS4 buffer that is allocated using
- :c:func:`PyMem_Malloc`. If this fails, *NULL* is returned with a
+ :c:func:`PyMem_Malloc`. If this fails, ``NULL`` is returned with a
:exc:`MemoryError` set. The returned buffer always has an extra
null code point appended.
@@ -670,15 +670,15 @@
.. c:function:: PyObject* PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size)
Create a Unicode object from the Py_UNICODE buffer *u* of the given size. *u*
- may be *NULL* which causes the contents to be undefined. It is the user's
+ may be ``NULL`` which causes the contents to be undefined. It is the user's
responsibility to fill in the needed data. The buffer is copied into the new
object.
- If the buffer is not *NULL*, the return value might be a shared object.
+ If the buffer is not ``NULL``, the return value might be a shared object.
Therefore, modification of the resulting Unicode object is only allowed when
- *u* is *NULL*.
+ *u* is ``NULL``.
- If the buffer is *NULL*, :c:func:`PyUnicode_READY` must be called once the
+ If the buffer is ``NULL``, :c:func:`PyUnicode_READY` must be called once the
string content has been filled before using any of the access macros such as
:c:func:`PyUnicode_KIND`.
@@ -689,7 +689,7 @@
.. c:function:: Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)
Return a read-only pointer to the Unicode object's internal
- :c:type:`Py_UNICODE` buffer, or *NULL* on error. This will create the
+ :c:type:`Py_UNICODE` buffer, or ``NULL`` on error. This will create the
:c:type:`Py_UNICODE*` representation of the object if it is not yet
available. The buffer is always terminated with an extra null code point.
Note that the resulting :c:type:`Py_UNICODE` string may also contain
@@ -705,7 +705,7 @@
Create a Unicode object by replacing all decimal digits in
:c:type:`Py_UNICODE` buffer of the given *size* by ASCII digits 0--9
- according to their decimal value. Return *NULL* if an exception occurs.
+ according to their decimal value. Return ``NULL`` if an exception occurs.
.. c:function:: Py_UNICODE* PyUnicode_AsUnicodeAndSize(PyObject *unicode, Py_ssize_t *size)
@@ -721,7 +721,7 @@
.. c:function:: Py_UNICODE* PyUnicode_AsUnicodeCopy(PyObject *unicode)
- Create a copy of a Unicode string ending with a null code point. Return *NULL*
+ Create a copy of a Unicode string ending with a null code point. Return ``NULL``
and raise a :exc:`MemoryError` exception on memory allocation failure,
otherwise return a new allocated buffer (use :c:func:`PyMem_Free` to free
the buffer). Note that the resulting :c:type:`Py_UNICODE*` string may
@@ -932,7 +932,7 @@
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,
using wcslen.
- Return *NULL* on failure.
+ Return ``NULL`` on failure.
.. c:function:: Py_ssize_t PyUnicode_AsWideChar(PyObject *unicode, wchar_t *w, Py_ssize_t size)
@@ -951,22 +951,22 @@
.. c:function:: wchar_t* PyUnicode_AsWideCharString(PyObject *unicode, Py_ssize_t *size)
Convert the Unicode object to a wide character string. The output string
- always ends with a null character. If *size* is not *NULL*, write the number
+ always ends with a null character. If *size* is not ``NULL``, write the number
of wide characters (excluding the trailing null termination character) into
*\*size*. Note that the resulting :c:type:`wchar_t` string might contain
null characters, which would cause the string to be truncated when used with
- most C functions. If *size* is *NULL* and the :c:type:`wchar_t*` string
+ most C functions. If *size* is ``NULL`` and the :c:type:`wchar_t*` string
contains null characters a :exc:`ValueError` is raised.
Returns a buffer allocated by :c:func:`PyMem_Alloc` (use
- :c:func:`PyMem_Free` to free it) on success. On error, returns *NULL*
+ :c:func:`PyMem_Free` to free it) on success. On error, returns ``NULL``
and *\*size* is undefined. Raises a :exc:`MemoryError` if memory allocation
is failed.
.. versionadded:: 3.2
.. versionchanged:: 3.7
- Raises a :exc:`ValueError` if *size* is *NULL* and the :c:type:`wchar_t*`
+ Raises a :exc:`ValueError` if *size* is ``NULL`` and the :c:type:`wchar_t*`
string contains null characters.
@@ -982,7 +982,7 @@
have the same semantics as the ones of the built-in :func:`str` string object
constructor.
-Setting encoding to *NULL* causes the default encoding to be used
+Setting encoding to ``NULL`` causes the default encoding to be used
which is ASCII. The file system calls should use
:c:func:`PyUnicode_FSConverter` for encoding file names. This uses the
variable :c:data:`Py_FileSystemDefaultEncoding` internally. This
@@ -990,7 +990,7 @@
pointer to a static string, on others, it will change at run-time
(such as when the application invokes setlocale).
-Error handling is set by errors which may also be set to *NULL* meaning to use
+Error handling is set by errors which may also be set to ``NULL`` meaning to use
the default handling defined for the codec. Default error handling for all
built-in codecs is "strict" (:exc:`ValueError` is raised).
@@ -1010,7 +1010,7 @@
Create a Unicode object by decoding *size* bytes of the encoded string *s*.
*encoding* and *errors* have the same meaning as the parameters of the same name
in the :func:`str` built-in function. The codec to be used is looked up
- using the Python codec registry. Return *NULL* if an exception was raised by
+ using the Python codec registry. Return ``NULL`` if an exception was raised by
the codec.
@@ -1020,7 +1020,7 @@
Encode a Unicode object and return the result as Python bytes object.
*encoding* and *errors* have the same meaning as the parameters of the same
name in the Unicode :meth:`~str.encode` method. The codec to be used is looked up
- using the Python codec registry. Return *NULL* if an exception was raised by
+ using the Python codec registry. Return ``NULL`` if an exception was raised by
the codec.
@@ -1030,7 +1030,7 @@
Encode the :c:type:`Py_UNICODE` buffer *s* of the given *size* and return a Python
bytes object. *encoding* and *errors* have the same meaning as the
parameters of the same name in the Unicode :meth:`~str.encode` method. The codec
- to be used is looked up using the Python codec registry. Return *NULL* if an
+ to be used is looked up using the Python codec registry. Return ``NULL`` if an
exception was raised by the codec.
.. deprecated-removed:: 3.3 4.0
@@ -1047,14 +1047,14 @@
.. c:function:: PyObject* PyUnicode_DecodeUTF8(const char *s, Py_ssize_t size, const char *errors)
Create a Unicode object by decoding *size* bytes of the UTF-8 encoded string
- *s*. Return *NULL* if an exception was raised by the codec.
+ *s*. Return ``NULL`` if an exception was raised by the codec.
.. c:function:: PyObject* PyUnicode_DecodeUTF8Stateful(const char *s, Py_ssize_t size, \
const char *errors, Py_ssize_t *consumed)
- If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeUTF8`. If
- *consumed* is not *NULL*, trailing incomplete UTF-8 byte sequences will not be
+ If *consumed* is ``NULL``, behave like :c:func:`PyUnicode_DecodeUTF8`. If
+ *consumed* is not ``NULL``, trailing incomplete UTF-8 byte sequences will not be
treated as an error. Those bytes will not be decoded and the number of bytes
that have been decoded will be stored in *consumed*.
@@ -1062,7 +1062,7 @@
.. c:function:: PyObject* PyUnicode_AsUTF8String(PyObject *unicode)
Encode a Unicode object using UTF-8 and return the result as Python bytes
- object. Error handling is "strict". Return *NULL* if an exception was
+ object. Error handling is "strict". Return ``NULL`` if an exception was
raised by the codec.
@@ -1070,11 +1070,11 @@
Return a pointer to the UTF-8 encoding of the Unicode object, and
store the size of the encoded representation (in bytes) in *size*. The
- *size* argument can be *NULL*; in this case no size will be stored. The
+ *size* argument can be ``NULL``; in this case no size will be stored. The
returned buffer always has an extra null byte appended (not included in
*size*), regardless of whether there are any other null code points.
- In the case of an error, *NULL* is returned with an exception set and no
+ In the case of an error, ``NULL`` is returned with an exception set and no
*size* is stored.
This caches the UTF-8 representation of the string in the Unicode object, and
@@ -1100,7 +1100,7 @@
.. c:function:: PyObject* PyUnicode_EncodeUTF8(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
Encode the :c:type:`Py_UNICODE` buffer *s* of the given *size* using UTF-8 and
- return a Python bytes object. Return *NULL* if an exception was raised by
+ return a Python bytes object. Return ``NULL`` if an exception was raised by
the codec.
.. deprecated-removed:: 3.3 4.0
@@ -1119,10 +1119,10 @@
const char *errors, int *byteorder)
Decode *size* bytes from a UTF-32 encoded buffer string and return the
- corresponding Unicode object. *errors* (if non-*NULL*) defines the error
+ corresponding Unicode object. *errors* (if non-``NULL``) defines the error
handling. It defaults to "strict".
- If *byteorder* is non-*NULL*, the decoder starts decoding using the given byte
+ If *byteorder* is non-``NULL``, the decoder starts decoding using the given byte
order::
*byteorder == -1: little endian
@@ -1137,16 +1137,16 @@
After completion, *\*byteorder* is set to the current byte order at the end
of input data.
- If *byteorder* is *NULL*, the codec starts in native order mode.
+ If *byteorder* is ``NULL``, the codec starts in native order mode.
- Return *NULL* if an exception was raised by the codec.
+ Return ``NULL`` if an exception was raised by the codec.
.. c:function:: PyObject* PyUnicode_DecodeUTF32Stateful(const char *s, Py_ssize_t size, \
const char *errors, int *byteorder, Py_ssize_t *consumed)
- If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeUTF32`. If
- *consumed* is not *NULL*, :c:func:`PyUnicode_DecodeUTF32Stateful` will not treat
+ If *consumed* is ``NULL``, behave like :c:func:`PyUnicode_DecodeUTF32`. If
+ *consumed* is not ``NULL``, :c:func:`PyUnicode_DecodeUTF32Stateful` will not treat
trailing incomplete UTF-32 byte sequences (such as a number of bytes not divisible
by four) as an error. Those bytes will not be decoded and the number of bytes
that have been decoded will be stored in *consumed*.
@@ -1156,7 +1156,7 @@
Return a Python byte string using the UTF-32 encoding in native byte
order. The string always starts with a BOM mark. Error handling is "strict".
- Return *NULL* if an exception was raised by the codec.
+ Return ``NULL`` if an exception was raised by the codec.
.. c:function:: PyObject* PyUnicode_EncodeUTF32(const Py_UNICODE *s, Py_ssize_t size, \
@@ -1175,7 +1175,7 @@
If *Py_UNICODE_WIDE* is not defined, surrogate pairs will be output
as a single code point.
- Return *NULL* if an exception was raised by the codec.
+ Return ``NULL`` if an exception was raised by the codec.
.. deprecated-removed:: 3.3 4.0
Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
@@ -1192,10 +1192,10 @@
const char *errors, int *byteorder)
Decode *size* bytes from a UTF-16 encoded buffer string and return the
- corresponding Unicode object. *errors* (if non-*NULL*) defines the error
+ corresponding Unicode object. *errors* (if non-``NULL``) defines the error
handling. It defaults to "strict".
- If *byteorder* is non-*NULL*, the decoder starts decoding using the given byte
+ If *byteorder* is non-``NULL``, the decoder starts decoding using the given byte
order::
*byteorder == -1: little endian
@@ -1211,16 +1211,16 @@
After completion, *\*byteorder* is set to the current byte order at the end
of input data.
- If *byteorder* is *NULL*, the codec starts in native order mode.
+ If *byteorder* is ``NULL``, the codec starts in native order mode.
- Return *NULL* if an exception was raised by the codec.
+ Return ``NULL`` if an exception was raised by the codec.
.. c:function:: PyObject* PyUnicode_DecodeUTF16Stateful(const char *s, Py_ssize_t size, \
const char *errors, int *byteorder, Py_ssize_t *consumed)
- If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeUTF16`. If
- *consumed* is not *NULL*, :c:func:`PyUnicode_DecodeUTF16Stateful` will not treat
+ If *consumed* is ``NULL``, behave like :c:func:`PyUnicode_DecodeUTF16`. If
+ *consumed* is not ``NULL``, :c:func:`PyUnicode_DecodeUTF16Stateful` will not treat
trailing incomplete UTF-16 byte sequences (such as an odd number of bytes or a
split surrogate pair) as an error. Those bytes will not be decoded and the
number of bytes that have been decoded will be stored in *consumed*.
@@ -1230,7 +1230,7 @@
Return a Python byte string using the UTF-16 encoding in native byte
order. The string always starts with a BOM mark. Error handling is "strict".
- Return *NULL* if an exception was raised by the codec.
+ Return ``NULL`` if an exception was raised by the codec.
.. c:function:: PyObject* PyUnicode_EncodeUTF16(const Py_UNICODE *s, Py_ssize_t size, \
@@ -1250,7 +1250,7 @@
represented as a surrogate pair. If it is not defined, each :c:type:`Py_UNICODE`
values is interpreted as a UCS-2 character.
- Return *NULL* if an exception was raised by the codec.
+ Return ``NULL`` if an exception was raised by the codec.
.. deprecated-removed:: 3.3 4.0
Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
@@ -1266,14 +1266,14 @@
.. c:function:: PyObject* PyUnicode_DecodeUTF7(const char *s, Py_ssize_t size, const char *errors)
Create a Unicode object by decoding *size* bytes of the UTF-7 encoded string
- *s*. Return *NULL* if an exception was raised by the codec.
+ *s*. Return ``NULL`` if an exception was raised by the codec.
.. c:function:: PyObject* PyUnicode_DecodeUTF7Stateful(const char *s, Py_ssize_t size, \
const char *errors, Py_ssize_t *consumed)
- If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeUTF7`. If
- *consumed* is not *NULL*, trailing incomplete UTF-7 base-64 sections will not
+ If *consumed* is ``NULL``, behave like :c:func:`PyUnicode_DecodeUTF7`. If
+ *consumed* is not ``NULL``, trailing incomplete UTF-7 base-64 sections will not
be treated as an error. Those bytes will not be decoded and the number of
bytes that have been decoded will be stored in *consumed*.
@@ -1282,7 +1282,7 @@
int base64SetO, int base64WhiteSpace, const char *errors)
Encode the :c:type:`Py_UNICODE` buffer of the given size using UTF-7 and
- return a Python bytes object. Return *NULL* if an exception was raised by
+ return a Python bytes object. Return ``NULL`` if an exception was raised by
the codec.
If *base64SetO* is nonzero, "Set O" (punctuation that has no otherwise
@@ -1305,20 +1305,20 @@
Py_ssize_t size, const char *errors)
Create a Unicode object by decoding *size* bytes of the Unicode-Escape encoded
- string *s*. Return *NULL* if an exception was raised by the codec.
+ string *s*. Return ``NULL`` if an exception was raised by the codec.
.. c:function:: PyObject* PyUnicode_AsUnicodeEscapeString(PyObject *unicode)
Encode a Unicode object using Unicode-Escape and return the result as a
- bytes object. Error handling is "strict". Return *NULL* if an exception was
+ bytes object. Error handling is "strict". Return ``NULL`` if an exception was
raised by the codec.
.. c:function:: PyObject* PyUnicode_EncodeUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)
Encode the :c:type:`Py_UNICODE` buffer of the given *size* using Unicode-Escape and
- return a bytes object. Return *NULL* if an exception was raised by the codec.
+ return a bytes object. Return ``NULL`` if an exception was raised by the codec.
.. deprecated-removed:: 3.3 4.0
Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
@@ -1335,13 +1335,13 @@
Py_ssize_t size, const char *errors)
Create a Unicode object by decoding *size* bytes of the Raw-Unicode-Escape
- encoded string *s*. Return *NULL* if an exception was raised by the codec.
+ encoded string *s*. Return ``NULL`` if an exception was raised by the codec.
.. c:function:: PyObject* PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)
Encode a Unicode object using Raw-Unicode-Escape and return the result as
- a bytes object. Error handling is "strict". Return *NULL* if an exception
+ a bytes object. Error handling is "strict". Return ``NULL`` if an exception
was raised by the codec.
@@ -1349,7 +1349,7 @@
Py_ssize_t size)
Encode the :c:type:`Py_UNICODE` buffer of the given *size* using Raw-Unicode-Escape
- and return a bytes object. Return *NULL* if an exception was raised by the codec.
+ and return a bytes object. Return ``NULL`` if an exception was raised by the codec.
.. deprecated-removed:: 3.3 4.0
Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
@@ -1367,20 +1367,20 @@
.. c:function:: PyObject* PyUnicode_DecodeLatin1(const char *s, Py_ssize_t size, const char *errors)
Create a Unicode object by decoding *size* bytes of the Latin-1 encoded string
- *s*. Return *NULL* if an exception was raised by the codec.
+ *s*. Return ``NULL`` if an exception was raised by the codec.
.. c:function:: PyObject* PyUnicode_AsLatin1String(PyObject *unicode)
Encode a Unicode object using Latin-1 and return the result as Python bytes
- object. Error handling is "strict". Return *NULL* if an exception was
+ object. Error handling is "strict". Return ``NULL`` if an exception was
raised by the codec.
.. c:function:: PyObject* PyUnicode_EncodeLatin1(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
Encode the :c:type:`Py_UNICODE` buffer of the given *size* using Latin-1 and
- return a Python bytes object. Return *NULL* if an exception was raised by
+ return a Python bytes object. Return ``NULL`` if an exception was raised by
the codec.
.. deprecated-removed:: 3.3 4.0
@@ -1399,20 +1399,20 @@
.. c:function:: PyObject* PyUnicode_DecodeASCII(const char *s, Py_ssize_t size, const char *errors)
Create a Unicode object by decoding *size* bytes of the ASCII encoded string
- *s*. Return *NULL* if an exception was raised by the codec.
+ *s*. Return ``NULL`` if an exception was raised by the codec.
.. c:function:: PyObject* PyUnicode_AsASCIIString(PyObject *unicode)
Encode a Unicode object using ASCII and return the result as Python bytes
- object. Error handling is "strict". Return *NULL* if an exception was
+ object. Error handling is "strict". Return ``NULL`` if an exception was
raised by the codec.
.. c:function:: PyObject* PyUnicode_EncodeASCII(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
Encode the :c:type:`Py_UNICODE` buffer of the given *size* using ASCII and
- return a Python bytes object. Return *NULL* if an exception was raised by
+ return a Python bytes object. Return ``NULL`` if an exception was raised by
the codec.
.. deprecated-removed:: 3.3 4.0
@@ -1436,10 +1436,10 @@
PyObject *mapping, const char *errors)
Create a Unicode object by decoding *size* bytes of the encoded string *s*
- using the given *mapping* object. Return *NULL* if an exception was raised
+ using the given *mapping* object. Return ``NULL`` if an exception was raised
by the codec.
- If *mapping* is *NULL*, Latin-1 decoding will be applied. Else
+ If *mapping* is ``NULL``, Latin-1 decoding will be applied. Else
*mapping* must map bytes ordinals (integers in the range from 0 to 255)
to Unicode strings, integers (which are then interpreted as Unicode
ordinals) or ``None``. Unmapped data bytes -- ones which cause a
@@ -1451,7 +1451,7 @@
.. c:function:: PyObject* PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)
Encode a Unicode object using the given *mapping* object and return the
- result as a bytes object. Error handling is "strict". Return *NULL* if an
+ result as a bytes object. Error handling is "strict". Return ``NULL`` if an
exception was raised by the codec.
The *mapping* object must map Unicode ordinal integers to bytes objects,
@@ -1464,7 +1464,7 @@
PyObject *mapping, const char *errors)
Encode the :c:type:`Py_UNICODE` buffer of the given *size* using the given
- *mapping* object and return the result as a bytes object. Return *NULL* if
+ *mapping* object and return the result as a bytes object. Return ``NULL`` if
an exception was raised by the codec.
.. deprecated-removed:: 3.3 4.0
@@ -1479,7 +1479,7 @@
PyObject *mapping, const char *errors)
Translate a Unicode object using the given *mapping* object and return the
- resulting Unicode object. Return *NULL* if an exception was raised by the
+ resulting Unicode object. Return ``NULL`` if an exception was raised by the
codec.
The *mapping* object must map Unicode ordinal integers to Unicode strings,
@@ -1493,7 +1493,7 @@
Translate a :c:type:`Py_UNICODE` buffer of the given *size* by applying a
character *mapping* table to it and return the resulting Unicode object.
- Return *NULL* when an exception was raised by the codec.
+ Return ``NULL`` when an exception was raised by the codec.
.. deprecated-removed:: 3.3 4.0
Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
@@ -1512,14 +1512,14 @@
.. c:function:: PyObject* PyUnicode_DecodeMBCS(const char *s, Py_ssize_t size, const char *errors)
Create a Unicode object by decoding *size* bytes of the MBCS encoded string *s*.
- Return *NULL* if an exception was raised by the codec.
+ Return ``NULL`` if an exception was raised by the codec.
.. c:function:: PyObject* PyUnicode_DecodeMBCSStateful(const char *s, Py_ssize_t size, \
const char *errors, Py_ssize_t *consumed)
- If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeMBCS`. If
- *consumed* is not *NULL*, :c:func:`PyUnicode_DecodeMBCSStateful` will not decode
+ If *consumed* is ``NULL``, behave like :c:func:`PyUnicode_DecodeMBCS`. If
+ *consumed* is not ``NULL``, :c:func:`PyUnicode_DecodeMBCSStateful` will not decode
trailing lead byte and the number of bytes that have been decoded will be stored
in *consumed*.
@@ -1527,14 +1527,14 @@
.. c:function:: PyObject* PyUnicode_AsMBCSString(PyObject *unicode)
Encode a Unicode object using MBCS and return the result as Python bytes
- object. Error handling is "strict". Return *NULL* if an exception was
+ object. Error handling is "strict". Return ``NULL`` if an exception was
raised by the codec.
.. c:function:: PyObject* PyUnicode_EncodeCodePage(int code_page, PyObject *unicode, const char *errors)
Encode the Unicode object using the specified code page and return a Python
- bytes object. Return *NULL* if an exception was raised by the codec. Use
+ bytes object. Return ``NULL`` if an exception was raised by the codec. Use
:c:data:`CP_ACP` code page to get the MBCS encoder.
.. versionadded:: 3.3
@@ -1543,7 +1543,7 @@
.. c:function:: PyObject* PyUnicode_EncodeMBCS(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
Encode the :c:type:`Py_UNICODE` buffer of the given *size* using MBCS and return
- a Python bytes object. Return *NULL* if an exception was raised by the
+ a Python bytes object. Return ``NULL`` if an exception was raised by the
codec.
.. deprecated-removed:: 3.3 4.0
@@ -1565,7 +1565,7 @@
(we refer to them as strings in the descriptions) and return Unicode objects or
integers as appropriate.
-They all return *NULL* or ``-1`` if an exception occurs.
+They all return ``NULL`` or ``-1`` if an exception occurs.
.. c:function:: PyObject* PyUnicode_Concat(PyObject *left, PyObject *right)
@@ -1575,7 +1575,7 @@
.. c:function:: PyObject* PyUnicode_Split(PyObject *s, PyObject *sep, Py_ssize_t maxsplit)
- Split a string giving a list of Unicode strings. If *sep* is *NULL*, splitting
+ Split a string giving a list of Unicode strings. If *sep* is ``NULL``, splitting
will be done at all whitespace substrings. Otherwise, splits occur at the given
separator. At most *maxsplit* splits will be done. If negative, no limit is
set. Separators are not included in the resulting list.
@@ -1601,7 +1601,7 @@
and sequences work well. Unmapped character ordinals (ones which cause a
:exc:`LookupError`) are left untouched and are copied as-is.
- *errors* has the usual meaning for codecs. It may be *NULL* which indicates to
+ *errors* has the usual meaning for codecs. It may be ``NULL`` which indicates to
use the default error handling.