JustStorage Python SDK
Python client for the JustStorage object storage service.
Features
- Type hints for all methods and models
- API key and JWT token authentication
- Streaming support for large files
- Exception hierarchy for error handling
- Automatic retries for transient failures
Installation
pip install just-storage
Or from source:
git clone https://github.com/yourorg/just_storage.git
cd just_storage/python-sdk
pip install -e .
Quick Start
from just_storage import JustStorageClient, StorageClass
# Initialize client
client = JustStorageClient(
base_url="http://localhost:8080",
api_key="your-api-key"
)
# Upload a file
with open("model.bin", "rb") as f:
obj = client.upload(
file_obj=f,
namespace="models",
tenant_id="550e8400-e29b-41d4-a716-446655440000",
key="llama-3.1-8b",
storage_class=StorageClass.HOT
)
print(f"Uploaded: {obj.id}")
# Download a file
with open("downloaded.bin", "wb") as f:
client.download(obj.id, "550e8400-e29b-41d4-a716-446655440000", output_file=f)
# List objects
response = client.list(
namespace="models",
tenant_id="550e8400-e29b-41d4-a716-446655440000",
limit=50
)
print(f"Found {response.total} objects")
# Delete object
client.delete(obj.id, "550e8400-e29b-41d4-a716-446655440000")
Authentication
The SDK supports two authentication methods:
API Key
client = JustStorageClient(
base_url="http://localhost:8080",
api_key="your-api-key"
)
JWT Token
client = JustStorageClient(
base_url="http://localhost:8080",
jwt_token="eyJ0eXAiOiJKV1QiLCJhbGc..."
)
API Reference
Client Initialization
JustStorageClient(
base_url: str,
api_key: Optional[str] = None,
jwt_token: Optional[str] = None,
timeout: int = 30,
max_retries: int = 3,
)
Methods
health() -> HealthStatus
Check service health (no authentication required).
status = client.health()
print(f"Status: {status.status}")
readiness() -> HealthStatus
Check service readiness including database connectivity.
status = client.readiness()
if status.status == "ready":
print("Service is ready")
upload(...) -> ObjectInfo
Upload an object to storage.
obj = client.upload(
file_obj: BinaryIO,
namespace: str,
tenant_id: str,
key: Optional[str] = None,
storage_class: StorageClass = StorageClass.HOT,
)
Parameters:
file_obj: File-like object opened in binary modenamespace: Object namespace (e.g., 'models', 'kb', 'uploads')tenant_id: Tenant identifier (UUID string)key: Optional human-readable key for retrievalstorage_class: Storage class (StorageClass.HOTorStorageClass.COLD)
Returns: ObjectInfo with uploaded object metadata
download(...) -> Union[bytes, ObjectInfo]
Download an object by ID.
# Download to file
obj = client.download(
object_id: str,
tenant_id: str,
output_file: Optional[BinaryIO] = None,
verify_hash: bool = False,
)
# Download to memory
data = client.download(
object_id: str,
tenant_id: str,
)
Parameters:
object_id: Object UUIDtenant_id: Tenant identifier (UUID string)output_file: Optional file-like object to write to. If None, returns bytes.verify_hash: If True, verify content hash matches
Returns: Bytes if output_file is None, otherwise ObjectInfo.
delete(...) -> None
Delete an object.
client.delete(
object_id: str,
tenant_id: str,
)
Parameters:
object_id: Object UUIDtenant_id: Tenant identifier (UUID string)
list(...) -> ListResponse
List objects with pagination.
response = client.list(
namespace: str,
tenant_id: str,
limit: int = 50,
offset: int = 0,
)
Parameters:
namespace: Filter by namespacetenant_id: Filter by tenantlimit: Results per page (default: 50, max: 1000)offset: Pagination offset (default: 0)
Returns: ListResponse with objects and pagination metadata
Error Handling
Exception hierarchy:
from just_storage import (
JustStorageError,
JustStorageAPIError,
JustStorageNotFoundError,
JustStorageUnauthorizedError,
JustStorageConflictError,
JustStorageBadRequestError,
)
try:
obj = client.upload(...)
except JustStorageNotFoundError:
print("Object not found")
except JustStorageUnauthorizedError:
print("Authentication failed")
except JustStorageConflictError:
print("Key already exists")
except JustStorageAPIError as e:
print(f"API error: {e.message} (status: {e.status_code})")
except JustStorageError as e:
print(f"Error: {e.message}")
Advanced Usage
Context Manager
with JustStorageClient(base_url="...", api_key="...") as client:
obj = client.upload(...)
Streaming Large Files
Streaming is handled automatically:
# Upload large file
with open("large_model.bin", "rb") as f:
obj = client.upload(f, namespace="models", tenant_id="...")
# Download large file
with open("downloaded.bin", "wb") as f:
client.download(obj.id, tenant_id="...", output_file=f)
Content Hash Verification
data = client.download(
object_id="...",
tenant_id="...",
verify_hash=True
)
Pagination
offset = 0
limit = 50
while True:
response = client.list(
namespace="models",
tenant_id="...",
limit=limit,
offset=offset
)
for obj in response.objects:
print(f"Object: {obj.id}")
if offset + limit >= response.total:
break
offset += limit
Data Models
ObjectInfo
@dataclass
class ObjectInfo:
id: str
namespace: str
tenant_id: str
key: Optional[str]
status: ObjectStatus
storage_class: StorageClass
content_hash: Optional[str]
size_bytes: Optional[int]
content_type: Optional[str]
metadata: Dict[str, Any]
created_at: datetime
updated_at: datetime
ListResponse
@dataclass
class ListResponse:
objects: list[ObjectInfo]
total: int
limit: int
offset: int
Enums
class StorageClass(str, Enum):
HOT = "hot"
COLD = "cold"
class ObjectStatus(str, Enum):
WRITING = "WRITING"
COMMITTED = "COMMITTED"
DELETING = "DELETING"
DELETED = "DELETED"
Examples
See the examples/ directory:
basic_usage.py- Upload, download, delete operationspagination.py- Listing with paginationerror_handling.py- Error handling
Requirements
- Python 3.9+
- requests >= 2.31.0
- urllib3 >= 2.0.0
Metadata
Release files for just-storage 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| just_storage-0.1.1.tar.gz | 74.3 kB | Without provenance | Details for just_storage-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| just_storage-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for just_storage-0.1.1-py3-none-any.whl |
Total release size: 85.3 kB
Release files / just_storage-0.1.1.tar.gz
| Download URL | just_storage-0.1.1.tar.gz |
|---|---|
| Size | 74.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d6726b07eb04985cc6efca4395d49f998136d7e0f86d4c5dd51644f76e3bdc38
|
|
BLAKE2b-256 checksum How to use checksums |
7af80147727bcfa1ae5f98ea3c0e8c172f967e3e0a38714ea2557724838fbeef
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.17 {"installer":{"name":"uv","version":"0.9.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / just_storage-0.1.1-py3-none-any.whl
| Download URL | just_storage-0.1.1-py3-none-any.whl |
|---|---|
| Size | 11.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3f83a9aab6e2fe0202c7915cc865411080e6a98f599b840c74c0e5efe7b16d8b
|
|
BLAKE2b-256 checksum How to use checksums |
990868441727bcacaf958c3e0d94c20c188f73b3c5c58a0e8b9575a4b5447638
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.17 {"installer":{"name":"uv","version":"0.9.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for just-storage 0.1.1
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
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.