Writers

Writers convert headerkit IR into various output formats. The WriterBackend protocol defines the interface that all writers implement.

Writers are accessed through a registry that mirrors the backend registry. Use get_writer() to obtain an instance and list_writers() to discover what is available.

Available Writers

Writer	Module	Description
cffi	headerkit.writers.cffi	CFFI cdef declarations for ffibuilder.cdef()
ctypes	headerkit.writers.ctypes	Python ctypes binding modules
cython	headerkit.writers.cython	Cython .pxd declarations with full C++ support
diff	headerkit.writers.diff	API compatibility reports (JSON/Markdown)
json	headerkit.writers.json	JSON serialization for inspection and tooling
lua	headerkit.writers.lua	LuaJIT FFI bindings
prompt	headerkit.writers.prompt	Token-optimized LLM context (compact/standard/verbose)

Protocol

WriterBackend

Bases: Protocol

Protocol defining the interface for output writers.

Writers convert headerkit IR (Header objects) into various output formats: CFFI cdef strings, JSON, PXD files, ctypes code, etc.

Writer-specific options (e.g. exclude_patterns for CFFI, indent for JSON) are constructor parameters or dataclass fields on the concrete class -- NOT part of the write() signature. This keeps the protocol simple and mypy-strict compatible.

Example

::

from headerkit.writers import get_writer

writer = get_writer("cffi")
output = writer.write(header)

name property

name

Human-readable name of this writer (e.g., "cffi").

format_description property

format_description

Short description of the output format.

write

write(header)

Convert parsed header IR to the target output format.

Writers should produce best-effort output, silently skipping declarations they cannot represent. Writers must not raise exceptions for valid Header input.

Parameters:

Name	Type	Description	Default
header	Header	Parsed header IR from a parser backend.	required

Returns:

Type	Description
str	String representation in the target format.

Registry Functions

get_writer

get_writer(name=None, **kwargs)

Get a writer instance.

Keyword arguments are forwarded to the writer constructor, allowing per-invocation configuration::

writer = get_writer("cffi", exclude_patterns=["__.*"])

Parameters:

Name	Type	Description	Default
name	str | None	Writer name, or None for the default writer.	None
kwargs	object	Forwarded to writer class constructor.	{}

Returns:

Type	Description
WriterBackend	New instance of the requested writer.

Raises:

Type	Description
ValueError	If the requested writer is not available.

get_default_writer

get_default_writer()

Get the name of the default writer.

Returns:

Type	Description
str	Writer name (e.g., "cffi").

Raises:

Type	Description
ValueError	If no writers are available.

list_writers

list_writers()

List names of all registered writers.

::

from headerkit.writers import list_writers

for name in list_writers():
    print(f"Available: {name}")

Returns:

Type	Description
list[str]	List of writer names that can be passed to :func:get_writer. Example

is_writer_available

is_writer_available(name)

Check if a writer is available for use.

Parameters:

Name	Type	Description	Default
name	str	Writer name to check.	required

Returns:

Type	Description
bool	True if the writer is registered and can be instantiated.

register_writer

register_writer(name, writer_class, is_default=False, description=None)

Register an output writer.

Called by writer modules during import to self-register. The first registered writer becomes the default unless is_default is explicitly set on a later registration.

Parameters:

Name	Type	Description	Default
name	str	Writer name used in :func:get_writer lookups.	required
writer_class	type[WriterBackend]	The writer class implementing :class:WriterBackend.	required
is_default	bool	If True, this writer becomes the default.	False
description	str | None	Optional short description for :func:get_writer_info. If not provided, falls back to the class docstring's first line.	None

get_writer_info

get_writer_info()

Get information about all known writers.

Returns metadata from the registry without instantiating any writer. Uses descriptions stored by :func:register_writer, falling back to the class docstring's first line if no description was provided.

.. note:: Keys differ from :func:~headerkit.backends.get_backend_info: uses "is_default" (not "default"), and omits the "available" key (writers have no external dependencies that could make them unavailable).

Returns:

Type	Description
list[dict[str, str | bool]]	List of dicts with keys: name, description, is_default.