OpenKache Python client

OpenKache is a high-performance cache server designed from the ground up for modern SSDs. Use this Python client to store, read, and delete values in a few lines.

PyPI package · GitHub source

Install

Python 3.11 or newer is required.

# pip
python -m pip install openkache

# uv
uv add openkache

# Existing uv virtual environment:
uv pip install openkache

# Poetry
poetry add openkache

# PDM
pdm add openkache

# Pipenv
pipenv install openkache

Published wheels support Linux x86_64/ARM64, macOS x86_64/ARM64, and Windows x86_64/ARM64. Linux wheels use the manylinux_2_38 policy tag; macOS and Windows tags come from their native Python packaging toolchain. Other Rust-supported targets can install from the source distribution.

The native Rust adapter supports Linux, macOS, and Windows on Rust-supported host architectures, including ARM64. Building from source requires Python, Rust 1.85 or newer, and the platform's normal C linker. The package selects .so, .dylib, or .dll at import time and does not assume Linux.

On Windows checkouts, run the generator from PowerShell:

$env:OPENKACHE_GENERATION_TARGET = "python"
..\generate.ts

Quick start

The example below assumes a local OpenKache server at 127.0.0.1:4433.

from openkache import Client

client = Client.connect("127.0.0.1:4433")
print(client.set("greeting", "hello"))  # -> created
print(client.get("greeting"))           # -> hello
print(client.delete("greeting"))        # -> True
client.close()

set returns SetOutcome.CREATED for a new key, get returns the value directly (None when the key is absent), and delete returns True when a value was removed.

The example uses the local development TLS profile, which does not verify the server certificate. Use it only with a local development server.

Reference

Client.connect(address)

Opens a connection and returns a Client.

  • Input: a non-empty host:port string. IPv6 endpoints use [host]:port.
  • Returns: Client.
  • Raises: OpenKacheError when the connection cannot be opened.
client = Client.connect("127.0.0.1:4433")

Client and OpenKacheClient refer to the same class.

client.get(key)

Reads one value as a native Python value by default.

  • Input: a UTF-8 str, signed 64-bit int, or bytes-like value (bytes, bytearray, or memoryview).
  • Returns: the decoded value, or None when the key is absent. Stored None and undefined values also return None, matching ordinary Python cache APIs.
  • Raises: OpenKacheValueError for an invalid key, an ambiguous native map, or a value that cannot be projected to Python; OpenKacheError for connection or server failures.
print(client.get("greeting"))  # -> "hello"

Use representation="lossless" when the exact value model matters:

exact = client.get("greeting", representation="lossless")
print(exact)  # -> TextStringValue(value='hello')

Native reads map integers to int, floats to float, bytes to bytes, arrays to list, and maps to dict when their keys remain distinct under Python equality. A stored None or undefined value returns None, just like an absent key. Use the lossless representation for the distinction between Null and Undefined, float width/raw bits, or model-distinct map keys such as True and 1.

client.set(key, value)

Stores one value, replacing any existing value for the key.

  • Input: the same key types accepted by get, plus a native or lossless structured value.
  • Returns: SetOutcome.CREATED for a new key or SetOutcome.REPLACED for an existing key.
  • Raises: OpenKacheValueError for an invalid key or value and OpenKacheError for connection or server failures.
outcome = client.set("greeting", "hello")
# outcome is SetOutcome.CREATED or SetOutcome.REPLACED

client.delete(key)

Deletes one key. Deleting a missing key is safe.

  • Input: a key accepted by get.
  • Returns: True when a value was removed, or False when no value existed.
  • Raises: OpenKacheValueError for an invalid key and OpenKacheError for connection or server failures.
removed = client.delete("greeting")
if removed:
    print("deleted")

client.close()

Closes the connection and returns None. Calling it more than once is safe.

client.close()

The client also supports with Client.connect(address), which closes the connection automatically when the block exits.

Keys

Keys are typed. Use:

  • str for UTF-8 text keys;
  • int for signed 64-bit integer keys;
  • bytes, bytearray, or memoryview for exact byte keys.
client.get("text-key")
client.get(42)
client.get(b"bytes-key")

Values

