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_BorrowedRef
alias PyObject_BorrowedRef = Borrowed!PyObject
Undocumented in source but is binding to C. You might be able to learn more by searching the web for its name.
PyObject_Bytes
alias PyObject_Bytes = PyObject_Str

Availability: 2.*

PyType_FastSubclass
alias PyType_FastSubclass = PyType_HasFeature
Undocumented in source but is binding to C. You might be able to learn more by searching the web for its name.
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_None
Borrowed!PyObject* Py_None()
Undocumented in source. Be warned that the author may not have intended to support it.
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.6

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.6

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;

These flags are used to determine if a type is a subclass. Availability: >= 2.6

Py_TPFLAGS_BYTES_SUBCLASS
enum Py_TPFLAGS_BYTES_SUBCLASS;
Undocumented in source but is binding to C. You might be able to learn more by searching the web for its name.
Py_TPFLAGS_DEFAULT
enum Py_TPFLAGS_DEFAULT;

_

Py_TPFLAGS_DEFAULT
enum Py_TPFLAGS_DEFAULT;

_

Py_TPFLAGS_DEFAULT_EXTERNAL
enum Py_TPFLAGS_DEFAULT_EXTERNAL;
Undocumented in source but is binding to C. You might be able to learn more by searching the web for its name.
Py_TPFLAGS_DICT_SUBCLASS
enum Py_TPFLAGS_DICT_SUBCLASS;

These flags are used to determine if a type is a subclass. Availability: >= 2.6

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.7

Py_TPFLAGS_HAVE_VERSION_TAG
enum Py_TPFLAGS_HAVE_VERSION_TAG;

Objects support type attribute cache Availability: >= 2.6

Py_TPFLAGS_INT_SUBCLASS
enum Py_TPFLAGS_INT_SUBCLASS;

These flags are used to determine if a type is a subclass. Availability: >= 2.6

Py_TPFLAGS_IS_ABSTRACT
enum Py_TPFLAGS_IS_ABSTRACT;

Type is abstract and cannot be instantiated Availability: >= 2.6

Py_TPFLAGS_LIST_SUBCLASS
enum Py_TPFLAGS_LIST_SUBCLASS;
Py_TPFLAGS_LONG_SUBCLASS
enum Py_TPFLAGS_LONG_SUBCLASS;

These flags are used to determine if a type is a subclass. Availability: >= 2.6

Py_TPFLAGS_STRING_SUBCLASS
enum Py_TPFLAGS_STRING_SUBCLASS;
Undocumented in source but is binding to C. You might be able to learn more by searching the web for its name.
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.6

Py_TPFLAGS_VALID_VERSION_TAG
enum Py_TPFLAGS_VALID_VERSION_TAG;

Objects support type attribute cache Availability: >= 2.6

Mixin templates

PyObject_HEAD
mixintemplate PyObject_HEAD()

_

PyObject_HEAD
mixintemplate PyObject_HEAD()

_

PyObject_VAR_HEAD
mixintemplate 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
mixintemplate 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.6

_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 Availability: 2.* API will still compile but the objects will not be tracked by the GC.

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

Meta