Type Objects

PyTypeObject¶

The C structure of the objects used to describe built-in types.

PyObject* PyType_Type¶

This is the type object for type objects; it is the same object as type and types.TypeType in the Python layer.

int PyType_Check(PyObject *o)¶

Return true if the object o is a type object, including instances of types derived from the standard type object. Return false in all other cases.

int PyType_CheckExact(PyObject *o)¶

Return true if the object o is a type object, but not a subtype of the standard type object. Return false in all other cases.

int PyType_HasFeature(PyObject *o, int feature)¶

Return true if the type object o sets the feature feature. Type features are denoted by single bit flags.

int PyType_IS_GC(PyObject *o)¶

Return true if the type object includes support for the cycle detector; this tests the type flag Py_TPFLAGS_HAVE_GC.

int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b)¶

Return true if a is a subtype of b.

PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)¶

XXX: Document.

PyObject* PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)¶

XXX: Document.

int PyType_Ready(PyTypeObject *type)¶

Finalize a type object. This should be called on all type objects to finish their initialization. This function is responsible for adding inherited slots from a type’s base class. Return 0 on success, or return -1 and sets an exception on error.

The None Object

Note that the PyTypeObject for None is not directly exposed in the Python/C API. Since None is a singleton, testing for object identity (using == in C) is sufficient. There is no PyNone_Check() function for the same reason.

PyObject* Py_None¶

The Python None object, denoting lack of value. This object has no methods. It needs to be treated just like any other object with respect to reference counts.

Py_RETURN_NONE¶

Properly handle returning Py_None from within a C function (that is, increment the reference count of None and return it.)

Boolean Objects

Booleans in Python are implemented as a subclass of integers. There are only two booleans, Py_False and Py_True. As such, the normal creation and deletion functions don’t apply to booleans. The following macros are available, however.

int PyBool_Check(PyObject *o)¶

Return true if o is of type PyBool_Type.

PyObject* Py_False¶

The Python False object. This object has no methods. It needs to be treated just like any other object with respect to reference counts.

PyObject* Py_True¶

The Python True object. This object has no methods. It needs to be treated just like any other object with respect to reference counts.

Py_RETURN_FALSE¶

Return Py_False from a function, properly incrementing its reference count.

Py_RETURN_TRUE¶

Return Py_True from a function, properly incrementing its reference count.

PyObject* PyBool_FromLong(long v)¶

Return a new reference to Py_True or Py_False depending on the truth value of v.

Integer Objects

All integers are implemented as “long” integer objects of arbitrary size.

PyLongObject¶

This subtype of PyObject represents a Python integer object.

PyTypeObject PyLong_Type¶

This instance of PyTypeObject represents the Python integer type. This is the same object as int.

int PyLong_Check(PyObject *p)¶

Return true if its argument is a PyLongObject or a subtype of PyLongObject.

int PyLong_CheckExact(PyObject *p)¶

Return true if its argument is a PyLongObject, but not a subtype of PyLongObject.

PyObject* PyLong_FromLong(long v)¶

Return a new PyLongObject object from v, or NULL on failure.

The current implementation keeps an array of integer objects for all integers between -5 and 256, when you create an int in that range you actually just get back a reference to the existing object. So it should be possible to change the value of 1. I suspect the behaviour of Python in this case is undefined. :-)

PyObject* PyLong_FromUnsignedLong(unsigned long v)¶

Return a new PyLongObject object from a C unsigned long, or NULL on failure.

PyObject* PyLong_FromSsize_t(Py_ssize_t v)¶

Return a new PyLongObject object with a value of v, or NULL on failure.

PyObject* PyLong_FromSize_t(size_t v)¶

Return a new PyLongObject object with a value of v, or NULL on failure.

PyObject* PyLong_FromLongLong(PY_LONG_LONG v)¶

Return a new PyLongObject object from a C long long, or NULL on failure.

PyObject* PyLong_FromUnsignedLongLong(unsigned PY_LONG_LONG v)¶

Return a new PyLongObject object from a C unsigned long long, or NULL on failure.

PyObject* PyLong_FromDouble(double v)¶

Return a new PyLongObject object from the integer part of v, or NULL on failure.

PyObject* PyLong_FromString(char *str, char **pend, int base)¶

Return a new PyLongObject based on the string value in str, which is interpreted according to the radix in base. If pend is non-NULL, *pend will point to the first character in str which follows the representation of the number. If base is 0, the radix will be determined based on the leading characters of str: if str starts with '0x' or '0X', radix 16 will be used; if str starts with '0o' or '0O', radix 8 will be used; if str starts with '0b' or '0B', radix 2 will be used; otherwise radix 10 will be used. If base is not 0, it must be between 2 and 36, inclusive. Leading spaces are ignored. If there are no digits, ValueError will be raised.

PyObject* PyLong_FromUnicode(Py_UNICODE *u, Py_ssize_t length, int base)¶

Convert a sequence of Unicode digits to a Python integer value. The Unicode string is first encoded to a byte string using PyUnicode_EncodeDecimal() and then converted using PyLong_FromString().

PyObject* PyLong_FromVoidPtr(void *p)¶

Create a Python integer from the pointer p. The pointer value can be retrieved from the resulting value using PyLong_AsVoidPtr().

long PyLong_AsLong(PyObject *pylong)¶

Return a C long representation of the contents of pylong. If pylong is greater than LONG_MAX, raise an OverflowError, and return -1. Convert non-long objects automatically to long first, and return -1 if that raises exceptions.

long PyLong_AsLongAndOverflow(PyObject *pylong, int* overflow)¶

Return a C long representation of the contents of pylong. If pylong is greater than LONG_MAX, return -1 and set *overflow to 1 (for overflow) or -1 (for underflow). If an exception is set because of type errors, also return -1.

unsigned long PyLong_AsUnsignedLong(PyObject *pylong)¶

Return a C unsigned long representation of the contents of pylong. If pylong is greater than ULONG_MAX, an OverflowError is raised.

Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)¶

Return a Py_ssize_t representation of the contents of pylong. If pylong is greater than PY_SSIZE_T_MAX, an OverflowError is raised.

size_t PyLong_AsSize_t(PyObject *pylong)¶

Return a size_t representation of the contents of pylong. If pylong is greater than the maximum value for a size_t, an OverflowError is raised.

PY_LONG_LONG PyLong_AsLongLong(PyObject *pylong)¶

Return a C long long from a Python integer. If pylong cannot be represented as a long long, an OverflowError will be raised.

unsigned PY_LONG_LONG PyLong_AsUnsignedLongLong(PyObject *pylong)¶

Return a C unsigned long long from a Python integer. If pylong cannot be represented as an unsigned long long, an OverflowError will be raised if the value is positive, or a TypeError will be raised if the value is negative.

unsigned long PyLong_AsUnsignedLongMask(PyObject *io)¶

Return a C unsigned long from a Python integer, without checking for overflow.

unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *io)¶

Return a C unsigned long long from a Python integer, without checking for overflow.

double PyLong_AsDouble(PyObject *pylong)¶

Return a C double representation of the contents of pylong. If pylong cannot be approximately represented as a double, an OverflowError exception is raised and -1.0 will be returned.

void* PyLong_AsVoidPtr(PyObject *pylong)¶

Convert a Python integer pylong to a C void pointer. If pylong cannot be converted, an OverflowError will be raised. This is only assured to produce a usable void pointer for values created with PyLong_FromVoidPtr().

long PyInt_GetMax()¶

Return the system’s idea of the largest integer it can handle (LONG_MAX, as defined in the system header files).

Floating Point Objects

PyFloatObject¶

This subtype of PyObject represents a Python floating point object.

PyTypeObject PyFloat_Type¶

This instance of PyTypeObject represents the Python floating point type. This is the same object as float and types.FloatType.

int PyFloat_Check(PyObject *p)¶

Return true if its argument is a PyFloatObject or a subtype of PyFloatObject.

