pico-fastapi

Pico-FastAPI

Pico-FastAPI seamlessly integrates Pico-IoC with FastAPI, bringing true inversion of control and constructor-based dependency injection to one of the fastest and most elegant Python web frameworks.

It provides scoped lifecycles, automatic controller registration, and clean architectural boundaries, without global state and without FastAPI’s function-based dependency system.

Requires Python 3.11+ (tested on 3.11, 3.12, 3.13 and 3.14) Built on FastAPI Fully async-compatible Real IoC with constructor injection Supports singleton, request, session, and websocket scopes

With Pico-FastAPI you get the speed, clarity, and async performance of FastAPI, enhanced by a real IoC container for clean, testable, and maintainable applications.

Why pico-fastapi

FastAPI’s built-in dependency system is function-based, which often ties business logic to the framework. Pico-FastAPI moves dependency resolution into the IoC container, promoting separation of concerns and testability.

Core Features

• Controller classes with @controller
• Route decorators: @get, @post, @put, @delete, @patch, @websocket
• Constructor injection for controllers and services
• Automatic registration into FastAPI
• Scoped resolution via middleware for request, session, and websocket
• Full Pico-IoC feature set: profiles, overrides, interceptors, cleanup hooks

Installation

pip install pico-fastapi

Quick Example

1. Controller

from pico_fastapi import controller, get

@controller(prefix="/api")
class ApiController:
    def __init__(self, service: "MyService"):
        self.service = service

    @get("/hello")
    async def hello(self):
        return {"msg": self.service.greet()}

2. Service

from pico_ioc import component

@component
class MyService:
    def greet(self) -> str:
        return "hello from service"

3. App initialization

from pico_boot import init
from fastapi import FastAPI

# pico_fastapi is auto-discovered via its entry point: do not list it.
container = init(
    modules=[
        "controllers",
        "services",
    ]
)

app = container.get(FastAPI)

WebSocket Example

from pico_fastapi import controller, websocket
from fastapi import WebSocket

@controller
class ChatController:
    @websocket("/ws")
    async def chat(self, websocket: WebSocket):
        await websocket.accept()
        while True:
            msg = await websocket.receive_text()
            await websocket.send_text(f"Echo: {msg}")

Testing with Overrides

from pico_ioc import init
from fastapi import FastAPI
from fastapi.testclient import TestClient

class FakeService:
    def greet(self) -> str:
        return "test"

# Tests use pico_ioc.init, not pico_boot.init: it loads exactly the listed
# modules, so other pico plugins installed in the venv cannot leak into the
# test. That is why "pico_fastapi" is declared explicitly here.
container = init(
    modules=["controllers", "services", "pico_fastapi"],
    overrides={"MyService": FakeService()}
)

app = container.get(FastAPI)
client = TestClient(app)

assert client.get("/api/hello").json() == {"msg": "test"}

Static Files Configuration Example

from dataclasses import dataclass
from typing import Protocol, runtime_checkable
from fastapi import FastAPI
from starlette.staticfiles import StaticFiles
from pico_ioc import component, configured
from pico_fastapi import FastApiConfigurer

@configured(target="self", prefix="fastapi", mapping="tree")
@dataclass
class StaticSettings:
    static_dir: str = "public"
    static_url: str = "/static"

@component
class StaticFilesConfigurer(FastApiConfigurer):
    priority = -100
    def __init__(self, settings: StaticSettings):
        self.settings = settings
    def configure_app(self, app: FastAPI) -> None:
        app.mount(self.settings.static_url, StaticFiles(directory=self.settings.static_dir), name="static")

from pico_boot import init
from pico_ioc import configuration, YamlTreeSource
from fastapi import FastAPI

container = init(
    modules=[
        "static_config",
    ],
    config=configuration(
        YamlTreeSource("config.yml")
    ),
)

app = container.get(FastAPI)

fastapi:
  title: "My App"
  version: "1.0.0"
  debug: true
  static_dir: "public"
  static_url: "/assets"

