This release is a pre-release and may not be stable for production use.
_____ _ _ _
/ ____| | | (_)
| | _ _| | |_ _ __ __ _ _ __
| | | | | | | | | '_ \ / _` | '_ \
| |___| |_| | | | | | | | (_| | | | |
\_____\__,_|_|_|_|_| |_|\__,_|_| |_|
Cullinan
A business-first Python web framework for building applications through decorators, module boundaries, and built-in IoC/DI.
Cullinan is a Python Web Framework for developers who want to organize applications around
business services, controllers, and methods instead of manually wiring an app object.
Its default path is decorator-first discovery plus @application + @configure(...),
with @module used as the application boundary when ownership, runtime structure, and stability
matter. The framework-facing API stays engine-neutral:
Cullinan internally bridges your business application into Tornado or ASGI runtimes instead of
making a concrete server framework the primary developer mental model.
What is Cullinan?
Cullinan is designed to make the framework work around your business architecture, not the other way around.
- Business-first application model - write services, controllers, middleware, and methods first
- Decorator-first discovery - let Python imports and decorator metadata assemble the runtime
- Structured module boundaries - use
@moduleto express ownership and runtime boundaries - Built-in IoC/DI and lifecycle - keep application wiring inside the framework model
- Engine-neutral Web facade - build against Cullinan semantics while the framework adapts to Tornado or ASGI internally
- Public semantic path - build, run, test, and extend applications through stable public APIs
Cullinan is not centered on treating an app object as a manual registration hub. The recommended development flow is to declare business components, define a root module when structure matters, and let the framework assemble the application runtime.
Why Cullinan?
1. Framework semantics before manual wiring
Cullinan gives you a clear application model: declare components with decorators, let the framework discover them, and keep explicit runtime internals as an advanced path rather than the default onboarding path.
2. Application boundaries that scale past toy examples
@module is more than a naming convention. It is the structured boundary for owned packages,
runtime composition, and higher-level lifecycle behavior when your application grows.
3. Web, DI, lifecycle, and testing in one model
Routing, parameter binding, dependency injection, lifecycle hooks, middleware, and test flow all sit inside one framework vocabulary instead of forcing developers to stitch together multiple unrelated patterns.
4. A Pythonic path for business applications
Cullinan is designed to keep developers focused on business architecture and business methods. You can stay on the public path for most application work and only move into internals when you intentionally need advanced extension behavior.
5. A clearer semantic package surface
Cullinan now exposes a clearer framework-shaped package surface:
cullinan- recommended public startup and declaration API for application codecullinan.web- controllers, route decorators, request/response, parameters, middlewarecullinan.core- IoC/DI, lifecycle, context, and semantic rulescullinan.application- advanced application semantics for maintainers and framework-aware integrationscullinan.testing- test-facing helperscullinan.runtime/cullinan.transport- advanced discovery and adapter boundariescullinan.support- constrained support utilities, not a second public app path
Framework capabilities
| Capability layer | What Cullinan provides |
|---|---|
| Application composition | @application + @configure(...), decorator-driven discovery, structured runtime assembly |
| Web API model | cullinan.web facade for @controller, RESTful decorators, WebResponse, parameters, middleware |
| Parameter system | Typed Path, Query, Body, validation, conversion, and controller-method binding |
| IoC/DI and lifecycle | Inject(), InjectByName(), request scope, startup/shutdown hooks, component lifecycle |
| Runtime boundaries | @module ownership, clearer package structure, better runtime organization |
| Testing and delivery | get_asgi_app(), resettable registries, packaging-friendly runtime, cross-platform support |
Cullinan's goal is not to expose every internal knob on the README homepage. The goal is to provide a coherent framework model that remains readable from first contact through production use.
Install
Cullinan is published on PyPI and currently supports Python 3.9+.
pip install -U pip
pip install cullinan
After installation, start from the minimal example in examples/minimal_app/
or the repository guide in docs/examples.md.
Quick Start
The recommended starting point is: define business components, decorate them,
and declare the application entry with @configure(...) + @application + main().
from cullinan import application, configure
from cullinan.core import service
from cullinan.web import controller, get_api
@service
class GreetingService:
def greet(self) -> str:
return "Hello from Cullinan!"
@controller(url="/hello")
class HelloController:
greeting_service: GreetingService # constructor injection: one line is all you need
@get_api(url="")
def hello(self):
return {"message": self.greeting_service.greet()}
@configure(user_packages=["minimal_app"], server_port=4080)
@application
def main(): ...
Run it:
python -m minimal_app
Then open:
http://localhost:4080/hello
This example shows the default Cullinan path:
- business service first
- controller methods as the public web surface
@application+@configure(...)+main()as the startup flow@moduleavailable when explicit runtime boundaries are needed- runtime backend selection delegated to Cullinan instead of driving application structure
Learning path
If you are new to Cullinan, use this order:
examples/minimal_app/- shortest public entrypointexamples/controller_service_inject/- service/controller layering withInject()examples/middleware_and_module/-@moduleboundaries and middleware semanticsexamples/middleware_control/- turn the built-in middleware layer off or replace it, and unify legacy@middlewareordering with@configure(...)examples/parameter_handling/- method-levelPath,Query, andBodyexamples/testing_flow/- public-API testing withget_asgi_app()
Then move into the documentation knowledge base:
docs/README.md- English knowledge base homedocs/zh/README.md- Chinese knowledge base homedocs/getting_started.md- recommended application entrydocs/framework_semantics.md- framework concepts and semanticsdocs/examples.md- example navigation page
Documentation
English
- Documentation home
- Getting Started
- Framework Semantics
- Examples
- Dependency Injection Guide
- Web Runtime Guide
- Static Files and SPA Guide
- Parameter System Guide
- Testing & Verification
Chinese
- Documentation home
- Getting Started
- Framework Semantics
- Examples
- Dependency Injection Guide
- Web Runtime Guide
- Static Files and SPA Guide
- Parameter System Guide
- Testing & Verification
Current series
v0.96a2 is the second alpha of the 0.96 line. It closes the gap between what the framework declares and what it actually does:
- component declarations outside the discovery scope are reported at default settings instead of being dropped silently, and the guard meant to catch them can finally fire
- the package ships a machine-readable description of its stability commitment, so whether an import surface is covered can be answered offline, in advance and as a plain yes or no
- deprecation removal windows are anchored to the version a deprecation was announced in, so announced removals arrive instead of sliding forward with every release
cullinan.core.extensionsno longer carries a divergent copy of the support implementation and a second registry with it- commits touching governed paths must carry a change declaration
- the guides state how lifecycle error records are actually surfaced, and how component-discovery diagnostics are actually delivered
- runnable API examples in docstrings are gated, and the local scratch directory can no longer be committed unnoticed
v0.96a1 was the first alpha of the 0.96 line. It closed the capability gaps found in the 0.95 middleware surface and declares the public API stability freeze ahead of the 1.0 milestone:
- a single ordering key for the gateway middleware pipeline, so a middleware declared on the application and one added to the pipeline can be ordered against each other
configure(builtin_middleware=...)to switch the built-in access-log layer off or replace itdrain_timeoutwired to the real shutdown-timeout source, with the default behaviour unchangedRouteGroup.middleware_tagsdeprecated- the 1.0 public API stability freeze declared in the API reference
- engine-neutral wording across the guides, examples and public docstrings
v0.95 remains the current stable line. It is the Phase A convergence cut for the 1.0 roadmap, continuing the v0.94 opt iteration, and locks down the public surface and packaging baseline around:
@application+@configure(...)+main()as the startup flow- decorator-first discovery through Python imports
@moduleas the structured boundary for runtime ownership- built-in IoC/DI, lifecycle, and semantic diagnostics
- a semantic package surface centered on the top-level
cullinanAPI, with advanced semantic namespaces undercullinan.application,cullinan.web, andcullinan.core - engine-neutral runtime selection over Tornado / ASGI backends
pyproject.toml+setuptools.build_metapackaging withsetup.pykept as a compatibility shim- PEP 561 typed-package distribution via
cullinan/py.typed
The v0.94 opt iteration (A1-A4 kernel behavior optimization + B1-B3 mkdocs
mechanism) deprecates legacy compatibility symbols, adds strict
_xxx private-injection and strict lifecycle propagation switches, optimizes
scope validation, and restructures the docs build channel mapping so
origin/preview is the single pre-release authority.
Version-specific details and migration notes live in the documentation knowledge base rather than in the homepage narrative.
Project status
Cullinan is the project name, and cullinan is the package name published on PyPI:
pip install cullinan
Verify the install with a one-line smoke check:
python -c "from cullinan import application, configure; import cullinan; print(cullinan.__version__)"
Maintainer: plumeink.
Project links
- GitHub: https://github.com/cullinan-py/cullinan
- PyPI: https://pypi.org/project/cullinan/
- Issues: https://github.com/cullinan-py/cullinan/issues
- Discussions: https://github.com/cullinan-py/cullinan/discussions
License
MIT License - see LICENSE for details.
Metadata
Release files for cullinan 0.96a2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| cullinan-0.96a2.tar.gz | 233.0 kB | Without provenance | Details for cullinan-0.96a2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| cullinan-0.96a2-py3-none-any.whl | Python 3 | none | any | Details for cullinan-0.96a2-py3-none-any.whl |
Total release size: 516.2 kB
Release files / cullinan-0.96a2.tar.gz
| Download URL | cullinan-0.96a2.tar.gz |
|---|---|
| Size | 233.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9da7905a3685947000d22aaa3223b33b46615035f4419545bc10401ff4d2c267
|
|
BLAKE2b-256 checksum How to use checksums |
2c19182557060c6373799a21b41a7b227349371f05d7e90d20fdfd964c29297b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
Release files / cullinan-0.96a2-py3-none-any.whl
| Download URL | cullinan-0.96a2-py3-none-any.whl |
|---|---|
| Size | 283.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
aee3989aceb5ab65dea997ff2b7926e59f4eebd4c87f784a9dd85df9010ae214
|
|
BLAKE2b-256 checksum How to use checksums |
30698e3ac7ac0b0bea456a0f5e5a0cbf26d82bfcc496b7239d4f0745b02b7bda
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
Security for cullinan 0.96a2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.