int PyFloat_CheckExact(PyObject *p)¶

Return true if its argument is a PyFloatObject, but not a subtype of PyFloatObject.

PyObject* PyFloat_FromString(PyObject *str)¶

Create a PyFloatObject object based on the string value in str, or NULL on failure.

PyObject* PyFloat_FromDouble(double v)¶

Create a PyFloatObject object from v, or NULL on failure.

double PyFloat_AsDouble(PyObject *pyfloat)¶

Return a C double representation of the contents of pyfloat. If pyfloat is not a Python floating point object but has a __float__() method, this method will first be called to convert pyfloat into a float.

double PyFloat_AS_DOUBLE(PyObject *pyfloat)¶

Return a C double representation of the contents of pyfloat, but without error checking.

PyObject* PyFloat_GetInfo(void)¶

Return a PyDictObject object which contains information about the precision, minimum and maximum values of a float. It’s a thin wrapper around the header file float.h.

double PyFloat_GetMax(void)¶

Return the maximum representable finite float DBL_MAX as C double.

double PyFloat_GetMin(void)¶

Return the minimum normalized positive float DBL_MIN as C double.

Complex Number Objects

Python’s complex number objects are implemented as two distinct types when viewed from the C API: one is the Python object exposed to Python programs, and the other is a C structure which represents the actual complex number value. The API provides functions for working with both.

String Objects

These functions raise TypeError when expecting a string parameter and are called with a non-string parameter.

PyStringObject¶

This subtype of PyObject represents a Python string object.

PyTypeObject PyString_Type¶

This instance of PyTypeObject represents the Python string type; it is the same object as str and types.StringType in the Python layer. .

int PyString_Check(PyObject *o)¶

Return true if the object o is a string object or an instance of a subtype of the string type.

int PyString_CheckExact(PyObject *o)¶

Return true if the object o is a string object, but not an instance of a subtype of the string type.

PyObject* PyString_FromString(const char *v)¶

Return a new string object with a copy of the string v as value on success, and NULL on failure. The parameter v must not be NULL; it will not be checked.

PyObject* PyString_FromStringAndSize(const char *v, Py_ssize_t len)¶

Return a new string object with a copy of the string v as value and length len on success, and NULL on failure. If v is NULL, the contents of the string are uninitialized.

PyObject* PyString_FromFormat(const char *format, ...)¶

Take a C printf()-style format string and a variable number of arguments, calculate the size of the resulting Python string and return a string with the values formatted into it. The variable arguments must be C types and must correspond exactly to the format characters in the format string. The following format characters are allowed:

Format Characters	Type	Comment
%%	n/a	The literal % character.
%c	int	A single character, represented as an C int.
%d	int	Exactly equivalent to printf("%d").
%u	unsigned int	Exactly equivalent to printf("%u").
%ld	long	Exactly equivalent to printf("%ld").
%lu	unsigned long	Exactly equivalent to printf("%lu").
%zd	Py_ssize_t	Exactly equivalent to printf("%zd").
%zu	size_t	Exactly equivalent to printf("%zu").
%i	int	Exactly equivalent to printf("%i").
%x	int	Exactly equivalent to printf("%x").
%s	char*	A null-terminated C character array.
%p	void*	The hex representation of a C pointer. Mostly equivalent to printf("%p") except that it is guaranteed to start with the literal 0x regardless of what the platform’s printf yields.

An unrecognized format character causes all the rest of the format string to be copied as-is to the result string, and any extra arguments discarded.

PyObject* PyString_FromFormatV(const char *format, va_list vargs)¶

Identical to PyString_FromFormat() except that it takes exactly two arguments.

Py_ssize_t PyString_Size(PyObject *string)¶

Return the length of the string in string object string.

Py_ssize_t PyString_GET_SIZE(PyObject *string)¶

Macro form of PyString_Size() but without error checking.

char* PyString_AsString(PyObject *string)¶

Return a NUL-terminated representation of the contents of string. The pointer refers to the internal buffer of string, not a copy. The data must not be modified in any way, unless the string was just created using PyString_FromStringAndSize(NULL, size). It must not be deallocated. If string is a Unicode object, this function computes the default encoding of string and operates on that. If string is not a string object at all, PyString_AsString() returns NULL and raises TypeError.

char* PyString_AS_STRING(PyObject *string)¶

Macro form of PyString_AsString() but without error checking. Only string objects are supported; no Unicode objects should be passed.

int PyString_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)¶

Return a NUL-terminated representation of the contents of the object obj through the output variables buffer and length.

The function accepts both string and Unicode objects as input. For Unicode objects it returns the default encoded version of the object. If length is NULL, the resulting buffer may not contain NUL characters; if it does, the function returns -1 and a TypeError is raised.

The buffer refers to an internal string buffer of obj, not a copy. The data must not be modified in any way, unless the string was just created using PyString_FromStringAndSize(NULL, size). It must not be deallocated. If string is a Unicode object, this function computes the default encoding of string and operates on that. If string is not a string object at all, PyString_AsStringAndSize() returns -1 and raises TypeError.

void PyString_Concat(PyObject **string, PyObject *newpart)¶

Create a new string object in *string containing the contents of newpart appended to string; the caller will own the new reference. The reference to the old value of string will be stolen. If the new string cannot be created, the old reference to string will still be discarded and the value of *string will be set to NULL; the appropriate exception will be set.

void PyString_ConcatAndDel(PyObject **string, PyObject *newpart)¶

Create a new string object in *string containing the contents of newpart appended to string. This version decrements the reference count of newpart.

int _PyString_Resize(PyObject **string, Py_ssize_t newsize)¶

A way to resize a string object even though it is “immutable”. Only use this to build up a brand new string object; don’t use this if the string may already be known in other parts of the code. It is an error to call this function if the refcount on the input string object is not one. Pass the address of an existing string object as an lvalue (it may be written into), and the new size desired. On success, *string holds the resized string object and 0 is returned; the address in *string may differ from its input value. If the reallocation fails, the original string object at *string is deallocated, *string is set to NULL, a memory exception is set, and -1 is returned.

PyObject* PyString_Format(PyObject *format, PyObject *args)¶

Return a new string object from format and args. Analogous to format % args. The args argument must be a tuple.

void PyString_InternInPlace(PyObject **string)¶

Intern the argument *string in place. The argument must be the address of a pointer variable pointing to a Python string object. If there is an existing interned string that is the same as *string, it sets *string to it (decrementing the reference count of the old string object and incrementing the reference count of the interned string object), otherwise it leaves *string alone and interns it (incrementing its reference count). (Clarification: even though there is a lot of talk about reference counts, think of this function as reference-count-neutral; you own the object after the call if and only if you owned it before the call.)

PyObject* PyString_InternFromString(const char *v)¶

A combination of PyString_FromString() and PyString_InternInPlace(), returning either a new string object that has been interned, or a new (“owned”) reference to an earlier interned string object with the same value.

PyObject* PyString_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)¶

Create an object by decoding size bytes of the encoded buffer s using the codec registered for encoding. encoding and errors have the same meaning as the parameters of the same name in the unicode() built-in function. The codec to be used is looked up using the Python codec registry. Return NULL if an exception was raised by the codec.

PyObject* PyString_AsDecodedObject(PyObject *str, const char *encoding, const char *errors)¶

Decode a string object by passing it to the codec registered for encoding and return the result as Python object. encoding and errors have the same meaning as the parameters of the same name in the string encode() method. The codec to be used is looked up using the Python codec registry. Return NULL if an exception was raised by the codec.

PyObject* PyString_AsEncodedObject(PyObject *str, const char *encoding, const char *errors)¶

Encode a string object using the codec registered for encoding and return the result as Python object. encoding and errors have the same meaning as the parameters of the same name in the string encode() method. The codec to be used is looked up using the Python codec registry. Return NULL if an exception was raised by the codec.

Unicode Objects

