8000 gh-93738: Documentation C syntax (:c:type:<C type> -> :c:expr:<C type… · python/cpython@0031e62 · GitHub
[go: up one dir, main page]

Skip to content

Commit 0031e62

Browse files
AA-Turnerambv
andauthored
gh-93738: Documentation C syntax (:c:type:<C type> -> :c:expr:<C type>) (#97768)
:c:type:`<C type>` -> :c:expr:`<C type>` Co-authored-by: Łukasz Langa <lukasz@langa.pl>
1 parent aeb28f5 commit 0031e62

34 files changed

+241
-241
lines changed

Doc/c-api/arg.rst

Lines changed: 36 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -152,10 +152,10 @@ which disallows mutable objects such as :class:`bytearray`.
152152
It only works for encoded data without embedded NUL bytes.
153153

154154
This format requires two arguments. The first is only used as input, and
155-
must be a :c:type:`const char*` which points to the name of an encoding as a
155+
must be a :c:expr:`const char*` which points to the name of an encoding as a
156156
NUL-terminated string, or ``NULL``, in which case ``'utf-8'`` encoding is used.
157157
An exception is raised if the named encoding is not known to Python. The
158-
second argument must be a :c:type:`char**`; the value of the pointer it
158+
second argument must be a :c:expr:`char**`; the value of the pointer it
159159
references will be set to a buffer with the contents of the argument text.
160160
The text will be encoded in the encoding specified by the first argument.
161161

@@ -175,10 +175,10 @@ which disallows mutable objects such as :class:`bytearray`.
175175
characters.
176176

177177
It requires three arguments. The first is only used as input, and must be a
178-
:c:type:`const char*` which points to the name of an encoding as a
178+
:c:expr:`const char*` which points to the name of an encoding as a
179179
NUL-terminated string, or ``NULL``, in which case ``'utf-8'`` encoding is used.
180180
An exception is raised if the named encoding is not known to Python. The
181-
second argument must be a :c:type:`char**`; the value of the pointer it
181+
second argument must be a :c:expr:`char**`; the value of the pointer it
182182
references will be set to a buffer with the contents of the argument text.
183183
The text will be encoded in the encoding specified by the first argument.
184184
The third argument must be a pointer to an integer; the referenced integer
@@ -215,59 +215,59 @@ Numbers
215215

216216
``b`` (:class:`int`) [unsigned char]
217217
Convert a nonnegative Python integer to an unsigned tiny int, stored in a C
218-
:c:type:`unsigned char`.
218+
:c:expr:`unsigned char`.
219219

220220
``B`` (:class:`int`) [unsigned char]
221221
Convert a Python integer to a tiny int without overflow checking, stored in a C
222-
:c:type:`unsigned char`.
222+
:c:expr:`unsigned char`.
223223

224224
``h`` (:class:`int`) [short int]
225-
Convert a Python integer to a C :c:type:`short int`.
225+
Convert a Python integer to a C :c:expr:`short int`.
226226

227227
``H`` (:class:`int`) [unsigned short int]
228-
Convert a Python integer to a C :c:type:`unsigned short int`, without overflow
228+
Convert a Python integer to a C :c:expr:`unsigned short int`, without overflow
229229
checking.
230230

231231
``i`` (:class:`int`) [int]
232-
Convert a Python integer to a plain C :c:type:`int`.
232+
Convert a Python integer to a plain C :c:expr:`int`.
233233

234234
``I`` (:class:`int`) [unsigned int]
235-
Convert a Python integer to a C :c:type:`unsigned int`, without overflow
235+
Convert a Python integer to a C :c:expr:`unsigned int`, without overflow
236236
checking.
237237

238238
``l`` (:class:`int`) [long int]
239-
Convert a Python integer to a C :c:type:`long int`.
239+
Convert a Python integer to a C :c:expr:`long int`.
240240

241241
``k`` (:class:`int`) [unsigned long]
242-
Convert a Python integer to a C :c:type:`unsigned long` without
242+
Convert a Python integer to a C :c:expr:`unsigned long` without
243243
overflow checking.
244244

245245
``L`` (:class:`int`) [long long]
246-
Convert a Python integer to a C :c:type:`long long`.
246+
Convert a Python integer to a C :c:expr:`long long`.
247247

248248
``K`` (:class:`int`) [unsigned long long]
249-
Convert a Python integer to a C :c:type:`unsigned long long`
249+
Convert a Python integer to a C :c:expr:`unsigned long long`
250250
without overflow checking.
251251

252252
``n`` (:class:`int`) [:c:type:`Py_ssize_t`]
253253
Convert a Python integer to a C :c:type:`Py_ssize_t`.
254254

255255
``c`` (:class:`bytes` or :class:`bytearray` of length 1) [char]
256256
Convert a Python byte, represented as a :class:`bytes` or
257-
:class:`bytearray` object of length 1, to a C :c:type:`char`.
257+
:class:`bytearray` object of length 1, to a C :c:expr:`char`.
258258

259259
.. versionchanged:: 3.3
260260
Allow :class:`bytearray` objects.
261261

262262
``C`` (:class:`str` of length 1) [int]
263263
Convert a Python character, represented as a :class:`str` object of
264-
length 1, to a C :c:type:`int`.
264+
length 1, to a C :c:expr:`int`.
265265

266266
``f`` (:class:`float`) [float]
267-
Convert a Python floating point number to a C :c:type:`float`.
267+
Convert a Python floating point number to a C :c:expr:`float`.
268268

269269
``d`` (:class:`float`) [double]
270-
Convert a Python floating point number to a C :c:type:`double`.
270+
Convert a Python floating point number to a C :c:expr:`double`.
271271

272272
``D`` (:class:`complex`) [Py_complex]
273273
Convert a Python complex number to a C :c:type:`Py_complex` structure.
@@ -292,13 +292,13 @@ Other objects
292292
``O&`` (object) [*converter*, *anything*]
293293
Convert a Python object to a C variable through a *converter* function. This
294294
takes two arguments: the first is a function, the second is the address of a C
295-
variable (of arbitrary type), converted to :c:type:`void *`. The *converter*
295+
variable (of arbitrary type), converted to :c:expr:`void *`. The *converter*
296296
function in turn is called as follows::
297297

298298
status = converter(object, address);
299299

300300
where *object* is the Python object to be converted and *address* is the
301-
:c:type:`void*` argument that was passed to the ``PyArg_Parse*`` function.
301+
:c:expr:`void*` argument that was passed to the ``PyArg_Parse*`` function.
302302
The returned *status* should be ``1`` for a successful conversion and ``0`` if
303303
the conversion has failed. When the conversion fails, the *converter* function
304304
should raise an exception and leave the content of *address* unmodified.
@@ -531,7 +531,7 @@ Building values
531531
Same as ``s#``.
532532
533533
``u`` (:class:`str`) [const wchar_t \*]
534-
Convert a null-terminated :c:type:`wchar_t` buffer of Unicode (UTF-16 or UCS-4)
534+
Convert a null-terminated :c:expr:`wchar_t` buffer of Unicode (UTF-16 or UCS-4)
535535
data to a Python Unicode object. If the Unicode buffer pointer is ``NULL``,
536536
``None`` is returned.
537537
@@ -547,51 +547,51 @@ Building values
547547
Same as ``s#``.
548548
549549
``i`` (:class:`int`) [int]
550-
Convert a plain C :c:type:`int` to a Python integer object.
550+
Convert a plain C :c:expr:`int` to a Python integer object.
551551
552552
``b`` (:class:`int`) [char]
553-
Convert a plain C :c:type:`char` to a Python integer object.
553+
Convert a plain C :c:expr:`char` to a Python integer object.
554554
555555
``h`` (:class:`int`) [short int]
556-
Convert a plain C :c:type:`short int` to a Python integer object.
556+
Convert a plain C :c:expr:`short int` to a Python integer object.
557557
558558
``l`` (:class:`int`) [long int]
559-
Convert a C :c:type:`long int` to a Python integer object.
559+
Convert a C :c:expr:`long int` to a Python integer object.
560560
561561
``B`` (:class:`int`) [unsigned char]
562-
Convert a C :c:type:`unsigned char` to a Python integer object.
562+
Convert a C :c:expr:`unsigned char` to a Python integer object.
563563
564564
``H`` (:class:`int`) [unsigned short int]
565-
Convert a C :c:type:`unsigned short int` to a Python integer object.
565+
Convert a C :c:expr:`unsigned short int` to a Python integer object.
566566
567567
``I`` (:class:`int`) [unsigned int]
568-
Convert a C :c:type:`unsigned int` to a Python integer object.
568+
Convert a C :c:expr:`unsigned int` to a Python integer object.
569569
570570
``k`` (:class:`int`) [unsigned long]
571-
Convert a C :c:type:`unsigned long` to a Python integer object.
571+
Convert a C :c:expr:`unsigned long` to a Python integer object.
572572
573573
``L`` (:class:`int`) [long long]
574-
Convert a C :c:type:`long long` to a Python integer object.
574+
Convert a C :c:expr:`long long` to a Python integer object.
575575
576576
``K`` (:class:`int`) [unsigned long long]
577-
Convert a C :c:type:`unsigned long long` to a Python integer object.
577+
Convert a C :c:expr:`unsigned long long` to a Python integer object.
578578
579579
``n`` (:class:`int`) [:c:type:`Py_ssize_t`]
580580
Convert a C :c:type:`Py_ssize_t` to a Python integer.
581581
582582
``c`` (:class:`bytes` of length 1) [char]
583-
Convert a C :c:type:`int` representing a byte to a Python :class:`bytes` object of
583+
Convert a C :c:expr:`int` representing a byte to a Python :class:`bytes` object of
584584
length 1.
585585
586586
``C`` (:class:`str` of length 1) [int]
587-
Convert a C :c:type:`int` representing a character to Python :class:`str`
587+
Convert a C :c:expr:`int` representing a character to Python :class:`str`
588588
object of length 1.
589589
590590
``d`` (:class:`float`) [double]
591-
Convert a C :c:type:`double` to a Python floating point number.
591+
Convert a C :c:expr:`double` to a Python floating point number.
592592
593593
``f`` (:class:`float`) [float]
594-
Convert a C :c:type:`float` to a Python floating point number.
594+
Convert a C :c:expr:`float` to a Python floating point number.
595595
596596
``D`` (:class:`complex`) [Py_complex \*]
597597
Convert a C :c:type:`Py_complex` structure to a Python complex number.
@@ -614,7 +614,7 @@ Building values
614614
615615
``O&`` (object) [*converter*, *anything*]
616616
Convert *anything* to a Python object through a *converter* function. The
617-
function is called with *anything* (which should be compatible with :c:type:`void*`)
617+
function is called with *anything* (which should be compatible with :c:expr:`void*`)
618618
as its argument and should return a "new" Python object, or ``NULL`` if an
619619
error occurred.
620620

Doc/c-api/capsule.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Refer to :ref:`using-capsules` for more information on using these objects.
1515
.. c:type:: PyCapsule
1616
1717
This subtype of :c:type:`PyObject` represents an opaque value, useful for C
18-
extension modules who need to pass an opaque value (as a :c:type:`void*`
18+
extension modules who need to pass an opaque value (as a :c:expr:`void*`
1919
pointer) through Python code to other C code. It is often used to make a C
2020
function pointer defined in one module available to other modules, so the
2121
regular import mechanism can be used to access C APIs defined in dynamically

Doc/c-api/complex.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -115,12 +115,12 @@ Complex Numbers as Python Objects
115115
116116
.. c:function:: double PyComplex_RealAsDouble(PyObject *op)
117117
118-
Return the real part of *op* as a C :c:type:`double`.
118+
Return the real part of *op* as a C :c:expr:`double`.
119119
120120
121121
.. c:function:: double PyComplex_ImagAsDouble(PyObject *op)
122122
123-
Return the imaginary part of *op* as a C :c:type:`double`.
123+
Return the imaginary part of *op* as a C :c:expr:`double`.
124124
125125
126126
.. c:function:: Py_complex PyComplex_AsCComplex(PyObject *op)

Doc/c-api/conversion.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ The following functions provide locale-independent string to number conversions.
4949
5050
.. c:function:: double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)
5151
52-
Convert a string ``s`` to a :c:type:`double`, raising a Python
52+
Convert a string ``s`` to a :c:expr:`double`, raising a Python
5353
exception on failure. The set of accepted strings corresponds to
5454
the set of strings accepted by Python's :func:`float` constructor,
5555
except that ``s`` must not have leading or trailing whitespace.
@@ -83,7 +83,7 @@ The following functions provide locale-independent string to number conversions.
8383
8484
.. c:function:: char* PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)
8585
86-
Convert a :c:type:`double` *val* to a string using supplied
86+
Convert a :c:expr:`double` *val* to a string using supplied
8787
*format_code*, *precision*, and *flags*.
8888
8989
*format_code* must be one of ``'e'``, ``'E'``, ``'f'``, ``'F'``,

Doc/c-api/dict.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ Dictionary Objects
7373
.. index:: single: PyUnicode_FromString()
7474
7575
Insert *val* into the dictionary *p* using *key* as a key. *key* should
76-
be a :c:type:`const char*`. The key object is created using
76+
be a :c:expr:`const char*`. The key object is created using
7777
``PyUnicode_FromString(key)``. Return ``0`` on success or ``-1`` on
7878
failure. This function *does not* steal a reference to *val*.
7979
@@ -118,7 +118,7 @@ Dictionary Objects
118118
.. c:function:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)
119119
120120
This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a
121-
:c:type:`const char*`, rather than a :c:expr:`PyObject*`.
121+
:c:expr:`const char*`, rather than a :c:expr:`PyObject*`.
122122
123123
Note that exceptions which occur while calling :meth:`__hash__` and
124124
:meth:`__eq__` methods and creating a temporary string object

