https://github.com/grelinfo/grelmicro
Grelmicro is a lightweight framework/toolkit which is ideal for building async microservices in Python.
https://github.com/grelinfo/grelmicro
anyio asyncio circuit-breaker fastapi faststream leader-election lock microservice pydantic python resilience
Last synced: 14 days ago
JSON representation
Grelmicro is a lightweight framework/toolkit which is ideal for building async microservices in Python.
- Host: GitHub
- URL: https://github.com/grelinfo/grelmicro
- Owner: grelinfo
- License: mit
- Created: 2024-10-21T04:31:31.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-03-12T22:39:40.000Z (15 days ago)
- Last Synced: 2026-03-13T04:57:49.668Z (15 days ago)
- Topics: anyio, asyncio, circuit-breaker, fastapi, faststream, leader-election, lock, microservice, pydantic, python, resilience
- Language: Python
- Homepage: https://grelmicro.grel.info/
- Size: 1.19 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Grelmicro
Grelmicro is a lightweight framework/toolkit which is ideal for building async microservices in Python.
It is the perfect companion for building cloud-native applications with FastAPI and FastStream, providing essential tools for running in distributed and containerized environments.
[](https://pypi.org/project/grelmicro/)
[](https://pypi.org/project/grelmicro/)
[](https://codecov.io/gh/grelinfo/grelmicro)
[](https://github.com/astral-sh/uv)
[](https://github.com/astral-sh/ruff)
[](https://github.com/astral-sh/ty)
______________________________________________________________________
**Documentation**: [https://grelinfo.github.io/grelmicro/](https://grelinfo.github.io/grelmicro)
**Source Code**: [https://github.com/grelinfo/grelmicro](https://github.com/grelinfo/grelmicro)
______________________________________________________________________
## Overview
Grelmicro provides essential features for building robust distributed systems, including:
- **Backends**: Technology-agnostic design supporting Redis, PostgreSQL, and in-memory backends for testing.
- **Logging**: Easy-to-configure logging with support for both text or JSON structured format with configurable timezone.
- **Resilience Patterns**: Implements common resilience patterns like retries and circuit breakers.
- **Synchronization Primitives**: Includes leader election and distributed lock mechanisms.
- **Task Scheduler**: A simple and efficient task scheduler for running periodic tasks.
These features address common challenges in microservices and distributed, containerized systems while maintaining ease of use.
### [Logging](https://grelinfo.github.io/grelmicro/logging/)
The `logging` package provides a simple and easy-to-configure logging system.
The logging feature adheres to the 12-factor app methodology, directing logs to `stdout`. It supports JSON and TEXT formatting with configurable timezone support and allows log level configuration via environment variables (`LOG_LEVEL`, `LOG_FORMAT`, `LOG_TIMEZONE`).
### [Resilience Patterns](https://grelinfo.github.io/grelmicro/resilience/)
The `resilience` package provides higher-order functions (decorators) that implement resilience patterns to improve fault tolerance and reliability in distributed systems.
- **Circuit Breaker**: Automatically detects repeated failures and temporarily blocks calls to unstable services, allowing them time to recover.
### [Synchronization Primitives](https://grelinfo.github.io/grelmicro/sync/)
The `sync` package provides synchronization primitives for distributed systems.
The primitives are technology agnostic, supporting multiple backends like Redis, PostgreSQL, and in-memory for testing.
The available primitives are:
- **Task Lock**: A distributed lock for scheduled tasks with minimum and maximum hold times. Best used via the [`scheduled()` decorator](https://grelinfo.github.io/grelmicro/task/#scheduled-task) which configures it automatically.
- **Leader Election**: A single worker is elected as the leader for performing tasks only once in a cluster.
- **Lock**: A distributed lock that can be used to synchronize access to shared resources.
### [Task Scheduler](https://grelinfo.github.io/grelmicro/task/)
The `task` package provides a simple task scheduler that can be used to run tasks periodically.
> **Note**: This is not a replacement for bigger tools like Celery, taskiq, or APScheduler. It is just lightweight, easy to use, and safe for running tasks in a distributed system with synchronization.
The key features are:
- **Fast & Easy**: Offers simple decorators to define and schedule tasks effortlessly.
- **Interval Task**: Allows tasks to run at specified intervals.
- **Synchronization**: Controls concurrency using synchronization primitives to manage simultaneous task execution (see the `sync` package).
- **Dependency Injection**: Use [FastDepends](https://lancetnik.github.io/FastDepends/) library to inject dependencies into tasks.
- **Error Handling**: Catches and logs errors, ensuring that task execution errors do not stop the scheduling.
## Installation
```bash
pip install grelmicro
```
## Examples
### FastAPI Integration
- Create a file `main.py` with:
```python
from contextlib import asynccontextmanager
import typer
from fastapi import FastAPI
from grelmicro.logging import configure_logging
from grelmicro.sync import LeaderElection, Lock
from grelmicro.sync.redis import RedisSyncBackend
from grelmicro.task import TaskManager
# === FastAPI ===
@asynccontextmanager
async def lifespan(app):
configure_logging()
# Start the lock backend and task manager
async with sync_backend, task:
yield
app = FastAPI(lifespan=lifespan)
@app.get("/")
def read_root():
return {"Hello": "World"}
# === Grelmicro ===
task = TaskManager()
sync_backend = RedisSyncBackend("redis://localhost:6379/0")
# --- Ensure that only one say hello world at the same time ---
lock = Lock("say_hello_world")
@task.interval(seconds=1, sync=lock)
def say_hello_world_every_second():
typer.echo("Hello World")
@task.interval(seconds=1, sync=lock)
def say_as_well_hello_world_every_second():
typer.echo("Hello World")
# --- Ensure that only one worker is the leader ---
leader_election = LeaderElection("leader-election")
task.add_task(leader_election)
@task.interval(seconds=10, sync=leader_election)
def say_hello_leader_every_ten_seconds():
typer.echo("Hello Leader")
```
## Dependencies
Grelmicro depends on Pydantic v2+, AnyIO v4+, and FastDepends.
### `standard` Dependencies
When you install Grelmicro with `pip install grelmicro[standard]` it comes with:
- `loguru`: A Python logging library.
- `orjson`: A fast, correct JSON library for Python.
### `redis` Dependencies
When you install Grelmicro with `pip install grelmicro[redis]` it comes with:
- `redis-py`: The Python interface to the Redis key-value store (the async interface depends on `asyncio`).
### `postgres` Dependencies
When you install Grelmicro with `pip install grelmicro[postgres]` it comes with:
- `asyncpg`: The Python `asyncio` interface for PostgreSQL.
## License
This project is licensed under the terms of the MIT license.