These are the basic Unicode object types used for the Unicode implementation in Python:

Py_UNICODE¶

This type represents the storage type which is used by Python internally as basis for holding Unicode ordinals. Python’s default builds use a 16-bit type for Py_UNICODE and store Unicode values internally as UCS2. It is also possible to build a UCS4 version of Python (most recent Linux distributions come with UCS4 builds of Python). These builds then use a 32-bit type for Py_UNICODE and store Unicode data internally as UCS4. On platforms where wchar_t is available and compatible with the chosen Python Unicode build variant, Py_UNICODE is a typedef alias for wchar_t to enhance native platform compatibility. On all other platforms, Py_UNICODE is a typedef alias for either unsigned short (UCS2) or unsigned long (UCS4).

Note that UCS2 and UCS4 Python builds are not binary compatible. Please keep this in mind when writing extensions or interfaces.

PyUnicodeObject¶

This subtype of PyObject represents a Python Unicode object.

PyTypeObject PyUnicode_Type¶

This instance of PyTypeObject represents the Python Unicode type. It is exposed to Python code as str.

The following APIs are really C macros and can be used to do fast checks and to access internal read-only data of Unicode objects:

int PyUnicode_Check(PyObject *o)¶

Return true if the object o is a Unicode object or an instance of a Unicode subtype.

int PyUnicode_CheckExact(PyObject *o)¶

Return true if the object o is a Unicode object, but not an instance of a subtype.

Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)¶

Return the size of the object. o has to be a PyUnicodeObject (not checked).

Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o)¶

Return the size of the object’s internal buffer in bytes. o has to be a PyUnicodeObject (not checked).

Py_UNICODE* PyUnicode_AS_UNICODE(PyObject *o)¶

Return a pointer to the internal Py_UNICODE buffer of the object. o has to be a PyUnicodeObject (not checked).

const char* PyUnicode_AS_DATA(PyObject *o)¶

Return a pointer to the internal buffer of the object. o has to be a PyUnicodeObject (not checked).

Unicode provides many different character properties. The most often needed ones are available through these macros which are mapped to C functions depending on the Python configuration.

int Py_UNICODE_ISSPACE(Py_UNICODE ch)¶

Return 1 or 0 depending on whether ch is a whitespace character.

int Py_UNICODE_ISLOWER(Py_UNICODE ch)¶

Return 1 or 0 depending on whether ch is a lowercase character.

int Py_UNICODE_ISUPPER(Py_UNICODE ch)¶

Return 1 or 0 depending on whether ch is an uppercase character.

int Py_UNICODE_ISTITLE(Py_UNICODE ch)¶

Return 1 or 0 depending on whether ch is a titlecase character.

int Py_UNICODE_ISLINEBREAK(Py_UNICODE ch)¶

Return 1 or 0 depending on whether ch is a linebreak character.

int Py_UNICODE_ISDECIMAL(Py_UNICODE ch)¶

Return 1 or 0 depending on whether ch is a decimal character.

int Py_UNICODE_ISDIGIT(Py_UNICODE ch)¶

Return 1 or 0 depending on whether ch is a digit character.

int Py_UNICODE_ISNUMERIC(Py_UNICODE ch)¶

Return 1 or 0 depending on whether ch is a numeric character.

int Py_UNICODE_ISALPHA(Py_UNICODE ch)¶

Return 1 or 0 depending on whether ch is an alphabetic character.

int Py_UNICODE_ISALNUM(Py_UNICODE ch)¶

Return 1 or 0 depending on whether ch is an alphanumeric character.

These APIs can be used for fast direct character conversions:

Py_UNICODE Py_UNICODE_TOLOWER(Py_UNICODE ch)¶

Return the character ch converted to lower case.

Py_UNICODE Py_UNICODE_TOUPPER(Py_UNICODE ch)¶

Return the character ch converted to upper case.

Py_UNICODE Py_UNICODE_TOTITLE(Py_UNICODE ch)¶

Return the character ch converted to title case.

int Py_UNICODE_TODECIMAL(Py_UNICODE ch)¶

Return the character ch converted to a decimal positive integer. Return -1 if this is not possible. This macro does not raise exceptions.

int Py_UNICODE_TODIGIT(Py_UNICODE ch)¶

Return the character ch converted to a single digit integer. Return -1 if this is not possible. This macro does not raise exceptions.

double Py_UNICODE_TONUMERIC(Py_UNICODE ch)¶

Return the character ch converted to a double. Return -1.0 if this is not possible. This macro does not raise exceptions.

To create Unicode objects and access their basic sequence properties, use these APIs:

PyObject* PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size)¶

Create a Unicode Object from the Py_UNICODE buffer u of the given size. u may be NULL which causes the contents to be undefined. It is the user’s responsibility to fill in the needed data. The buffer is copied into the new object. If the buffer is not NULL, the return value might be a shared object. Therefore, modification of the resulting Unicode object is only allowed when u is NULL.

PyObject* PyUnicode_FromStringAndSize(const char *u, Py_ssize_t size)¶

Create a Unicode Object from the char buffer u. The bytes will be interpreted as being UTF-8 encoded. u may also be NULL which causes the contents to be undefined. It is the user’s responsibility to fill in the needed data. The buffer is copied into the new object. If the buffer is not NULL, the return value might be a shared object. Therefore, modification of the resulting Unicode object is only allowed when u is NULL.

PyObject *PyUnicode_FromString(const char *u)¶

Create a Unicode object from an UTF-8 encoded null-terminated char buffer u.

PyObject* PyUnicode_FromFormat(const char *format, ...)¶

Take a C printf()-style format string and a variable number of arguments, calculate the size of the resulting Python unicode string and return a string with the values formatted into it. The variable arguments must be C types and must correspond exactly to the format characters in the format string. The following format characters are allowed:

Format Characters	Type	Comment
%%	n/a	The literal % character.
%c	int	A single character, represented as an C int.
%d	int	Exactly equivalent to printf("%d").
%u	unsigned int	Exactly equivalent to printf("%u").
%ld	long	Exactly equivalent to printf("%ld").
%lu	unsigned long	Exactly equivalent to printf("%lu").
%zd	Py_ssize_t	Exactly equivalent to printf("%zd").
%zu	size_t	Exactly equivalent to printf("%zu").
%i	int	Exactly equivalent to printf("%i").
%x	int	Exactly equivalent to printf("%x").
%s	char*	A null-terminated C character array.
%p	void*	The hex representation of a C pointer. Mostly equivalent to printf("%p") except that it is guaranteed to start with the literal 0x regardless of what the platform’s printf yields.
%U	PyObject*	A unicode object.
%V	PyObject*, char *	A unicode object (which may be NULL) and a null-terminated C character array as a second parameter (which will be used, if the first parameter is NULL).
%S	PyObject*	The result of calling PyObject_Unicode().
%R	PyObject*	The result of calling PyObject_Repr().

An unrecognized format character causes all the rest of the format string to be copied as-is to the result string, and any extra arguments discarded.

PyObject* PyUnicode_FromFormatV(const char *format, va_list vargs)¶

Identical to PyUnicode_FromFormat() except that it takes exactly two arguments.

Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)¶

Return a read-only pointer to the Unicode object’s internal Py_UNICODE buffer, NULL if unicode is not a Unicode object.

Py_ssize_t PyUnicode_GetSize(PyObject *unicode)¶

Return the length of the Unicode object.

PyObject* PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)¶

Coerce an encoded object obj to an Unicode object and return a reference with incremented refcount.

String and other char buffer compatible objects are decoded according to the given encoding and using the error handling defined by errors. Both can be NULL to have the interface use the default values (see the next section for details).

All other objects, including Unicode objects, cause a TypeError to be set.

The API returns NULL if there was an error. The caller is responsible for decref’ing the returned objects.

PyObject* PyUnicode_FromObject(PyObject *obj)¶

