Async-first toolkit. Microservice patterns inside.
A Python toolkit for distributed systems: microservices, modular monoliths, and self-contained systems.
Documentation: https://grelmicro.grel.info/
Source Code: https://github.com/grelinfo/grelmicro
What your service gains
Your FastAPI, Starlette, Litestar or FastStream service keeps its routes, its lifespan and its database code. grelmicro adds what a service needs once it runs on more than one replica:
- a scheduled job that runs once per interval across replicas, not on each of them,
- a lock, a cache and a rate limit that every replica shares,
- a retry, a circuit breaker and a timeout around the calls that fail,
- health probes, logs, traces and metrics that Kubernetes and your dashboards read.
Use one pattern, a few, or all of them. Each one you add works with the ones you have. Pay only for what you import: grelmicro needs three dependencies, each backend is an extra, and a module loads only what it uses.
One line says where the shared state lives: Redis, Valkey, PostgreSQL or SQLite. Change that line and the rest of the code stays the same.
Every pattern behaves the same on each framework, and a parity test holds the claim. The hot paths run in a compiled Rust core: a JWT signature check is about four times faster than in a pure-Python library.
Coming from another stack? See the mapping for Spring Boot, Quarkus, Django, Laravel or Symfony.
Start with one pattern
Run a job once a minute across all your replicas, not once per replica. Create a file main.py with:
from fastapi import FastAPI
from grelmicro import Grelmicro
from grelmicro.providers.redis import RedisProvider
from grelmicro.task import Tasks
app = FastAPI()
tasks = Tasks()
micro = Grelmicro(uses=[RedisProvider("redis://localhost:6379/0"), tasks])
micro.install(app)
@tasks.every(interval=60, gate="claim")
async def send_report() -> None:
print("report sent by this copy")
Start Redis, then run each copy of the app in its own terminal:
docker run -d -p 6379:6379 redis
pip install "grelmicro[fastapi,redis]" "fastapi[standard]"
# Terminal 1
fastapi run main.py
# Terminal 2
fastapi run main.py --port 8001
Each minute the report is sent once, by whichever copy claims it. micro.install(app) opens grelmicro when the app starts and closes it when the app stops. Already pass a lifespan to FastAPI(...)? It keeps running.
Add the next one
The same provider line serves every pattern you add. Here a lock keeps two inventory syncs from running at once across replicas, and a circuit breaker stops calling a warehouse service that keeps failing. The job from above stays:
from fastapi import FastAPI
from grelmicro import Grelmicro
from grelmicro.coordination import Lock
from grelmicro.providers.redis import RedisProvider
from grelmicro.resilience import CircuitBreaker
from grelmicro.task import Tasks
app = FastAPI()
tasks = Tasks()
micro = Grelmicro(uses=[RedisProvider("redis://localhost:6379/0"), tasks])
micro.install(app)
sync_lock = Lock("inventory-sync")
warehouse = CircuitBreaker("warehouse")
@app.post("/inventory/sync")
async def sync_inventory() -> dict[str, str]:
async with sync_lock, warehouse:
return {"status": "synced"} # your warehouse call
@tasks.every(interval=60, gate="claim")
async def send_report() -> None:
print("report sent by this copy")
Both copies now share the lock and the breaker's state as well as the job.
What each module guarantees
| Module | Guarantee |
|---|---|
| Cache | @cached(ttl=30) memoizes in one process. @cached(TTLCache(...)) shares entries across replicas, and concurrent misses on one key run the function once per process. With a Coordination backend, lock="cluster" runs it once across replicas. |
| Idempotency | A repeated key within ttl replays the stored response without running the operation again. |
| Coordination | A Lock has one holder at a time for as long as its lease, and a LeaderElection one leader. A lost extension metric tells you when the work outran the lease. |
| Outbox | A message published inside your transaction runs its handler at least once, and never for a transaction that rolled back. |
| Task Scheduler | With gate="claim", one worker runs each interval or cron fire. A claimed cron fire runs at most once, and a fire missed while every worker was down replays once. |
| Resilience | An open circuit breaker fails calls fast until reset_timeout, then lets a few probe calls through. A Rate Limiter on a shared backend counts one budget for every replica. Retry, Timeout, Bulkhead and Fallback compose through a Shield. |
| Health | Each check runs at most once per cache_ttl, however many probes arrive. |
| Security | A JWT  is accepted only with a valid signature and exp, and with aud and iss when you name them. Signing keys refresh from the JWKS when they rotate. Client IP trusts only your own proxies. |
| Logging, Tracing, Metrics | A log line written inside a traced request carries that request's trace and span id. |
| Configuration | ExternalConfig changes a running component's settings from a mounted ConfigMap, Secret or file, without a restart. |
grelmicro is not a task queue (reach for Celery, Dramatiq, or taskiq), not a message broker client (reach for FastStream to publish and subscribe over Kafka, RabbitMQ, NATS, or Redis), and not a web framework (it plugs into FastAPI, Starlette, Litestar, and FastStream). It fills the gap between the web framework you picked and the infrastructure you run.
Already using aiocache, slowapi, pybreaker, tenacity, or aioredlock? See the comparison page for a per-domain breakdown.
Pre-1.0, the API may change on a minor release. 1.x follows standard semver.
Installation
pip install grelmicro
See the Installation guide for uv and poetry commands, plus optional extras for Redis, PostgreSQL, SQLite, Kubernetes, OpenTelemetry, structlog, and JWT verification.
Run the demo
Want to see every pattern running against real Redis and Postgres? The FastAPI demo starts in three commands:
cd examples/fastapi-demo
docker compose up --wait
open http://localhost:8000/docs
It wires a cached endpoint, a rate-limited endpoint, a circuit-breaker-protected endpoint, a distributed lock, a leader-gated task, and /healthz / /readyz probes. Read app.py to see each one.
The User Guide covers multiple Redis instances, separate names and test overrides.
Contributing
Report bugs and request features in GitHub issues. The reporting guide lists what to include and what happens after you file.
To contribute code or docs, read the contributing guide. It explains the pull request process and the requirements for acceptable contributions: the development setup, the code style, and the pre-merge checklist.
Report security issues privately through the security policy, not a public issue.
License
This project is licensed under the terms of the MIT license.
1 maintainer
Metadata
1 maintainer
Release files for grelmicro 0.42.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| grelmicro-0.42.0.tar.gz | 3.3 MB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| grelmicro-0.42.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 4.2 MB
Release files / grelmicro-0.42.0.tar.gz
| Download URL | grelmicro-0.42.0.tar.gz |
|---|---|
| Size | 3.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f7f352d25627c8b7402ff2b195a5abb247232d8b7a4ac8301c5e19016b48dcf5
|
|
BLAKE2b-256 checksum How to use checksums |
0acec13c8b41787db0099cafe3025be00929ee88de2d9e90df343dac046e0705
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 19, 2026.
Transparency logRelease files / grelmicro-0.42.0-py3-none-any.whl
| Download URL | grelmicro-0.42.0-py3-none-any.whl |
|---|---|
| Size | 896.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
22d8e853adf2de0d25c336f9d28535ed5bdb7b363828ff07a08517417c3a610b
|
|
BLAKE2b-256 checksum How to use checksums |
274d9ef6ac8cedd784676f0f8b41e82f66ea46e73023eb7478680e41ecf743dc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 19, 2026.
Transparency logSecurity for grelmicro 0.42.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for grelmicro-0.42.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 19, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
