Write a CPython C Extension Module from Scratch

Topic Overview

C Extension Modules

CPython exposes a C API for writing native modules that import like Python code. Extensions accelerate hot paths and wrap system libraries. NumPy, optional C helpers in networking libraries, and countless stdlib modules all build on this same scaffolding.

Module Boilerplate

A minimal extension exports a PyMethodDef table and a module init function:

cCopy
Loading…

Key pieces you will wire up:

• PyMethodDef: maps Python names to C function pointers
• PyModuleDef: module metadata passed to PyModule_Create
• PyInit_*: entry symbol the import machinery looks up

Build with python3-config --cflags --ldflags or setuptools. Reference counting rules apply: Py_INCREF/Py_DECREF around objects you create or borrow.

For example, a C add that parses two PyLong arguments and returns a new PyLong runs at native speed when called from Python.

Design Notes

Reference counts on borrowed versus new references trip up most first extensions. Document whether each helper returns a borrowed reference from a tuple slot or a new reference you must decref.

For This Exercise

This exercise asks you to scaffold a C extension module from scratch. You will implement method definitions, argument parsing with PyArg_ParseTuple, and module initialization so Python can import your native code.

You will use the same mental model here when reading production interpreter source later in the track. Sketch one concrete input on paper, predict the outcome, then confirm with code. That discipline catches logic errors early and makes debugging far faster when you extend the implementation in follow-on tasks.

Your Task

Write the C side of a CPython extension module, fastmath, together with the thin interpreter harness around it. This means:

• a PyMethodDef table and a PyModuleDef;
• PyInit_fastmath;
• the method functions;
• a PyArg_ParseTuple supporting the l (C long) and s (C string) units, which raises CPython's exact TypeError/OverflowError messages.

A C function signals an error the CPython way: it sets an exception and returns NULL. The harness then prints Type: message.

Input

One Python-like line at a time:

cCopy
Loading…

The module

The docs are printed with repr like any other string:

• the module: Fast integer helpers;
• add(a, b): sum of two C longs;
• power(base, exp): integer power;
• repeat(s, n): s repeated n times;
• version(): module version;
• typename(obj): name of the object's type.

Rules

• import: import fastmath runs PyInit_fastmath once and prints PyInit_fastmath() -> <module 'fastmath'> with 5 methods. A second import prints nothing, because sys.modules caches it. Using fastmath before importing it raises NameError: name 'fastmath' is not defined. Other modules raise ModuleNotFoundError: No module named 'X', and any other name raises a NameError.
• PyArg_ParseTuple:
  • wrong count: add() takes exactly 2 arguments (1 given);
  • l given a float: integer argument expected, got float;
  • l given another non-int: an integer is required (got type str);
  • l given an int outside a 64-bit C long: OverflowError: Python int too large to convert to C long;
  • s given a non-str: repeat() argument 1 must be str, not int (not None for None).
• Flags:
  • METH_NOARGS given arguments: version() takes no arguments (1 given);
  • METH_O given anything other than one argument: typename() takes exactly one argument (0 given).
• Other errors: an unknown method raises AttributeError: module 'fastmath' has no attribute 'X', and malformed lines print SyntaxError: invalid syntax.
• Output: results use Python repr. Strings are single-quoted, unless they contain ' and no ", in which case they are double-quoted. fastmath prints <module 'fastmath'> and fastmath.power prints <built-in function power>.

Example

Input:

cCopy
Loading…

Output:

cCopy
Loading…

Requirements

1. Dispatch through the method table and its ml_flags, as PyCFunction call slots do. Don't special-case method names in the call path.
2. Errors travel as NULL return + exception set. The caller checks the return value, and never the other way round.

Hidden tests cover C long boundaries (LONG_MIN passes, one past it overflows), power edge cases (0**0, (-1)**odd, (-2)**63), wrong argument types including None, METH_O/METH_NOARGS count errors, the doc strings, and unknown modules or attributes.