Skip to main content

JASIL

License Release PyPI version PyPI downloads Python Docs Stars

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.12.0 - the API is still settling. Expect breaking changes on minor versions until 1.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 no AsyncSession support. On an async framework, call into JASIL from a worker thread (a def FastAPI 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("order.created", {"order_id": 42}, source="api:create_order", 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 (the gate)
uv run ty check            # advisory type check (non-blocking in CI)
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.

Built with ❤️ from Portugal | Part of the Endurain ecosystem

Metadata

Release files for jasil 0.12.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for jasil 0.12.0
File Size Uploaded Provenance Actions
jasil-0.12.0.tar.gz 208.9 kB Without provenance Details for jasil-0.12.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for jasil 0.12.0
File Interpreter ABI Platform Actions
jasil-0.12.0-py3-none-any.whl Python 3 none any Details for jasil-0.12.0-py3-none-any.whl

Total release size: 443.1 kB

Release files / jasil-0.12.0.tar.gz

Download URL jasil-0.12.0.tar.gz
Size 208.9 kB
Tags Source
SHA-256 checksum
How to use checksums
de6034dcbefd8bb06092a023dcfadffae91f85350032a231e3447faa9c931a09
BLAKE2b-256 checksum
How to use checksums
57124e257ffbb94ed632c4d8f2758be26de1494cf10144760228174eba9ffea2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","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.12.0-py3-none-any.whl

Download URL jasil-0.12.0-py3-none-any.whl
Size 234.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0317896fdcfc91a44e1d34b9465c87cdbb8b8092bd586800734a9fb9230c5f5d
BLAKE2b-256 checksum
How to use checksums
7e9428800aa110f220fdcd4ca1990c06f51ceedde1785efd44cdb11bf7a387b3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","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.12.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.

Release history Release notifications | RSS feed

This release

0.12.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page