pico-resilience

Spring-style resilience annotations for the Pico ecosystem, built on pico-ioc method interception and auto-discovered by pico-boot. Zero-config.

Install

pip install pico-resilience

Use

from pico_ioc import component
from pico_resilience import retryable, circuit_breaker, timeout

@component
class PaymentGateway:
    @retryable(max_attempts=3, backoff_seconds=0.2, retry_on=(ConnectionError,))
    @circuit_breaker(failure_threshold=5, reset_timeout_seconds=30)
    def charge(self, order): ...

    @timeout(2.0)
    async def query_partner(self, q): ...

Failures raise RetryExhaustedError / CircuitOpenError / TimeoutError with the method name. resilience.enabled: false in application.yaml bypasses every policy (handy in tests).

Chain rule: put @retryable at the top when combining decorators (it runs innermost); @circuit_breaker/@cacheable below it then wrap the whole retry loop — the circuit counts exhausted retries and the cache stores the final result. @timeout rejects sync methods at import time: a thread cannot be cancelled, and a timeout that lies is worse than none.

Hot config reload

resilience.enabled reacts live to container.refresh_config() (or pico-actuator's POST /actuator/refresh) — pico-ioc >= 2.3.0:

data["resilience"]["enabled"] = False
container.refresh_config()   # every policy passes through from this moment

Hot reload is on by default and requires an EventBus (pico_ioc.event_bus in init(modules=[...])); without one, startup fails fast. Opt out explicitly with resilience.hot_reload: false. See the Hot Config Reload how-to.

Documentation

Full docs at dperezcabrera.github.io/pico-resilience.

Built for AI-assisted development

pico-resilience 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

The pico-conventions skill teaches the assistant this module's API surface and invariants; /add-component and /add-tests scaffold components and tests that use it.

License

MIT