API Reference¶

Note (v0.90): The core module has been reorganized. For the new API structure, see Dependency Injection Guide and Import Migration Guide.

This page provides an overview of the public API surface of Cullinan and clarifies which APIs are recommended and which stay in advanced runtime-facing layers.

Need the recommended learning path first? Start from Application Build and Framework Semantics.
Need advanced runtime internals? Continue in Internals & Extensions.

API layering¶

Recommended default API¶

cullinan — top-level application API for regular business projects:
startup: @application, configure(...), run(...), get_asgi_app(...)
declaration: @service, @controller, @module (advanced boundary), route decorators
injection / params: Inject, InjectByName, Path, Query, Body, ...
framework mental model: decorator-first business code, component discovery, IoC/DI wiring, and module boundaries with hot-pluggable runtime semantics

Advanced integration API¶

cullinan.application — advanced public application semantics for maintainers and framework-aware integrations (Application, Runtime, module)
cullinan.transport.adapter — server integration (WebAdapter, TornadoAdapter, ASGIAdapter)
cullinan.web.gateway — request / response / dispatcher contracts
cullinan.core — low-level container and lifecycle primitives

These advanced modules are not the default application-facing mental model. Regular business code should stay on the top-level cullinan API and the framework's own decorator / DI / module semantics rather than dropping into low-level runtime orchestration or a concrete server adapter.

For regular applications, prefer the top-level cullinan API. Advanced modules should be imported explicitly so the boundary stays visible in code review, IDE completion, and onboarding docs.

New in v0.90+: Parameter System¶

The parameter system provides type-safe request parameter handling. See Parameter System Guide for details.

cullinan.web.params (v0.90a4+)¶

Symbol	Type	Description
`Param`	class	Base parameter class
`Path`	class	URL path parameter marker
`Query`	class	Query string parameter marker
`Body`	class	Request body parameter marker
`Header`	class	HTTP header parameter marker
`File`	class	File upload parameter marker
`RawBody`	class	Raw unparsed request body, use `bytes = RawBody()` (v0.90a5+)
`UNSET`	sentinel	Sentinel value for unset parameters
`TypeConverter`	class	Type conversion utility
`Auto`	class	Auto type inference utility
`AutoType`	class	Auto type marker for signatures
`DynamicBody`	class	Dynamic request body container
`SafeAccessor`	class	Chain-safe property accessor
`EMPTY`	sentinel	Empty value sentinel
`ParamValidator`	class	Parameter validation utility
`ValidationError`	exception	Validation error
`ModelResolver`	class	dataclass model resolution
`ModelError`	exception	Model resolution error
`ParamResolver`	class	Parameter resolution orchestrator
`ResolveError`	exception	Parameter resolution error

cullinan.web.params (v0.90a5+)¶

Symbol	Type	Description
`FileInfo`	class	File metadata container
`FileList`	class	Multiple files container
`field_validator`	decorator	Dataclass field validator
`validated_dataclass`	decorator	Auto-validating dataclass
`FieldValidationError`	exception	Field validation error
`Response`	decorator	Response model decorator
`ResponseModel`	class	Response model definition
`ResponseSerializer`	class	Response serialization utility
`serialize_response`	function	Convenience serialization function
`get_response_models`	function	Get response models from function

cullinan.web.params.model_handlers (v0.90a5+)¶

Pluggable model handler architecture for third-party library integration.

Symbol	Type	Description
`ModelHandler`	class	Abstract base class for model handlers
`ModelHandlerError`	exception	Model handler error
`ModelHandlerRegistry`	class	Registry for model handlers
`DataclassHandler`	class	Built-in dataclass handler
`PydanticHandler`	class	Optional Pydantic handler (if installed)
`get_model_handler_registry()`	function	Get global handler registry
`reset_model_handler_registry()`	function	Reset registry (testing)

cullinan.codec¶

Symbol	Type	Description
`BodyCodec`	class	Abstract request body codec
`ResponseCodec`	class	Abstract response codec
`JsonBodyCodec`	class	JSON body decoder
`JsonResponseCodec`	class	JSON response encoder
`FormBodyCodec`	class	Form body decoder
`CodecRegistry`	class	Codec registry
`get_codec_registry()`	function	Get global codec registry
`reset_codec_registry()`	function	Reset codec registry (testing)
`DecodeError`	exception	Decoding error
`EncodeError`	exception	Encoding error
`CodecError`	exception	Base codec error

cullinan.web.middleware (new additions)¶

Symbol	Type	Description
`BodyDecoderMiddleware`	class	Auto body decoding middleware
`get_decoded_body()`	function	Get decoded request body
`set_decoded_body()`	function	Set decoded body (testing)

Public symbols and signatures (recommended structure)¶

For each module, the API reference is recommended to follow this structure:

Module path, for example: cullinan.web.controller
Short description: primary responsibility and typical usage scenarios
List of public classes and functions (example):
@controller(...) — Controller decorator, responsible for auto-registering controllers and their routes
@get_api(url=..., query_params=..., body_params=..., headers=...) — GET endpoint decorator
@post_api(url=..., body_params=..., headers=...) — POST endpoint decorator
Inject, InjectByName — Property/constructor injection markers

A complete API reference can be populated using this structure, either via automated generation or by manual curation.

Regenerating API documentation (example workflow)¶

When adding automation later, a static analysis script can be used to generate the API index and keep this page in sync with the source. A typical workflow might be:

Maintain a script under docs/work/ (for example generate_api_reference.py) that scans modules and emits Markdown fragments.
Have the script produce a per-module API list (classes, functions, signatures, short descriptions) into docs/work/api_modules.md or update this page directly.
Run the script periodically in CI or as part of local documentation build steps to ensure the API reference reflects the current codebase.

The exact tooling and script implementation can be refined based on project conventions and the chosen documentation toolchain.