pico-conventions
Skill4 starsChanged 4 months agoMITView on GitHub
Pico-framework conventions, patterns and API reference for all pico-* packages. Use when writing code that uses any pico module (pico-ioc, pico-boot, pico-fastapi, pico-sqlalchemy, pico-celery, pico-pydantic, pico-client-auth, pico-server-auth, pico-actuator, pico-resilience, pico-caching, pico-otel, pico-scheduling, pico-httpx, pico-data-redis, pico-rabbitmq, pico-kafka, pico-testing).
- Installs packages
In this repository12 other files it gives its agents.
- add-actuatorSkill
- add-appSkill
- add-authSkill
- add-celery-taskSkill
- add-componentSkill
- add-controllerSkill
- add-repositorySkill
- add-server-authSkill
- add-testsSkill
- add-validationSkill
- init-projectSkill
- releaseSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 12
All pico-ioc imports: from pico_ioc import ...
- Very specific: line 13
All satellite packages import from their own namespace: from pico_sqlalchemy import ...
- Distinctive: line 14
Use type hints for automatic dependency injection — constructor parameters are resolved by type
- Very specific: line 211
Add to accepted_algorithms to enable.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Pico-Framework Conventions
General Rules
- Python >= 3.11 required
- All pico-ioc imports:
from pico_ioc import ... - All satellite packages import from their own namespace:
from pico_sqlalchemy import ... - Use type hints for automatic dependency injection — constructor parameters are resolved by type
- Async-first: prefer
async defmethods
pico-ioc Core API
from pico_ioc import (
# Registration
component, # @component or @component(scope="singleton")
factory, # @factory on class containing @provides methods
provides, # @provides(Type, scope="singleton") on factory methods
configured, # @configured(prefix="key") on @dataclass for settings
Qualifier, # Annotated[Type, Qualifier("name")] for disambiguation
# Container
init, # init(modules=[...], config=...) -> PicoContainer
cleanup, # cleanup() — shutdown all scopes
PicoContainer, # Container type
# Configuration
configuration, # configuration(Source1(), Source2()) -> ContextConfig
ContextConfig, # Unified config object
YamlTreeSource, # YAML file source
JsonTreeSource, # JSON file source
EnvSource, # Environment variables
FileSource, # .properties / .ini files
FlatDictSource, # Dict source
Value, # @Value("key") for injecting config values
# AOP
MethodInterceptor, # Base class for interceptors
MethodCtx, # Context passed to interceptor.invoke()
intercepted_by, # @intercepted_by(InterceptorClass) on methods
health, # @health on methods for health checks
# Events
EventBus, # Event bus
Event, # Base event class
subscribe, # @subscribe(EventType) on handler methods
ConfigChanged, # Event published by container.refresh_config() (pico-ioc >= 2.3.0)
# Scopes
ScopeManager, # Manage custom scopes
ContextVarScope, # ContextVar-based scope implementation
# Introspection & extension (pico-ioc >= 2.4.0)
CustomScanner, # Base for custom component scanners
ProviderMetadata, # Scanner ABI: metadata returned by scan()
DeferredProvider, # Scanner ABI: wraps a zero-arg provider callable
Provider, # Scanner ABI: Callable[[], Any] alias
)container.get(Cls) is typed: it returns Cls, not Any (pico-ioc >= 2.3.5), so
IDEs and type-checkers infer the component. String keys still return Any.
Enumerate the registry through the public seam — never container._locator
(pico-ioc >= 2.4.0):
container.keys() # -> list of registered keys (types and str names)
container.metadata_for(key) # -> ProviderMetadata | None (read-only)Custom scanners import the ABI from the facade (from pico_ioc import DeferredProvider, ...);
the internal pico_ioc.factory module was renamed to a private _providers in 2.4.0.
Scopes
| Scope | Behavior |
singleton | One instance per container (default for services) |
prototype | New instance on every resolution |
request | One instance per request context (activated by pico-fastapi middleware) |
session | One instance per session context |
websocket | One instance per websocket connection |
transaction | One instance per DB transaction — Unit-of-Work / identity-map. With pico-sqlalchemy, TransactionalInterceptor activates it on each new transaction (REQUIRES_NEW, or REQUIRED with no enclosing tx) and releases it (running @cleanup) on commit/rollback. Resolving one outside a transaction raises ScopeError |
Short-lived scopes: use with container.scope("request", id, cleanup=True): so per-scope instances are evicted (and their @cleanup hooks run) on exit.
pico-boot
from pico_boot import init # Wraps pico_ioc.init() with auto-discovery
container = init(modules=["my_app"], config=config)
# All installed pico-* plugins are auto-discovered via entry pointsDisable auto-discovery: PICO_BOOT_AUTO_PLUGINS=false
pico-fastapi
from pico_fastapi import (
controller, # @controller(prefix="/path", tags=["tag"])
get, post, put, delete, patch, websocket, # Route decorators
FastApiSettings, # @configured settings
FastApiConfigurer, # Protocol for app customization
)@controller automatically applies @component(scope="request").
pico-sqlalchemy
from pico_sqlalchemy import (
repository, # @repository or @repository(entity=Model)
query, # @query(expr="field = :param") or @query(sql="...")
transactional, # @transactional(propagation="REQUIRED", read_only=False)
SessionManager, # Injected dependency for session access
get_session, # get_session(manager) -> AsyncSession
AppBase, # SQLAlchemy DeclarativeBase
Mapped, mapped_column, # Re-exported from SQLAlchemy
Page, PageRequest, Sort, # Pagination types
)Transaction propagation: REQUIRED, REQUIRES_NEW, SUPPORTS, MANDATORY, NOT_SUPPORTED, NEVER
pico-celery
from pico_celery import (
task, # @task("task.name") on async worker methods
send_task, # @send_task("task.name") on client methods
celery, # @celery on client classes
CeleryClient, # Protocol for client classes
CelerySettings, # @configured settings
)pico-pydantic
from pico_pydantic import (
validate, # @validate on methods with BaseModel params
ValidationFailedError, # Raised when validation fails
)pico-client-auth
from pico_client_auth import (
# Decorators
allow_anonymous, # @allow_anonymous — skip auth for endpoint
requires_role, # @requires_role("admin", "editor") — require any of these roles
requires_group, # @requires_group("group-id") — require group membership
# Context
SecurityContext, # Static accessor for current request's auth state
TokenClaims, # Frozen dataclass: sub, email, role, org_id, jti, groups
# Extension
RoleResolver, # Protocol for custom role extraction
AuthClientSettings, # @configured settings (prefix="auth_client")
# Errors
AuthClientError, # Base exception
MissingTokenError, # 401 — no Bearer token
TokenExpiredError, # 401 — expired JWT
TokenInvalidError, # 401 — bad signature, wrong issuer/audience
InsufficientPermissionsError, # 403 — missing required role/group
AuthConfigurationError, # Startup — missing issuer/audience
)Auth is enabled by default on all routes. Use @allow_anonymous to opt out.
SecurityContext static methods:
| Method | Returns | Description |
get() | TokenClaims | None | Current claims, or None if unauthenticated |
require() | TokenClaims | Current claims, raises MissingTokenError if absent |
get_roles() | list[str] | Resolved roles for current request |
has_role(role) | bool | Check if user has a role |
require_role(*roles) | None | Assert at least one role, raises 403 |
get_groups() | tuple[str, ...] | Group IDs from token |
has_group(group_id) | bool | Check group membership |
require_group(*group_ids) | None | Assert at least one group, raises 403 |
AuthClientSettings fields:
| Field | Type | Default | Description |
enabled | bool | True | Enable/disable auth middleware |
issuer | str | "" | Expected JWT issuer |
audience | str | "" | Expected JWT audience |
jwks_ttl_seconds | int | 300 | JWKS cache TTL |
jwks_endpoint | str | "" | Custom JWKS URL (defaults to {issuer}/api/v1/auth/jwks) |
accepted_algorithms | tuple[str, ...] | ("RS256",) | Accepted JWT algorithms (RS256, ML-DSA-65, ML-DSA-87) |
Post-quantum ML-DSA support (optional pqc extra, requires liboqs-python):
ML-DSA-65(NIST Level 3) andML-DSA-87(NIST Level 5)- Add to
accepted_algorithmsto enable; RS256 tokens continue to work alongside - JWK key type:
AKPwithpubfield (base64url raw public key bytes) - Install:
pip install pico-client-auth[pqc]
Custom role resolver (overrides default automatically via on_missing_selector):
@component
class MyRoleResolver:
async def resolve(self, claims: TokenClaims, raw_claims: dict) -> list[str]:
return raw_claims.get("roles", [])pico-server-auth
Embeddable auth server, auto-discovered by pico-boot. Exposes
POST /auth/challenge, POST /auth/wallet (wallet login: ML-DSA-65, Ed25519,
secp256k1), POST /auth/login (password), GET /auth/jwks. Configure under
the server_auth: prefix (issuer, audience, auto_create_admin,
challenge_ttl_seconds, supported_wallet_algorithms). Pair with
pico-client-auth: auth_client.issuer must match server_auth.issuer.
pico-actuator
Spring Boot-style actuator, auto-discovered by pico-boot — zero config needed.
Endpoints: /actuator/health, /health/live, /health/ready, /info,
/metrics (extra pico-actuator[metrics]).
from pico_ioc import component
from pico_actuator import HealthIndicator, InfoContributor # protocols
@component
class DbHealth: # satisfies HealthIndicator — no registration needed
name = "db"
def check(self): # sync or async; return dict or truthy
return {"status": "UP"}POST /actuator/refresh re-reads tree config sources and publishes
ConfigChanged (Spring Cloud style); subscribed components re-read their
config — pico-resilience toggles its policies live through it.
Settings under the actuator: prefix: enabled, show_components,
check_timeout_seconds (per-indicator budget, default 5s), info (static map).
Indicators run concurrently; a raising/hanging indicator reports DOWN in
isolation (endpoint answers 503, never 500s). Liveness is dependency-free by
design — wire /health/live to livenessProbe and /health/ready to
readinessProbe.
pico-scheduling
@scheduled methods on components, auto-discovered by pico-boot. Exactly one
of every= (seconds) or cron= (5-field crontab). Sync or async. Jobs start
with the container and stop with it; a raising job logs and keeps its schedule.
from pico_ioc import component
from pico_scheduling import scheduled
@component
class Reports:
@scheduled(every=300)
def refresh_cache(self): ...
@scheduled(cron="0 3 * * *")
async def nightly_rollup(self): ...Settings under scheduling:: enabled (kill-switch for tests/scripts).
Note on pico-sqlalchemy (>= 0.5.0): database.migrations_path runs Alembic
upgrade head on startup (extra [migrations]).
pico-resilience
Resilience AOP over pico-ioc interception, auto-discovered by pico-boot;
zero-config. Decorate methods on @component classes (sync or async). When
stacking with other AOP decorators, @retryable goes on top.
from pico_resilience import retryable, circuit_breaker, timeout
@component
class PaymentGateway:
@retryable(max_attempts=3, backoff_seconds=0.1, retry_on=(Exception,))
@circuit_breaker(failure_threshold=5, reset_timeout_seconds=30.0)
@timeout(2.0) # async methods only (asyncio time budget)
async def charge(self, order_id: str) -> dict: ...Exceptions: RetryExhaustedError, CircuitOpenError (both subclass
PicoResilienceError). Settings under resilience:: enabled (false = every
interceptor becomes a pass-through), hot_reload (default true — re-reads
enabled live on ConfigChanged; requires an EventBus (pico_ioc.event_bus)
or startup fails fast, opt out with resilience.hot_reload: false). Needs
pico-ioc >= 2.3.0.
pico-caching
@cacheable over pico-ioc interception with a pluggable CacheBackend
(built-in thread-safe in-memory LRU + TTL). Auto-discovered by pico-boot;
zero-config. Installing pico-data-redis switches the backend to Redis
automatically (the interceptor prefers a non-in-memory backend).
from pico_caching import cacheable
@component
class Catalog:
@cacheable(ttl_seconds=60, key=lambda self, sku: sku)
async def price(self, sku: str) -> Decimal: ...key defaults to the method arguments; ttl_seconds falls back to
cache.default_ttl_seconds. Settings under cache:: enabled (false =
pass-through), default_ttl_seconds (300.0), max_entries (1024).
pico-otel
OpenTelemetry auto-instrumentation — install it and a pico-boot app gets
tracing (FastAPI, SQLAlchemy, Celery — whichever are present), log correlation
and Prometheus metrics written into the default prometheus_client registry
that pico-actuator serves at /actuator/metrics. No code required: install +
configure. Zero-config by default.
Settings under otel:: enabled, service_name ("pico-app"), endpoint
(OTLP), traces_exporter ("auto"), traces_sample_ratio (1.0),
prometheus_metrics (True), and per-library toggles instrument_logging,
instrument_sqlalchemy, instrument_celery, instrument_fastapi (all
True). Public symbols: OtelSettings, OtelBootstrap,
OtelFastApiConfigurer.
pico-httpx
Declarative HTTP clients: the class is the interface, the implementation is
generated. Path {placeholders} bind to parameters, json is the body,
other params become query params (None dropped). Return annotation
httpx.Response = raw; anything else = response.json(). Non-2xx raises
httpx.HTTPStatusError — stack @retryable on top for retries.
from pico_httpx import http_client, get, post
@http_client(name="users") # base_url from http.clients.users.base_url
class UsersApi:
@get("/users/{user_id}")
def get_user(self, user_id: int) -> dict: ...
@post("/users")
async def create_user(self, json: dict) -> dict: ...Settings under http:: timeout_seconds, clients.<name>.base_url.
Clients close on container shutdown.
pico-data-redis
Redis integration: injectable redis.Redis singleton plus a distributed
CacheBackend for pico-caching. Installing it is opting in — @cacheable
switches to Redis automatically (interceptor prefers non-in-memory backends).
Fail-open: Redis down degrades to cache misses, never errors. Values are
pickled — the Redis instance must be trusted.
Settings under redis:: url, socket_timeout_seconds, cache_prefix.
pico-rabbitmq
RabbitMQ pub-sub (aio-pika) — events, fan-out and topic routing (pico-celery stays for tasks). Runs on a dedicated background loop: no lifespan wiring. Ack on success; on exception the message is logged and rejected WITHOUT requeue (use a dead-letter exchange to keep failures).
from pico_rabbitmq import consumer, publisher, publish
@component
class Projections:
@consumer("orders-projection", exchange="events", routing_key="orders.*")
async def on_order(self, message: dict): ...
@publisher
class Events:
@publish(exchange="events", routing_key="orders.created")
def order_created(self, message): ...Settings under rabbitmq:: url, enabled, prefetch_count,
publish_timeout_seconds.
pico-kafka
Kafka (aiokafka), same shape as pico-rabbitmq. A raising handler logs and
SKIPS its record (offsets advance — poison records never stall a partition).
Different group_ids on the same topic fan the stream out.
from pico_kafka import kafka_consumer, kafka_producer, produce
@component
class Projection:
@kafka_consumer("orders")
async def on_order(self, message: dict): ...
@kafka_producer
class Events:
@produce("orders")
def order_created(self, message): ...Settings under kafka:: bootstrap_servers, enabled, group_id,
produce_timeout_seconds.
pico-testing
Pytest plugin, active on install. Sets PICO_BOOT_AUTO_PLUGINS=false for
every test (suite results never depend on what else is installed in the
venv); opt back in per-test with @pytest.mark.pico_auto_plugins. Provides
make_container(*modules, config=dict|configuration, boot=False) with
automatic shutdown on teardown — replaces the hand-written conftest fixtures.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

