Skip to main content

abstraction-job, in Python

A record on disk describing work somebody asked for, and rules for who is allowed to be doing it right now. Any process, in any of three languages, can pick up work another one left. No daemon, no database: one directory of files. Standard library only.

This page is the Python package. The contract, the Go and C++ implementations, what is measured and what is UNPROVEN are on the repository.

Install

Not on PyPI, and the names on PyPI are not ours. Clone the three repositories beside each other and install them in dependency order:

git clone https://github.com/openabstractions/abstraction-cas
git clone https://github.com/openabstractions/abstraction-watch
git clone https://github.com/openabstractions/abstraction-job

pip install ./abstraction-cas/python ./abstraction-watch/python
pip install ./abstraction-job/python

Python 3.9 or later. The order is not a style: pyproject.toml names these dependencies by the names they would have on an index, and pip can only satisfy them from what is installed already. Copying the three modules into a _vendor/ directory of your own works too — each is pure standard library.

An example that runs

One worker takes a job, records how far it got, and goes away. A second worker picks it up and reads what the first one proved.

import abstraction_job as job

store = job.FileStore("jobs")

record = job.Record(id="", kind="example", spec={"fetch": "anything at all"})
job_id = store.submit(record)

mine = store.claim(job_id, "worker-a", 60)

def got_a_megabyte(r):
    r.progress.done = 1 << 20
    r.checkpoint = {"bytes": 1 << 20}

store.update(job_id, mine.lease.epoch, got_a_megabyte)
store.release(job_id, mine.lease.epoch)

nxt = store.claim(job_id, "worker-b", 60)
print("worker-b took over at", nxt.progress.done, "bytes, resuming from", nxt.checkpoint)

It prints worker-b took over at 1048576 bytes, resuming from {'bytes': 1048576}. worker-b is a second claim in the same program here, but the store does not require that — it can be another process, another language, or this machine after a reboot. store.orphans() is how the next launch finds the jobs nobody is working on.

What an application calls

call what it does
FileStore(root) the store that ships. root is a directory
submit(record) write a new job, return its id
load(id) / list() read one, or all
claim(id, owner, ttl_seconds) take ownership for a while. LeaseHeld if somebody else holds it
renew(id, epoch, ttl) / release(id, epoch) extend or give up ownership
update(id, epoch, mutate) change the record. The epoch you were given must still be current, or the write is refused with StaleEpoch
orphans() jobs nobody is working on: the lease lapsed, or was released
set_intent(id, want, by) ask the owner to pause, resume or cancel, when you are not the owner
recall(id, epoch, reason, by, grace) demand the record back from an owner that has stopped answering
watch(store, kind, budget) be told a record changed, and told when nothing has

A lease is time-bounded ownership; the epoch on every write is its fencing token, so a worker that froze and woke up cannot overwrite its successor. A checkpoint is what a successor needs to carry on, progress is what was observed, and intent is what somebody wants to happen. spec and checkpoint are opaque dicts here and kind says who may read them.

Every normative rule is on CONTRACT.md, tagged; none is restated here.

What may break

  • No tagged release and no package index. Pin a commit you have read.
  • A store on a network filesystem is only as fresh as the client's cache. Over SMB a record has been read 154 s stale by the Windows redirector — the transcript.
  • watch, which this depends on, carries no conformance verdict. What is proven and what is not.
  • Every published transcript was produced on Windows or Linux. macOS is UNPROVEN throughout.

Apache-2.0. See LICENSE.

Metadata

Release files for abstraction-job 0.1.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 abstraction-job 0.1.0
File Size Uploaded Provenance Actions
abstraction_job-0.1.0.tar.gz 38.8 kB With provenance Details for abstraction_job-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for abstraction-job 0.1.0
File Interpreter ABI Platform Actions
abstraction_job-0.1.0-py3-none-any.whl Python 3 none any Details for abstraction_job-0.1.0-py3-none-any.whl

Total release size: 78.1 kB

Release files / abstraction_job-0.1.0.tar.gz

Download URL abstraction_job-0.1.0.tar.gz
Size 38.8 kB
Tags Source
SHA-256 checksum
How to use checksums
512d0b45d39286b853a7c18f0435a731e49aa77810790258908e1b9ee8af5b89
BLAKE2b-256 checksum
How to use checksums
95fb5dd495910d3a472508ce283263a0d508cf38ee19555f5e513d2101295d44
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 10, 2026.

Transparency log

Release files / abstraction_job-0.1.0-py3-none-any.whl

Download URL abstraction_job-0.1.0-py3-none-any.whl
Size 39.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d1951ae01bbe105f1f505dedf12856dd9867670254a3f10ed9eac07ec7859994
BLAKE2b-256 checksum
How to use checksums
0c35cb9cd6c987379006033377b5ccb8f5f7b37c5526a155aa543050f252fad4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 10, 2026.

Transparency log

Security for abstraction-job 0.1.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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for abstraction_job-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 10, 2026.

Transparency log

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.1.0 This release

2 release files Full 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