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.2.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.2.0
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)

Table of built distributions (wheels) for canary-framework 1.2.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

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

Select from 2 files

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