JASIL
Just Another Substrate & Infrastructure Library — a framework-agnostic infrastructure substrate for Python services: swappable capability backends, an event pipeline, durable jobs, and observability.
Status:
0.7.0- the API is still settling. Expect breaking changes on minor versions until1.0.0.
What it gives you
| Layer | What it does |
|---|---|
| Providers | Small composable protocols - state, storage, events, realtime hints, lock, clock, geocoding, mail - that domain code depends on instead of Redis, S3, or Postgres. Complete aggregate protocols keep URI-selected backends interchangeable. |
| Backends | A working implementation of each, selected by URI: memory:// or redis://, local:// or s3://, noop:// or postgres-advisory://, smtp:// or smtps://. |
| Deployment profiles | local runs single-process with zero extra infrastructure. distributed requires shared backends and refuses to guess them. |
| Event pipeline | One envelope, one publish seam, payload schema versioning that survives a rolling deploy. |
| Durable jobs | A transactional outbox relayed into named, leased per-subscriber queues, with fair/selective workers, exponential backoff, and a dead-letter queue. |
| Observability | An event lifecycle log and bounded retention pruning for every table it owns. |
A core install depends on sqlalchemy and pydantic only. Every backend
client lives behind an extra and is imported lazily, so a single-process
deployment never loads redis, boto3, or requests.
JASIL is synchronous. Every provider, subscriber, and the durable-jobs layer is blocking Python, and the ORM integration expects a synchronous
sessionmaker— there is noAsyncSessionsupport. On an async framework, call into JASIL from a worker thread (adefFastAPI route or dependency does this for you). See the docs.
Installation
pip install jasil # core: memory / local disk / in-process
pip install "jasil[redis,s3]" # distributed state, events and storage
pip install "jasil[all]" # every optional backend
| Extra | Enables |
|---|---|
redis |
Redis state store, Redis-Streams event bus and Pub/Sub realtime hints |
s3 |
S3-compatible object storage |
postgres |
PostgreSQL advisory locks |
jobs |
Durable-job scheduling |
fastapi |
Depends helpers exposing the providers to routes |
geocoding |
HTTP reverse geocoding |
migrations |
Packaged Alembic revisions |
Verifying a release
Releases are built and published by this repository's release workflow through PyPI Trusted Publishing, with PEP 740 attestations. You can confirm a downloaded artifact came from that workflow and was not substituted:
uvx pypi-attestations verify pypi \
--repository https://github.com/endurain-project/jasil \
pypi:jasil-<version>-py3-none-any.whl
A successful run prints OK: <filename>. Provenance for file ... was not found means the artifact predates attested publishing rather than that verification failed.
Each release run also produces a CycloneDX SBOM and SHA256SUMS, generated from a clean install of the built wheel. These are retained as workflow artifacts on the release run rather than published to PyPI.
Quick start
JASIL never reads your environment, creates your engine, or owns your declarative base — the host supplies all three.
from sqlalchemy import create_engine
from sqlalchemy.orm import DeclarativeBase, sessionmaker
import jasil.orm as jasil_orm
import jasil.settings as jasil_settings
from jasil.container import build_platform
from jasil.runtime import set_active_platform
class Base(DeclarativeBase):
"""Your application's declarative base."""
# 1. Map JASIL's tables into your registry, before any database use.
jasil_orm.map_models(Base)
# 2. Hand JASIL a session factory bound to your engine.
engine = create_engine("postgresql+psycopg://...")
jasil_orm.configure_sessionmaker(sessionmaker(bind=engine))
# 3. Configure, build, publish.
jasil_settings.configure(jasil_settings.JasilSettings(data_dir="/srv/data"))
set_active_platform(build_platform())
Then depend on capabilities, not on infrastructure:
from jasil.runtime import get_active_platform
platform = get_active_platform()
platform.state.set("session:abc", b"...", ttl_seconds=3600)
platform.storage.save("thumbnails", "42.webp", image_bytes)
with platform.lock.try_acquire("nightly-backfill") as acquired:
if acquired:
run_backfill()
Publishing an event goes through one seam, so switching from best-effort delivery to a transactional outbox is a configuration change, not a rewrite:
from jasil.publisher import publish
publish("activity.created", {"activity_id": 42}, source="api:store_activity", db=db)
Going distributed
Change the profile and point the capability URIs at real infrastructure:
jasil_settings.configure(
jasil_settings.JasilSettings(
profile=jasil.DeploymentProfile.DISTRIBUTED,
state_uri="redis://cache:6379/0",
events_uri="redis://cache:6379/1",
storage_uri="s3://my-bucket",
lock_uri="postgres-advisory://",
)
)
The distributed profile refuses to start if a capability URI is unset. A
silent fallback to a process-local backend across replicas is the failure the
profile system exists to prevent.
Development
uv sync --all-extras --group dev
uv run pytest # tests + coverage gate
uv run ruff check . # lint
uv run mypy # type check
uv run lint-imports # architectural import contracts
Documentation
Full documentation is available at the JASIL docs site.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Contributing
Contributions welcome! See Contributing Guidelines for guidelines.
Metadata
Release files for jasil 0.7.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 | Actions |
|---|---|---|---|---|
| jasil-0.7.0.tar.gz | 181.3 kB | Without provenance | Details for jasil-0.7.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| jasil-0.7.0-py3-none-any.whl | Python 3 | none | any | Details for jasil-0.7.0-py3-none-any.whl |
Total release size: 387.1 kB
Release files / jasil-0.7.0.tar.gz
| Download URL | jasil-0.7.0.tar.gz |
|---|---|
| Size | 181.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8ce539bc475be3ac991062d6c9958c51d091a0e60e907cee5817657308f6d76c
|
|
BLAKE2b-256 checksum How to use checksums |
f909dd552c562f75507ea730a87d3e29aa98b5d828841f34c63ae8b708d1a05e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.24 {"installer":{"name":"uv","version":"0.12.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / jasil-0.7.0-py3-none-any.whl
| Download URL | jasil-0.7.0-py3-none-any.whl |
|---|---|
| Size | 205.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fac5a598e05d835cb9045a7c8baa872ec89833df25f1ea09d99bb5f74ec987d0
|
|
BLAKE2b-256 checksum How to use checksums |
2b00c3562dbc504b12f6f46005b3e63ff7754d52ac8fbadb8b4315463e3dccc6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.24 {"installer":{"name":"uv","version":"0.12.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for jasil 0.7.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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A 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.
To learn more about protecting yourself from malicious actors, visit our package security documentation.