Shortcut for PyUnicode_FromEncodedObject(obj, NULL, "strict") which is used throughout the interpreter whenever coercion to Unicode is needed.

If the platform supports wchar_t and provides a header file wchar.h, Python can interface directly to this type using the following functions. Support is optimized if Python’s own Py_UNICODE type is identical to the system’s wchar_t.

PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size)¶

Create a Unicode object from the wchar_t buffer w of the given size. Return NULL on failure.

Py_ssize_t PyUnicode_AsWideChar(PyUnicodeObject *unicode, wchar_t *w, Py_ssize_t size)¶

Copy the Unicode object contents into the wchar_t buffer w. At most size wchar_t characters are copied (excluding a possibly trailing 0-termination character). Return the number of wchar_t characters copied or -1 in case of an error. Note that the resulting wchar_t string may or may not be 0-terminated. It is the responsibility of the caller to make sure that the wchar_t string is 0-terminated in case this is required by the application.

Buffer Objects

Python objects implemented in C can export a group of functions called the “buffer interface.” These functions can be used by an object to expose its data in a raw, byte-oriented format. Clients of the object can use the buffer interface to access the object data directly, without needing to copy it first.

Two examples of objects that support the buffer interface are strings and arrays. The string object exposes the character contents in the buffer interface’s byte-oriented form. An array can also expose its contents, but it should be noted that array elements may be multi-byte values.

An example user of the buffer interface is the file object’s write() method. Any object that can export a series of bytes through the buffer interface can be written to a file. There are a number of format codes to PyArg_ParseTuple() that operate against an object’s buffer interface, returning data from the target object.

More information on the buffer interface is provided in the section Buffer Object Structures, under the description for PyBufferProcs.

A “buffer object” is defined in the bufferobject.h header (included by Python.h). These objects look very similar to string objects at the Python programming level: they support slicing, indexing, concatenation, and some other standard string operations. However, their data can come from one of two sources: from a block of memory, or from another object which exports the buffer interface.

Buffer objects are useful as a way to expose the data from another object’s buffer interface to the Python programmer. They can also be used as a zero-copy slicing mechanism. Using their ability to reference a block of memory, it is possible to expose any data to the Python programmer quite easily. The memory could be a large, constant array in a C extension, it could be a raw block of memory for manipulation before passing to an operating system library, or it could be used to pass around structured data in its native, in-memory format.

PyBufferObject¶

This subtype of PyObject represents a buffer object.

PyTypeObject PyBuffer_Type¶

The instance of PyTypeObject which represents the Python buffer type; it is the same object as buffer and types.BufferType in the Python layer. .

int Py_END_OF_BUFFER¶

This constant may be passed as the size parameter to PyBuffer_FromObject() or PyBuffer_FromReadWriteObject(). It indicates that the new PyBufferObject should refer to base object from the specified offset to the end of its exported buffer. Using this enables the caller to avoid querying the base object for its length.

int PyBuffer_Check(PyObject *p)¶

Return true if the argument has type PyBuffer_Type.

PyObject* PyBuffer_FromObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size)¶

Return a new read-only buffer object. This raises TypeError if base doesn’t support the read-only buffer protocol or doesn’t provide exactly one buffer segment, or it raises ValueError if offset is less than zero. The buffer will hold a reference to the base object, and the buffer’s contents will refer to the base object’s buffer interface, starting as position offset and extending for size bytes. If size is Py_END_OF_BUFFER, then the new buffer’s contents extend to the length of the base object’s exported buffer data.

PyObject* PyBuffer_FromReadWriteObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size)¶

Return a new writable buffer object. Parameters and exceptions are similar to those for PyBuffer_FromObject(). If the base object does not export the writable buffer protocol, then TypeError is raised.

PyObject* PyBuffer_FromMemory(void *ptr, Py_ssize_t size)¶

Return a new read-only buffer object that reads from a specified location in memory, with a specified size. The caller is responsible for ensuring that the memory buffer, passed in as ptr, is not deallocated while the returned buffer object exists. Raises ValueError if size is less than zero. Note that Py_END_OF_BUFFER may not be passed for the size parameter; ValueError will be raised in that case.

PyObject* PyBuffer_FromReadWriteMemory(void *ptr, Py_ssize_t size)¶

Similar to PyBuffer_FromMemory(), but the returned buffer is writable.

PyObject* PyBuffer_New(Py_ssize_t size)¶

Return a new writable buffer object that maintains its own memory buffer of size bytes. ValueError is returned if size is not zero or positive. Note that the memory buffer (as returned by PyObject_AsWriteBuffer()) is not specifically aligned.

Tuple Objects

PyTupleObject¶

This subtype of PyObject represents a Python tuple object.

PyTypeObject PyTuple_Type¶

This instance of PyTypeObject represents the Python tuple type; it is the same object as tuple and types.TupleType in the Python layer..

int PyTuple_Check(PyObject *p)¶

Return true if p is a tuple object or an instance of a subtype of the tuple type.

int PyTuple_CheckExact(PyObject *p)¶

Return true if p is a tuple object, but not an instance of a subtype of the tuple type.

PyObject* PyTuple_New(Py_ssize_t len)¶

Return a new tuple object of size len, or NULL on failure.

PyObject* PyTuple_Pack(Py_ssize_t n, ...)¶

Return a new tuple object of size n, or NULL on failure. The tuple values are initialized to the subsequent n C arguments pointing to Python objects. PyTuple_Pack(2, a, b) is equivalent to Py_BuildValue("(OO)", a, b).

Py_ssize_t PyTuple_Size(PyObject *p)¶

Take a pointer to a tuple object, and return the size of that tuple.

Py_ssize_t PyTuple_GET_SIZE(PyObject *p)¶

Return the size of the tuple p, which must be non-NULL and point to a tuple; no error checking is performed.

PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos)¶

Return the object at position pos in the tuple pointed to by p. If pos is out of bounds, return NULL and sets an IndexError exception.

PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)¶

Like PyTuple_GetItem(), but does no checking of its arguments.

PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)¶

Take a slice of the tuple pointed to by p from low to high and return it as a new tuple.

int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)¶

Insert a reference to object o at position pos of the tuple pointed to by p. Return 0 on success.

Note

This function “steals” a reference to o.

void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)¶

Like PyTuple_SetItem(), but does no error checking, and should only be used to fill in brand new tuples.

Note

This function “steals” a reference to o.

int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)¶

Can be used to resize a tuple. newsize will be the new length of the tuple. Because tuples are supposed to be immutable, this should only be used if there is only one reference to the object. Do not use this if the tuple may already be known to some other part of the code. The tuple will always grow or shrink at the end. Think of this as destroying the old tuple and creating a new one, only more efficiently. Returns 0 on success. Client code should never assume that the resulting value of *p will be the same as before calling this function. If the object referenced by *p is replaced, the original *p is destroyed. On failure, returns -1 and sets *p to NULL, and raises MemoryError or SystemError.

List Objects

PyListObject¶

This subtype of PyObject represents a Python list object.

PyTypeObject PyList_Type¶

This instance of PyTypeObject represents the Python list type. This is the same object as list and types.ListType in the Python layer.

int PyList_Check(PyObject *p)¶

Return true if p is a list object or an instance of a subtype of the list type.

int PyList_CheckExact(PyObject *p)¶

Return true if p is a list object, but not an instance of a subtype of the list type.

PyObject* PyList_New(Py_ssize_t len)¶

Return a new list of length len on success, or NULL on failure.

Note

If length is greater than zero, the returned list object’s items are set to NULL. Thus you cannot use abstract API functions such as PySequence_SetItem() or expose the object to Python code before setting all items to a real object with PyList_SetItem().

Py_ssize_t PyList_Size(PyObject *list)¶

Return the length of the list object in list; this is equivalent to len(list) on a list object.

Py_ssize_t PyList_GET_SIZE(PyObject *list)¶

Macro form of PyList_Size() without error checking.

