mirror of
https://github.com/python/cpython
synced 2024-10-14 16:59:44 +00:00
gh-93738: Documentation C syntax (:c:type:PyObject
-> :c:expr:PyObject
) (#97776)
:c:type:`PyObject` -> :c:expr:`PyObject`
This commit is contained in:
parent
4ebb025031
commit
0bf6a617ed
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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::
|
||||
|
|
|
@ -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:
|
||||
|
|
|
@ -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.
|
||||
|
||||
|
|
|
@ -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 *);
|
||||
|
|
|
@ -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.
|
||||
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Reference in a new issue