Plugin Protocol

API reference for the runtime-checkable Plugin protocol defining modular application lifecycles.

The Plugin module defines the structured contract interface (a runtime_checkable Protocol) that all modular ZCore domain plugins must satisfy to register with the central application orchestrator Kernel.

Protocol Definition

from typing import Protocol, runtime_checkable
from fastapi import FastAPI
from zcore import Plugin

@runtime_checkable
class Plugin(Protocol):
    name: str
    version: str
    dependencies: list[str]

    def setup(self, app: FastAPI) -> None: ...
    async def before_startup(self) -> None: ...
    async def on_startup(self) -> None: ...
    async def after_startup(self) -> None: ...
    async def on_shutdown(self) -> None: ...

Required Protocol Attributes

Prop

Type

Lifecycle Methods

All classes implementing Plugin must provide these lifecycle methods:

`setup`

Executes core module registration tasks and attaches routers/middlewares to the FastAPI app. Invoked during kernel.setup(app).

def setup(self, app: FastAPI) -> None: ...

Prop

Type

`before_startup`

Performs pre-initialization operations before any other application startup phases begin.

async def before_startup(self) -> None: ...

`on_startup`

Executes core asynchronous logic during application startup (e.g., warming local caches, validating external services).

async def on_startup(self) -> None: ...

`after_startup`

Executes post-initialization processes after all plugins have finished their primary startup phases.

async def after_startup(self) -> None: ...

`on_shutdown`

Performs graceful cleanup and releases external resources (e.g., connection pools, background workers) during application termination.

async def on_shutdown(self) -> None: ...

Implementation Example

from fastapi import FastAPI
from zcore import Plugin
from .routers import router_instance

class TasksPlugin(Plugin):
    name: str = "tasks"
    version: str = "1.0.0"
    dependencies: list[str] = ["auth"]  # Requires AuthPlugin to start first

    def setup(self, app: FastAPI) -> None:
        # Attach this module's sub-router to the main app
        app.include_router(router_instance.router)

    async def before_startup(self) -> None:
        pass

    async def on_startup(self) -> None:
        # Perform startup logic
        pass

    async def after_startup(self) -> None:
        pass

    async def on_shutdown(self) -> None:
        # Cleanup resources
        pass

Scaffolding Plugins: Running zc startapp <name> --template in your terminal automatically generates a populated plugin.py file satisfying this protocol.

On this page