* ``pythoncapi_compat.h``: Header file providing new functions of the Python C

API to Python 3.6.

* ``upgrade_pythoncapi.py``: Script upgrading C extension modules to newer

Python API without losing support for Python 3.6. It relies on

``pythoncapi_compat.h``.

Python 3.6 to Python 3.10 are supported. A subset of C99 is required, like

``static inline`` functions: see `PEP 7

<https://www.python.org/dev/peps/pep-0007/>`_.

Run upgrade_pythoncapi.py

Upgrade all ``.c`` and ``.h`` files of a project::

WARNING: files are modified in-place! If a file is modified, the original file

is saved as ``<filename>.old``.

To see command line options and list available operations, run it with no

arguments::

For example, to only replace ``op->ob_type`` with ``Py_TYPE(op)``, use::

Or the opposite, to apply all operations but leave ``op->ob_type`` unchanged,

use::

Copy pythoncapi_compat.h

Most upgrade_pythoncapi.py operations add ``#include "pythoncapi_compat.h"``.

You may have to copy the ``pythoncapi_compat.h`` header file to your project.

It can be copied from::

Upgrade Operations

``upgrade_pythoncapi.py`` implements the following operations:

* ``Py_TYPE``:

* Replace ``op->ob_type`` with ``Py_TYPE(op)``.

* ``Py_SIZE``:

* Replace ``op->ob_size`` with ``Py_SIZE(op)``.

* ``Py_REFCNT``:

* Replace ``op->ob_refcnt`` with ``Py_REFCNT(op)``.

* ``Py_SET_TYPE``:

* Replace ``obj->ob_type = type;`` with ``Py_SET_TYPE(obj, type);``.

* Replace ``Py_TYPE(obj) = type;`` with ``Py_SET_TYPE(obj, type);``.

* ``Py_SET_SIZE``:

* Replace ``obj->ob_size = size;`` with ``Py_SET_SIZE(obj, size);``.

* Replace ``Py_SIZE(obj) = size;`` with ``Py_SET_SIZE(obj, size);``.

* ``Py_SET_REFCNT``:

* Replace ``obj->ob_refcnt = refcnt;`` with ``Py_SET_REFCNT(obj, refcnt);``.

* Replace ``Py_REFCNT(obj) = refcnt;`` with ``Py_SET_REFCNT(obj, refcnt);``.

* ``PyObject_NEW``:

* Replace ``PyObject_NEW(...)`` with ``PyObject_New(...)``.

* Replace ``PyObject_NEW_VAR(...)`` with ``PyObject_NewVar(...)``.

* ``PyMem_MALLOC``:

* Replace ``PyMem_MALLOC(n)`` with ``PyMem_Malloc(n)``.

* Replace ``PyMem_REALLOC(ptr, n)`` with ``PyMem_Realloc(ptr, n)``.

* Replace ``PyMem_FREE(ptr)``, ``PyMem_DEL(ptr)`` and ``PyMem_Del(ptr)`` .

with ``PyMem_Free(n)``.

* ``PyObject_MALLOC``:

* Replace ``PyObject_MALLOC(n)`` with ``PyObject_Malloc(n)``.

* Replace ``PyObject_REALLOC(ptr, n)`` with ``PyObject_Realloc(ptr, n)``.

* Replace ``PyObject_FREE(ptr)``, ``PyObject_DEL(ptr)``

and ``PyObject_Del(ptr)`` . with ``PyObject_Free(n)``.

* ``PyFrame_GetBack``:

* Replace ``frame->f_back`` with ``_PyFrame_GetBackBorrow(frame)``.

* ``PyFrame_GetCode``:

* Replace ``frame->f_code`` with ``_PyFrame_GetCodeBorrow(frame)``.

* ``PyThreadState_GetInterpreter``:

* Replace ``tstate->interp`` with ``PyThreadState_GetInterpreter(tstate)``.

* ``PyThreadState_GetFrame``:

* Replace ``tstate->frame`` with ``_PyThreadState_GetFrameBorrow(tstate)``.

pythoncapi_compat.h functions

Verbose mode::

See tests in the ``tests/`` subdirectory.

Links

* `pythoncapi_compat.h header

<https://github.com/pythoncapi/pythoncapi_compat>`_:

Header file providing new functions of the Python C API for old Python

versions.

* `Py_SET_TYPE() function documentation

<https://docs.python.org/dev/c-api/structures.html#c.Py_SET_TYPE>`_

(Python 3.9)

* `Py_SET_SIZE() function documentation

<https://docs.python.org/dev/c-api/structures.html#c.Py_SET_SIZE>`_

(Python 3.9)

* `Py_SET_REFCNT() function documentation

<https://docs.python.org/dev/c-api/structures.html#c.Py_SET_REFCNT>`_

(Python 3.9)

* `bpo-39573: [C API] Make PyObject an opaque structure in the limited C API

<https://bugs.python.org/issue39573>`_

* `PEP 620 -- Hide implementation details from the C API

<https://www.python.org/dev/peps/pep-0620/>`_

* 2020-11-30: Creation of the upgrade_pythoncapi.py script.

* 2020-06-04: Creation of the pythoncapi_compat.h header file.

import os.path

import subprocess

import sys

import shutil

TEST_DIR = os.path.join(os.path.dirname(__file__), 'tests')

TEST_COMPAT = os.path.join(TEST_DIR, "test_pythoncapi_compat.py")

TEST_UPGRADE = os.path.join(TEST_DIR, "test_upgrade_pythoncapi.py")

PYTHONS = (

"python3.6",

"python3.7",

"python3.8",

"python3.9",

"python3.10",

"python3",

"python3-debug",

)

def run_command(cmd):

proc = subprocess.Popen(cmd)

proc.wait()

exitcode = proc.returncode

if exitcode:

sys.exit(exitcode)

def run_tests_exe(executable, verbose, tested):

executable = os.path.realpath(executable)

if executable in tested:

return

cmd = [executable, TEST_COMPAT]

if verbose:

cmd.append('-v')

run_command(cmd)

tested.add(executable)

def run_tests(python, verbose, tested):

executable = shutil.which(python)

if not executable:

print(f"Ignore missing: {python}")

return

run_tests_exe(executable, verbose, tested)

def main():

verbose = "-v" in sys.argv[1:]

cmd = [sys.executable, TEST_UPGRADE]

if verbose:

cmd.append('-v')

run_command(cmd)

tested = set()

for python in PYTHONS:

run_tests(python, verbose, tested)

run_tests_exe(sys.executable, verbose, tested)

print()

print(f"Tested: {len(tested)} Python executables")

if __name__ == "__main__":

main()

set -e -x

python3 tests/test_upgrade_pythoncapi.py -v

python3 tests/test_matrix.py

ext = Extension('test_pythoncapi_compat_cext',

sources=['test_pythoncapi_compat_cext.c'])

pythonpath = None

if not pythonpath:

raise Exception("Failed to find the build directory")

import test_pythoncapi_compat_cext

return test_pythoncapi_compat_cext

.m_name = "test_pythoncapi_compat_cext",

PyInit_test_pythoncapi_compat_cext(void)