Skip to content

upgrade.rst

Latest commit

 

History

History
168 lines (109 loc) · 4.45 KB

upgrade.rst

File metadata and controls

168 lines (109 loc) · 4.45 KB

upgrade_pythoncapi.py script

upgrade_pythoncapi.py requires Python 3.6 or newer.

Usage

Run the with no arguments to display command line options and list available operations:

python3 upgrade_pythoncapi.py

Select files and directories

To upgrade module.c file, type:

python3 upgrade_pythoncapi.py module.c

To upgrade all C and C++ files (.c, .h, .cc, .cpp, .cxx and .hpp files) in the directory/ directory, type:

python3 upgrade_pythoncapi.py directory/

Multiple filenames an directories can be specified on the command line.

Files are modified in-place! If a file is modified, a copy of the original file is created with the .old suffix.

Select operations

To only replace op->ob_type with Py_TYPE(op), select the Py_TYPE operation with:

python3 upgrade_pythoncapi.py -o Py_TYPE module.c

Or the opposite, to apply all operations but leave op->ob_type unchanged, deselect the Py_TYPE operation with:

python3 upgrade_pythoncapi.py -o all,-Py_TYPE module.c

Download pythoncapi_compat.h

Most upgrade_pythoncapi.py operations add #include "pythoncapi_compat.h". You may have to download the pythoncapi_compat.h header file to your project. It can be downloaded with:

python3 upgrade_pythoncapi.py --download PATH

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);.

Py_Is

  • Replace x == Py_None with Py_IsNone(x).
  • Replace x == Py_True with Py_IsTrue(x).
  • Replace x == Py_False with Py_IsFalse(x).
  • Replace x != Py_None with !Py_IsNone(x).
  • Replace x != Py_True with !Py_IsTrue(x).
  • Replace x != Py_False with !Py_IsFalse(x).

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).

Experimental operations

The following operations are experimental (ex: can introduce compiler warnings) and so not included in the all group, they have to be selected explicitly. Example: -o all,Py_SETREF.

Experimental operations:

  • Py_NewRef:
    • Replace Py_INCREF(res); return res; with return Py_NewRef(res);
    • Replace x = y; Py_INCREF(x); with x = Py_NewRef(y);
    • Replace x = y; Py_INCREF(y); with x = Py_NewRef(y);
    • Replace Py_INCREF(y); x = y; with x = Py_NewRef(y);
  • Py_CLEAR:
    • Replace Py_XDECREF(var); var = NULL; with Py_CLEAR(var);
  • Py_SETREF:
    • Replace Py_DECREF(x); x = y; with Py_SETREF(x, y);
    • Replace Py_XDECREF(x); x = y; with Py_XSETREF(x, y);