[Python-checkins] gh-93738: Documentation C syntax (:c:type:`PyObject` -> :c:expr:`PyObject`) (#97776)
ambv
webhook-mailer at python.org
Tue Oct 4 19:13:11 EDT 2022
https://github.com/python/cpython/commit/0bf6a617ed1832bc4803e532c8d6b3427cf48b13
commit: 0bf6a617ed1832bc4803e532c8d6b3427cf48b13
branch: main
author: Adam Turner <9087854+AA-Turner at users.noreply.github.com>
committer: ambv <lukasz at langa.pl>
date: 2022-10-04T16:13:03-07:00
summary:
gh-93738: Documentation C syntax (:c:type:`PyObject` -> :c:expr:`PyObject`) (#97776)
:c:type:`PyObject` -> :c:expr:`PyObject`
files:
M Doc/c-api/arg.rst
M Doc/c-api/call.rst
M Doc/c-api/dict.rst
M Doc/c-api/exceptions.rst
M Doc/c-api/init.rst
M Doc/c-api/intro.rst
M Doc/c-api/structures.rst
M Doc/c-api/tuple.rst
M Doc/c-api/typeobj.rst
M Doc/library/ctypes.rst
diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst
index 2e63e4d4563d..c9dcf746ef2f 100644
--- a/Doc/c-api/arg.rst
+++ b/Doc/c-api/arg.rst
@@ -129,17 +129,17 @@ which disallows mutable objects such as :class:`bytearray`.
``S`` (:class:`bytes`) [PyBytesObject \*]
Requires that the Python object is a :class:`bytes` object, without
attempting any conversion. Raises :exc:`TypeError` if the object is not
- a bytes object. The C variable may also be declared as :c:type:`PyObject*`.
+ a bytes object. The C variable may also be declared as :c:expr:`PyObject*`.
``Y`` (:class:`bytearray`) [PyByteArrayObject \*]
Requires that the Python object is a :class:`bytearray` object, without
attempting any conversion. Raises :exc:`TypeError` if the object is not
- a :class:`bytearray` object. The C variable may also be declared as :c:type:`PyObject*`.
+ a :class:`bytearray` object. The C variable may also be declared as :c:expr:`PyObject*`.
``U`` (:class:`str`) [PyObject \*]
Requires that the Python object is a Unicode object, without attempting
any conversion. Raises :exc:`TypeError` if the object is not a Unicode
- object. The C variable may also be declared as :c:type:`PyObject*`.
+ object. The C variable may also be declared as :c:expr:`PyObject*`.
``w*`` (read-write :term:`bytes-like object`) [Py_buffer]
This format accepts any object which implements the read-write buffer
@@ -283,7 +283,7 @@ Other objects
``O!`` (object) [*typeobject*, PyObject \*]
Store a Python object in a C object pointer. This is similar to ``O``, but
takes two C arguments: the first is the address of a Python type object, the
- second is the address of the C variable (of type :c:type:`PyObject*`) into which
+ second is the address of the C variable (of type :c:expr:`PyObject*`) into which
the object pointer is stored. If the Python object does not have the required
type, :exc:`TypeError` is raised.
@@ -444,7 +444,7 @@ API Functions
*args*; it must actually be a tuple. The length of the tuple must be at least
*min* and no more than *max*; *min* and *max* may be equal. Additional
arguments must be passed to the function, each of which should be a pointer to a
- :c:type:`PyObject*` variable; these will be filled in with the values from
+ :c:expr:`PyObject*` variable; these will be filled in with the values from
*args*; they will contain :term:`borrowed references <borrowed reference>`.
The variables which correspond
to optional parameters not given by *args* will not be filled in; these should
diff --git a/Doc/c-api/call.rst b/Doc/c-api/call.rst
index 11d5c33a2d15..6fb2e1519610 100644
--- a/Doc/c-api/call.rst
+++ b/Doc/c-api/call.rst
@@ -284,7 +284,7 @@ please see individual documentation for details.
This is the equivalent of the Python expression: ``callable(*args)``.
- Note that if you only pass :c:type:`PyObject *` args,
+ Note that if you only pass :c:expr:`PyObject *` args,
:c:func:`PyObject_CallFunctionObjArgs` is a faster alternative.
.. versionchanged:: 3.4
@@ -305,7 +305,7 @@ please see individual documentation for details.
This is the equivalent of the Python expression:
``obj.name(arg1, arg2, ...)``.
- Note that if you only pass :c:type:`PyObject *` args,
+ Note that if you only pass :c:expr:`PyObject *` args,
:c:func:`PyObject_CallMethodObjArgs` is a faster alternative.
.. versionchanged:: 3.4
@@ -315,7 +315,7 @@ please see individual documentation for details.
.. c:function:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ...)
Call a callable Python object *callable*, with a variable number of
- :c:type:`PyObject *` arguments. The arguments are provided as a variable number
+ :c:expr:`PyObject *` arguments. The arguments are provided as a variable number
of parameters followed by *NULL*.
Return the result of the call on success, or raise an exception and return
@@ -329,7 +329,7 @@ please see individual documentation for details.
Call a method of the Python object *obj*, where the name of the method is given as a
Python string object in *name*. It is called with a variable number of
- :c:type:`PyObject *` arguments. The arguments are provided as a variable number
+ :c:expr:`PyObject *` arguments. The arguments are provided as a variable number
of parameters followed by *NULL*.
Return the result of the call on success, or raise an exception and return
diff --git a/Doc/c-api/dict.rst b/Doc/c-api/dict.rst
index d257c9b5f763..67c2026baa14 100644
--- a/Doc/c-api/dict.rst
+++ b/Doc/c-api/dict.rst
@@ -118,7 +118,7 @@ Dictionary Objects
.. c:function:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)
This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a
- :c:type:`const char*`, rather than a :c:type:`PyObject*`.
+ :c:type:`const char*`, rather than a :c:expr:`PyObject*`.
Note that exceptions which occur while calling :meth:`__hash__` and
:meth:`__eq__` methods and creating a temporary string object
@@ -167,7 +167,7 @@ Dictionary Objects
prior to the first call to this function to start the iteration; the
function returns true for each pair in the dictionary, and false once all
pairs have been reported. The parameters *pkey* and *pvalue* should either
- point to :c:type:`PyObject*` variables that will be filled in with each key
+ point to :c:expr:`PyObject*` variables that will be filled in with each key
and value, respectively, or may be ``NULL``. Any references returned through
them are borrowed. *ppos* should not be altered during iteration. Its
value represents offsets within the internal dictionary structure, and
diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst
index df73f23d2de2..7221957fe1db 100644
--- a/Doc/c-api/exceptions.rst
+++ b/Doc/c-api/exceptions.rst
@@ -848,7 +848,7 @@ Standard Exceptions
All standard Python exceptions are available as global variables whose names are
``PyExc_`` followed by the Python exception name. These have the type
-:c:type:`PyObject*`; they are all class objects. For completeness, here are all
+:c:expr:`PyObject*`; they are all class objects. For completeness, here are all
the variables:
.. index::
@@ -1068,7 +1068,7 @@ Standard Warning Categories
All standard Python warning categories are available as global variables whose
names are ``PyExc_`` followed by the Python exception name. These have the type
-:c:type:`PyObject*`; they are all class objects. For completeness, here are all
+:c:expr:`PyObject*`; they are all class objects. For completeness, here are all
the variables:
.. index::
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index ec3034893b90..cb3bfedc97e8 100644
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -1875,7 +1875,7 @@ you need to include :file:`pythread.h` to use thread-local storage.
.. note::
None of these API functions handle memory management on behalf of the
:c:type:`void*` values. You need to allocate and deallocate them yourself.
- If the :c:type:`void*` values happen to be :c:type:`PyObject*`, these
+ If the :c:type:`void*` values happen to be :c:expr:`PyObject*`, these
functions don't do refcount operations on them either.
.. _thread-specific-storage-api:
diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst
index 557ccfc05234..991bc3b09fd8 100644
--- a/Doc/c-api/intro.rst
+++ b/Doc/c-api/intro.rst
@@ -264,13 +264,13 @@ Objects, Types and Reference Counts
.. index:: object: type
Most Python/C API functions have one or more arguments as well as a return value
-of type :c:type:`PyObject*`. This type is a pointer to an opaque data type
+of type :c:expr:`PyObject*`. This type is a pointer to an opaque data type
representing an arbitrary Python object. Since all Python object types are
treated the same way by the Python language in most situations (e.g.,
assignments, scope rules, and argument passing), it is only fitting that they
should be represented by a single C type. Almost all Python objects live on the
heap: you never declare an automatic or static variable of type
-:c:type:`PyObject`, only pointer variables of type :c:type:`PyObject*` can be
+:c:type:`PyObject`, only pointer variables of type :c:expr:`PyObject*` can be
declared. The sole exception are the type objects; since these must never be
deallocated, they are typically static :c:type:`PyTypeObject` objects.
diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst
index f1eb09bb5691..1cc5c4647120 100644
--- a/Doc/c-api/structures.rst
+++ b/Doc/c-api/structures.rst
@@ -27,7 +27,7 @@ the definition of all other Python objects.
object. In a normal "release" build, it contains only the object's
reference count and a pointer to the corresponding type object.
Nothing is actually declared to be a :c:type:`PyObject`, but every pointer
- to a Python object can be cast to a :c:type:`PyObject*`. Access to the
+ to a Python object can be cast to a :c:expr:`PyObject*`. Access to the
members must be done by using the macros :c:macro:`Py_REFCNT` and
:c:macro:`Py_TYPE`.
@@ -184,7 +184,7 @@ Implementing functions and methods
.. c:type:: PyCFunction
Type of the functions used to implement most Python callables in C.
- Functions of this type take two :c:type:`PyObject*` parameters and return
+ Functions of this type take two :c:expr:`PyObject*` parameters and return
one such value. If the return value is ``NULL``, an exception shall have
been set. If not ``NULL``, the return value is interpreted as the return
value of the function as exposed in Python. The function must return a new
@@ -263,10 +263,10 @@ Implementing functions and methods
+------------------+---------------+-------------------------------+
The :attr:`ml_meth` is a C function pointer. The functions may be of different
-types, but they always return :c:type:`PyObject*`. If the function is not of
+types, but they always return :c:expr:`PyObject*`. If the function is not of
the :c:type:`PyCFunction`, the compiler will require a cast in the method table.
Even though :c:type:`PyCFunction` defines the first parameter as
-:c:type:`PyObject*`, it is common that the method implementation uses the
+:c:expr:`PyObject*`, it is common that the method implementation uses the
specific C type of the *self* object.
The :attr:`ml_flags` field is a bitfield which can include the following flags.
@@ -278,7 +278,7 @@ There are these calling conventions:
.. data:: METH_VARARGS
This is the typical calling convention, where the methods have the type
- :c:type:`PyCFunction`. The function expects two :c:type:`PyObject*` values.
+ :c:type:`PyCFunction`. The function expects two :c:expr:`PyObject*` values.
The first one is the *self* object for methods; for module functions, it is
the module object. The second parameter (often called *args*) is a tuple
object representing all arguments. This parameter is typically processed
@@ -299,7 +299,7 @@ There are these calling conventions:
Fast calling convention supporting only positional arguments.
The methods have the type :c:type:`_PyCFunctionFast`.
The first parameter is *self*, the second parameter is a C array
- of :c:type:`PyObject*` values indicating the arguments and the third
+ of :c:expr:`PyObject*` values indicating the arguments and the third
parameter is the number of arguments (the length of the array).
.. versionadded:: 3.7
@@ -315,7 +315,7 @@ There are these calling conventions:
with methods of type :c:type:`_PyCFunctionFastWithKeywords`.
Keyword arguments are passed the same way as in the
:ref:`vectorcall protocol <vectorcall>`:
- there is an additional fourth :c:type:`PyObject*` parameter
+ there is an additional fourth :c:expr:`PyObject*` parameter
which is a tuple representing the names of the keyword arguments
(which are guaranteed to be strings)
or possibly ``NULL`` if there are no keywords. The values of the keyword
@@ -354,7 +354,7 @@ There are these calling conventions:
Methods with a single object argument can be listed with the :const:`METH_O`
flag, instead of invoking :c:func:`PyArg_ParseTuple` with a ``"O"`` argument.
They have the type :c:type:`PyCFunction`, with the *self* parameter, and a
- :c:type:`PyObject*` parameter representing the single argument.
+ :c:expr:`PyObject*` parameter representing the single argument.
These two constants are not used to indicate the calling convention but the
@@ -522,7 +522,7 @@ Accessing attributes of extension types
| | | getter and setter |
+-------------+------------------+-----------------------------------+
- The ``get`` function takes one :c:type:`PyObject*` parameter (the
+ The ``get`` function takes one :c:expr:`PyObject*` parameter (the
instance) and a function pointer (the associated ``closure``)::
typedef PyObject *(*getter)(PyObject *, void *);
@@ -530,7 +530,7 @@ Accessing attributes of extension types
It should return a new reference on success or ``NULL`` with a set exception
on failure.
- ``set`` functions take two :c:type:`PyObject*` parameters (the instance and
+ ``set`` functions take two :c:expr:`PyObject*` parameters (the instance and
the value to be set) and a function pointer (the associated ``closure``)::
typedef int (*setter)(PyObject *, PyObject *, void *);
diff --git a/Doc/c-api/tuple.rst b/Doc/c-api/tuple.rst
index 9b85522600d4..0bfd4b308d93 100644
--- a/Doc/c-api/tuple.rst
+++ b/Doc/c-api/tuple.rst
@@ -161,7 +161,7 @@ type.
.. c:type:: PyStructSequence_Field
Describes a field of a struct sequence. As a struct sequence is modeled as a
- tuple, all fields are typed as :c:type:`PyObject*`. The index in the
+ tuple, all fields are typed as :c:expr:`PyObject*`. The index in the
:attr:`fields` array of the :c:type:`PyStructSequence_Desc` determines which
field of the struct sequence is described.
diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index 2439f7c41b56..32ecc111d9df 100644
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -1520,7 +1520,7 @@ and :c:type:`PyType_Type` effectively act as defaults.)
than zero and contains the offset in the instance structure of the weak
reference list head (ignoring the GC header, if present); this offset is used by
:c:func:`PyObject_ClearWeakRefs` and the :c:func:`PyWeakref_\*` functions. The
- instance structure needs to include a field of type :c:type:`PyObject*` which is
+ instance structure needs to include a field of type :c:expr:`PyObject*` which is
initialized to ``NULL``.
Do not confuse this field with :c:member:`~PyTypeObject.tp_weaklist`; that is the list head for
diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst
index 9546696e1c3d..685ff835346f 100644
--- a/Doc/library/ctypes.rst
+++ b/Doc/library/ctypes.rst
@@ -2387,8 +2387,8 @@ These are the fundamental ctypes data types:
.. class:: py_object
- Represents the C :c:type:`PyObject *` datatype. Calling this without an
- argument creates a ``NULL`` :c:type:`PyObject *` pointer.
+ Represents the C :c:expr:`PyObject *` datatype. Calling this without an
+ argument creates a ``NULL`` :c:expr:`PyObject *` pointer.
The :mod:`ctypes.wintypes` module provides quite some other Windows specific
data types, for example :c:type:`HWND`, :c:type:`WPARAM`, or :c:type:`DWORD`. Some
More information about the Python-checkins
mailing list