https://github.com/dperezcabrera/pico-fastapi
pico-fastapi integrates Pico-IoC with FastAPI, providing real inversion-of-control, controller-based routing, scoped dependency resolution, and clean application lifecycle management—without global state or manual wiring.
https://github.com/dperezcabrera/pico-fastapi
async asyncio controllers dependency-injection fastapi ioc pico-framework rest-api scoped-dependencies web-framework
Last synced: 18 days ago
JSON representation
pico-fastapi integrates Pico-IoC with FastAPI, providing real inversion-of-control, controller-based routing, scoped dependency resolution, and clean application lifecycle management—without global state or manual wiring.
- Host: GitHub
- URL: https://github.com/dperezcabrera/pico-fastapi
- Owner: dperezcabrera
- License: mit
- Created: 2025-11-01T22:50:40.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-02-16T08:37:41.000Z (23 days ago)
- Last Synced: 2026-02-16T16:17:22.812Z (22 days ago)
- Topics: async, asyncio, controllers, dependency-injection, fastapi, ioc, pico-framework, rest-api, scoped-dependencies, web-framework
- Language: Python
- Size: 161 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# 📦 pico-fastapi
[](https://pypi.org/project/pico-fastapi/)
[](https://deepwiki.com/dperezcabrera/pico-fastapi)
[](https://opensource.org/licenses/MIT)
[](https://codecov.io/gh/dperezcabrera/pico-fastapi)
[](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-fastapi)
[](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-fastapi)
[](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-fastapi)
[](https://dperezcabrera.github.io/pico-fastapi/)
# Pico-FastAPI
**[Pico-FastAPI](https://github.com/dperezcabrera/pico-fastapi)** seamlessly integrates **[Pico-IoC](https://github.com/dperezcabrera/pico-ioc)** with **[FastAPI](https://github.com/fastapi/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
```bash
pip install pico-fastapi
```
---
## 🚀 Quick Example
```python
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()}
```
```python
from pico_ioc import component
@component
class MyService:
def greet(self) -> str:
return "hello from service"
```
```python
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
```python
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
```python
from pico_ioc import component
@component
class MyService:
def greet(self) -> str:
return "hello from service"
```
### 3. App Initialization (Using pico-boot)
```python
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
```python
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
```python
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
```python
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")
```
```python
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)
```
```yaml
fastapi:
title: "My App"
version: "1.0.0"
debug: true
static_dir: "public"
static_url: "/assets"
```
---
## 🔐 JWT Authentication Configuration Example
```python
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)
```
```python
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.
---
## AI Coding Skills
Install [Claude Code](https://code.claude.com) or [OpenAI Codex](https://openai.com/index/introducing-codex/) skills for AI-assisted development with pico-fastapi:
```bash
curl -sL https://raw.githubusercontent.com/dperezcabrera/pico-skills/main/install.sh | bash -s -- fastapi
```
| Command | Description |
|---------|-------------|
| `/add-controller` | Add FastAPI controllers with route decorators |
| `/add-component` | Add components, factories, interceptors, settings |
| `/add-tests` | Generate tests for pico-framework components |
All skills: `curl -sL https://raw.githubusercontent.com/dperezcabrera/pico-skills/main/install.sh | bash`
See [pico-skills](https://github.com/dperezcabrera/pico-skills) for details.
---
## 📝 License
MIT