Doc/c-api/file.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ the :mod:`io` APIs instead.
3838
3939
.. c:function:: int PyObject_AsFileDescriptor(PyObject *p)
4040
41-
Return the file descriptor associated with *p* as an :c:type:`int`. If the
41+
Return the file descriptor associated with *p* as an :c:expr:`int`. If the
4242
object is an integer, its value is returned. If not, the
4343
object's :meth:`~io.IOBase.fileno` method is called if it exists; the
4444
method must return an integer, which is returned as the file descriptor

Doc/c-api/float.rst

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ Floating Point Objects
4444
4545
.. c:function:: double PyFloat_AsDouble(PyObject *pyfloat)
4646
47-
Return a C :c:type:`double` representation of the contents of *pyfloat*. If
47+
Return a C :c:expr:`double` representation of the contents of *pyfloat*. If
4848
*pyfloat* is not a Python floating point object but has a :meth:`__float__`
4949
method, this method will first be called to convert *pyfloat* into a float.
5050
If ``__float__()`` is not defined then it falls back to :meth:`__index__`.
@@ -57,7 +57,7 @@ Floating Point Objects
5757
5858
.. c:function:: double PyFloat_AS_DOUBLE(PyObject *pyfloat)
5959
60-
Return a C :c:type:`double` representation of the contents of *pyfloat*, but
60+
Return a C :c:expr:`double` representation of the contents of *pyfloat*, but
6161
without error checking.
6262
6363
@@ -70,21 +70,21 @@ Floating Point Objects
7070
7171
.. c:function:: double PyFloat_GetMax()
7272
73-
Return the maximum representable finite float *DBL_MAX* as C :c:type:`double`.
73+
Return the maximum representable finite float *DBL_MAX* as C :c:expr:`double`.
7474
7575
7676
.. c:function:: double PyFloat_GetMin()
7777
78-
Return the minimum normalized positive float *DBL_MIN* as C :c:type:`double`.
78+
Return the minimum normalized positive float *DBL_MIN* as C :c:expr:`double`.
7979
8080
8181
Pack and Unpack functions
8282
=========================
8383
8484
The pack and unpack functions provide an efficient platform-independent way to
8585
store floating-point values as byte strings. The Pack routines produce a bytes
86-
string from a C :c:type:`double`, and the Unpack routines produce a C
87-
:c:type:`double` from such a bytes string. The suffix (2, 4 or 8) specifies the
86+
string from a C :c:expr:`double`, and the Unpack routines produce a C
87+
:c:expr:`double` from such a bytes string. The suffix (2, 4 or 8) specifies the
8888
number of bytes in the bytes string.
8989
9090
On platforms that appear to use IEEE 754 formats these functions work by
@@ -107,7 +107,7 @@ Pack functions
107107
--------------
108108
109109
The pack routines write 2, 4 or 8 bytes, starting at *p*. *le* is an
110-
:c:type:`int` argument, non-zero if you want the bytes string in little-endian
110+
:c:expr:`int` argument, non-zero if you want the bytes string in little-endian
111111
format (exponent last, at ``p+1``, ``p+3``, or ``p+6`` ``p+7``), zero if you
112112
want big-endian format (exponent first, at *p*). The :c:data:`PY_BIG_ENDIAN`
113113
constant can be used to use the native endian: it is equal to ``1`` on big
@@ -138,7 +138,7 @@ Unpack functions
138138
----------------
139139
140140
The unpack routines read 2, 4 or 8 bytes, starting at *p*. *le* is an
141-
:c:type:`int` argument, non-zero if the bytes string is in little-endian format
141+
:c:expr:`int` argument, non-zero if the bytes string is in little-endian format
142142
(exponent last, at ``p+1``, ``p+3`` or ``p+6`` and ``p+7``), zero if big-endian
143143
(exponent first, at *p*). The :c:data:`PY_BIG_ENDIAN` constant can be used to
144144
use the native endian: it is equal to ``1`` on big endian processor, or ``0``

0 commit comments

Comments
 (0)
0