PyObject* PyList_GetItem(PyObject *list, Py_ssize_t index)¶

Return the object at position pos in the list pointed to by p. The position must be positive, indexing from the end of the list is not supported. If pos is out of bounds, return NULL and set an IndexError exception.

PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i)¶

Macro form of PyList_GetItem() without error checking.

int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)¶

Set the item at index index in list to item. Return 0 on success or -1 on failure.

Note

This function “steals” a reference to item and discards a reference to an item already in the list at the affected position.

void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)¶

Macro form of PyList_SetItem() without error checking. This is normally only used to fill in new lists where there is no previous content.

Note

This function “steals” a reference to item, and, unlike PyList_SetItem(), does not discard a reference to any item that it being replaced; any reference in list at position i will be leaked.

int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)¶

Insert the item item into list list in front of index index. Return 0 if successful; return -1 and set an exception if unsuccessful. Analogous to list.insert(index, item).

int PyList_Append(PyObject *list, PyObject *item)¶

Append the object item at the end of list list. Return 0 if successful; return -1 and set an exception if unsuccessful. Analogous to list.append(item).

PyObject* PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)¶

Return a list of the objects in list containing the objects between low and high. Return NULL and set an exception if unsuccessful. Analogous to list[low:high].

int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)¶

Set the slice of list between low and high to the contents of itemlist. Analogous to list[low:high] = itemlist. The itemlist may be NULL, indicating the assignment of an empty list (slice deletion). Return 0 on success, -1 on failure.

int PyList_Sort(PyObject *list)¶

Sort the items of list in place. Return 0 on success, -1 on failure. This is equivalent to list.sort().

int PyList_Reverse(PyObject *list)¶

Reverse the items of list in place. Return 0 on success, -1 on failure. This is the equivalent of list.reverse().

PyObject* PyList_AsTuple(PyObject *list)¶

Return a new tuple object containing the contents of list; equivalent to tuple(list).

Dictionary Objects

PyDictObject¶

This subtype of PyObject represents a Python dictionary object.

PyTypeObject PyDict_Type¶

This instance of PyTypeObject represents the Python dictionary type. This is exposed to Python programs as dict and types.DictType.

int PyDict_Check(PyObject *p)¶

Return true if p is a dict object or an instance of a subtype of the dict type.

int PyDict_CheckExact(PyObject *p)¶

Return true if p is a dict object, but not an instance of a subtype of the dict type.

PyObject* PyDict_New()¶

Return a new empty dictionary, or NULL on failure.

PyObject* PyDictProxy_New(PyObject *dict)¶

Return a proxy object for a mapping which enforces read-only behavior. This is normally used to create a proxy to prevent modification of the dictionary for non-dynamic class types.

void PyDict_Clear(PyObject *p)¶

Empty an existing dictionary of all key-value pairs.

int PyDict_Contains(PyObject *p, PyObject *key)¶

Determine if dictionary p contains key. If an item in p is matches key, return 1, otherwise return 0. On error, return -1. This is equivalent to the Python expression key in p.

PyObject* PyDict_Copy(PyObject *p)¶

Return a new dictionary that contains the same key-value pairs as p.

int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)¶

Insert value into the dictionary p with a key of key. key must be hashable; if it isn’t, TypeError will be raised. Return 0 on success or -1 on failure.

int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)¶

Insert value into the dictionary p using key as a key. key should be a char*. The key object is created using PyString_FromString(key). Return 0 on success or -1 on failure.

int PyDict_DelItem(PyObject *p, PyObject *key)¶

Remove the entry in dictionary p with key key. key must be hashable; if it isn’t, TypeError is raised. Return 0 on success or -1 on failure.

int PyDict_DelItemString(PyObject *p, char *key)¶

Remove the entry in dictionary p which has a key specified by the string key. Return 0 on success or -1 on failure.

PyObject* PyDict_GetItem(PyObject *p, PyObject *key)¶

Return the object from dictionary p which has a key key. Return NULL if the key key is not present, but without setting an exception.

PyObject* PyDict_GetItemString(PyObject *p, const char *key)¶

This is the same as PyDict_GetItem(), but key is specified as a char*, rather than a PyObject*.

PyObject* PyDict_Items(PyObject *p)¶

Return a PyListObject containing all the items from the dictionary, as in the dictionary method dict.items().

PyObject* PyDict_Keys(PyObject *p)¶

Return a PyListObject containing all the keys from the dictionary, as in the dictionary method dict.keys().

PyObject* PyDict_Values(PyObject *p)¶

Return a PyListObject containing all the values from the dictionary p, as in the dictionary method dict.values().

Py_ssize_t PyDict_Size(PyObject *p)¶

Return the number of items in the dictionary. This is equivalent to len(p) on a dictionary.

int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)¶

Iterate over all key-value pairs in the dictionary p. The int referred to by ppos must be initialized to 0 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 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 since the structure is sparse, the offsets are not consecutive.

For example:

PyObject *key, *value;
Py_ssize_t pos = 0;


.. cnid:: 175

while (PyDict_Next(self->dict, &pos, &key, &value)) {
    /* do something interesting with the values... */
    ...
}

The dictionary p should not be mutated during iteration. It is safe (since Python 2.1) to modify the values of the keys as you iterate over the dictionary, but only so long as the set of keys does not change. For example:

PyObject *key, *value;
Py_ssize_t pos = 0;


.. cnid:: 177

while (PyDict_Next(self->dict, &pos, &key, &value)) {
    int i = PyInt_AS_LONG(value) + 1;
    PyObject *o = PyInt_FromLong(i);
    if (o == NULL)
        return -1;
    if (PyDict_SetItem(self->dict, key, o) < 0) {
        Py_DECREF(o);
        return -1;
    }
    Py_DECREF(o);
}

int PyDict_Merge(PyObject *a, PyObject *b, int override)¶

Iterate over mapping object b adding key-value pairs to dictionary a. b may be a dictionary, or any object supporting PyMapping_Keys() and PyObject_GetItem(). If override is true, existing pairs in a will be replaced if a matching key is found in b, otherwise pairs will only be added if there is not a matching key in a. Return 0 on success or -1 if an exception was raised.

int PyDict_Update(PyObject *a, PyObject *b)¶

This is the same as PyDict_Merge(a, b, 1) in C, or a.update(b) in Python. Return 0 on success or -1 if an exception was raised.

int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)¶

Update or merge into dictionary a, from the key-value pairs in seq2. seq2 must be an iterable object producing iterable objects of length 2, viewed as key-value pairs. In case of duplicate keys, the last wins if override is true, else the first wins. Return 0 on success or -1 if an exception was raised. Equivalent Python (except for the return value):

def PyDict_MergeFromSeq2(a, seq2, override):
    for key, value in seq2:
        if override or key not in a:
            a[key] = value

File Objects

Python’s built-in file objects are implemented entirely on the FILE* support from the C standard library. This is an implementation detail and may change in future releases of Python.

PyFileObject¶

This subtype of PyObject represents a Python file object.

PyTypeObject PyFile_Type¶

This instance of PyTypeObject represents the Python file type. This is exposed to Python programs as file and types.FileType.

int PyFile_Check(PyObject *p)¶

Return true if its argument is a PyFileObject or a subtype of PyFileObject.

int PyFile_CheckExact(PyObject *p)¶

Return true if its argument is a PyFileObject, but not a subtype of PyFileObject.

PyFile_FromFd(int fd, char *name, char *mode, int buffering, char *encoding, char *newline, int closefd)¶

Create a new PyFileObject from the file descriptor of an already opened file fd. The arguments name, encoding and newline can be NULL to use the defaults; buffering can be -1 to use the default. Return NULL on failure.

Caveat

Take care when you are mixing streams and descriptors! For more information, see the GNU C Library docs.

int PyObject_AsFileDescriptor(PyObject *p)¶

