spork-state
Thread-safe state management with one implementation for both Spork and Python.
The first release provides Atom: a mutable reference whose updates are synchronized, validated before commit, and observable through synchronous watches. The implementation and type declarations live in Spork; spork build generates the typed Python package facade directly from the manifest.
Install
Python projects:
python -m pip install spork-state
Spork projects add the package to spork.it and synchronize the project environment:
:dependencies ["spork-state>=0.1,<0.2"]
spork sync
spork-state supports Python 3.10–3.14, including free-threaded 3.14.
Python API
from spork_state import Atom
counter = Atom(0, validator=lambda value: value >= 0)
unsubscribe = counter.subscribe(
lambda old, new: print(f"{old} -> {new}"),
fire_immediately=True,
)
counter.swap(lambda value, amount: value + amount, 3)
assert counter.value == 3
assert counter.compare_and_set(counter.value, 4)
unsubscribe()
Functional equivalents (atom, deref, swap, reset, and others) are also exported.
Spork API
(ns example.counter
(:require [spork-state.core :as state]))
(def counter (state.atom 0 (fn [value] (>= value 0))))
(state.add-watch! counter :log
(fn [key reference old-value new-value]
(print old-value "->" new-value)))
(state.swap! counter (fn [value amount] (+ value amount)) 3)
(assert (= (state.deref counter) 3))
The core Spork functions are atom, atom?, deref, swap!, swap-vals!, reset!, reset-vals!, compare-and-set!, add-watch!, remove-watch!, get-validator, and set-validator!.
Guarantees
swap,reset, validator replacement, and compare-and-set are linearizable.- A swap function runs exactly once while the atom's reentrant lock is held.
- Validators run before commit. Rejection leaves the old value unchanged.
- Watches run synchronously after commit, outside the lock, in registration order.
- A watch exception propagates but never rolls back committed state.
- Compare-and-set and change notification use object identity, not equality.
- Reading an atom is safe; mutating a mutable value obtained from it is not synchronized. Prefer immutable values.
See the API reference and design semantics for concurrency details.
Development
Requires spork-lang 0.3.8 or newer. Package initializers, generic stubs, version metadata, and py.typed are generated from spork.it and core.spork; none are maintained as parallel source files.
spork sync --dev
spork test
mypy tests/typing/usage.py
spork dist --clean
python -m twine check dist/*
License
MIT
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file spork_state-0.1.1.tar.gz.
File metadata
- Download URL: spork_state-0.1.1.tar.gz
- Upload date:
- Size: 15.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
8fc3e48922b0cb4d60caa4b87f1cb3b74692af2a715a4ad3e870a0e034712c26
|
|
| MD5 |
9fd5f7044dc7a36e995acb874866633d
|
|
| BLAKE2b-256 |
328b28a14fd44585d0b05a6359774c1969c6177d0e1a15581db7605c764c91ec
|
Provenance
The following attestation bundles were made for spork_state-0.1.1.tar.gz:
Publisher:
build.yml on spork-it/spork-state
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
spork_state-0.1.1.tar.gz -
Subject digest:
8fc3e48922b0cb4d60caa4b87f1cb3b74692af2a715a4ad3e870a0e034712c26 - Sigstore transparency entry: 2633004648
- Sigstore integration time:
-
Permalink:
spork-it/spork-state@f9eb65147fb697165dd6fa23303fb3e11ef9c676 -
Branch / Tag:
refs/tags/v0.1.1 - Owner: https://github.com/spork-it
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
build.yml@f9eb65147fb697165dd6fa23303fb3e11ef9c676 -
Trigger Event:
push
-
Statement type:
File details
Details for the file spork_state-0.1.1-py3-none-any.whl.
File metadata
- Download URL: spork_state-0.1.1-py3-none-any.whl
- Upload date:
- Size: 15.7 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
a77ed5d5483d45a9ef094df615756158e26bb4aa3b709ef23988d8bd112c2c1b
|
|
| MD5 |
542a01d2d391d738145dcb5d47a0f43e
|
|
| BLAKE2b-256 |
ec6da62cad5b50f44c837fd636912ebaac985a4ee6f7853017ad4037057abf02
|
Provenance
The following attestation bundles were made for spork_state-0.1.1-py3-none-any.whl:
Publisher:
build.yml on spork-it/spork-state
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
spork_state-0.1.1-py3-none-any.whl -
Subject digest:
a77ed5d5483d45a9ef094df615756158e26bb4aa3b709ef23988d8bd112c2c1b - Sigstore transparency entry: 2633004665
- Sigstore integration time:
-
Permalink:
spork-it/spork-state@f9eb65147fb697165dd6fa23303fb3e11ef9c676 -
Branch / Tag:
refs/tags/v0.1.1 - Owner: https://github.com/spork-it
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
build.yml@f9eb65147fb697165dd6fa23303fb3e11ef9c676 -
Trigger Event:
push
-
Statement type:
