跳转至

常见用法

常见任务的写法,只用 Canary、dep() 与阶段。

测试替身

继承要替换的单元,在生命周期开始之前把实例登记进作用域。之后图中所有 dep(Database) 都 取回这个替身:

import pytest

from canary_framework import scope_of


class FakeDatabase(Database):
    @start
    async def connect(self) -> None:
        self.rows: list[dict] = []

    @stop
    async def close(self) -> None: ...


@pytest.fixture
async def service():
    service = UserService()
    scope_of(service).provide(Database, FakeDatabase())
    async with service:
        yield service


async def test_register(service: UserService) -> None:
    await service.register("ada")
    assert service.database.rows == [{"name": "ada"}]

替身运行自己的钩子,进入自己的类声明的依赖。规则见单元 › 替身。

按配置选择实现

连接到什么由单元自己决定。从依赖中读取配置,在 @start 里选择实现:

import os


class Settings(Canary):
    @init
    def load(self) -> None:
        self.backend = os.environ.get("DB_BACKEND", "sqlite")
        self.url = os.environ.get("DB_URL", "app.db")


class Database(Canary):
    settings = dep(Settings)
    driver: Driver | None = None

    @start
    async def connect(self) -> None:
        match self.settings.backend:
            case "postgres":
                self.driver = PostgresDriver(self.settings.url)
            case "sqlite":
                self.driver = SqliteDriver(self.settings.url)
            case other:
                raise ValueError(f"unknown DB_BACKEND: {other}")
        await self.driver.open()

    @stop
    async def close(self) -> None:
        if self.driver is not None:
            await self.driver.close()

其余单元只依赖 Database,不需要知道背后是哪个实现。

各个实现应在钩子里构造,而不是各自用 dep() 声明:依赖是静态的,声明过的单元无论是否 用到都会被启动。

同一种东西的多个实例

一张图里每个类型一个实例,而子类是另一个类型。需要固定的几个同类实例时,各写一个子类:

class Database(Canary):
    dsn = "postgresql://primary/app"

    @start
    async def connect(self) -> None:
        self.pool = await open_pool(self.dsn)

    @stop
    async def close(self) -> None:
        await self.pool.close()


class Replica(Database):
    dsn = "postgresql://replica/app"


class ReportService(Canary):
    primary = dep(Database)
    replica = dep(Replica)

Database 与 Replica 是两个单元:各有一个实例,各自运行继承来的钩子,各自被回收。

数量要到运行时才知道的情形(按配置起 N 个)不能这样表达——依赖是写在类上的。这时由一个单元 在自己的 @start 里创建并持有它们。

执行到一半失败的钩子

执行到一半抛出的 @start 会立即运行本单元的 @stop,start() 随后释放它启动的依赖。 @stop 应只释放实际获取到的资源——上例中 driver 默认为 None 正是为此。

钩子里的阻塞操作

同步钩子在事件循环里执行。耗时的同步钩子会拖住所有与它一起进入的单元,而不只是依赖它的 单元。把阻塞调用放到线程里:

class Index(Canary):
    @init
    async def build(self) -> None:
        self.index = await asyncio.to_thread(build_index, self.corpus.path)

很快就能完成的同步钩子——读一个配置、构造一个小对象——保持原样即可。

限时关闭

stop() 等待每个 @stop 完成——依赖者在前,互不依赖的单元同时进行——也会等待仍在进行的 start()。需要给关闭设期限时,用 asyncio.timeout 包住它:

try:
    async with asyncio.timeout(10):
        await service.stop()
except TimeoutError:
    log.warning("shutdown timed out")

到期时正在执行的钩子被取消,不会重试。还没轮到的单元仍持有它获取的东西,再调用一次 stop() 会从那里继续回收。

分两步停机

守护进程的停机常常不是一步:先停止接收新的工作,把在途的做完,然后才回收资源。@stop 只能 表达后一半。前一半用一对自定义阶段,离开它时本单元在前——根先关闸,再轮到下面的单元排空:

from canary_framework import Canary, Phase, dep, enter, leave, start, stop

drain = Phase("drain")
serving = Phase("serving", after=start, leave=drain)


class Worker(Canary):
    queue = dep(Queue)

    @drain
    async def finish(self) -> None:
        await self.queue.join()             # 把在途的做完

    @stop
    async def cancel(self) -> None:
        self.task.cancel()


class Daemon(Canary):
    worker = dep(Worker)

    async def start(self) -> None:
        await super().start()
        await enter(self, serving)

    async def stop(self) -> None:
        await leave(self, serving)          # @drain,本单元在前
        await super().stop()                # @stop

    @drain
    def refuse(self) -> None:
        self.accepting = False              # 不再接新的

async with Daemon() 与直接调用 start() / stop() 都会经过这两个覆盖的方法。停机的顺序是 Daemon.refuse → Worker.finish → Worker.cancel → 队列的 @stop。leave(self, serving) 不动 start,所以排空期间整张图仍然是启动着的;重复调用 stop() 是空操作,重启之后 serving 会重新进入。

接入宿主

框架不认识任何外壳。宿主接收异步上下文管理器时:

from contextlib import asynccontextmanager

from fastapi import FastAPI

service = UserService()


@asynccontextmanager
async def lifespan(_app: FastAPI):
    async with service:
        yield


app = FastAPI(lifespan=lifespan)

宿主接收启停回调时,交给它单元的方法:

scheduler.on_startup(service.init, service.start)
scheduler.on_shutdown(service.stop)

脚本与命令行:

async def main() -> None:
    async with UserService() as service:
        await service.run_once()


asyncio.run(main())

重启与重试

stop() 会撤销 start,因此停止的图可以再次启动。失败的 start() 已经释放了它启动的一切, 重试就是再调用一次:

for attempt in range(3):
    try:
        await service.start()
        break
    except ConnectionError:
        if attempt == 2:
            raise
        await asyncio.sleep(2**attempt)

@init 在一个作用域内只运行一次。见生命周期 › 再次启动。