Return the file descriptor associated with p as an int. If the object is an integer, its value is returned. If not, the object’s fileno() method is called if it exists; the method must return an integer, which is returned as the file descriptor value. Sets an exception and returns -1 on failure.

PyObject* PyFile_GetLine(PyObject *p, int n)¶

Equivalent to p.readline([n]), this function reads one line from the object p. p may be a file object or any object with a readline() method. If n is 0, exactly one line is read, regardless of the length of the line. If n is greater than 0, no more than n bytes will be read from the file; a partial line can be returned. In both cases, an empty string is returned if the end of the file is reached immediately. If n is less than 0, however, one line is read regardless of length, but EOFError is raised if the end of the file is reached immediately.

PyObject* PyFile_Name(PyObject *p)¶

Return the name of the file specified by p as a string object.

void PyFile_SetBufSize(PyFileObject *p, int n)¶

Available on systems with setvbuf() only. This should only be called immediately after file object creation.

int PyFile_SetEncoding(PyFileObject *p, const char *enc)¶

Set the file’s encoding for Unicode output to enc. Return 1 on success and 0 on failure.

int PyFile_SoftSpace(PyObject *p, int newflag)¶

This function exists for internal use by the interpreter. Set the softspace attribute of p to newflag and return the previous value. p does not have to be a file object for this function to work properly; any object is supported (thought its only interesting if the softspace attribute can be set). This function clears any errors, and will return 0 as the previous value if the attribute either does not exist or if there were errors in retrieving it. There is no way to detect errors from this function, but doing so should not be needed.

int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)¶

Write object obj to file object p. The only supported flag for flags is Py_PRINT_RAW; if given, the str() of the object is written instead of the repr(). Return 0 on success or -1 on failure; the appropriate exception will be set.

int PyFile_WriteString(const char *s, PyObject *p)¶

Write string s to file object p. Return 0 on success or -1 on failure; the appropriate exception will be set.

Function Objects

There are a few functions specific to Python functions.

PyFunctionObject¶

The C structure used for functions.

PyTypeObject PyFunction_Type¶

This is an instance of PyTypeObject and represents the Python function type. It is exposed to Python programmers as types.FunctionType.

int PyFunction_Check(PyObject *o)¶

Return true if o is a function object (has type PyFunction_Type). The parameter must not be NULL.

PyObject* PyFunction_New(PyObject *code, PyObject *globals)¶

Return a new function object associated with the code object code. globals must be a dictionary with the global variables accessible to the function.

The function’s docstring, name and __module__ are retrieved from the code object, the argument defaults and closure are set to NULL.

PyObject* PyFunction_GetCode(PyObject *op)¶

Return the code object associated with the function object op.

PyObject* PyFunction_GetGlobals(PyObject *op)¶

Return the globals dictionary associated with the function object op.

PyObject* PyFunction_GetModule(PyObject *op)¶

Return the __module__ attribute of the function object op. This is normally a string containing the module name, but can be set to any other object by Python code.

PyObject* PyFunction_GetDefaults(PyObject *op)¶

Return the argument default values of the function object op. This can be a tuple of arguments or NULL.

int PyFunction_SetDefaults(PyObject *op, PyObject *defaults)¶

Set the argument default values for the function object op. defaults must be Py_None or a tuple.

Raises SystemError and returns -1 on failure.

PyObject* PyFunction_GetClosure(PyObject *op)¶

Return the closure associated with the function object op. This can be NULL or a tuple of cell objects.

int PyFunction_SetClosure(PyObject *op, PyObject *closure)¶

Set the closure associated with the function object op. closure must be Py_None or a tuple of cell objects.

Raises SystemError and returns -1 on failure.

Method Objects

Methods are bound function objects. Methods are always bound to an instance of an user-defined class. Unbound methods (methods bound to a class object) are no longer available.

PyTypeObject PyMethod_Type¶

This instance of PyTypeObject represents the Python method type. This is exposed to Python programs as types.MethodType.

int PyMethod_Check(PyObject *o)¶

Return true if o is a method object (has type PyMethod_Type). The parameter must not be NULL.

PyObject* PyMethod_New(PyObject *func, PyObject *self)¶

Return a new method object, with func being any callable object and self the instance the method should be bound. func is is the function that will be called when the method is called. self must not be NULL.

PyObject* PyMethod_Function(PyObject *meth)¶

Return the function object associated with the method meth.

PyObject* PyMethod_GET_FUNCTION(PyObject *meth)¶

Macro version of PyMethod_Function() which avoids error checking.

PyObject* PyMethod_Self(PyObject *meth)¶

Return the instance associated with the method meth.

PyObject* PyMethod_GET_SELF(PyObject *meth)¶

Macro version of PyMethod_Self() which avoids error checking.

Module Objects

There are only a few functions special to module objects.

PyTypeObject PyModule_Type¶

This instance of PyTypeObject represents the Python module type. This is exposed to Python programs as types.ModuleType.

int PyModule_Check(PyObject *p)¶

Return true if p is a module object, or a subtype of a module object.

int PyModule_CheckExact(PyObject *p)¶

Return true if p is a module object, but not a subtype of PyModule_Type.

PyObject* PyModule_New(const char *name)¶

Return a new module object with the __name__ attribute set to name. Only the module’s __doc__ and __name__ attributes are filled in; the caller is responsible for providing a __file__ attribute.

PyObject* PyModule_GetDict(PyObject *module)¶

Return the dictionary object that implements module‘s namespace; this object is the same as the __dict__ attribute of the module object. This function never fails. It is recommended extensions use other PyModule_*() and PyObject_*() functions rather than directly manipulate a module’s __dict__.

char* PyModule_GetName(PyObject *module)¶

Return module‘s __name__ value. If the module does not provide one, or if it is not a string, SystemError is raised and NULL is returned.

char* PyModule_GetFilename(PyObject *module)¶

Return the name of the file from which module was loaded using module‘s __file__ attribute. If this is not defined, or if it is not a string, raise SystemError and return NULL.

int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)¶

Add an object to module as name. This is a convenience function which can be used from the module’s initialization function. This steals a reference to value. Return -1 on error, 0 on success.

int PyModule_AddIntConstant(PyObject *module, const char *name, long value)¶

Add an integer constant to module as name. This convenience function can be used from the module’s initialization function. Return -1 on error, 0 on success.

int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)¶

Add a string constant to module as name. This convenience function can be used from the module’s initialization function. The string value must be null-terminated. Return -1 on error, 0 on success.

Iterator Objects

Python provides two general-purpose iterator objects. The first, a sequence iterator, works with an arbitrary sequence supporting the __getitem__() method. The second works with a callable object and a sentinel value, calling the callable for each item in the sequence, and ending the iteration when the sentinel value is returned.

PyTypeObject PySeqIter_Type¶

Type object for iterator objects returned by PySeqIter_New() and the one-argument form of the iter() built-in function for built-in sequence types.

int PySeqIter_Check(op)¶

Return true if the type of op is PySeqIter_Type.

PyObject* PySeqIter_New(PyObject *seq)¶

Return an iterator that works with a general sequence object, seq. The iteration ends when the sequence raises IndexError for the subscripting operation.

PyTypeObject PyCallIter_Type¶

Type object for iterator objects returned by PyCallIter_New() and the two-argument form of the iter() built-in function.

int PyCallIter_Check(op)¶

Return true if the type of op is PyCallIter_Type.

PyObject* PyCallIter_New(PyObject *callable, PyObject *sentinel)¶

Return a new iterator. The first parameter, callable, can be any Python callable object that can be called with no parameters; each call to it should return the next item in the iteration. When callable returns a value equal to sentinel, the iteration will be terminated.

Descriptor Objects

“Descriptors” are objects that describe some attribute of an object. They are found in the dictionary of type objects.

PyTypeObject PyProperty_Type¶

The type object for the built-in descriptor types.

PyObject* PyDescr_NewGetSet(PyTypeObject *type, struct PyGetSetDef *getset)¶

