Cython Writer¶

The Cython writer generates .pxd declaration files from headerkit IR. It supports the full range of C and C++ declarations including structs, enums, functions, typedefs, namespaces, templates, and operator aliasing. Python and Cython keywords are automatically escaped with a _ suffix and a C name alias.

Writer Class¶

CythonWriter ¶

CythonWriter(*, stub_cimport_prefix='headerkit.stubs')

Bases: BaseWriter

Writer that converts Header IR into Cython .pxd declarations.

Example::

from headerkit.writers import get_writer

writer = get_writer("cython")
pxd_string = writer.write(header)

write ¶

write(header)

Convert header IR to Cython .pxd string.

hash_comment_format ¶

hash_comment_format()

Return format string for wrapping TOML cache metadata in Cython comments.

Convenience Function¶

write_pxd ¶

write_pxd(header, *, stub_cimport_prefix='headerkit.stubs')

Convenience function to convert a Header IR to Cython .pxd format.

Parameters:

Name	Type	Description	Default
`header`	`Header`	The Header IR to convert	required
`stub_cimport_prefix`	`str \| None`	If set, emit cimport lines for stub types (e.g., "headerkit.stubs" -> "from headerkit.stubs.stdarg cimport va_list"). Defaults to "headerkit.stubs". Pass None to suppress stub cimports.	`'headerkit.stubs'`

Returns:

Type	Description
`str`	The generated .pxd file contents as a string

Internal Writer¶

The PxdWriter class handles the actual conversion logic. It is created internally by CythonWriter and write_pxd.

PxdWriter ¶

PxdWriter(header, *, stub_cimport_prefix='headerkit.stubs')

Writes IR to Cython .pxd format.

Converts a :class:~headerkit.ir.Header containing parsed C/C++ declarations into valid Cython .pxd syntax. Handles keyword escaping, stdint imports, topological sorting, circular dependency detection, C++ namespaces, templates, operator aliasing, and automatic cimport generation.

Parameters:

Name	Type	Description	Default
`header`	`Header`	The parsed header to convert.	required

write ¶

write()

Convert IR Header to Cython .pxd string.

The body is rendered before the cimport header. A cimport is only correct when the type it names actually reaches the output, and for bool that decision is taken inside :meth:_format_ctype while a declaration is being formatted. Rendering first is what lets the header state what the body really emitted rather than what the IR merely mentioned.

Example¶

from headerkit.backends import get_backend
from headerkit.writers import get_writer

backend = get_backend()
header = backend.parse("""
typedef struct {
    int x;
    int y;
} Point;

int distance(const Point* a, const Point* b);
""", "geometry.h")

writer = get_writer("cython")
print(writer.write(header))

Output:

cdef extern from "geometry.h":

    ctypedef struct Point:
        int x
        int y

    int distance(const Point* a, const Point* b)