What's New in 1.2¶
1.2 adds four extension packages beside the core. The core itself has two fixes; the first changes what one way of writing a subclass does, so it comes first. Nothing else needs changing.
For the current release, see What's New in 1.3; for earlier ones, What's New in 1.1 and What's New in 1.0.
Behaviour fix: overriding a dependency by name replaces it¶
Dependencies now resolve by attribute name, as hooks already did. Write another dep() under
the same name in a subclass and the base class's is replaced:
class Service(Canary):
store = dep(SqlStore)
class TestService(Service):
store = dep(MemoryStore) # 1.1: SqlStore was still built and started. 1.2: only MemoryStore.
Override the name with something that is not a dep() and the dependency is dropped. If your
code relied on the old behaviour — expecting the base class's dependency to start in the
subclass as well — give it an attribute name of its own.
Extension packages¶
Four extensions ship with the core and share its version number. The core imports none of
them, and import canary_framework still loads no third-party package; install the ones you
use.
| Package | What it is | Install |
|---|---|---|
canary_framework.test |
Start a graph on test doubles; reach a unit by type | with the core |
canary_framework.config |
pydantic-settings configuration that is also a unit | canary-framework[config] |
canary_framework.web.asgi.app |
Application units: a small web framework | canary-framework[app] |
canary_framework.web.asgi.server |
The server unit: listening as part of the lifecycle | canary-framework[server] |
canary-framework[web] installs both the application and the server side.
They are provisional for now: until each is declared stable its API may change in a minor release; see Versioning & Compatibility.
An example¶
from canary_framework import dep
from canary_framework.config import Settings
from canary_framework.test import running
from canary_framework.web.asgi.app import App, Router, get
from canary_framework.web.asgi.server import Server
class AppConfig(Settings):
greeting: str = "hello"
class ReaderApi(Router, prefix="/readers"):
config = dep(AppConfig)
@get("/{reader_id}")
async def show(self, reader_id: int) -> Reader:
return Reader(id=reader_id, name=self.config.greeting)
class LibraryApi(App):
readers = dep(ReaderApi)
class Gateway(Server):
api = dep(LibraryApi)
port = 8010
async with Gateway(): # binding the port is @start, closing it is @stop
...
async with running(Gateway, {AppConfig: AppConfig(greeting="hi")}) as gateway:
... # a test: the whole graph on another configuration
Routers and the application are units, and dependencies are dep(). An application unit is
itself an ASGI application, so it also runs without Server — uvicorn main:app — and
Server in turn serves any ASGI application, a FastAPI object included.
Application units generate no OpenAPI, but App.endpoints exposes the flattened endpoint
table, from which writing one takes a few dozen lines; see
Web Application › The endpoint table.
Also in 1.2¶
Scope.entered(phase)always lists dependencies first. Callingstop()on a graph that had been initialised but never started used to leave it root first after the nextstart().- Two new sections in Patterns: Several instances of one kind and Shutting down in two steps.
benchmarks/web.pyload-tests the same endpoints written as application units and as FastAPI, scenario by scenario.- Development: the
devextra now pulls in the extensions' dependencies, and a newtestextra holds only what the core's tests need; CI also runs the core's tests in an environment without those dependencies. - The full list is in the changelog.