Use the Python SDK

Applies to: current development source bundles. Obtain a matched client/server release through early-access support; registry publication is not available yet. Paths below are relative to the supplied source checkout.

Thread-safe synchronous TCP client. Requires Python 3.10+; no runtime dependencies. This first release has not been published to PyPI.

Install and use

From the repository root:

python3 -m pip install ./python-smkv

from smkv import Client, SmkvError

with Client("127.0.0.1:7379", pool_size=4, timeout=5) as client:
    client.put(b"greeting", b"hello", sync=True, ttl_ms=60000)
    print(client.get(b"greeting"))
    users = client.table("users")
    users.put(b"42", {"name": "Ada", "visits": 1})
    users.update(b"42", {"visits": 2})
    print(users.get(b"42", columns=["name"]))
    try:
        client.get(b"missing")
    except SmkvError as error:
        if error.code != "not_found":
            raise

Run python3 python-smkv/examples/basic.py 127.0.0.1:7379 against a disposable node. Keys and raw values are bytes; empty values are valid. Columns accept bytes, str, signed 64-bit int, float, and bool. Integers outside int64 are rejected.

Cluster connections

from smkv import ClusterClient

with ClusterClient(["127.0.0.1:7381"], timeout=5) as cluster:
    print(cluster.get(b"greeting"))
    # Explicitly allow stale data:
    print(cluster.get_replica(b"greeting"))

Seeds are management endpoints. Routing includes the table in row keys. refresh() updates topology; topology returns a copy. table(...).get_replica reads a replica when used on a cluster client.

Options, errors, and security

The default pool has four connections per node, a five-second operation deadline and idle timeout, 1 KiB keys, and 1 MiB values. Configure pool_size, timeout, idle_timeout, max_key_bytes, and max_value_bytes. Per-call timeout can shorten the deadline, which covers pool wait and socket I/O. Native DNS resolution cannot be interrupted; use IP endpoints when a strict end-to-end bound is needed. Clients can be shared across threads, but must be created separately after fork. close() cancels outstanding socket I/O and closes the pool.

Writes accept sync, replica_ack, and durable_replica_ack; defaults do not request per-write disk synchronization. ttl_ms on put/update uses milliseconds: omitted means no expiry for put and preserves expiry for update; zero expires immediately. Delete does not accept TTL. Atomic update(key, set_columns, remove) preserves columns not mentioned; get(key, columns=...) projects columns.

SmkvError.code identifies server/transport failures; status is the numeric server status when present. An error with outcome_unknown=True means a write may have completed. Do not blindly retry it. Only explicit wrong_owner is retried by the cluster client, within the original deadline.

Plaintext and no authentication are defaults. For verified TLS and bearer auth:

import ssl
from smkv import Security

security = Security(tls=ssl.create_default_context(cafile="ca.pem"),
                    credential={"name": "app", "token": token})
client = Client("db.example.com:7379", security=security)

Load token from your secret provider. Cluster security and management_security are separate options; configure both when both ports require security. TLS always verifies the certificate and hostname. There is no downgrade.

Scans, batch operations, and an async Python API are not included yet. See shared contract and tests.