\n\nPyCAPI is a Python package containing over 600 fast bindings to the CPython C API. Its goal is to support as much of the Python 3.5 - 3.8 stable public APIs as possible.\n\nTo install, just run:\n```sh\n$ pip install pycapi\n```\n\nWhere is the documentation?\n---------------------------\n\nDocumentation of the full CPython C API can be found [here](https://docs.python.org/3/c-api/index.html). It's not a goal of this project to maintain a separate API reference.\n\nAny type conversions (such as Python `int` with C `long`, or Python `bytes` with C `char*`) should be obvious, and all other semantics (such as refcounts, etc.) are identical to the documented API behavior. For simplicity, PyCAPI doesn't provide any additional functionality or utilities beyond CPython's documented stable public API.\n\nHow is PyCAPI better than `ctypes.pythonapi`?\n---------------------------------------------\n\n### It's easier to use.\n\n`pycapi` works as expected, right out of the box:\n\n```py\n>>> import pycapi\n>>> pycapi.PyNumber_Add(1, 2)\n3\n```\n\n`ctypes.pythonapi` implicity requires users to specify the argument and return types as `ctypes` types:\n\n```py\n>>> import ctypes\n>>> ctypes.pythonapi.PyNumber_Add(1, 2)\nSegmentation fault: 11\n```\n\n```py\n>>> import ctypes\n>>> ctypes.pythonapi.PyNumber_Add.argtypes = (ctypes.py_object, ctypes.py_object)\n>>> ctypes.pythonapi.PyNumber_Add.restype = ctypes.py_object\n>>> ctypes.pythonapi.PyNumber_Add(1, 2)\n3\n```\n\n### It's more complete.\n\n`pycapi` is designed to provide properly typed bindings for *any* part of the C API that's reasonable to call from the Python layer:\n\n```py\n>>> import pycapi\n>>> pycapi.PyDict_Check({})\n1\n```\n\nIn comparison, `ctypes.pythonapi` is loaded directly from the `Python.h` DLL. As a consequence, it isn't able to offer any APIs that happen to be implemented as macros:\n\n```py\n>>> import ctypes\n>>> ctypes.pythonapi.PyDict_Check(ctypes.py_object({}))\nTraceback (most recent call last):\n File \"\", line 1, in \n File \"/usr/local/Cellar/python/3.7.2_1/Frameworks/Python.framework/Versions/3.7/lib/python3.7/ctypes/__init__.py\", line 369, in __getattr__\n func = self.__getitem__(name)\n File \"/usr/local/Cellar/python/3.7.2_1/Frameworks/Python.framework/Versions/3.7/lib/python3.7/ctypes/__init__.py\", line 374, in __getitem__\n func = self._FuncPtr((name_or_ordinal, self))\nAttributeError: dlsym(RTLD_DEFAULT, PyDict_Check): symbol not found\n```\n\n`pycapi` is also fully loaded on import, so you can use tab-completion and other introspection techniques to discover APIs. `ctypes.pythonapi` requires you to access the attribute *before* it is loaded, and there is no way to get a complete listing of what it supports.\n\n### It's faster.\n\nIn many cases, it can be even *faster than the built-in equivalent* in the Python layer. The numbers speak for themselves:\n\n```py\nIn [1]: from pycapi import PyDict_New, PyDict_Clear, PyDict_Copy\n\nIn [2]: %timeit PyDict_New()\n44.7 ns \u00b1 1.38 ns per loop (mean \u00b1 std. dev. of 7 runs, 10000000 loops each)\n\nIn [3]: %timeit PyDict_Clear({})\n54 ns \u00b1 0.448 ns per loop (mean \u00b1 std. dev. of 7 runs, 10000000 loops each)\n\nIn [4]: %timeit PyDict_Copy({})\n68.9 ns \u00b1 0.362 ns per loop (mean \u00b1 std. dev. of 7 runs, 10000000 loops each)\n```\n\n```py\nIn [1]: PyDict_New = dict\n ...: PyDict_Clear = dict.clear\n ...: PyDict_Copy = dict.copy\n\nIn [2]: %timeit PyDict_New()\n71.7 ns \u00b1 0.569 ns per loop (mean \u00b1 std. dev. of 7 runs, 10000000 loops each)\n\nIn [3]: %timeit PyDict_Clear({})\n55.8 ns \u00b1 0.506 ns per loop (mean \u00b1 std. dev. of 7 runs, 10000000 loops each)\n\nIn [4]: %timeit PyDict_Copy({})\n73.1 ns \u00b1 1.06 ns per loop (mean \u00b1 std. dev. of 7 runs, 10000000 loops each)\n```\n\n```py\nIn [1]: import ctypes\n ...: \n ...: PyDict_New = ctypes.pythonapi.PyDict_New\n ...: PyDict_New.argtypes = ()\n ...: PyDict_New.restype = ctypes.py_object\n ...: \n ...: PyDict_Clear = ctypes.pythonapi.PyDict_Clear\n ...: PyDict_Clear.argtypes = (ctypes.py_object,)\n ...: PyDict_Clear.restype = None\n ...: \n ...: PyDict_Copy = ctypes.pythonapi.PyDict_Copy\n ...: PyDict_Copy.argtypes = (ctypes.py_object,)\n ...: PyDict_Copy.restype = None\n\nIn [2]: %timeit PyDict_New()\n113 ns \u00b1 0.424 ns per loop (mean \u00b1 std. dev. of 7 runs, 10000000 loops each)\n\nIn [3]: %timeit PyDict_Clear({})\n273 ns \u00b1 3.34 ns per loop (mean \u00b1 std. dev. of 7 runs, 1000000 loops each)\n\nIn [4]: %timeit PyDict_Copy({})\n378 ns \u00b1 9.77 ns per loop (mean \u00b1 std. dev. of 7 runs, 1000000 loops each)\n```\n\n