OpenTelemetry (FastAPI >= 0.142)

FastAPI 0.142 instruments apps with OpenTelemetry by default. pico-fastapi sets fastapi.telemetry to {"auto_configure": False} so FastAPI records spans against the providers your app configures (for example with pico-otel) but never adds a second exporter of its own. Any key FastAPI accepts for telemetry can be set under fastapi.telemetry; see Configuration.

JWT Authentication Configuration Example

import base64
import json
import hmac
import hashlib
from dataclasses import dataclass
from typing import Optional
from fastapi import FastAPI, Request
from starlette.middleware.base import BaseHTTPMiddleware
from pico_ioc import component, configured, PicoContainer
from pico_fastapi import FastApiConfigurer

def _b64url_decode(data: str) -> bytes:
    padding = "=" * (-len(data) % 4)
    return base64.urlsafe_b64decode(data + padding)

def _verify_hs256(token: str, secret: str) -> Optional[dict]:
    parts = token.split(".")
    if len(parts) != 3:
        return None
    header_b64, payload_b64, sig_b64 = parts
    signing_input = f"{header_b64}.{payload_b64}".encode()
    expected = hmac.new(secret.encode(), signing_input, hashlib.sha256).digest()
    try:
        signature = _b64url_decode(sig_b64)
    except Exception:
        return None
    if not hmac.compare_digest(signature, expected):
        return None
    try:
        payload_json = _b64url_decode(payload_b64)
        return json.loads(payload_json.decode())
    except Exception:
        return None

class JwtMiddleware(BaseHTTPMiddleware):
    def __init__(self, app, container: PicoContainer, secret: str):
        super().__init__(app)
        self.container = container
        self.secret = secret
    async def dispatch(self, request: Request, call_next):
        auth = request.headers.get("Authorization", "")
        if auth.startswith("Bearer "):
            token = auth.split(" ", 1)[1]
            claims = _verify_hs256(token, self.secret)
            if claims is not None:
                request.state.jwt_claims = claims
        response = await call_next(request)
        return response

@dataclass
class JwtSettings:
    secret: str = "changeme"
    header: str = "Authorization"

@component
class JwtConfigurer(FastApiConfigurer):
    priority = 10
    def __init__(self, container: PicoContainer, settings: JwtSettings):
        self.container = container
        self.settings = settings
    def configure_app(self, app: FastAPI) -> None:
        app.add_middleware(JwtMiddleware, container=self.container, secret=self.settings.secret)

from pico_boot import init
from fastapi import FastAPI, Request
from pico_fastapi import controller, get

@controller(prefix="/api")
class ProfileController:
    def __init__(self):
        pass
    @get("/me")
    async def me(self, request: Request):
        claims = getattr(request.state, "jwt_claims", None)
        if claims is None:
            return {"error": "not authenticated"}, 401
        return {"sub": claims.get("sub")}

container = init(
    modules=[
        "jwt_config",
        "controllers",
    ]
)

app = container.get(FastAPI)

How It Works

• Controller classes are discovered and registered automatically
• Each route executes within its own request or websocket scope
• All dependencies are resolved via Pico-IoC
• Cleanup and teardown occur at FastAPI lifespan

No global state and no implicit singletons.

Built for AI-assisted development

pico-fastapi is part of an ecosystem designed for humans and coding agents building software together. Every package ships AGENTS.md working conventions, an llms.txt machine-readable docs index and documented behaviour pinned by regression tests; pico-testing gives agents a verification loop for their own changes, and releases are gated by the whole ecosystem booting together against real infrastructure. The full story: Built for AI-assisted development.

Install the agent skills for Claude Code or OpenAI Codex:

curl -sL https://raw.githubusercontent.com/dperezcabrera/pico-skills/main/install.sh | bash -s -- fastapi

All skills: curl -sL https://raw.githubusercontent.com/dperezcabrera/pico-skills/main/install.sh | bash

See pico-skills for details.

License

MIT