Object Protocol

PyObject *Py_GetConstant(unsigned int constant_id)

Part of the Stable ABI since version 3.13.

Get a strong reference to a constant.

Set an exception and return NULL if constant_id is invalid.

constant_id must be one of these constant identifiers:

Constant Identifier	Value	Returned object
Py_CONSTANT_NONE	0	None
Py_CONSTANT_FALSE	1	False
Py_CONSTANT_TRUE	2	True
Py_CONSTANT_ELLIPSIS	3	Ellipsis
Py_CONSTANT_NOT_IMPLEMENTED	4	NotImplemented
Py_CONSTANT_ZERO	5	0
Py_CONSTANT_ONE	6	1
Py_CONSTANT_EMPTY_STR	7	''
Py_CONSTANT_EMPTY_BYTES	8	b''
Py_CONSTANT_EMPTY_TUPLE	9	()

Numeric values are only given for projects which cannot use the constant identifiers.

Added in version 3.13.

CPython implementation detail: In CPython, all of these constants are immortal.

PyObject *Py_GetConstantBorrowed(unsigned int constant_id)

Part of the Stable ABI since version 3.13.

Similar to Py_GetConstant(), but return a borrowed reference.

This function is primarily intended for backwards compatibility: using Py_GetConstant() is recommended for new code.

The reference is borrowed from the interpreter, and is valid until the interpreter finalization.

Added in version 3.13.

PyObject *Py_NotImplemented

The NotImplemented singleton, used to signal that an operation is not implemented for the given type combination.

Py_RETURN_NOTIMPLEMENTED

Properly handle returning Py_NotImplemented from within a C function (that is, create a new strong reference to NotImplemented and return it).

Py_PRINT_RAW

Flag to be used with multiple functions that print the object (like PyObject_Print() and PyFile_WriteObject()). If passed, these functions use the str() of the object instead of the repr().

int PyObject_Print(PyObject *o, FILE *fp, int flags)

Print an object o, on file fp. Returns -1 on error. The flags argument is used to enable certain printing options. The only option currently supported is Py_PRINT_RAW; if given, the str() of the object is written instead of the repr().

void PyObject_Dump(PyObject *op)

Dump an object op to stderr. This should only be used for debugging.

The output is intended to try dumping objects even after memory corruption:

• Information is written starting with fields that are the least likely to crash when accessed.

• This function can be called without an attached thread state, but it’s not recommended to do so: it can cause deadlocks.

• An object that does not belong to the current interpreter may be dumped, but this may also cause crashes or unintended behavior.

• Implement a heuristic to detect if the object memory has been freed. Don’t display the object contents in this case, only its memory address.

• The output format may change at any time.

Example of output:

object address  : 0x7f80124702c0
object refcount : 2
object type     : 0x9902e0
object type name: str
object repr     : 'abcdef'

Added in version 3.15.

int PyObject_HasAttrWithError(PyObject *o, PyObject *attr_name)

Part of the Stable ABI since version 3.13.

Returns 1 if o has the attribute attr_name, and 0 otherwise. This is equivalent to the Python expression hasattr(o, attr_name). On failure, return -1.

Added in version 3.13.

int PyObject_HasAttrStringWithError(PyObject *o, const char *attr_name)

Part of the Stable ABI since version 3.13.

This is the same as PyObject_HasAttrWithError(), but attr_name is specified as a const char* UTF-8 encoded bytes string, rather than a PyObject*.

Added in version 3.13.

int PyObject_HasAttr(PyObject *o, PyObject *attr_name)

Part of the Stable ABI.

Returns 1 if o has the attribute attr_name, and 0 otherwise. This function always succeeds.

Note

Exceptions that occur when this calls __getattr__() and __getattribute__() methods aren’t propagated, but instead given to sys.unraisablehook(). For proper error handling, use PyObject_HasAttrWithError(), PyObject_GetOptionalAttr() or PyObject_GetAttr() instead.

int PyObject_HasAttrString(PyObject *o, const char *attr_name)

Part of the Stable ABI.

This is the same as PyObject_HasAttr(), but attr_name is specified as a const char* UTF-8 encoded bytes string, rather than a PyObject*.

Note

Exceptions that occur when this calls __getattr__() and __getattribute__() methods or while creating the temporary str object are silently ignored. For proper error handling, use PyObject_HasAttrStringWithError(), PyObject_GetOptionalAttrString() or PyObject_GetAttrString() instead.

PyObject *PyObject_GetAttr(PyObject *o, PyObject *attr_name)

Return value: New reference. Part of the Stable ABI.

Retrieve an attribute named attr_name from object o. Returns the attribute value on success, or NULL on failure. This is the equivalent of the Python expression o.attr_name.

If the missing attribute should not be treated as a failure, you can use PyObject_GetOptionalAttr() instead.

PyObject *PyObject_GetAttrString(PyObject *o, const char *attr_name)

Return value: New reference. Part of the Stable ABI.

This is the same as PyObject_GetAttr(), but attr_name is specified as a const char* UTF-8 encoded bytes string, rather than a PyObject*.

If the missing attribute should not be treated as a failure, you can use PyObject_GetOptionalAttrString() instead.

int PyObject_GetOptionalAttr(PyObject *obj, PyObject *attr_name, PyObject **result);

Part of the Stable ABI since version 3.13.

Variant of PyObject_GetAttr() which doesn’t raise