c api next level changes

What Needs to Change and Why

This document presents further details on the changes envisioned in Taking the C API to the Next Level.

Don't return borrowed references

A function returns a borrowed reference to a Python object obj if instead of returning a new reference to obj, it loans the caller an existing reference.

This saves the caller from having to call Py_DECREF(obj) but at the cost of exposing the lifetime of the reference as part of the API and preventing the Python implementation from knowing when the caller has finished using the borrowed reference.

As a simple example, imagine that a Python module contained t = (1, 2, 3) and that a Python implementation wished to efficiently store that tuple as int t[] = {1, 2, 3}. PyTuple_GetItem returns a borrowed reference, so calling PyTuple_GetItem(obj_t, 0) would require creating a new reference that could never be freed even though the caller would likely only require it for a short time.

Don't steal references

Don't expose reference counting as part of the API

Don't rely on pointers for object identity

Don't expose the memory layout of Python objects as part of the API

Don't expose static types

Expose Python (the language), not a specific Python implementation version

Expose constructs generally useful in C

Provide an explicit execution context