Object Protocol

Overview

The Object Protocol provides generic operations that work with any Python object through the abstract object interface. These functions operate on PyObject* pointers.

Type Checking

PyObject_Type

PyObject* PyObject_Type(PyObject *o)

Return the type object for object o. Equivalent to type(o) in Python.

PyObject*

required

Object to get the type of

Returns: New reference to the type object, or NULL on error

PyObject_TypeCheck

int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)

Check if object o is of type type or a subtype. Returns: 1 if true, 0 if false Example:

if (PyObject_TypeCheck(obj, &PyList_Type)) {
    // obj is a list or list subclass
}

PyObject_IsInstance

int PyObject_IsInstance(PyObject *inst, PyObject *cls)

Check if inst is an instance of class cls. Equivalent to isinstance(inst, cls). Returns: 1 for true, 0 for false, -1 on error

Attribute Access

PyObject_HasAttr

int PyObject_HasAttr(PyObject *o, PyObject *attr_name)

Check if object has an attribute. Equivalent to hasattr(o, attr_name).

PyObject*

required

Object to check

attr_name

PyObject*

required

Attribute name (string object)

Returns: 1 if attribute exists, 0 otherwise

PyObject_GetAttr

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

Get an attribute from an object. Equivalent to o.attr_name or getattr(o, attr_name). Returns: New reference to attribute value, or NULL on error Example:

PyObject *name_str = PyUnicode_FromString("__name__");
PyObject *name = PyObject_GetAttr(module, name_str);
Py_DECREF(name_str);

if (name == NULL) {
    PyErr_Clear();
} else {
    // Use name
    Py_DECREF(name);
}

PyObject_GetAttrString

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

Convenience function for getting attributes with C string names. Example:

PyObject *name = PyObject_GetAttrString(obj, "name");
if (name != NULL) {
    const char *name_str = PyUnicode_AsUTF8(name);
    printf("Name: %s\n", name_str);
    Py_DECREF(name);
}

PyObject_SetAttr

int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)

Set an attribute. Equivalent to o.attr_name = v or setattr(o, attr_name, v).

PyObject*

required

Object to modify

attr_name

PyObject*

required

Attribute name (string object)

PyObject*

required

New attribute value

Returns: 0 on success, -1 on error

PyObject_DelAttr

int PyObject_DelAttr(PyObject *o, PyObject *attr_name)

Delete an attribute. Equivalent to del o.attr_name. Returns: 0 on success, -1 on error

Rich Comparison

PyObject_RichCompare

PyObject* PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)

Compare two objects with a comparison operator.

PyObject*

required

Left operand

PyObject*

required

Right operand

opid

int

required

Comparison operator: Py_LT, Py_LE, Py_EQ, Py_NE, Py_GT, Py_GE

Returns: Comparison result (new reference), or NULL on error Example:

PyObject *result = PyObject_RichCompare(a, b, Py_EQ);
if (result == NULL)
    return NULL;

int is_equal = PyObject_IsTrue(result);
Py_DECREF(result);

if (is_equal < 0)
    return NULL;

if (is_equal) {
    printf("Objects are equal\n");
}

PyObject_RichCompareBool

int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)

Convenience function returning boolean result directly. Returns: 1 for true, 0 for false, -1 on error

Callable Objects

PyCallable_Check

int PyCallable_Check(PyObject *o)

Check if object is callable. Returns: 1 if callable, 0 otherwise (never fails)

PyObject_Call

PyObject* PyObject_Call(PyObject *callable, PyObject *args, PyObject *kwargs)

Call a callable object.

callable

PyObject*

required

Callable object (function, method, class, etc.)

args

PyObject*

required

Tuple of positional arguments (can be empty tuple)

kwargs

PyObject*

Dictionary of keyword arguments (can be NULL)

Returns: Return value (new reference), or NULL on error Example:

// Call: func(42, name="Alice")
PyObject *args = Py_BuildValue("(i)", 42);
PyObject *kwargs = Py_BuildValue("{ss}", "name", "Alice");

PyObject *result = PyObject_Call(func, args, kwargs);

Py_DECREF(args);
Py_DECREF(kwargs);