PyObject* PyDescr_NewMember(PyTypeObject *type, struct PyMemberDef *meth)¶

PyObject* PyDescr_NewMethod(PyTypeObject *type, struct PyMethodDef *meth)¶

PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *wrapper, void *wrapped)¶

PyObject* PyDescr_NewClassMethod(PyTypeObject *type, PyMethodDef *method)¶

int PyDescr_IsData(PyObject *descr)¶

Return true if the descriptor objects descr describes a data attribute, or false if it describes a method. descr must be a descriptor object; there is no error checking.

PyObject* PyWrapper_New(PyObject *, PyObject *)¶

Slice Objects

PyTypeObject PySlice_Type¶

The type object for slice objects. This is the same as slice and types.SliceType.

int PySlice_Check(PyObject *ob)¶

Return true if ob is a slice object; ob must not be NULL.

PyObject* PySlice_New(PyObject *start, PyObject *stop, PyObject *step)¶

Return a new slice object with the given values. The start, stop, and step parameters are used as the values of the slice object attributes of the same names. Any of the values may be NULL, in which case the None will be used for the corresponding attribute. Return NULL if the new object could not be allocated.

int PySlice_GetIndices(PySliceObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step)¶

Retrieve the start, stop and step indices from the slice object slice, assuming a sequence of length length. Treats indices greater than length as errors.

Returns 0 on success and -1 on error with no exception set (unless one of the indices was not None and failed to be converted to an integer, in which case -1 is returned with an exception set).

You probably do not want to use this function. If you want to use slice objects in versions of Python prior to 2.3, you would probably do well to incorporate the source of PySlice_GetIndicesEx(), suitably renamed, in the source of your extension.

int PySlice_GetIndicesEx(PySliceObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step, Py_ssize_t *slicelength)¶

Usable replacement for PySlice_GetIndices(). Retrieve the start, stop, and step indices from the slice object slice assuming a sequence of length length, and store the length of the slice in slicelength. Out of bounds indices are clipped in a manner consistent with the handling of normal slices.

Returns 0 on success and -1 on error with exception set.

Weak Reference Objects

Python supports weak references as first-class objects. There are two specific object types which directly implement weak references. The first is a simple reference object, and the second acts as a proxy for the original object as much as it can.

int PyWeakref_Check(ob)¶

Return true if ob is either a reference or proxy object.

int PyWeakref_CheckRef(ob)¶

Return true if ob is a reference object.

int PyWeakref_CheckProxy(ob)¶

Return true if ob is a proxy object.

PyObject* PyWeakref_NewRef(PyObject *ob, PyObject *callback)¶

Return a weak reference object for the object ob. This will always return a new reference, but is not guaranteed to create a new object; an existing reference object may be returned. The second parameter, callback, can be a callable object that receives notification when ob is garbage collected; it should accept a single parameter, which will be the weak reference object itself. callback may also be None or NULL. If ob is not a weakly-referencable object, or if callback is not callable, None, or NULL, this will return NULL and raise TypeError.

PyObject* PyWeakref_NewProxy(PyObject *ob, PyObject *callback)¶

Return a weak reference proxy object for the object ob. This will always return a new reference, but is not guaranteed to create a new object; an existing proxy object may be returned. The second parameter, callback, can be a callable object that receives notification when ob is garbage collected; it should accept a single parameter, which will be the weak reference object itself. callback may also be None or NULL. If ob is not a weakly-referencable object, or if callback is not callable, None, or NULL, this will return NULL and raise TypeError.

PyObject* PyWeakref_GetObject(PyObject *ref)¶

Return the referenced object from a weak reference, ref. If the referent is no longer live, returns None.

PyObject* PyWeakref_GET_OBJECT(PyObject *ref)¶

Similar to PyWeakref_GetObject(), but implemented as a macro that does no error checking.

CObjects

Refer to Extending and Embedding the Python Interpreter, section 1.12, “Providing a C API for an Extension Module,” for more information on using these objects.

PyCObject¶

This subtype of PyObject represents an opaque value, useful for C extension modules who need to pass an opaque value (as a void* pointer) through Python code to other C code. It is often used to make a C function pointer defined in one module available to other modules, so the regular import mechanism can be used to access C APIs defined in dynamically loaded modules.

int PyCObject_Check(PyObject *p)¶

Return true if its argument is a PyCObject.

PyObject* PyCObject_FromVoidPtr(void* cobj, void (*destr)(void *))¶

Create a PyCObject from the void * cobj. The destr function will be called when the object is reclaimed, unless it is NULL.

PyObject* PyCObject_FromVoidPtrAndDesc(void* cobj, void* desc, void (*destr)(void *, void *))¶

Create a PyCObject from the void * cobj. The destr function will be called when the object is reclaimed. The desc argument can be used to pass extra callback data for the destructor function.

void* PyCObject_AsVoidPtr(PyObject* self)¶

Return the object void * that the PyCObject self was created with.

void* PyCObject_GetDesc(PyObject* self)¶

Return the description void * that the PyCObject self was created with.

int PyCObject_SetVoidPtr(PyObject* self, void* cobj)¶

Set the void pointer inside self to cobj. The PyCObject must not have an associated destructor. Return true on success, false on failure.

Cell Objects

“Cell” objects are used to implement variables referenced by multiple scopes. For each such variable, a cell object is created to store the value; the local variables of each stack frame that references the value contains a reference to the cells from outer scopes which also use that variable. When the value is accessed, the value contained in the cell is used instead of the cell object itself. This de-referencing of the cell object requires support from the generated byte-code; these are not automatically de-referenced when accessed. Cell objects are not likely to be useful elsewhere.

PyCellObject¶

The C structure used for cell objects.

PyTypeObject PyCell_Type¶

The type object corresponding to cell objects.

int PyCell_Check(ob)¶

Return true if ob is a cell object; ob must not be NULL.

PyObject* PyCell_New(PyObject *ob)¶

Create and return a new cell object containing the value ob. The parameter may be NULL.

PyObject* PyCell_Get(PyObject *cell)¶

Return the contents of the cell cell.

PyObject* PyCell_GET(PyObject *cell)¶

Return the contents of the cell cell, but without checking that cell is non-NULL and a cell object.

int PyCell_Set(PyObject *cell, PyObject *value)¶

Set the contents of the cell object cell to value. This releases the reference to any current content of the cell. value may be NULL. cell must be non-NULL; if it is not a cell object, -1 will be returned. On success, 0 will be returned.

void PyCell_SET(PyObject *cell, PyObject *value)¶

Sets the value of the cell object cell to value. No reference counts are adjusted, and no checks are made for safety; cell must be non-NULL and must be a cell object.

Generator Objects

Generator objects are what Python uses to implement generator iterators. They are normally created by iterating over a function that yields values, rather than explicitly calling PyGen_New().

PyGenObject¶

The C structure used for generator objects.

PyTypeObject PyGen_Type¶

The type object corresponding to generator objects

int PyGen_Check(ob)¶

Return true if ob is a generator object; ob must not be NULL.

int PyGen_CheckExact(ob)¶

Return true if ob‘s type is PyGen_Type is a generator object; ob must not be NULL.

PyObject* PyGen_New(PyFrameObject *frame)¶

Create and return a new generator object based on the frame object. A reference to frame is stolen by this function. The parameter must not be NULL.

DateTime Objects

Various date and time objects are supplied by the datetime module. Before using any of these functions, the header file datetime.h must be included in your source (note that this is not included by Python.h), and the macro PyDateTime_IMPORT() must be invoked. The macro puts a pointer to a C structure into a static variable, PyDateTimeAPI, that is used by the following macros.

Type-check macros:

int PyDate_Check(PyObject *ob)¶

Return true if ob is of type PyDateTime_DateType or a subtype of PyDateTime_DateType. ob must not be NULL.

int PyDate_CheckExact(PyObject *ob)¶

Return true if ob is of type PyDateTime_DateType. ob must not be NULL.

