pico-fastapi 0.2.3.dev0

Pico-ioc integration for FastAPI. Adds Spring Boot-style controllers, autoconfiguration, and scopes (request, websocket, session).

📦 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+ ⚡ 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.

Concern	FastAPI Default	pico-fastapi
Dependency injection	Function-based	Constructor-based
Architecture	Framework-driven	Domain-driven
Testing	Simulate DI calls	Override components in container
Scopes	Manual or ad-hoc	Automatic (singleton, request, session, websocket)

---

🧱 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

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()}

from pico_ioc import component

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

from pico_ioc import init
from fastapi import FastAPI

container = init(
    modules=[
        "controllers",
        "services",
        "pico_fastapi",
    ]
)

app = container.get(FastAPI)

---

🚀 Quick Example (with pico-boot auto-discovery)

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 (Using pico-boot)

from pico_boot import init
from fastapi import FastAPI

# No need to declare "pico_fastapi" anymore.
# pico-fastapi is auto-discovered via entry points.

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"

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(self, app: FastAPI) -> None:
        app.mount(self.settings.static_url, StaticFiles(directory=self.settings.static_dir), name="static")

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

container = init(
    modules=[
        "pico_fastapi",
        "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"

---

🔐 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(self, app: FastAPI) -> None:
        app.add_middleware(JwtMiddleware, container=self.container, secret=self.settings.secret)

from pico_ioc 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=[
        "pico_fastapi",
        "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.

---

🤖 Claude Code Skills

This project includes pre-designed skills for Claude Code, enabling AI-assisted development with pico-fastapi patterns.

Skill	Command	Description
Pico FastAPI Endpoint	/pico-fastapi	Creates endpoints with controller-based routing and DI
Pico Test Generator	/pico-tests	Generates tests for pico-framework components

See Skills documentation for full details and installation instructions.

---

📝 License

MIT