``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`) [const Py_UNICODE \*]
Convert a Python Unicode object to a C pointer to a NUL-terminated buffer of
``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
``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.
*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
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
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
.. 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
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
.. 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:expr:`const char*`, rather than a :c:expr:`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
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
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::
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::
.. note::
None of these API functions handle memory management on behalf of the
- :c:expr:`void*` values. You need to allocate and deallocate them yourself.
- If the :c:expr:`void*` values happen to be :c:expr:`PyObject*`, these
+ :c:type:`void*` values. You need to allocate and deallocate them yourself.
+ 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:
.. 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.
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`.
.. 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
+------------------+---------------+-------------------------------+
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.
.. 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
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
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
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
| | | 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 *);
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 *);
.. 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.
If the instances of this type are weakly referenceable, this field is greater
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 ``PyWeakref_*`` functions. The
+ :c:func:`PyObject_ClearWeakRefs` and the :c:func:`PyWeakref_\*` functions. The
instance structure needs to include a field of type :c:expr:`PyObject*` which is
initialized to ``NULL``.
.. 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
projects / thirdparty / Python / cpython.git / commitdiff
