Canary Framework
Dependency injection and lifecycle for plain Python classes — standard library only, zero dependencies.
中文 · Documentation · Changelog
Install
pip install canary-framework
Requires Python 3.12 or newer. Installing pulls in no third-party packages.
The model
Subclass Canary and you have a unit: it declares what it depends on with dep(), and
what it does in each phase with @init / @start / @stop. Start one unit and its
dependencies come up in dependency order; leaving reclaims them in reverse.
import asyncio
from canary_framework import Canary, dep, init, start, stop
class Config(Canary):
@init
def load(self) -> None:
self.dsn = "postgresql://localhost/dev"
class Database(Canary):
config = dep(Config)
@start
async def connect(self) -> None:
print(f"connecting to {self.config.dsn}")
@stop
async def close(self) -> None:
print("disconnected")
class UserService(Canary):
database = dep(Database)
async def main() -> None:
async with UserService() as service:
print(service.database.config.dsn)
asyncio.run(main())
connecting to postgresql://localhost/dev
postgresql://localhost/dev
disconnected
Two rules
Entering runs dependencies first: a unit enters a phase only after its dependencies have completed it. One unit runs one phase exactly once no matter how many units depend on it, and independent units enter concurrently.
Releasing runs the unit first: stopping a unit stops it — unless something still uses it —
then tries its dependencies the same way, so what nothing else uses goes down with it. A failed
start() releases what it brought up before it raises.
Both run on the dependency graph, built before any hook runs — which is also where cycles are caught.
init / start / stop are three names for these two rules. Adding a fourth phase is one
line: Phase("migrate", after=init).
Highlights
- Typed end to end.
self.configis aConfig,async with serviceyields your type, anddep(SomethingElse)is a type error. No plugin required. - Plain classes. Decorators only mark methods; units stay subclassable, mixable, nestable,
and lifecycle methods can be overridden with
super(). - Failure paths are part of the design. A failing
start()releases what it started;stop()is the single reclamation path, shared by success and failure, and is idempotent. A stopped graph starts again; a failed enter can be retried. - Test doubles without mocks.
scope_of(service).provide(Database, FakeDatabase())swaps a dependency across the whole graph, and the double runs its own lifecycle. - Concurrent by default. Independent units start together and stop together, scheduled by the dependency graph.
- Zero dependencies. A test asserts that
import canary_frameworkloads no third-party package, and none of the extensions.
Hosting
The core knows nothing about shells — HTTP, CLI, schedulers and consumers are all yours:
@asynccontextmanager
async def lifespan(_app: FastAPI):
async with service:
yield
app = FastAPI(lifespan=lifespan)
Extensions
Four optional packages sit beside the core. The core never imports them, so
pip install canary-framework stays dependency-free.
| Package | What it is | Install |
|---|---|---|
canary_framework.test |
running() and unit() — start a graph on test doubles |
included |
canary_framework.config |
Settings — a pydantic-settings model that is a unit |
canary-framework[config] |
canary_framework.web.asgi.app |
Application units — a small web framework whose application is itself an ASGI app, for any ASGI server | canary-framework[app] |
canary_framework.web.asgi.server |
The server unit — listening is part of the lifecycle, and it serves any ASGI app | canary-framework[server] |
canary-framework[web] installs the last two together.
from canary_framework import dep
from canary_framework.web.asgi.app import App, Router, get
from canary_framework.web.asgi.server import Server
class ReaderApi(Router, prefix="/readers"):
readers = dep(ReaderService)
@get("/{reader_id}")
async def show(self, reader_id: int) -> Reader:
return await self.readers.get(reader_id)
class LibraryApi(App):
readers = dep(ReaderApi)
class Gateway(Server):
api = dep(LibraryApi) # another application unit here would share the port
port = 8010
async with Gateway(): # dependencies start, then it listens
...
The application and the server know only the ASGI protocol, so they also work apart:
app = LibraryApi() then uvicorn main:app, or a Server serving a FastAPI application.
Extensions are provisional: their API may still change in a minor release.
Stability
1.0 is the first stable release. The public API follows Semantic Versioning: no breaking changes before 2.0, and removals are deprecated for at least one minor release first.
Documentation
- Why Canary — where it fits,
where it does not, and a measured comparison with dishka, dependency-injector, injector and
FastAPI
Depends - Documentation — What's new in 1.2, patterns, upgrading from 0.9.x
- Complete examples — five projects of deliberately different shapes, from an HTTP API to a
long-running daemon:
Canary-Framework-Example
(checked out at
examples/as a submodule)
Community
Questions and ideas go to Discussions, bugs to Issues. See CONTRIBUTING, GOVERNANCE and SECURITY.
License
Apache-2.0. See LICENSE.
Metadata
Release files for canary-framework 1.2.0
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 |
|---|---|---|---|---|
| canary_framework-1.2.0.tar.gz | 94.9 kB | With provenance | Details for canary_framework-1.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| canary_framework-1.2.0-py3-none-any.whl | Python 3 | none | any | Details for canary_framework-1.2.0-py3-none-any.whl |
Total release size: 157.4 kB
Release files / canary_framework-1.2.0.tar.gz
| Download URL | canary_framework-1.2.0.tar.gz |
|---|---|
| Size | 94.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
36c9df1eb25b1325c1368f256c047743c6d1a0599b0052b9ea3c36ccb6076115
|
|
BLAKE2b-256 checksum How to use checksums |
b48677c5472f17226a3fd9a68f6aac2f7a03d4b8914adc00c6e6d5c73dc72bd7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.
Transparency logRelease files / canary_framework-1.2.0-py3-none-any.whl
| Download URL | canary_framework-1.2.0-py3-none-any.whl |
|---|---|
| Size | 62.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d1aea7308a47cec6263cf8d8b6b8e644c8b0c0dc0c6043f112525c8c3eaf32ec
|
|
BLAKE2b-256 checksum How to use checksums |
a45df239111906063ad09a34fddb720e55495487f37556a078866454b5911abd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.
Transparency logSecurity for canary-framework 1.2.0
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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for canary_framework-1.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.
Transparency logA 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.