Skip to main content

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.

CI

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

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)

Source distribution for kstash 0.2.0
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)

Table of built distributions (wheels) for kstash 0.2.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

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

Select from 2 files

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