if (result == NULL)
    return NULL;

Py_DECREF(result);

PyObject_CallObject

PyObject* PyObject_CallObject(PyObject *callable, PyObject *args)

Call with only positional arguments. Example:

PyObject *args = Py_BuildValue("(ss)", "hello", "world");
PyObject *result = PyObject_CallObject(func, args);
Py_DECREF(args);

PyObject_CallFunction

PyObject* PyObject_CallFunction(PyObject *callable, const char *format, ...)

Call with C arguments built using format string. Example:

// Call: func("hello", 42)
PyObject *result = PyObject_CallFunction(func, "si", "hello", 42);

PyObject_CallMethod

PyObject* PyObject_CallMethod(PyObject *obj, const char *name, const char *format, ...)

Call a method on an object. Example:

// Call: obj.append(42)
PyObject *result = PyObject_CallMethod(obj, "append", "i", 42);
if (result == NULL)
    return NULL;
Py_DECREF(result);

Item Access

PyObject_GetItem

PyObject* PyObject_GetItem(PyObject *o, PyObject *key)

Get item from mapping or sequence. Equivalent to o[key].

PyObject*

required

Container object

key

PyObject*

required

Key or index

Returns: New reference to item, or NULL on error Example:

// dict["key"]
PyObject *key = PyUnicode_FromString("key");
PyObject *value = PyObject_GetItem(dict, key);
Py_DECREF(key);

if (value == NULL) {
    if (PyErr_ExceptionMatches(PyExc_KeyError)) {
        PyErr_Clear();
        // Handle missing key
    }
    return NULL;
}
Py_DECREF(value);

PyObject_SetItem

int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *value)

Set item in container. Equivalent to o[key] = value. Returns: 0 on success, -1 on error

PyObject_DelItem

int PyObject_DelItem(PyObject *o, PyObject *key)

Delete item from container. Equivalent to del o[key]. Returns: 0 on success, -1 on error

Sequence Protocol

PyObject_Length / PyObject_Size

Py_ssize_t PyObject_Length(PyObject *o)
Py_ssize_t PyObject_Size(PyObject *o)  // Alias

Get length of sequence or mapping. Equivalent to len(o). Returns: Length, or -1 on error

PyObject_GetIter

PyObject* PyObject_GetIter(PyObject *o)

Get iterator for object. Equivalent to iter(o). Returns: New reference to iterator, or NULL on error Example:

PyObject *iter = PyObject_GetIter(sequence);
if (iter == NULL)
    return NULL;

PyObject *item;
while ((item = PyIter_Next(iter)) != NULL) {
    // Process item
    printf("Item: %ld\n", PyLong_AsLong(item));
    Py_DECREF(item);
}

Py_DECREF(iter);

if (PyErr_Occurred())
    return NULL;

Truth Value Testing

PyObject_IsTrue

int PyObject_IsTrue(PyObject *o)

Test truth value. Equivalent to bool(o). Returns: 1 for true, 0 for false, -1 on error

PyObject_Not

int PyObject_Not(PyObject *o)

Logical negation. Equivalent to not o. Returns: 1 if false, 0 if true, -1 on error

String Representation

PyObject_Repr

PyObject* PyObject_Repr(PyObject *o)

Get object representation. Equivalent to repr(o). Returns: New reference to string, or NULL on error

PyObject_Str

PyObject* PyObject_Str(PyObject *o)

Get string representation. Equivalent to str(o). Returns: New reference to string, or NULL on error

PyObject_ASCII

PyObject* PyObject_ASCII(PyObject *o)

Get ASCII representation. Equivalent to ascii(o). Returns: New reference to string with non-ASCII characters escaped

Hash Values

PyObject_Hash

Py_hash_t PyObject_Hash(PyObject *o)

Compute hash value. Equivalent to hash(o). Returns: Hash value, or -1 on error

Don’t confuse return value -1 with hash value -1. Check PyErr_Occurred() on -1 return.

PyObject_HashNotImplemented

Py_hash_t PyObject_HashNotImplemented(PyObject *o)

Helper to raise TypeError for unhashable types. Returns: Always -1 and sets exception

Reference Counting Helpers

