8000 [3.11] gh-93738: Documentation C syntax (:c:type:`PyObject` -> :c:exp… · python/cpython@800c9c0 · GitHub
[go: up one dir, main page]
Skip to content

Commit 800c9c0

Browse files
miss-islingtonAA-Turner
authored and
pablogsal
committed
[3.11] gh-93738: Documentation C syntax (:c:type:PyObject -> :c:expr:PyObject) (GH-97776) (#97889)
:c:type:`PyObject` -> :c:expr:`PyObject` (cherry picked from commit 0bf6a61) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
1 parent e2f7642 commit 800c9c0

File tree

10 files changed

+31
-31
lines changed

10 files changed

+31
-31
lines changed

‎Doc/c-api/arg.rst

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -129,12 +129,12 @@ which disallows mutable objects such as :class:`bytearray`.
129129
``S`` (:class:`bytes`) [PyBytesObject \*]
130130
Requires that the Python object is a :class 9E19 :`bytes` object, without
131131
attempting any conversion. Raises :exc:`TypeError` if the object is not
132-
a bytes object. The C variable may also be declared as :c:type:`PyObject*`.
132+
a bytes object. The C variable may also be declared as :c:expr:`PyObject*`.
133133

134134
``Y`` (:class:`bytearray`) [PyByteArrayObject \*]
135135
Requires that the Python object is a :class:`bytearray` object, without
136136
attempting any conversion. Raises :exc:`TypeError` if the object is not
137-
a :class:`bytearray` object. The C variable may also be declared as :c:type:`PyObject*`.
137+
a :class:`bytearray` object. The C variable may also be declared as :c:expr:`PyObject*`.
138138

139139
``u`` (:class:`str`) [const Py_UNICODE \*]
140140
Convert a Python Unicode object to a C pointer to a NUL-terminated buffer of
@@ -181,7 +181,7 @@ which disallows mutable objects such as :class:`bytearray`.
181181
``U`` (:class:`str`) [PyObject \*]
182182
Requires that the Python object is a Unicode object, without attempting
183183
any conversion. Raises :exc:`TypeError` if the object is not a Unicode
184-
object. The C variable may also be declared as :c:type:`PyObject*`.
184+
object. The C variable may also be declared as :c:expr:`PyObject*`.
185185

186186
``w*`` (read-write :term:`bytes-like object`) [Py_buffer]
187187
This format accepts any object which implements the read-write buffer
@@ -320,7 +320,7 @@ Other objects
320320
``O!`` (object) [*typeobject*, PyObject \*]
321321
Store a Python object in a C object pointer. This is similar to ``O``, but
322322
takes two C arguments: the first is the address of a Python type object, the
323-
second is the address of the C variable (of type :c:type:`PyObject*`) into which
323+
second is the address of the C variable (of type :c:expr:`PyObject*`) into which
324324
the object pointer is stored. If the Python object does not have the required
325325
type, :exc:`TypeError` is raised.
326326

@@ -481,7 +481,7 @@ API Functions
481481
*args*; it must actually be a tuple. The length of the tuple must be at least
482482
*min* and no more than *max*; *min* and *max* may be equal. Additional
483483
arguments must be passed to the function, each of which should be a pointer to a
484-
:c:type:`PyObject*` variable; these will be filled in with the values from
484+
:c:expr:`PyObject*` variable; these will be filled in with the values from
485485
*args*; they will contain :term:`borrowed references <borrowed reference>`.
486486
The variables which correspond
487487
to optional parameters not given by *args* will not be filled in; these should

‎Doc/c-api/call.rst

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -275,7 +275,7 @@ please see individual documentation for details.
275275
276276
This is the equivalent of the Python expression: ``callable(*args)``.
277277
278-
Note that if you only pass :c:type:`PyObject *` args,
278+
Note that if you only pass :c:expr:`PyObject *` args,
279279
:c:func:`PyObject_CallFunctionObjArgs` is a faster alternative.
280280
281281
.. versionchanged:: 3.4
@@ -296,7 +296,7 @@ please see individual documentation for details.
296296
This is the equivalent of the Python expression:
297297
``obj.name(arg1, arg2, ...)``.
298298
299-
Note that if you only pass :c:type:`PyObject *` args,
299+
Note that if you only pass :c:expr:`PyObject *` args,
300300
:c:func:`PyObject_CallMethodObjArgs` is a faster alternative.
301301
302302
.. versionchanged:: 3.4
@@ -306,7 +306,7 @@ please see individual documentation for details.
306306
.. c:function:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ...)
307307
308308
Call a callable Python object *callable*, with a variable number of
309-
:c:type:`PyObject *` arguments. The arguments are provided as a variable number
309+
:c:expr:`PyObject *` arguments. The arguments are provided as a variable number
310310
of parameters followed by *NULL*.
311311
312312
Return the result of the call on success, or raise an exception and return
@@ -320,7 +320,7 @@ please see individual documentation for details.
320320
321321
Call a method of the Python object *obj*, where the name of the method is given as a
322322
Python string object in *name*. It is called with a variable number of
323-
:c:type:`PyObject *` arguments. The arguments are provided as a variable number
323+
:c:expr:`PyObject *` arguments. The arguments are provided as a variable number
324324
of parameters followed by *NULL*.
325325
326326
Return the result of the call on success, or raise an exception and return

‎Doc/c-api/dict.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -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:expr:`const char*`, rather than a :c:expr:`PyObject*`.
121+
:c:type:`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
@@ -167,7 +167,7 @@ Dictionary Objects
167167
prior to the first call to this function to start the iteration; the
168168
function returns true for each pair in the dictionary, and false once all
169169
pairs have been reported. The parameters *pkey* and *pvalue* should either
170-
point to :c:type:`PyObject*` variables that will be filled in with each key
170+
point to :c:expr:`PyObject*` variables that will be filled in with each key
171171
and value, respectively, or may be ``NULL``. Any references returned through
172172
them are borrowed. *ppos* should not be altered during iteration. Its
173173
value represents offsets within the internal dictionary structure, and

‎Doc/c-api/exceptions.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -848,7 +848,7 @@ Standard Exceptions
848848
849849
All standard Python exceptions are available as global variables whose names are
850850
``PyExc_`` followed by the Python exception name. These have the type
851-
:c:type:`PyObject*`; they are all class objects. For completeness, here are all
851+
:c:expr:`PyObject*`; they are all class objects. For completeness, here are all
852852
the variables:
853853
854854
.. index::
@@ -1068,7 +1068,7 @@ Standard Warning Categories
10681068
10691069
All standard Python warning categories are available as global variables whose
10701070
names are ``PyExc_`` followed by the Python exception name. These have the type
1071-
:c:type:`PyObject*`; they are all class objects. For completeness, here are all
1071+
:c:expr:`PyObject*`; they are all class objects. For completeness, here are all
10721072
the variables:
10731073
10741074
.. index::

‎Doc/c-api/init.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1741,8 +1741,8 @@ you need to include :file:`pythread.h` to use thread-local storage.
17411741
17421742
.. note::
17431743
None of these API functions handle memory management on behalf of the
1744-
:c:expr:`void*` values. You need to allocate and deallocate them yourself.
1745-
If the :c:expr:`void*` values happen to be :c:expr:`PyObject*`, these
1744+
:c:type:`void*` values. You need to allocate and deallocate them yourself.
1745+
If the :c:type:`void*` values happen to be :c:expr:`PyObject*`, these
17461746
functions don't do refcount operations on them either.
17471747
17481748
.. _thread-specific-storage-api:

‎Doc/c-api/intro.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -264,13 +264,13 @@ Objects, Types and Reference Counts
264264
.. index:: object: type
265265

266266
Most Python/C API functions have one or more arguments as well as a return value
267-
of type :c:type:`PyObject*`. This type is a pointer to an opaque data type
267+
of type :c:expr:`PyObject*`. This type is a pointer to an opaque data type
268268
representing an arbitrary Python object. Since all Python object types are
269269
treated the same way by the Python language in most situations (e.g.,
270270
assignments, scope rules, and argument passing), it is only fitting that they
271271
should be represented by a single C type. Almost all Python objects live on the
272272
heap: you never declare an automatic or static variable of type
273-
:c:type:`PyObject`, only pointer variables of type :c:type:`PyObject*` can be
273+
:c:type:`PyObject`, only pointer variables of type :c:expr:`PyObject*` can be
274274
declared. The sole exception are the type objects; since these must never be
275275
deallocated, they are typically static :c:type:`PyTypeObject` objects.
276276

‎Doc/c-api/structures.rst

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ the definition of all other Python objects.
2727
object. In a normal "release" build, it contains only the object's
2828
reference count and a pointer to the corresponding type object.
2929
Nothing is actually declared to be a :c:type:`PyObject`, but every pointer
30-
to a Python object can be cast to a :c:type:`PyObject*`. Access to the
30+
to a Python object can be cast to a :c:expr:`PyObject*`. Access to the
3131
members must be done by using the macros :c:macro:`Py_REFCNT` and
3232
:c:macro:`Py_TYPE`.
3333

@@ -184,7 +184,7 @@ Implementing functions and methods
184184
.. c:type:: PyCFunction
185185
186186
Type of the functions used to implement most Python callables in C.
187-
Functions of this type take two :c:type:`PyObject*` parameters and return
187+
Functions of this type take two :c:expr:`PyObject*` parameters and return
188188
one such value. If the return value is ``NULL``, an exception shall have
189189
been set. If not ``NULL``, the return value is interpreted as the return
190190
value of the function as exposed in Python. The function must return a new
@@ -263,10 +263,10 @@ Implementing functions and methods
263263
+------------------+---------------+-------------------------------+
264264
265265
The :attr:`ml_meth` is a C function pointer. The functions may be of different
266-
types, but they always return :c:type:`PyObject*`. If the function is not of
266+
types, but they always return :c:expr:`PyObject*`. If the function is not of
267267
the :c:type:`PyCFunction`, the compiler will require a cast in the method table.
268268
Even though :c:type:`PyCFunction` defines the first parameter as
269-
:c:type:`PyObject*`, it is common that the method implementation uses the
269+
:c:expr:`PyObject*`, it is common that the method implementation uses the
270270
specific C type of the *self* object.
271271
272272
The :attr:`ml_flags` field is a bitfield which can include the following flags.
@@ -278,7 +278,7 @@ There are these calling conventions:
278278
.. data:: METH_VARARGS
279279
280280
This is the typical calling convention, where the methods have the type
281-
:c:type:`PyCFunction`. The function expects two :c:type:`PyObject*` values.
281+
:c:type:`PyCFunction`. The function expects two :c:expr:`PyObject*` values.
282282
The first one is the *self* object for methods; for module functions, it is
283283
the module object. The second parameter (often called *args*) is a tuple
284284
object representing all arguments. This parameter is typically processed
@@ -299,7 +299,7 @@ There are these calling conventions:
299299
Fast calling convention supporting only positional arguments.
300300
The methods have the type :c:type:`_PyCFunctionFast`.
301301
The first parameter is *self*, the second parameter is a C array
302-
of :c:type:`PyObject*` values indicating the arguments and the third
302+
of :c:expr:`PyObject*` values indicating the arguments and the third
303303
parameter is the number of arguments (the length of the array).
304304
305305
.. versionadded:: 3.7
@@ -315,7 +315,7 @@ There are these calling conventions:
315315
with methods of type :c:type:`_PyCFunctionFastWithKeywords`.
316316
Keyword arguments are passed the same way as in the
317317
:ref:`vectorcall protocol <vectorcall>`:
318-
there is an additional fourth :c:type:`PyObject*` parameter
318+
there is an additional fourth :c:expr:`PyObject*` parameter
319319
which is a tuple representing the names of the keyword arguments
320320
(which are guaranteed to be strings)
321321
or possibly ``NULL`` if there are no keywords. The values of the keyword
@@ -354,7 +354,7 @@ There are these calling conventions:
354354
Methods with a single object argument can be listed with the :const:`METH_O`
355355
flag, instead of invoking :c:func:`PyArg_ParseTuple` with a ``"O"`` argument.
356356
They have the type :c:type:`PyCFunction`, with the *self* parameter, and a
357-
:c:type:`PyObject*` parameter representing the single argument.
357+
:c:expr:`PyObject*` parameter representing the single argument.
358358
359359
360360
These two constants are not used to indicate the calling convention but the
@@ -520,15 +520,15 @@ Accessing attributes of extension types
520520
| | | getter and setter |
521521
+-------------+------------------+-----------------------------------+
522522
523-
The ``get`` function takes one :c:type:`PyObject*` parameter (the
523+
The ``get`` function takes one :c:expr:`PyObject*` parameter (the
524524
instance) and a function pointer (the associated ``closure``)::
525525
526526
typedef PyObject *(*getter)(PyObject *, void *);
527527
528528
It should return a new reference on success or ``NULL`` with a set exception
529529
on failure.
530530
531-
``set`` functions take two :c:type:`PyObject*` parameters (the instance and
531+
``set`` functions take two :c:expr:`PyObject*` parameters (the instance and
532532
the value to be set) and a function pointer (the associated ``closure``)::
533533
534534
typedef int (*setter)(PyObject *, PyObject *, void *);

‎Doc/c-api/tuple.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -161,7 +161,7 @@ type.
161161
.. c:type:: PyStructSequence_Field
162162
163163
Describes a field of a struct sequence. As a struct sequence is modeled as a
164-
tuple, all fields are typed as :c:type:`PyObject*`. The index in the
164+
tuple, all fields are typed as :c:expr:`PyObject*`. The index in the
165165
:attr:`fields` array of the :c:type:`PyStructSequence_Desc` determines which
166166
field of the struct sequence is described.
167167

‎Doc/c-api/typeobj.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1484,7 +1484,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
14841484
If the instances of this type are weakly referenceable, this field is greater
14851485
than zero and contains the offset in the instance structure of the weak
14861486
reference list head (ignoring the GC header, if present); this offset is used by
1487-
:c:func:`PyObject_ClearWeakRefs` and the ``PyWeakref_*`` functions. The
1487+
:c:func:`PyObject_ClearWeakRefs` and the :c:func:`PyWeakref_\*` functions. The
14881488
instance structure needs to include a field of type :c:expr:`PyObject*` which is
14891489
initialized to ``NULL``.
14901490

‎Doc/library/ctypes.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2366,8 +2366,8 @@ These are the fundamental ctypes data types:
23662366

23672367
.. class:: py_object
23682368

2369-
Represents the C :c:type:`PyObject *` datatype. Calling this without an
2370-
argument creates a ``NULL`` :c:type:`PyObject *` pointer.
2369+
Represents the C :c:expr:`PyObject *` datatype. Calling this without an
2370+
argument creates a ``NULL`` :c:expr:`PyObject *` pointer.
23712371

23722372
The :mod:`ctypes.wintypes` module provides quite some other Windows specific
23732373
data types, for example :c:type:`HWND`, :c:type:`WPARAM`, or :c:type:`DWORD`. Some

0 commit comments

Comments
 (0)
0