A small async Python framework for long-running processes: service hosting, in-process task scheduling, and a lightweight HTTP server — all built on AnyIO (runs on asyncio and Trio).
LocalPost is not a monolith. Each module is usable on its own; pick what you need.
- Service hosting with a structured lifecycle (
Starting → Running → ShuttingDown → Stopped), signal handling, and composable middleware. - Scheduler with declarative triggers (
every,after,cron) and operator-based composition (every("1m") // delay((0, 10))). - HTTP server — sync, h11-based, ~400 LOC; wrap any WSGI app.
- IoC container —
.NET-style, scoped, with Flask integration.
pip install localpostOptional extras:
| Extra | Adds |
|---|---|
[cron] |
croniter — cron-expression trigger |
[scheduler] |
humanize, pytimeparse2 — string durations |
[http] |
h11 — the HTTP server |
[http-fast] |
httptools — alternative C-based parser |
import random
from localpost.hosting import run_app
from localpost.scheduler import after, delay, every, scheduled_task, take_first
@scheduled_task(every("3s") // delay((0, 1)))
async def task1():
return random.randint(1, 22)
@scheduled_task(after(task1) // take_first(3))
async def task2(task1_result: int):
print(f"task1 emitted: {task1_result}")
if __name__ == "__main__":
run_app(task1, task2)run_app wires signal handling (SIGINT / SIGTERM), starts every service in
parallel, exits cleanly when they all stop, and raises SystemExit with
the resulting status code — no sys.exit(...) wrapper needed.
| Module | Purpose |
|---|---|
hosting |
Service lifecycle, signals, middleware, ASGI/gRPC adapters |
scheduler |
Composable in-process task scheduler |
di |
Scoped IoC container |
http |
Small h11-based HTTP/1.1 server |
All four modules have stable public APIs and are not expected to break in patch or minor releases.
Each subdirectory has its own README with a quickstart, key concepts, and extension points.
- Type-safe — public API is checked with
tyandbasedpyright --verifytypes. - FastAPI-style ergonomics — decorators for tasks, services, and HTTP operations; declarative middleware.
- Async-first — built on AnyIO, so structured concurrency is the default, and you get Trio support for free.
- Handle-both — the scheduler accepts sync or async callables; sync ones are offloaded to a thread pool.
- Small — each module is focused and independently usable; take just the scheduler, just the hosting, or the full stack.
Beta — actively developed. Python 3.12+ required. See CHANGELOG.md for history.
Examples for every module live under examples/.
MIT — see LICENSE.
See CONTRIBUTING.md for dev setup, code style, commit conventions, the pull-request checklist, and (for maintainers) the release process.
Quick start:
just deps # uv sync --all-groups --all-extras
just tests