Metadata-Version: 2.4
Name: azbrand-s3
Version: 1.0.0
Summary: Official Python SDK & CLI for AZBrand zero-egress S3-compatible cloud object storage.
Author-email: AZBrand Canada <admin@azbrand.ca>
License: MIT
Project-URL: Homepage, https://azbrand.ca/storage
Project-URL: Documentation, https://azbrand.ca
Project-URL: Bug Tracker, https://azbrand.ca/dashboard/tickets
Keywords: s3,cloud-storage,zero-egress,azbrand,backup,object-storage,r2,storage-sdk
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Dynamic: license-file

# AZBrand S3 Cloud Storage SDK for Python

Official Python client and CLI tool for [AZBrand S3 Cloud Object Storage](https://azbrand.ca/storage).

Store, stream, and distribute media, database backups, and large files globally with zero egress bandwidth fees and 100% S3 compatibility.

---

## Features

- Zero Egress Fees: Download unlimited bandwidth without surprise hyperscaler invoices.
- Direct S3 Presigned Uploads: Stream large multi-gigabyte files directly to storage edge nodes.
- Bucket Management: Programmatically create Private Vaults (AES-256), Public CDN Buckets, and Multi-Tenant Shared Workspaces.
- Command-Line Interface: Includes the built-in `azbrand-s3` CLI command for bash scripts and automated cron backups.
- Full Metadata & Head Inspection: Fast HEAD requests for ETags, Content-Type, and byte counts.

---

## Installation

```bash
pip install azbrand-s3
```

---

## Quick Start (Python)

Generate your API Access Keys from your [AZBrand Storage Dashboard](https://azbrand.ca/dashboard/storage).

```python
from azbrand_s3 import AZBrandStorage

storage = AZBrandStorage(
    access_key_id="az_ak_YOUR_ACCESS_KEY",
    secret_access_key="az_sk_YOUR_SECRET_KEY",
)

# 1. Upload a local file to a bucket
file = storage.upload_file(
    bucket="my-backups",
    file_source="./database.sql.gz",
    file_name="database.sql.gz",
    content_type="application/gzip",
)
print("Uploaded File ID:", file["id"])

# 2. List files in a bucket
files = storage.list_files(bucket="my-backups")
for f in files:
    print(f" • {f['file_name']} ({f['size_bytes']} bytes)")

# 3. Get a signed temporary download URL (1 hour)
download_url = storage.get_download_url(file["id"])
print("Download Link:", download_url)

# 4. Check account quota and request metrics
metrics = storage.get_usage()
print("Used Bytes:", metrics["used_bytes"])
```

---

## Command-Line Interface (CLI)

The package installs the `azbrand-s3` command globally:

```bash
# Set your credentials
export AZ_ACCESS_KEY_ID="az_ak_..."
export AZ_SECRET_ACCESS_KEY="az_sk_..."

# List buckets
azbrand-s3 buckets

# Upload a backup file
azbrand-s3 upload my-backups ./backup.tar.gz

# List files in bucket
azbrand-s3 list my-backups

# Get a signed download link
azbrand-s3 download <FILE_UUID>

# Check storage usage
azbrand-s3 usage
```

---

## API Reference

### Bucket Operations
- `storage.list_buckets()` - List all buckets.
- `storage.create_bucket(name, bucket_type="private")` - Create an S3 storage bucket.
- `storage.delete_bucket(bucket_id)` - Permanently delete a bucket and its contents.

### File Operations
- `storage.upload_file(bucket, file_source, file_name, content_type)` - Direct S3 signed PUT upload.
- `storage.list_files(bucket, query)` - Query files with prefix filtering.
- `storage.get_download_url(file_id)` - Generate temporary signed S3 download URL.
- `storage.get_metadata(file_id)` - Inspect size, ETag, and Content-Type (HEAD).
- `storage.copy_file(source_file_id, target_bucket_id, new_file_name)` - Fast server-side S3 copy.
- `storage.delete_file(file_id)` - Permanently delete a storage object.
- `storage.share_file(file_id, is_public, expires_in_days)` - Create public share link.

### Usage
- `storage.get_usage()` - Check storage quota and Class A/B request metrics.

---

## Links & Resources

- [Official Website](https://azbrand.ca)
- [S3 Cloud Storage Plans](https://azbrand.ca/storage)
- [Webmastering & Cloud Engineering](https://azbrand.ca/agency/webmastering)
- [Support Desk](https://azbrand.ca/dashboard/tickets)

---

## License

MIT (c) [AZBrand Canada](https://azbrand.ca)
