depozit-python

Python client for Depozit — a self-hosted file storage service.

Install

pip install depozit

Server

This package is only the client. To install and run the server, see depozit-server.

Usage

import depozit

default = depozit.connect("localhost:50051", api_key="your-api-key") # container default

default.upload("photo.jpg", "images/photo.jpg")        # upload a local file
default.upload(b"hello", "notes/hello.txt")            # upload raw bytes
default.upload_stream((c for c in [b"hel", b"lo"]), "notes/hello.txt")  # upload a generator of bytes

data = default.read("images/photo.jpg")                # read a whole file

with open("photo.jpg", "wb") as f:                     # read chunk by chunk
    for chunk in default.read_stream("images/photo.jpg"):
        f.write(chunk)

default.rename("notes/hello.txt", "greet.txt")         # rename, now notes/greet.txt
default.delete("images/photo.jpg")                     # delete

for path in default.find(prefix="images/"):            # list files
    print(path)

Errors raise Python exceptions: FileNotFoundError (missing file or container), FileExistsError (upload without overwrite, rename onto an existing file), PermissionError (wrong API key, deleting or renaming the default container), ValueError (invalid path or name). Anything else raises depozit.errors.DepozitError, with the gRPC status in code: RESOURCE_EXHAUSTED for an upload over the server's MAX_FILE_SIZE, DATA_LOSS for a stored file that fails its integrity check.

TLS

If the server sets TLS_CERT / TLS_KEY, connect with tls=True. For a self-signed certificate, pass it as root_certificates:

default = depozit.connect("myserver:50051", api_key="your-api-key", root_certificates=open("cert.pem", "rb").read())

Containers

Each connection is bound to one container. connect creates the container if it does not exist.

uploads = depozit.connect("localhost:50051", api_key="your-api-key", container="uploads")
uploads.upload_stream((c for c in [b"hello"]), "hello.txt")  # stored in "uploads"
uploads.close()

Only a client on the default container can manage containers. On any other container these methods raise PermissionError. This is a guard against mistakes, not a security boundary: the API key itself allows managing every container.

default = depozit.connect("localhost:50051", api_key="your-api-key")

default.create_container("backups")
default.rename_container("backups", "archive")
default.delete_container("archive")

Use with to close the connection automatically:

with depozit.connect("localhost:50051", api_key="your-api-key", container="uploads") as uploads:
    uploads.read("hello.txt")

Async

import depozit.aio

async with await depozit.aio.connect("localhost:50051", api_key="your-api-key") as default:
    data = await default.read("images/photo.jpg")