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.
Organize your application around business services, controllers, and methods — declare them with decorators and let Cullinan assemble the runtime, instead of wiring an app object by hand.
Quick start
Declare business components with decorators — there is no app object to wire by hand:
from cullinan import application, configure
from cullinan.core import service
from cullinan.web import controller, get_api
@service
class GreetingService:
def greet(self):
return "Hello from Cullinan!"
@controller(url="/hello")
class HelloController:
greeting: GreetingService # injected: no constructor wiring to write
@get_api(url="")
def hello(self):
return {"message": self.greeting.greet()}
@configure(user_packages=["minimal_app"], server_port=4080)
@application
def main(): ...
Save it in a minimal_app/ package, run python -m minimal_app, and open http://localhost:4080/hello.
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.
A one-line smoke check confirms which version you are running:
python -c "from cullinan import application, configure; import cullinan; print(cullinan.__version__)"
What is Cullinan?
Cullinan makes the framework work around your business architecture, not the other way around: you declare services, controllers, and methods, and the framework assembles the runtime.
- Business-first application model - write services, controllers, middleware, and methods first
- Decorator-first discovery - Python imports and decorator metadata assemble the runtime
- Structured module boundaries -
@moduleexpresses 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
The quick-start example shows the default path: a business service first, controller methods as
the public web surface, and @application + @configure(...) + main() as the startup flow.
@module is available when explicit runtime boundaries are needed, and runtime backend selection
is delegated to Cullinan instead of driving application structure.
Why Cullinan?
- Semantics before manual wiring - declare components with decorators and let the framework discover them; explicit runtime internals stay an advanced path rather than the default onboarding path.
- Application boundaries that scale past toy examples -
@moduleis a structured boundary for owned packages, runtime composition, and higher-level lifecycle behavior, not just a naming convention. - Web, DI, lifecycle, and testing in one model - routing, parameter binding, dependency injection, lifecycle hooks, middleware, and test flow share one framework vocabulary instead of several unrelated patterns.
- A Pythonic path for business applications - stay on the public path for most application work and move into internals only when you intentionally need advanced extension behavior.
- A clearer semantic package surface -
cullinanfor recommended public startup and declaration,cullinan.webfor controllers, route decorators, request/response, parameters, and middleware,cullinan.corefor IoC/DI, lifecycle, context, and semantic rules,cullinan.testingfor test-facing helpers. - Advanced surfaces stay explicit -
cullinan.applicationfor maintainers and framework-aware integrations,cullinan.runtime/cullinan.transportfor discovery and adapter boundaries, andcullinan.supportfor constrained support utilities that are 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.
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.96a7.post1 is the current release of the 0.96 line; v0.95 remains the current stable line, centered on the top-level cullinan API.
The release history for earlier versions is recorded in CHANGELOG.md.
Project status
Cullinan — the project carries the name Cullinan, the package on PyPI is
cullinan — is under active development, working through the 0.96 alpha
line towards 1.0. Alphas are published to PyPI as they land, so
pip install cullinan installs the stable line (v0.95 today) and
pip install --pre cullinan installs the newest alpha. Ask for the alphas
explicitly; pip will not choose one for you while a stable release exists.
Development is driven by plumeink, who reads and answers issues and pull
requests as time allows — usually within a week, though real life occasionally
stretches that.
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.96a7.post1
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.96a7.post1.tar.gz | 251.5 kB | Without provenance | Details for cullinan-0.96a7.post1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| cullinan-0.96a7.post1-py3-none-any.whl | Python 3 | none | any | Details for cullinan-0.96a7.post1-py3-none-any.whl |
Total release size: 554.8 kB
Release files / cullinan-0.96a7.post1.tar.gz
| Download URL | cullinan-0.96a7.post1.tar.gz |
|---|---|
| Size | 251.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a020271505cfca11913df931aa6b8977ea1b651f5a845b5a1693516eb792df16
|
|
BLAKE2b-256 checksum How to use checksums |
a372fc9c4d7b57bdaa044311a2fc3b4214f730bae2262e885702804ac5425fbc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.17
|
Release files / cullinan-0.96a7.post1-py3-none-any.whl
| Download URL | cullinan-0.96a7.post1-py3-none-any.whl |
|---|---|
| Size | 303.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1ab8b34245a05e2bd3021b3e0a50b851eeac2231cba433c03e28bfba53fbc242
|
|
BLAKE2b-256 checksum How to use checksums |
32fc65c2439ed793d7016117b6d0ae4636a98cabc58d93f5a459c2956765fba3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.17
|
Security for cullinan 0.96a7.post1
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.