zionai-utils 1.1.0

A simple utility library for Google Cloud Storage operations

ZionAI Utils - GCS Upload Made Simple

A dead-simple utility library for uploading files to Google Cloud Storage.

Installation

pip install zionai_utils==1.1.0

Quick Start

1. Upload a File (Simplest Way)

from zionai_utils import GCSClient

# Initialize client
client = GCSClient(
    credentials_path="/path/to/service-account.json",
    project_id="your-project-id"
)

# Upload any file with one line
success, gcs_uri = client.upload_file(
    bucket_name="your-bucket",
    file_path="document.pdf"
)

if success:
    print(f"✅ Uploaded: {gcs_uri}")
else:
    print("❌ Upload failed")

2. Upload Text Content

from zionai_utils import GCSClient

client = GCSClient(
    credentials_path="/path/to/service-account.json",
    project_id="your-project-id"
)

# Upload text directly
success, gcs_uri = client.upload_text(
    bucket_name="your-bucket",
    file_name="hello.txt",
    text_content="Hello, World!"
)

3. Upload from Memory (Advanced)

from zionai_utils import GCSClient
import json

client = GCSClient(
    credentials_path="/path/to/service-account.json",
    project_id="your-project-id"
)

# Create JSON data
data = {"name": "John", "age": 30}
json_bytes = json.dumps(data).encode('utf-8')

success, gcs_uri = client.upload_bytes(
    bucket_name="your-bucket",
    file_name="data.json",
    file_data=json_bytes,
    content_type="application/json"
)

Environment Variables Setup

Set your credentials as an environment variable to avoid passing the path:

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"

Then initialize without credentials path:

from zionai_utils import GCSClient

# No need to specify credentials_path if env var is set
client = GCSClient(project_id="your-project-id")

success, gcs_uri = client.upload_file("your-bucket", "document.pdf")

Methods Available

Method	Description	Best For
upload_file()	Upload from file path	Most common use case
upload_text()	Upload text content	Quick text uploads
upload_bytes()	Upload raw bytes	Advanced scenarios

Features

• ✅ Auto-detects file types - No need to specify content type
• ✅ Simple error handling - Returns success boolean + URI
• ✅ Flexible initialization - Use credentials file or environment variables
• ✅ Metadata support - Add custom metadata to uploads
• ✅ Backward compatible - Existing code continues to work

Common Use Cases

Upload with Custom Destination Name

success, gcs_uri = client.upload_file(
    bucket_name="your-bucket",
    file_path="local_file.pdf",
    destination_name="renamed_file.pdf"
)

Upload with Metadata

success, gcs_uri = client.upload_file(
    bucket_name="your-bucket",
    file_path="document.pdf",
    meta_data={
        "author": "John Doe",
        "department": "Engineering",
        "version": "1.0"
    }
)

Batch Upload

files_to_upload = ["file1.pdf", "file2.jpg", "file3.txt"]

for file_path in files_to_upload:
    success, gcs_uri = client.upload_file("your-bucket", file_path)
    if success:
        print(f"✅ {file_path} -> {gcs_uri}")
    else:
        print(f"❌ Failed to upload {file_path}")

Error Handling

All methods return a tuple (success: bool, gcs_uri: str | None):

success, gcs_uri = client.upload_file("bucket", "file.pdf")

if success:
    print(f"File uploaded successfully: {gcs_uri}")
    # Do something with the GCS URI
else:
    print("Upload failed - check your credentials and bucket name")

Requirements

• Python 3.7+
• Google Cloud Storage credentials
• google-cloud-storage>=2.0.0 (installed automatically)