Py_Is

int Py_Is(PyObject *x, PyObject *y)

Test identity. Equivalent to x is y. Returns: 1 if same object, 0 otherwise

Py_IsNone

int Py_IsNone(PyObject *x)

Test if object is None. Equivalent to x is None.

Py_IsTrue / Py_IsFalse

int Py_IsTrue(PyObject *x)
int Py_IsFalse(PyObject *x)

Test if object is True or False singleton.

Memory and Copying

PyObject_Bytes

PyObject* PyObject_Bytes(PyObject *o)

Get bytes representation. Equivalent to bytes(o). Returns: New reference to bytes object, or NULL on error

Complete Example

static PyObject* process_object(PyObject *self, PyObject *args) {
    PyObject *obj, *result = NULL;
    
    if (!PyArg_ParseTuple(args, "O", &obj))
        return NULL;
    
    // Check if callable
    if (PyCallable_Check(obj)) {
        // Call with no arguments
        PyObject *empty_args = PyTuple_New(0);
        result = PyObject_Call(obj, empty_args, NULL);
        Py_DECREF(empty_args);
        return result;
    }
    
    // Try to get 'value' attribute
    if (PyObject_HasAttrString(obj, "value")) {
        result = PyObject_GetAttrString(obj, "value");
        return result;
    }
    
    // Try to get length
    Py_ssize_t len = PyObject_Length(obj);
    if (len >= 0) {
        return PyLong_FromSsize_t(len);
    }
    
    // Fall back to string representation
    PyErr_Clear();
    return PyObject_Str(obj);
}

Type Objects

Define and work with type objects

Reference Counting

Manage object lifetimes

Concrete Objects

Type-specific operations

Exception Handling

Handle errors in object operations

Overview

Object Protocol

Concrete Objects

Advanced

​Overview

​Type Checking

​PyObject_Type

​PyObject_TypeCheck

​PyObject_IsInstance

​Attribute Access

​PyObject_HasAttr

​PyObject_GetAttr

​PyObject_GetAttrString

​PyObject_SetAttr

​PyObject_DelAttr

​Rich Comparison

​PyObject_RichCompare

​PyObject_RichCompareBool

​Callable Objects

​PyCallable_Check

​PyObject_Call

​PyObject_CallObject

​PyObject_CallFunction

​PyObject_CallMethod

​Item Access

​PyObject_GetItem

​PyObject_SetItem

​PyObject_DelItem

​Sequence Protocol

​PyObject_Length / PyObject_Size

​PyObject_GetIter

​Truth Value Testing

​PyObject_IsTrue

​PyObject_Not

​String Representation

​PyObject_Repr

​PyObject_Str

​PyObject_ASCII

​Hash Values

​PyObject_Hash

​PyObject_HashNotImplemented

​Reference Counting Helpers

​Py_Is

​Py_IsNone

​Py_IsTrue / Py_IsFalse

​Memory and Copying

​PyObject_Bytes

​Complete Example

​See Also

Type Objects

Reference Counting

Concrete Objects

Exception Handling

Build docs developers (and LLMs) love

Overview

Type Checking

PyObject_Type

PyObject_TypeCheck

PyObject_IsInstance

Attribute Access

PyObject_HasAttr

PyObject_GetAttr

PyObject_GetAttrString

PyObject_SetAttr

PyObject_DelAttr

Rich Comparison

PyObject_RichCompare

PyObject_RichCompareBool

Callable Objects

PyCallable_Check

PyObject_Call

PyObject_CallObject

PyObject_CallFunction

PyObject_CallMethod

Item Access

PyObject_GetItem

PyObject_SetItem

PyObject_DelItem

Sequence Protocol

PyObject_Length / PyObject_Size

PyObject_GetIter

Truth Value Testing

PyObject_IsTrue

PyObject_Not

String Representation

PyObject_Repr

PyObject_Str

PyObject_ASCII

Hash Values

PyObject_Hash

PyObject_HashNotImplemented

Reference Counting Helpers

Py_Is

Py_IsNone

Py_IsTrue / Py_IsFalse

Memory and Copying

PyObject_Bytes

Complete Example

See Also