The client converts common Python values to structured values:

  • None becomes Null.
  • bool becomes Boolean.
  • int becomes an exact Integer.
  • float becomes an IEEE-754 binary64 Float.
  • str becomes UTF-8 TextString.
  • bytes, bytearray, and memoryview become Bytes.
  • list and tuple become Array.
  • dict becomes Map.
client.set("profile", {"name": "Ada", "active": True})

Use the lossless model when the exact representation matters: UNDEFINED/UndefinedValue, IntegerValue, FloatValue, ByteStringValue, TextStringValue, ArrayValue, and MapValue. The short names Undefined, Integer, Float, ByteString, TextString, Array, Map, and Value are compatibility aliases.

Value helpers

  • to_value(value, limits=None) converts a native Python value to the lossless model.
  • encode_value(value, limits=None) returns one encoded StructuredValue-CBOR-v1 item as bytes.
  • decode_value(data, limits=None) decodes one complete item from bytes-like input.
  • model_equal(left, right) compares model values without treating True and 1 as equal.
  • to_native(value) projects a decoded lossless value to the native representation used by client.get(..., representation="native").
  • ValueLimits bounds encoded bytes, nesting depth, item count, and integer magnitude.
from openkache import decode_value, encode_value, model_equal, to_value

encoded = encode_value({"count": 1})
decoded = decode_value(encoded)
assert model_equal(decoded, to_value({"count": 1}))

StructuredValueError reports conversion, encoding, decoding, and resource limit failures. Its kind property is a ValueErrorKind.

Errors

  • OpenKacheError — connection, protocol, server, or operation failure.
  • OpenKacheValueError — invalid key or value supplied by the caller.
  • OpenKacheUnknownMutationError — a mutation may have reached the server without a confirmed result; do not replay it automatically.
  • OpenKacheIncompatibleServerError — the server returned an outcome that this client does not support.
  • StructuredValueError — invalid structured-value data or resource limits.

Strings must contain well-formed Unicode. Unpaired UTF-16 surrogate code units are rejected.

More information

Project links

Data verified by PyPI on Aug 26, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for kkimdev from gravatar.com kkimdev

Credits

Author: OpenKache Team

GitHub Statistics

Data verified by PyPI on Aug 26, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.11

Tags

cache openkache ssd

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

