Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

Python version PyPI version PyPI downloads Ask DeepWiki GitHub stars License

   _____      _ _ _
  / ____|    | | (_)
 | |    _   _| | |_ _ __   __ _ _ __
 | |   | | | | | | | '_ \ / _` | '_ \
 | |___| |_| | | | | | | | (_| | | | |
  \_____\__,_|_|_|_|_| |_|\__,_|_| |_|

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 - @module expresses 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 - @module is 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 - cullinan for recommended public startup and declaration, cullinan.web for controllers, route decorators, request/response, parameters, and middleware, cullinan.core for IoC/DI, lifecycle, context, and semantic rules, cullinan.testing for test-facing helpers.
  • Advanced surfaces stay explicit - cullinan.application for maintainers and framework-aware integrations, cullinan.runtime / cullinan.transport for discovery and adapter boundaries, and cullinan.support for 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:

  1. examples/minimal_app/ - shortest public entrypoint
  2. examples/controller_service_inject/ - service/controller layering with Inject()
  3. examples/middleware_and_module/ - @module boundaries and middleware semantics
  4. examples/middleware_control/ - turn the built-in middleware layer off or replace it, and unify legacy @middleware ordering with @configure(...)
  5. examples/parameter_handling/ - method-level Path, Query, and Body
  6. examples/testing_flow/ - public-API testing with get_asgi_app()

Then move into the documentation knowledge base:


Documentation

English

Chinese


Current series

v0.96a6 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 follows the alpha line, while v0.95 stays the stable one.

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.



License

MIT License - see LICENSE for details.

Metadata

Release files for cullinan 0.96a6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cullinan 0.96a6
File Size Uploaded Provenance Actions
cullinan-0.96a6.tar.gz 254.9 kB Without provenance Details for cullinan-0.96a6.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cullinan 0.96a6
File Interpreter ABI Platform Actions
cullinan-0.96a6-py3-none-any.whl Python 3 none any Details for cullinan-0.96a6-py3-none-any.whl

Total release size: 562.0 kB

Release files / cullinan-0.96a6.tar.gz

Download URL cullinan-0.96a6.tar.gz
Size 254.9 kB
Tags Source
SHA-256 checksum
How to use checksums
d05a105796264b9357a2eb4140a8b28a63fdc5ba488db2a6570971157b16d837
BLAKE2b-256 checksum
How to use checksums
449ec0afd5a358e87467a9cb405a09c23f917266d26ad7dbcbc8efbddc5c85e2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / cullinan-0.96a6-py3-none-any.whl

Download URL cullinan-0.96a6-py3-none-any.whl
Size 307.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
95f1f873c06a495e1a7a7d0bd28ecf1cf7fbe13514e57e863bb01c3c0cbae71b
BLAKE2b-256 checksum
How to use checksums
03335d3264585e40c80c07fbb2096a86ae30f6a1ab34a57d35f0882001db7d44
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for cullinan 0.96a6

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.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page