int PyDateTime_Check(PyObject *ob)¶

Return true if ob is of type PyDateTime_DateTimeType or a subtype of PyDateTime_DateTimeType. ob must not be NULL.

int PyDateTime_CheckExact(PyObject *ob)¶

Return true if ob is of type PyDateTime_DateTimeType. ob must not be NULL.

int PyTime_Check(PyObject *ob)¶

Return true if ob is of type PyDateTime_TimeType or a subtype of PyDateTime_TimeType. ob must not be NULL.

int PyTime_CheckExact(PyObject *ob)¶

Return true if ob is of type PyDateTime_TimeType. ob must not be NULL.

int PyDelta_Check(PyObject *ob)¶

Return true if ob is of type PyDateTime_DeltaType or a subtype of PyDateTime_DeltaType. ob must not be NULL.

int PyDelta_CheckExact(PyObject *ob)¶

Return true if ob is of type PyDateTime_DeltaType. ob must not be NULL.

int PyTZInfo_Check(PyObject *ob)¶

Return true if ob is of type PyDateTime_TZInfoType or a subtype of PyDateTime_TZInfoType. ob must not be NULL.

int PyTZInfo_CheckExact(PyObject *ob)¶

Return true if ob is of type PyDateTime_TZInfoType. ob must not be NULL.

Macros to create objects:

PyObject* PyDate_FromDate(int year, int month, int day)¶

Return a datetime.date object with the specified year, month and day.

PyObject* PyDateTime_FromDateAndTime(int year, int month, int day, int hour, int minute, int second, int usecond)¶

Return a datetime.datetime object with the specified year, month, day, hour, minute, second and microsecond.

PyObject* PyTime_FromTime(int hour, int minute, int second, int usecond)¶

Return a datetime.time object with the specified hour, minute, second and microsecond.

PyObject* PyDelta_FromDSU(int days, int seconds, int useconds)¶

Return a datetime.timedelta object representing the given number of days, seconds and microseconds. Normalization is performed so that the resulting number of microseconds and seconds lie in the ranges documented for datetime.timedelta objects.

Macros to extract fields from date objects. The argument must be an instance of PyDateTime_Date, including subclasses (such as PyDateTime_DateTime). The argument must not be NULL, and the type is not checked:

int PyDateTime_GET_YEAR(PyDateTime_Date *o)¶

Return the year, as a positive int.

int PyDateTime_GET_MONTH(PyDateTime_Date *o)¶

Return the month, as an int from 1 through 12.

int PyDateTime_GET_DAY(PyDateTime_Date *o)¶

Return the day, as an int from 1 through 31.

Macros to extract fields from datetime objects. The argument must be an instance of PyDateTime_DateTime, including subclasses. The argument must not be NULL, and the type is not checked:

int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o)¶

Return the hour, as an int from 0 through 23.

int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o)¶

Return the minute, as an int from 0 through 59.

int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o)¶

Return the second, as an int from 0 through 59.

int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o)¶

Return the microsecond, as an int from 0 through 999999.

Macros to extract fields from time objects. The argument must be an instance of PyDateTime_Time, including subclasses. The argument must not be NULL, and the type is not checked:

int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o)¶

Return the hour, as an int from 0 through 23.

int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o)¶

Return the minute, as an int from 0 through 59.

int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o)¶

Return the second, as an int from 0 through 59.

int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o)¶

Return the microsecond, as an int from 0 through 999999.

Macros for the convenience of modules implementing the DB API:

PyObject* PyDateTime_FromTimestamp(PyObject *args)¶

Create and return a new datetime.datetime object given an argument tuple suitable for passing to datetime.datetime.fromtimestamp().

PyObject* PyDate_FromTimestamp(PyObject *args)¶

Create and return a new datetime.date object given an argument tuple suitable for passing to datetime.date.fromtimestamp().

Set Objects

This section details the public API for set and frozenset objects. Any functionality not listed below is best accessed using the either the abstract object protocol (including PyObject_CallMethod(), PyObject_RichCompareBool(), PyObject_Hash(), PyObject_Repr(), PyObject_IsTrue(), PyObject_Print(), and PyObject_GetIter()) or the abstract number protocol (including PyNumber_And(), PyNumber_Subtract(), PyNumber_Or(), PyNumber_Xor(), PyNumber_InPlaceAnd(), PyNumber_InPlaceSubtract(), PyNumber_InPlaceOr(), and PyNumber_InPlaceXor()).

PySetObject¶

This subtype of PyObject is used to hold the internal data for both set and frozenset objects. It is like a PyDictObject in that it is a fixed size for small sets (much like tuple storage) and will point to a separate, variable sized block of memory for medium and large sized sets (much like list storage). None of the fields of this structure should be considered public and are subject to change. All access should be done through the documented API rather than by manipulating the values in the structure.

PyTypeObject PySet_Type¶

This is an instance of PyTypeObject representing the Python set type.

PyTypeObject PyFrozenSet_Type¶

This is an instance of PyTypeObject representing the Python frozenset type.

The following type check macros work on pointers to any Python object. Likewise, the constructor functions work with any iterable Python object.

int PyAnySet_Check(PyObject *p)¶

Return true if p is a set object, a frozenset object, or an instance of a subtype.

int PyAnySet_CheckExact(PyObject *p)¶

Return true if p is a set object or a frozenset object but not an instance of a subtype.

int PyFrozenSet_CheckExact(PyObject *p)¶

Return true if p is a frozenset object but not an instance of a subtype.

PyObject* PySet_New(PyObject *iterable)¶

Return a new set containing objects returned by the iterable. The iterable may be NULL to create a new empty set. Return the new set on success or NULL on failure. Raise TypeError if iterable is not actually iterable. The constructor is also useful for copying a set (c=set(s)).

PyObject* PyFrozenSet_New(PyObject *iterable)¶

Return a new frozenset containing objects returned by the iterable. The iterable may be NULL to create a new empty frozenset. Return the new set on success or NULL on failure. Raise TypeError if iterable is not actually iterable.

The following functions and macros are available for instances of set or frozenset or instances of their subtypes.

Py_ssize_t PySet_Size(PyObject *anyset)¶

Return the length of a set or frozenset object. Equivalent to len(anyset). Raises a PyExc_SystemError if anyset is not a set, frozenset, or an instance of a subtype.

Py_ssize_t PySet_GET_SIZE(PyObject *anyset)¶

Macro form of PySet_Size() without error checking.

int PySet_Contains(PyObject *anyset, PyObject *key)¶

Return 1 if found, 0 if not found, and -1 if an error is encountered. Unlike the Python __contains__() method, this function does not automatically convert unhashable sets into temporary frozensets. Raise a TypeError if the key is unhashable. Raise PyExc_SystemError if anyset is not a set, frozenset, or an instance of a subtype.

The following functions are available for instances of set or its subtypes but not for instances of frozenset or its subtypes.

int PySet_Add(PyObject *set, PyObject *key)¶

Add key to a set instance. Does not apply to frozenset instances. Return 0 on success or -1 on failure. Raise a TypeError if the key is unhashable. Raise a MemoryError if there is no room to grow. Raise a SystemError if set is an not an instance of set or its subtype.

int PySet_Discard(PyObject *set, PyObject *key)¶

Return 1 if found and removed, 0 if not found (no action taken), and -1 if an error is encountered. Does not raise KeyError for missing keys. Raise a TypeError if the key is unhashable. Unlike the Python discard() method, this function does not automatically convert unhashable sets into temporary frozensets. Raise PyExc_SystemError if set is an not an instance of set or its subtype.

PyObject* PySet_Pop(PyObject *set)¶

Return a new reference to an arbitrary object in the set, and removes the object from the set. Return NULL on failure. Raise KeyError if the set is empty. Raise a SystemError if set is an not an instance of set or its subtype.

int PySet_Clear(PyObject *set)¶

Empty an existing set of all elements.