kstash
kstash converts payloads into addressable stashes.
It allows programs to communicate using stash addresses instead of entire payloads, reducing the strain on messaging systems.
Installation
pip install kstash
Requirements
- Python >= 3.13
- AWS credentials configured (for S3 storage)
Basics
Use kstash to put a payload into an addressable stash.
Then provide kstash with the address to recover the payload.
import kstash
stash = kstash.create("my-payload", "some-data")
loaded = kstash.retrieve(stash.address)
stash == loaded
Simple Storage (S3)
By default, kstash.create() saves large payloads to S3.
# Optional: Test Backend Setup
import boto3
from moto import mock_aws
mock_aws().start()
conn = boto3.resource("s3", region_name="us-east-1")
conn.create_bucket(Bucket="stashes")
import kstash
# Process A: Sends a message containing the address of a stashed payload.
context = {"as_of": "today", "bin": b"0" * 1024 * 512}
stash = kstash.create("context", context, namespace="stashes")
message = {"context": str(stash.address), "command": "gen_report"}
assert str(stash.address) == "s3://stashes/context.c6ab205fe81dcad3eec3ab48b96b0618"
# Process B: Rebuilds the message from the stash's address.
loaded_stash = kstash.retrieve(message["context"])
assert loaded_stash == stash
Shared Links
Use stash.share() to produce a short-lived HTTPS link to the stash.
See kstash.Config.share_ttl_sec for configuration details.
import time
# Process A: Sends a message containing a shared link.
shared_link = stash.share(ttl_sec=5)
# Process B: Rebuilds the message from the shared link.
time.sleep(3)
loaded_stash = kstash.retrieve(shared_link)
assert loaded_stash == shared_stash
# Process B: Fails to retrieve the stash from an expired link.
time.sleep(3)
loaded_stash = kstash.retrieve(shared_link)
# Error: StashNotFound, share link expired
Inline Data Optimization
kstash.create() embeds small payloads in the stash's address.
See kstash.Config.max_inline_len for configuration details.
import kstash
stash = kstash.create("colorcode", 12, namespace="stashes")
assert str(stash.address) == "inline://stashes/colorcode?data=DA%3D%3D"
loaded_stash = kstash.retrieve(stash.address)
assert loaded_stash == stash
loaded_stash.data
Backends
Storage backends can be disabled to address specific deployment or test scenarios.
See kstash.Config.backends for more details.
import kstash
config = kstash.Config(backends=["mem"])
stash = kstash.create("object", {"data": 123}, config=config)
assert str(stash.address) == "mem://default/object.34472d91b2f84052bf26d4eaa862ef86"
loaded_stash = kstash.retrieve(stash.address, config=config)
assert loaded_stash == stash
Development Setup
uv sync
source .venv/bin/activate
pytest
Metadata
Release files for kstash 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| kstash-0.2.0.tar.gz | 34.5 kB | With provenance | Details for kstash-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| kstash-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for kstash-0.2.0-py3-none-any.whl |
Total release size: 45.8 kB
Release files / kstash-0.2.0.tar.gz
| Download URL | kstash-0.2.0.tar.gz |
|---|---|
| Size | 34.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
db9a300309b1532e39320517af6c5dcb312b6ea684a6b578e2e4988b57191d17
|
|
BLAKE2b-256 checksum How to use checksums |
e2984f72e920efb9b371aae78eac43f9693be4445eb8996deb9f735d0285ce2c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
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 May 22, 2025.
Transparency logRelease files / kstash-0.2.0-py3-none-any.whl
| Download URL | kstash-0.2.0-py3-none-any.whl |
|---|---|
| Size | 11.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
368e5b3b16d59f0851be7c2e6d7f9f29767996b28dcfb548a5996e8b5c8663e8
|
|
BLAKE2b-256 checksum How to use checksums |
ee5a2020c56f1131bfd3971b5b65d3db36ae96554aa6ecf18023db1b66f0468e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
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 May 22, 2025.
Transparency logSecurity for kstash 0.2.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.
Attestation for kstash-0.2.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 May 22, 2025.
Transparency logA 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.