openkache-0.1.3.tar.gz (518.9 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

openkache-0.1.3-py3-none-win_arm64.whl (3.3 MB view details)

Uploaded Python 3Windows ARM64

openkache-0.1.3-py3-none-win_amd64.whl (3.6 MB view details)

Uploaded Python 3Windows x86-64

openkache-0.1.3-py3-none-manylinux_2_38_x86_64.whl (4.1 MB view details)

Uploaded Python 3manylinux: glibc 2.38+ x86-64

openkache-0.1.3-py3-none-manylinux_2_38_aarch64.whl (3.9 MB view details)

Uploaded Python 3manylinux: glibc 2.38+ ARM64

openkache-0.1.3-py3-none-macosx_11_0_arm64.whl (3.7 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

openkache-0.1.3-py3-none-macosx_10_13_x86_64.whl (4.0 MB view details)

Uploaded Python 3macOS 10.13+ x86-64

File details

Details for the file openkache-0.1.3.tar.gz.

File metadata

  • Download URL: openkache-0.1.3.tar.gz
  • Upload date:
  • Size: 518.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for openkache-0.1.3.tar.gz
Algorithm Hash digest
SHA256 36e7c84752997df31cc86882ceb335f4c68775bace0f6996fe11503adaeeac10
MD5 a3a6081ec3cdb7f73ab9bb78b096a8b1
BLAKE2b-256 d08118649e6f5b31c3efadfdd8423e4dc71ee2be005bd458d099d7a0fb8bd9ae

See more details on using hashes here.

Provenance

The following attestation bundles were made for openkache-0.1.3.tar.gz:

Publisher: publish-pypi.yml on openkache/openkache

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openkache-0.1.3-py3-none-win_arm64.whl.

File metadata

  • Download URL: openkache-0.1.3-py3-none-win_arm64.whl
  • Upload date:
  • Size: 3.3 MB
  • Tags: Python 3, Windows ARM64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for openkache-0.1.3-py3-none-win_arm64.whl
Algorithm Hash digest
SHA256 bdcb8a38140bcd652a81c6005d4b511a457ab72cd4898c4891c7c2f8d8e3b0b6
MD5 6a4002742d98316b045e8a277f529ba8
BLAKE2b-256 60f1e6bb7bde51684569d4e85579f36d8e656bf1193bdac9ae87983a0b7cc10d

See more details on using hashes here.

Provenance

The following attestation bundles were made for openkache-0.1.3-py3-none-win_arm64.whl:

Publisher: publish-pypi.yml on openkache/openkache

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openkache-0.1.3-py3-none-win_amd64.whl.

File metadata

  • Download URL: openkache-0.1.3-py3-none-win_amd64.whl
  • Upload date:
  • Size: 3.6 MB
  • Tags: Python 3, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for openkache-0.1.3-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 a2ebf50faecdd53ab932756f1e961448b91d650b404ff07dbcae565050c4d38b
MD5 21771fedbe6e21b072138fd4d4fe865d
BLAKE2b-256 393fb6bb51d7746f18bce0846d7a6cec1f7315381af4af489dc74f8d35aacd94

See more details on using hashes here.

Provenance

The following attestation bundles were made for openkache-0.1.3-py3-none-win_amd64.whl:

Publisher: publish-pypi.yml on openkache/openkache

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openkache-0.1.3-py3-none-manylinux_2_38_x86_64.whl.

File metadata

File hashes

Hashes for openkache-0.1.3-py3-none-manylinux_2_38_x86_64.whl
Algorithm Hash digest
SHA256 c70c8d923a318af7615e9067153541857960eb3030e684d174fee63aba86d42c
MD5 a98eb278c2327c1221b713ee1dc0c776
BLAKE2b-256 8c96c2922c91f9bf0838a9780082f61d52d51efe1539d1337dd2b8bd8246dcf9

See more details on using hashes here.

Provenance

The following attestation bundles were made for openkache-0.1.3-py3-none-manylinux_2_38_x86_64.whl:

Publisher: publish-pypi.yml on openkache/openkache

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openkache-0.1.3-py3-none-manylinux_2_38_aarch64.whl.

File metadata

File hashes

Hashes for openkache-0.1.3-py3-none-manylinux_2_38_aarch64.whl
Algorithm Hash digest
SHA256 c16dc6ff1e0fde2c32990d8c7c1a4e3eca8005386c08c8ed5140f7ba856a50b9
MD5 b5e5a11690654e747ab556fb7875c30b
BLAKE2b-256 c2f22946a80b71c058465f454808964842a638d9214d0796a3897f7fb0be3371

See more details on using hashes here.

Provenance

The following attestation bundles were made for openkache-0.1.3-py3-none-manylinux_2_38_aarch64.whl:

Publisher: publish-pypi.yml on openkache/openkache

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openkache-0.1.3-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for openkache-0.1.3-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 5aab9553a55fa595ce887a58efc4bf2ec3cbfaa9ecf29da30ea7faab5bd68d5e
MD5 dfabfd85223bf63a7a763cee2426bd1c
BLAKE2b-256 ee13769e57b9f1c96f36c028420724da2e255a89ca0806325bc7674c727765ef

See more details on using hashes here.

Provenance

The following attestation bundles were made for openkache-0.1.3-py3-none-macosx_11_0_arm64.whl:

Publisher: publish-pypi.yml on openkache/openkache

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openkache-0.1.3-py3-none-macosx_10_13_x86_64.whl.

File metadata

File hashes

Hashes for openkache-0.1.3-py3-none-macosx_10_13_x86_64.whl
Algorithm Hash digest
SHA256 ac4c7873925dc6a634c47bb3ec69e47d4f67ca918aee97c3be126d8a8a632542
MD5 037e4c0cf4f0039c3b8d1200b99546c4
BLAKE2b-256 e15c42933d5ab109d42d41f02738c1e5c86dc1f270e638f065e668664feca862

See more details on using hashes here.

Provenance

The following attestation bundles were made for openkache-0.1.3-py3-none-macosx_10_13_x86_64.whl:

Publisher: publish-pypi.yml on openkache/openkache

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.1.3 This release

7 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

0.0.2

2 files

0.0.1

2 files

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