buckerio 0.2.0

Python SDK for Buckerio - S3-compatible object storage

Buckerio Python SDK

A Python SDK for Buckerio - S3-compatible object storage server.

Installation

pip install buckerio

Or install from source:

git clone https://github.com/KamoliddinS/buckerio.git
cd buckerio/buckerio-py
pip install -e .

Quick Start

from buckerio import Buckerio

# Initialize client
client = Buckerio(
    endpoint="http://localhost:9000",
    access_key="admin",
    secret_key="admin",
)

# Create a bucket
client.create_bucket("my-bucket")

# Upload an object
client.put_object("my-bucket", "hello.txt", b"Hello, World!")

# Download an object
result = client.get_object("my-bucket", "hello.txt")
print(result.content)  # b"Hello, World!"

# List objects
for obj in client.list_all_objects("my-bucket"):
    print(f"{obj.key}: {obj.size} bytes")

# Delete an object
client.delete_object("my-bucket", "hello.txt")

# Delete the bucket
client.delete_bucket("my-bucket")

Configuration

Environment Variables

Variable	Default	Description
BUCKERIO_ACCESS_KEY	admin	Access key for authentication
BUCKERIO_SECRET_KEY	admin	Secret key for authentication
BUCKERIO_ENDPOINT	-	S3 endpoint URL (for tests)

Client Options

client = Buckerio(
    endpoint="http://localhost:9000",  # S3 endpoint URL
    access_key="admin",                 # Access key (or env var)
    secret_key="admin",                 # Secret key (or env var)
    region="us-east-1",                 # AWS region for signing
    timeout=30.0,                       # Request timeout in seconds
    verify_ssl=True,                    # Verify SSL certificates
)

API Reference

Bucket Operations

# List all buckets
buckets = client.list_buckets()
for bucket in buckets:
    print(bucket.name, bucket.creation_date)

# Create a bucket
client.create_bucket("new-bucket")

# Check if bucket exists
if client.bucket_exists("my-bucket"):
    print("Bucket exists!")

# Delete a bucket (must be empty)
client.delete_bucket("my-bucket")

Object Operations

# Upload object from bytes/string
result = client.put_object("bucket", "key", b"content")
print(result.etag)

# Upload with content type and metadata
result = client.put_object(
    "bucket",
    "document.json",
    '{"key": "value"}',
    content_type="application/json",
    metadata={"author": "alice", "version": "1.0"},
)

# Download object
result = client.get_object("bucket", "key")
print(result.content)       # bytes
print(result.etag)          # ETag hash
print(result.content_type)  # MIME type
print(result.metadata)      # Custom metadata

# Get object metadata (without content)
info = client.head_object("bucket", "key")
print(info.size, info.content_type)

# Check if object exists
if client.object_exists("bucket", "key"):
    print("Object exists!")

# Delete object
client.delete_object("bucket", "key")

# Copy object
client.copy_object(
    source_bucket="bucket1",
    source_key="original.txt",
    dest_bucket="bucket2",
    dest_key="copy.txt",
)

File Operations

# Upload from file path
client.upload_file("bucket", "remote-key.txt", "/local/path/file.txt")

# Upload from file object
with open("file.txt", "rb") as f:
    client.upload_fileobj("bucket", "key", f)

# Download to file path
client.download_file("bucket", "key", "/local/path/output.txt")

# Download to file object
with open("output.txt", "wb") as f:
    client.download_fileobj("bucket", "key", f)

Listing Objects

# List objects (single page)
result = client.list_objects("bucket", prefix="data/", max_keys=100)
for obj in result.objects:
    print(obj.key, obj.size)

# Handle pagination
if result.is_truncated:
    next_result = client.list_objects(
        "bucket",
        continuation_token=result.next_continuation_token,
    )

# Iterate all objects (handles pagination automatically)
for obj in client.list_all_objects("bucket", prefix="logs/"):
    print(obj.key)

# List with delimiter (folder-like structure)
result = client.list_objects("bucket", delimiter="/")
for prefix in result.common_prefixes:
    print(f"Folder: {prefix}")

Presigned URLs

# Generate download URL (valid for 1 hour)
result = client.presign_get("bucket", "key", expires_in=3600)
print(result.url)

# Generate upload URL
result = client.presign_put("bucket", "key", expires_in=3600)
print(result.url)

# Use with any HTTP client
import requests
response = requests.get(result.url)

Error Handling

from buckerio import (
    BuckerioError,
    BucketNotFoundError,
    BucketAlreadyExistsError,
    BucketNotEmptyError,
    ObjectNotFoundError,
    AccessDeniedError,
    InvalidCredentialsError,
    ConnectionError,
)

try:
    client.get_object("bucket", "nonexistent-key")
except ObjectNotFoundError as e:
    print(f"Object not found: {e.key}")
except BucketNotFoundError as e:
    print(f"Bucket not found: {e.bucket}")
except AccessDeniedError:
    print("Access denied!")
except ConnectionError as e:
    print(f"Connection failed: {e}")
except BuckerioError as e:
    print(f"Error: {e.code} - {e.message}")

Context Manager

# Client is automatically closed
with Buckerio() as client:
    client.put_object("bucket", "key", b"content")

Development

Install Development Dependencies

pip install -e ".[dev]"

Run Tests

# Unit tests only
pytest tests/test_auth.py tests/test_client.py

# Integration tests (requires running Buckerio server)
pytest tests/ -m integration

Code Quality

# Linting
ruff check src/

# Type checking
mypy src/

Publishing to PyPI

# Install build tools
pip install build twine

# Build the package
python -m build

# Check the distribution
twine check dist/*

# Upload to TestPyPI (for testing)
twine upload --repository testpypi dist/*

# Upload to PyPI (production)
twine upload dist/*

Prerequisites:

• Create account on PyPI
• Create API token at https://pypi.org/manage/account/token/
• Configure ~/.pypirc:

  [pypi]
  username = __token__
  password = pypi-your-api-token-here
  

Version bump:

# Update version in src/buckerio/__version__.py
echo '__version__ = "0.2.0"' > src/buckerio/__version__.py

# Commit and tag
git add -A
git commit -m "chore: bump version to 0.2.0"
git tag v0.2.0
git push && git push --tags

License

MIT - See LICENSE for details.