Skip to main content

Canary Framework

Dependency injection and lifecycle for plain Python classes — standard library only, zero dependencies.

CI PyPI Python License

中文 · 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.config is a Config, async with service yields your type, and dep(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_framework loads 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

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.3.0

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

Source distribution (sdist)

Source distribution for canary-framework 1.3.0
File Size Uploaded Provenance Actions
canary_framework-1.3.0.tar.gz 103.1 kB With provenance Details for canary_framework-1.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for canary-framework 1.3.0
File Interpreter ABI Platform Actions
canary_framework-1.3.0-py3-none-any.whl Python 3 none any Details for canary_framework-1.3.0-py3-none-any.whl

Total release size: 170.3 kB

Release files / canary_framework-1.3.0.tar.gz

Download URL canary_framework-1.3.0.tar.gz
Size 103.1 kB
Tags Source
SHA-256 checksum
How to use checksums
1cee285f673ecdd950a235af78dcc9e01e5b39c0b0a81fa2bec9dc2917521af9
BLAKE2b-256 checksum
How to use checksums
7339b26821d6f338363b82bd59c689ad0ccdea2a74a8e2ee7289bcd3ec4f8d86
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 2, 2026.

Transparency log

Release files / canary_framework-1.3.0-py3-none-any.whl

Download URL canary_framework-1.3.0-py3-none-any.whl
Size 67.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fc61ee44a5031605943ad4e806c4169df3761163e5e4236091ef647d569da168
BLAKE2b-256 checksum
How to use checksums
02b1130eb40e40a87cc804e90ba38866e01efdd736c805338d6dd88ce583e972
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 2, 2026.

Transparency log

Security for canary-framework 1.3.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.

Select from 2 files

Attestation for canary_framework-1.3.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 Nov 2, 2026.

Transparency log

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

1.3.0 This release

2 release files Full provenance

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