Writers

Writers convert HeaderKit IR into various output formats, from single-file binding modules to multi-file package scaffolding. Concrete writers inherit from BaseWriter (which satisfies the WriterBackend protocol).

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()
cshim	headerkit.writers.cshim	Pure C-ABI wrappers (extern "C") for C++ classes and APIs
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
mojo	headerkit.writers.mojo	Idiomatic Mojo FFI bindings with sys.ffi.DLHandle and CShim bridge
nim	headerkit.writers.nim	Native Nim bindings with C and C++ interop
prompt	headerkit.writers.prompt	Token-optimized LLM context (compact/standard/verbose)

Base Class & Protocol

BaseWriter

Base class providing unified layout generation for all output writers.

write_layout

write_layout(unit, options=None)

Convert parsed unit IR into a complete ProjectLayout.

write

write(header)

Convert parsed header IR to the target output format.

Delegates to write_layout(layout='file') to satisfy the Zero-Dual-System Rule.

WriterOption dataclass

WriterOption(name, description, default=None, choices=None, type=str)

Specification of a writer-configurable option or parameter.

coerce

coerce(val)

Coerce a raw value (e.g. from CLI string) to this option's expected type.

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.

write_layout

write_layout(unit, options=None)

Convert parsed unit IR into a complete ProjectLayout.

Parameters:

Name	Type	Description	Default
unit	SourceUnit | Header	Parsed unit IR from a parser backend.	required
options	ScaffoldOptions | None	Scaffolding configuration options.	None

Returns:

Type	Description
ProjectLayout	ProjectLayout containing all generated files.

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

list_writer_layouts

list_writer_layouts(name)

Return the tuple of layouts supported by the named writer.

Parameters:

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

Returns:

Type	Description
tuple[str, ...]	Tuple of supported layout names (e.g. ("file", "package")).

Raises:

Type	Description
ValueError	If the requested writer is not found.

list_writer_options

list_writer_options(name)

Return the tuple of options supported by the named writer.

Parameters:

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

Returns:

Type	Description
tuple[WriterOption, ...]	Tuple of WriterOption specifications.

Raises:

Type	Description
ValueError	If the requested writer is not found.

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, priority=STANDARD)

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
priority	int	Execution priority for hook dispatch.	STANDARD

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.