CloudUploader Python SDK - Sample Application

A practical example application demonstrating how to use the clouduploader-py package for uploading files to various cloud storage backends (S3, R2, Azure Blob, GCS, and more).

📋 Prerequisites

• Python 3.9 or higher
• pip/pip3
• Virtual environment (recommended)

🚀 Quick Start

1. Clone or Navigate to This Directory

cd /home/rafeeque/Rafeeque/sample-python-app

2. Create and Activate Virtual Environment

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install Dependencies

pip install clouduploader-py

4. Set Up Environment Variables

Create a .env file or export these variables:

export CLOUD_UPLOADER_API_KEY="your_api_key_here"
export CLOUD_UPLOADER_URL="https://api.clouduploader.io"

📁 Project Structure

sample-python-app/
├── README.md                 # This file
├── upload_example.py         # Comprehensive example script
├── venv/                     # Virtual environment
└── .gitignore               # Git ignore rules

📚 Usage Examples

Basic Setup

from cloud_uploader import CloudUploader

# Initialize the uploader
uploader = CloudUploader(
    api_key="your_api_key",
    base_url="https://api.clouduploader.io"
)

Example 1: Simple File Upload

Upload a single file to the default storage backend:

result = uploader.upload_file("path/to/file.mp4")
print(f"✅ Upload complete!")
print(f"   Storage path: {result.storage_path}")
print(f"   Upload ID: {result.upload_id}")

Example 2: Upload with Progress Tracking

Track upload progress in real-time:

def progress(uploaded: int, total: int) -> None:
    pct = (uploaded / total * 100) if total else 0
    print(f"\rProgress: {pct:.1f}%", end="", flush=True)

result = uploader.upload_file(
    "large_video.mp4",
    progress_callback=progress
)
print(f"\n✅ Done → {result.storage_path}")

Example 3: Upload to Specific Backend

Upload to a specific storage backend (S3, Azure, GCS, etc.):

# Upload to S3
result = uploader.upload_file("data.csv", storage="s3")

# Supported backends: r2, s3, minio, azure, gcs

Example 4: Upload with Error Handling

Handle errors gracefully:

from cloud_uploader import (
    CloudUploaderError,
    AuthenticationError,
    UploadFailedError
)

try:
    result = uploader.upload_file("file.pdf")
    print(f"✅ {result.storage_path}")
except AuthenticationError:
    print("❌ Invalid API key")
except UploadFailedError as e:
    print(f"❌ Upload failed: {e.message}")
except CloudUploaderError as e:
    print(f"❌ Error: {e.message} (HTTP {e.status_code})")

Example 5: Upload Folder

Upload all files in a directory recursively:

result = uploader.upload_folder("./assets")
print(f"✅ Uploaded {result.succeeded}/{result.total_files} files")

if result.failures:
    print(f"⚠️  Failed files: {len(result.failures)}")
    for failure in result.failures:
        print(f"   - {failure.file_path}: {failure.error}")

Example 6: Check Upload Status

Query the status of a previous upload:

status = uploader.get_upload_status("upload_id_123")
print(f"Status: {status['status']}")
print(f"Success: {status['success']}")

Example 7: Download File

Download a file by its ID:

path = uploader.download_file(
    file_id="file_123",
    output_path="./downloads/file.jpg"
)
print(f"✅ Downloaded to: {path}")

⚙️ Configuration Options

uploader = CloudUploader(
    api_key="your_api_key",              # Required: Your API key
    base_url="https://api.clouduploader.io",  # Default: http://localhost:8080
    timeout=30,                           # HTTP timeout in seconds
    max_retries=3,                        # Retry attempts for failures
    max_parallel_uploads=5,               # Thread pool size for multipart
    debug=False,                          # Enable debug logging
)

🧪 Running the Example Script

# Run the example script
python upload_example.py

# With a specific file
python upload_example.py /path/to/file.mp4

# With progress tracking
python upload_example.py /path/to/file.mp4 --progress

🔑 Getting an API Key

1. Visit https://clouduploader.io
2. Sign up or log in
3. Navigate to API settings
4. Generate a new API key
5. Copy the key and use it in your code

📦 Available Backends

• r2 - Cloudflare R2 (default)
• s3 - Amazon S3
• minio - MinIO
• azure - Azure Blob Storage
• gcs - Google Cloud Storage

🐛 Troubleshooting

"externally-managed-environment" Error

Use a virtual environment:

python3 -m venv venv
source venv/bin/activate
pip install clouduploader-py

Authentication Errors

Ensure your API key is correct and valid:

export CLOUD_UPLOADER_API_KEY="your_correct_key"

Connection Errors

Check your base URL and ensure the CloudUploader service is running:

export CLOUD_UPLOADER_URL="https://api.clouduploader.io"

📖 Documentation

• PyPI Package: https://pypi.org/project/clouduploader-py/
• GitHub Repository: https://github.com/CloudUploader/clouduploader-py
• Official Docs: https://docs.clouduploader.io/sdk/python

🤝 Support

For issues, questions, or feedback:

• 📧 Email: support@clouduploader.io
• 🐛 GitHub Issues: https://github.com/CloudUploader/clouduploader-py/issues
• 💬 Discussions: https://github.com/CloudUploader/clouduploader-py/discussions

📝 License

MIT License - See the main package repository for details

🎯 Next Steps

1. ✅ Install the package: pip install clouduploader-py
2. ✅ Set your API key in environment variables
3. ✅ Run the example script: python upload_example.py
4. ✅ Explore the different examples in the script
5. ✅ Build your own upload logic using the SDK

---

Version: Based on clouduploader-py 0.1.5+ Last Updated: April 2026