Python client

PutFS ships a Python client that currently wraps anystore's Store interface over HTTP (using fsspec HTTPFileSystem under the hood).

Install

pip install putfs[client]

Connect

from putfs.client import PutFS

# url, key and secret can be inferred from environment vars:
# `PUTFS_ENDPOINT_URL`, `PUTFS_API_KEY`, `PUTFS_API_SECRET`
client = PutFS("http://localhost:8000", key="my-key", secret="my-secret")

The key and secret are sent as X-Api-Key and X-Api-Secret headers on every request. See Auth for the nginx-side key configuration.

Store and retrieve

# Put a value (bytes, str, dict, pydantic model, ...)
client.put("acme/invoices/q1.txt", "invoice data")
client.put("acme/invoices/q1.json", {"amount": 1000, "currency": "EUR"})

# Get it back
data = client.get("acme/invoices/q1.txt")
invoice = client.get("acme/invoices/q1.json")

Check existence

if client.exists("acme/invoices/q1.txt"):
    print("exists")

Delete

client.delete("acme/invoices/q1.txt")

File-like access

# Stream write big file
with open("./big.pdf", "rb") as i:
    with client.open("acme/big.pdf", "wb") as o:
        while chunk := i.read(1024 * 1024 * 10):
            o.write(chunk)

# Read
import csv

with client.open("acme/invoices/q1.csv", "r") as f:
    for row in csv.DictReader(f):
        print(row)

List keys

# All keys under a prefix
for key in client.iterate_keys(prefix="acme/invoices"):
    print(key)

# With glob
for key in client.iterate_keys(glob="acme/invoices/*.pdf"):
    print(key)

Metadata

info = client.info("acme/invoices/q1.pdf")
# Stats object with size, last_modified, etc.

Serialization

anystore handles serialization automatically based on value type. You can also control it explicitly:

from anystore.serialize import Mode

# Force a specific serialization mode
client.put("acme/data/config", {"key": "value"}, serialization_mode=Mode.JSON)
client.get("acme/data/config", serialization_mode=Mode.JSON)

See the anystore documentation for the full Store API.