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.7.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("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.

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

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)

Source distribution for jasil 0.7.0
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)

Table of built distributions (wheels) for jasil 0.7.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.7.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