spork-state
Thread-safe state management with one implementation for both Spork and Python.
spork-state 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 idiomatic package-level Spork and typed Python APIs 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.2,<0.3"]
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 :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.4.0 or newer. The public Spork namespace, Python initializer, generic stubs, version metadata, and py.typed are generated from the unified :api declaration in spork.it; none are maintained as parallel facade 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.2.0.tar.gz.
File metadata
- Download URL: spork_state-0.2.0.tar.gz
- Upload date:
- Size: 15.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
2cf926821671cde609bbf3059cd09bc0165bd60bec817179ab95db584739cabc
|
|
| MD5 |
77a6fc97fa4a09fb2eb8a192897ee7ca
|
|
| BLAKE2b-256 |
a7bab48e64c3f22a85bd37e6f5858f434d9fc69eeb0f164d49fd3c765d89aaec
|
Provenance
The following attestation bundles were made for spork_state-0.2.0.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.2.0.tar.gz -
Subject digest:
2cf926821671cde609bbf3059cd09bc0165bd60bec817179ab95db584739cabc - Sigstore transparency entry: 2633526887
- Sigstore integration time:
-
Permalink:
spork-it/spork-state@180782922b106fd2ecc52aa796ab5604df6ec879 -
Branch / Tag:
refs/tags/v0.2.0 - Owner: https://github.com/spork-it
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
build.yml@180782922b106fd2ecc52aa796ab5604df6ec879 -
Trigger Event:
push
-
Statement type:
File details
Details for the file spork_state-0.2.0-py3-none-any.whl.
File metadata
- Download URL: spork_state-0.2.0-py3-none-any.whl
- Upload date:
- Size: 16.1 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 |
9a03d8026cf5370039ead3316e74dc318f734d1cb54b555c6ff94d803d6fa6a1
|
|
| MD5 |
eb619dd44d95d797a30b466184708e3e
|
|
| BLAKE2b-256 |
c3225e4d72478c356482539725502a21ef2d2edc7492d83617dc8f662a47c518
|
Provenance
The following attestation bundles were made for spork_state-0.2.0-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.2.0-py3-none-any.whl -
Subject digest:
9a03d8026cf5370039ead3316e74dc318f734d1cb54b555c6ff94d803d6fa6a1 - Sigstore transparency entry: 2633527202
- Sigstore integration time:
-
Permalink:
spork-it/spork-state@180782922b106fd2ecc52aa796ab5604df6ec879 -
Branch / Tag:
refs/tags/v0.2.0 - Owner: https://github.com/spork-it
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
build.yml@180782922b106fd2ecc52aa796ab5604df6ec879 -
Trigger Event:
push
-
Statement type:
