deimos.python.object

Mirror object.h

Object and type object interface

Objects are structures allocated on the heap. Special rules apply to the use of objects to ensure they are properly garbage-collected. Objects are never allocated statically or on the stack; they must be accessed through special macros and functions only. (Type objects are exceptions to the first rule; the standard types are represented by statically initialized type objects, although work on type/class unification for Python 2.2 made it possible to have heap-allocated type objects too).

An object has a 'reference count' that is increased or decreased when a pointer to the object is copied or deleted; when the reference count reaches zero there are no references to the object left and it can be removed from the heap.

An object has a 'type' that determines what it represents and what kind of data it contains. An object's type is fixed when it is created. Types themselves are represented as objects; an object contains a pointer to the corresponding type object. The type itself has a type pointer pointing to the object representing the type 'type', which contains a pointer to itself!).

Objects do not float around in memory; once allocated an object keeps the same size and address. Objects that must hold variable-size data can contain pointers to variable-size parts of the object. Not all objects of the same type have the same size; but the size cannot change after allocation. (These restrictions are made so a reference to an object can be simply a pointer -- moving an object would require updating all the pointers, and changing an object's size would require moving it if there was another object right next to it.)

Objects are always accessed through pointers of the type 'PyObject *'. The type 'PyObject' is a structure that only contains the reference count and the type pointer. The actual memory allocated for an object contains other data that can only be accessed after casting the pointer to a pointer to a longer structure type. This longer type must start with the reference count and type fields; the macro PyObject_HEAD should be used for this (to accommodate for future changes). The implementation of a particular object type can cast the object pointer to the proper type and back.

A standard interface exists for objects that contain an array of items whose size is determined when the object is allocated.

Members

Aliases

PyObject_Bytes alias PyObject_Bytes = PyObject_Str: Availability: 2.*
allocfunc alias allocfunc = PyObject* function(PyTypeObject*, Py_ssize_t): _
binaryfunc alias binaryfunc = PyObject* function(PyObject*, PyObject*): _
charbufferproc
alias charbufferproc = Py_ssize_t function(PyObject*, Py_ssize_t, char**): ssize_t-based buffer interface Availability: 2.*
cmpfunc alias cmpfunc = int function(PyObject*, PyObject*): Availability: 2.*
coercion
alias coercion = int function(PyObject**, PyObject**): Availability: 2.*
descrgetfunc alias descrgetfunc = PyObject* function(PyObject*, PyObject*, PyObject*): _
descrsetfunc alias descrsetfunc = int function(PyObject*, PyObject*, PyObject*): _
destructor alias destructor = void function(PyObject*): _
freefunc alias freefunc = void function(void*): _
getattrfunc alias getattrfunc = PyObject* function(PyObject*, char*): _
getattrofunc alias getattrofunc = PyObject* function(PyObject*, PyObject*): _
getbufferproc alias getbufferproc = int function(PyObject*, Py_buffer*, int): Availability: >= 2.6
getcharbufferproc alias getcharbufferproc = charbufferproc: int-based buffer interface Availability: 2.4
getiterfunc alias getiterfunc = PyObject* function(PyObject*): _
getreadbufferproc alias getreadbufferproc = readbufferproc
getsegcountproc alias getsegcountproc = segcountproc
getwritebufferproc alias getwritebufferproc = writebufferproc: int-based buffer interface Availability: 2.4
hashfunc alias hashfunc = Py_hash_t function(PyObject*): _
initproc alias initproc = int function(PyObject*, PyObject*, PyObject*): _
inquiry alias inquiry = lenfunc: _
intargfunc alias intargfunc = ssizeargfunc: Availability: 2.4
intintargfunc alias intintargfunc = ssizessizeargfunc: Availability: 2.4
intintobjargproc alias intintobjargproc = ssizessizeobjargproc: Availability: 2.4
intobjargproc alias intobjargproc = ssizeobjargproc: Availability: 2.4
iternextfunc alias iternextfunc = PyObject* function(PyObject*): _
lenfunc alias lenfunc = Py_ssize_t function(PyObject*): _
newfunc alias newfunc = PyObject* function(PyTypeObject*, PyObject*, PyObject*): _
objobjargproc alias objobjargproc = int function(PyObject*, PyObject*, PyObject*): _
objobjproc alias objobjproc = int function(PyObject*, PyObject*): _
printfunc alias printfunc = int function(PyObject*, FILE*, int): _
readbufferproc
alias readbufferproc = Py_ssize_t function(PyObject*, Py_ssize_t, void**): ssize_t-based buffer interface Availability: 2.*
releasebufferproc alias releasebufferproc = void function(PyObject*, Py_buffer*): Availability: >= 2.6
reprfunc alias reprfunc = PyObject* function(PyObject*): _
richcmpfunc alias richcmpfunc = PyObject* function(PyObject*, PyObject*, int): _
segcountproc alias segcountproc = Py_ssize_t function(PyObject*, Py_ssize_t*): ssize_t-based buffer interface Availability: 2.*
setattrfunc alias setattrfunc = int function(PyObject*, char*, PyObject*): _
setattrofunc alias setattrofunc = int function(PyObject*, PyObject*, PyObject*): _
ssizeargfunc alias ssizeargfunc = PyObject* function(PyObject*, Py_ssize_t): _
ssizeobjargproc alias ssizeobjargproc = int function(PyObject*, Py_ssize_t, PyObject*): _
ssizessizeargfunc alias ssizessizeargfunc = PyObject* function(PyObject*, Py_ssize_t, Py_ssize_t): _
ssizessizeobjargproc alias ssizessizeobjargproc = int function(PyObject*, Py_ssize_t, Py_ssize_t, PyObject*): _
ternaryfunc alias ternaryfunc = PyObject* function(PyObject*, PyObject*, PyObject*): _
traverseproc alias traverseproc = int function(PyObject*, visitproc, void*): _
unaryfunc alias unaryfunc = PyObject* function(PyObject*): _
visitproc alias visitproc = int function(PyObject*, void*): _
writebufferproc
alias writebufferproc = Py_ssize_t function(PyObject*, Py_ssize_t, void**): ssize_t-based buffer interface Availability: 2.*

Functions

PyCallable_Check int PyCallable_Check(PyObject*): _
PyNumber_Coerce
int PyNumber_Coerce(PyObject**, PyObject**): Availability: 2.*
PyNumber_CoerceEx
int PyNumber_CoerceEx(PyObject**, PyObject**): Availability: 2.*
PyObject_ASCII PyObject* PyObject_ASCII(PyObject*): Availability: 3.*
PyObject_Bytes PyObject* PyObject_Bytes(PyObject*): Availability: 3.*
PyObject_ClearWeakRefs void PyObject_ClearWeakRefs(PyObject*): _
PyObject_Compare int PyObject_Compare(PyObject*, PyObject*): Availability: 2.*
PyObject_Dir PyObject* PyObject_Dir(PyObject*): PyObject_Dir(obj) acts like Python __builtin__.dir(obj), returning a list of strings. PyObject_Dir(NULL) is like __builtin__.dir(), returning the names of the current locals. In this case, if there are no current locals, NULL is returned, and PyErr_Occurred() is false.
PyObject_GenericGetAttr PyObject* PyObject_GenericGetAttr(PyObject*, PyObject*): _
PyObject_GenericSetAttr int PyObject_GenericSetAttr(PyObject*, PyObject*, PyObject*): _
PyObject_GetAttr PyObject* PyObject_GetAttr(PyObject*, PyObject*): _
PyObject_GetAttrString PyObject* PyObject_GetAttrString(PyObject*, const(char)*): _
PyObject_HasAttr int PyObject_HasAttr(PyObject*, PyObject*): _
PyObject_HasAttrString int PyObject_HasAttrString(PyObject*, const(char)*): _
PyObject_Hash Py_hash_t PyObject_Hash(PyObject*): _
PyObject_HashNotImplemented Py_hash_t PyObject_HashNotImplemented(PyObject*): Availability: >= 2.6
PyObject_IsTrue int PyObject_IsTrue(PyObject*): _
PyObject_Not int PyObject_Not(PyObject*): _
PyObject_Print int PyObject_Print(PyObject*, FILE*, int): _
PyObject_REPR auto PyObject_REPR(PyObject* obj): _
PyObject_Repr PyObject* PyObject_Repr(PyObject*): _
PyObject_RichCompare PyObject* PyObject_RichCompare(PyObject*, PyObject*, int): _
PyObject_RichCompareBool int PyObject_RichCompareBool(PyObject*, PyObject*, int): _
PyObject_SelfIter PyObject* PyObject_SelfIter(PyObject*): _
PyObject_SetAttr int PyObject_SetAttr(PyObject*, PyObject*, PyObject*): _
PyObject_SetAttrString int PyObject_SetAttrString(PyObject*, const(char)*, PyObject*): _
PyObject_Str PyObject* PyObject_Str(PyObject*): _
PyObject_TypeCheck int PyObject_TypeCheck(PyObject* ob, PyTypeObject* tp): _
PyObject_Unicode PyObject* PyObject_Unicode(PyObject*): Availability: 2.*
PyType_Check int PyType_Check(PyObject* op): _
PyType_CheckExact int PyType_CheckExact(PyObject* op): _
PyType_ClearCache uint PyType_ClearCache(): Availability: >= 2.6
PyType_FromSpec PyObject* PyType_FromSpec(PyType_Spec*): Availability: 3.*
PyType_GenericAlloc PyObject* PyType_GenericAlloc(PyTypeObject*, Py_ssize_t): _
PyType_GenericNew PyObject* PyType_GenericNew(PyTypeObject*, PyObject*, PyObject*): _
PyType_GetFlags C_long PyType_GetFlags(PyTypeObject*): Availability: >= 3.2
PyType_HasFeature int PyType_HasFeature(PyTypeObject* t, int f): _
PyType_IsSubtype int PyType_IsSubtype(PyTypeObject*, PyTypeObject*): Generic type check
PyType_Modified void PyType_Modified(PyTypeObject*): Availability: >= 2.6
PyType_Ready int PyType_Ready(PyTypeObject*): _
Py_DECREF void Py_DECREF(PyObject* op): Used to decrement reference counts. Calls the object's deallocator function when the refcount falls to 0; for objects that don't contain references to other objects or heap memory this can be the standard function free(). Can be used wherever a void expression is allowed. The argument must not be a NULL pointer. If it may be NULL, use Py_XDECREF instead.
Py_DecRef void Py_DecRef(PyObject*): These are provided as conveniences to Python runtime embedders, so that they can have object code that is not dependent on Python compilation flags.
Py_INCREF auto Py_INCREF(T op): Increment reference counts. Can be used wherever a void expression is allowed. The argument must not be a NULL pointer. If it may be NULL, use Py_XINCREF instead.
Py_IncRef void Py_IncRef(PyObject*): These are provided as conveniences to Python runtime embedders, so that they can have object code that is not dependent on Python compilation flags.
Py_REFCNT auto Py_REFCNT(T* ob): _
Py_ReprEnter int Py_ReprEnter(PyObject*)
Py_ReprLeave void Py_ReprLeave(PyObject*): Helpers for printing recursive container types
Py_SET_REFCNT void Py_SET_REFCNT(T* ob, int refcnt)
Py_SET_SIZE void Py_SET_SIZE(T* ob, Py_ssize_t size)
Py_SET_TYPE void Py_SET_TYPE(T* ob, PyTypeObject* tipo): Not part of the python api, but annoying to do without.
Py_SIZE auto Py_SIZE(T* ob): _
Py_TYPE auto Py_TYPE(T* ob): _
Py_XDECREF void Py_XDECREF(PyObject* op): Same as Py_DECREF, except is a no-op if op is null.
Py_XINCREF auto Py_XINCREF(T op): Increment reference counts. Can be used wherever a void expression is allowed. The argument may be a NULL pointer.
_PyObject_LookupSpecial
PyObject* _PyObject_LookupSpecial(PyObject*, char*, PyObject**): Availability: >= 2.7
_PyObject_Str PyObject* _PyObject_Str(PyObject*): Availability: 2.5, 2.6, 2.7
_PyType_CalculateMetaclass PyTypeObject* _PyType_CalculateMetaclass(PyTypeObject*, PyObject*): Availability: 3.*
_PyType_Lookup PyObject* _PyType_Lookup(PyTypeObject*, PyObject*): _
_Py_BreakPoint void _Py_BreakPoint(): Availability: 3.*
_Py_Dealloc void _Py_Dealloc(PyObject*): Availability: 3.*
_Py_HashDouble Py_hash_t _Py_HashDouble(double): _
_Py_HashPointer Py_hash_t _Py_HashPointer(void*): _
_Py_NewReference void _Py_NewReference(PyObject* op): Initializes reference counts to 1, and in special builds (Py_REF_DEBUG, Py_TRACE_REFS) performs additional bookkeeping appropriate to the special build.
borrowed Borrowed!T* borrowed(T* obj): Convert a python reference to borrowed reference. (Not part of Python api)

Manifest constants

PyBUF_ANY_CONTIGUOUS enum PyBUF_ANY_CONTIGUOUS;
PyBUF_CONTIG enum PyBUF_CONTIG;
PyBUF_CONTIG_RO enum PyBUF_CONTIG_RO;
PyBUF_C_CONTIGUOUS enum PyBUF_C_CONTIGUOUS;
PyBUF_FORMAT enum PyBUF_FORMAT;
PyBUF_FULL enum PyBUF_FULL;
PyBUF_FULL_RO enum PyBUF_FULL_RO;
PyBUF_F_CONTIGUOUS enum PyBUF_F_CONTIGUOUS;
PyBUF_INDIRECT enum PyBUF_INDIRECT;
PyBUF_ND enum PyBUF_ND;
PyBUF_READ enum PyBUF_READ;
PyBUF_RECORDS enum PyBUF_RECORDS;
PyBUF_RECORDS_RO enum PyBUF_RECORDS_RO;
PyBUF_SHADOW enum PyBUF_SHADOW;: Flags for getting buffers */ /// Availability: >= 2.
PyBUF_SIMPLE enum PyBUF_SIMPLE;
PyBUF_STRIDED enum PyBUF_STRIDED;
PyBUF_STRIDED_RO enum PyBUF_STRIDED_RO;
PyBUF_STRIDES enum PyBUF_STRIDES;
PyBUF_WRITABLE enum PyBUF_WRITABLE;
PyBUF_WRITE enum PyBUF_WRITE;
PyBUF_WRITEABLE enum PyBUF_WRITEABLE;: Flags for getting buffers */ /// Availability: >= 2.
Py_EQ enum Py_EQ;
Py_GE enum Py_GE;
Py_GT enum Py_GT;
Py_LE enum Py_LE;: Rich comparison opcodes
Py_LT enum Py_LT;
Py_NE enum Py_NE;: Rich comparison opcodes
Py_TPFLAGS_BASE_EXC_SUBCLASS enum Py_TPFLAGS_BASE_EXC_SUBCLASS;
Py_TPFLAGS_BYTES_SUBCLASS enum Py_TPFLAGS_BYTES_SUBCLASS;: These flags are used to determine if a type is a subclass. */ /// Availability: >= 2.
Py_TPFLAGS_DEFAULT enum Py_TPFLAGS_DEFAULT;: _
Py_TPFLAGS_DEFAULT enum Py_TPFLAGS_DEFAULT;: _
Py_TPFLAGS_DICT_SUBCLASS enum Py_TPFLAGS_DICT_SUBCLASS;: These flags are used to determine if a type is a subclass. */ /// Availability: >= 2.
Py_TPFLAGS_HAVE_INDEX enum Py_TPFLAGS_HAVE_INDEX;: Objects support nb_index in PyNumberMethods */ /// Availability: 2.
Py_TPFLAGS_HAVE_NEWBUFFER enum Py_TPFLAGS_HAVE_NEWBUFFER;: Has the new buffer protocol */ /// Availability: 2.6,2.
Py_TPFLAGS_HAVE_VERSION_TAG enum Py_TPFLAGS_HAVE_VERSION_TAG;: Objects support type attribute cache */ /// Availability: >= 2.
Py_TPFLAGS_INT_SUBCLASS enum Py_TPFLAGS_INT_SUBCLASS;: These flags are used to determine if a type is a subclass. */ /// Availability: >= 2.
Py_TPFLAGS_IS_ABSTRACT enum Py_TPFLAGS_IS_ABSTRACT;: Type is abstract and cannot be instantiated */ /// Availability: >= 2.
Py_TPFLAGS_LIST_SUBCLASS enum Py_TPFLAGS_LIST_SUBCLASS;
Py_TPFLAGS_LONG_SUBCLASS enum Py_TPFLAGS_LONG_SUBCLASS;
Py_TPFLAGS_TUPLE_SUBCLASS enum Py_TPFLAGS_TUPLE_SUBCLASS;
Py_TPFLAGS_TYPE_SUBCLASS enum Py_TPFLAGS_TYPE_SUBCLASS;
Py_TPFLAGS_UNICODE_SUBCLASS enum Py_TPFLAGS_UNICODE_SUBCLASS;: These flags are used to determine if a type is a subclass. */ /// Availability: >= 2.
Py_TPFLAGS_VALID_VERSION_TAG enum Py_TPFLAGS_VALID_VERSION_TAG;: Objects support type attribute cache */ /// Availability: >= 2.

Mixin templates

PyObject_HEAD mixin template PyObject_HEAD(): _
PyObject_HEAD mixin template PyObject_HEAD(): _
PyObject_VAR_HEAD mixin template PyObject_VAR_HEAD(): PyObject_VAR_HEAD defines the initial segment of all variable-size container objects. These end with a declaration of an array with 1 element, but enough space is malloc'ed so that the array actually has room for ob_size elements. Note that ob_size is an element count, not necessarily a byte count.
PyObject_VAR_HEAD mixin template PyObject_VAR_HEAD(): _

Structs

Borrowed struct Borrowed(T): Denotes a borrowed reference. (Not part of Python api)
PyAsyncMethods struct PyAsyncMethods: _
PyBufferProcs struct PyBufferProcs: _
PyHeapTypeObject struct PyHeapTypeObject: The *real* layout of a type object when allocated on the heap
PyMappingMethods struct PyMappingMethods: _
PyNumberMethods struct PyNumberMethods: For numbers without flag bit Py_TPFLAGS_CHECKTYPES set, all arguments are guaranteed to be of the object's type (modulo coercion hacks -- i.e. if the type's coercion function returns other types, then these are allowed as well). Numbers that have the Py_TPFLAGS_CHECKTYPES flag bit set should check *both* arguments for proper type and implement the necessary conversions in the slot functions themselves.
PyObject struct PyObject: Nothing is actually declared to be a PyObject, but every pointer to a Python object can be cast to a PyObject*. This is inheritance built by hand. Similarly every pointer to a variable-size Python object can, in addition, be cast to PyVarObject*.
PySequenceMethods struct PySequenceMethods: _
PyTypeObject struct PyTypeObject: Type objects contain a string containing the type name (to help somewhat in debugging), the allocation parameters (see PyObject_New() and PyObject_NewVar()), and methods for accessing objects of the type. Methods are optional, a nil pointer meaning that particular kind of access is not available for this type. The Py_DECREF() macro uses the tp_dealloc method without checking for a nil pointer; it should always be implemented except if the implementation can guarantee that the reference count will never reach zero (e.g., for statically allocated type objects).
PyType_Slot struct PyType_Slot: Availability: 3.*
PyType_Spec struct PyType_Spec: Availability: 3.*
PyVarObject struct PyVarObject: _
Py_buffer struct Py_buffer: Py3k buffer interface */ /// Availability: >= 2.
_Py_HashSecret_t struct _Py_HashSecret_t: Availability: 2.7, >= 3.1

Templates

_PyObject_HEAD_EXTRA template _PyObject_HEAD_EXTRA(): _

Variables

Py_PRINT_RAW enum int Py_PRINT_RAW;: _
Py_TPFLAGS_BASETYPE enum int Py_TPFLAGS_BASETYPE;: Set if the type allows subclassing
Py_TPFLAGS_CHECKTYPES enum int Py_TPFLAGS_CHECKTYPES;: PyNumberMethods do their own coercion */ /// Availability: 2.
Py_TPFLAGS_DEFAULT enum int Py_TPFLAGS_DEFAULT;: _
Py_TPFLAGS_GC enum int Py_TPFLAGS_GC;: This is here for backwards compatibility. Extensions that use the old GC API will still compile but the objects will not be tracked by the GC. */ /// Availability: 2.
Py_TPFLAGS_HAVE_CLASS enum int Py_TPFLAGS_HAVE_CLASS;: New members introduced by Python 2.2 exist */ /// Availability: 2.
Py_TPFLAGS_HAVE_GC enum int Py_TPFLAGS_HAVE_GC;: Objects support garbage collection (see objimp.h)
Py_TPFLAGS_HAVE_GETCHARBUFFER enum int Py_TPFLAGS_HAVE_GETCHARBUFFER;: PyBufferProcs contains bf_getcharbuffer */ /// Availability: 2.
Py_TPFLAGS_HAVE_INPLACEOPS enum int Py_TPFLAGS_HAVE_INPLACEOPS;: PySequenceMethods and PyNumberMethods contain in-place operators */ /// Availability: 2.
Py_TPFLAGS_HAVE_ITER enum int Py_TPFLAGS_HAVE_ITER;: tp_iter is defined */ /// Availability: 2.
Py_TPFLAGS_HAVE_RICHCOMPARE enum int Py_TPFLAGS_HAVE_RICHCOMPARE;: tp_richcompare is defined */ /// Availability: 2.
Py_TPFLAGS_HAVE_SEQUENCE_IN enum int Py_TPFLAGS_HAVE_SEQUENCE_IN;: PySequenceMethods contains sq_contains */ /// Availability: 2.
Py_TPFLAGS_HAVE_STACKLESS_EXTENSION enum int Py_TPFLAGS_HAVE_STACKLESS_EXTENSION;: _
Py_TPFLAGS_HAVE_WEAKREFS enum int Py_TPFLAGS_HAVE_WEAKREFS;: Objects which are weakly referencable if their tp_weaklistoffset is >0 */ /// Availability: 2.
Py_TPFLAGS_HEAPTYPE enum int Py_TPFLAGS_HEAPTYPE;: Set if the type object is dynamically allocated
Py_TPFLAGS_READY enum int Py_TPFLAGS_READY;: Set if the type is 'ready' -- fully initialized
Py_TPFLAGS_READYING enum int Py_TPFLAGS_READYING;: Set while the type is being 'readied', to prevent recursive ready calls