Metadata-Version: 2.4
Name: filezen-python
Version: 0.1.0
Summary: Python SDK for FileZen file management service
Project-URL: Homepage, https://filezen.dev
Project-URL: Documentation, https://docs.filezen.dev
Project-URL: Repository, https://github.com/filezen/filezen-python
Project-URL: Issues, https://github.com/filezen/filezen-python/issues
Author-email: FileZen Team <support@filezen.dev>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Filesystems
Requires-Python: <3.14,>=3.8
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic<3.0.0,>=2.0.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: isort>=5.12.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# FileZen Python SDK

A Python SDK for FileZen, providing easy file upload and management capabilities.

## Features

- ✅ **File Upload**: Upload single files efficiently
- ✅ **Bulk Upload**: Upload multiple files concurrently
- ✅ **URL Upload**: Upload files directly from URLs
- ✅ **Signed URLs**: Generate secure signed URLs for direct uploads
- ✅ **Multipart Upload**: Automatic multipart upload for large files (>10MB)
- ✅ **File Deletion**: Delete files by URL
- ✅ **Error Handling**: Comprehensive error handling and retry logic
- ✅ **Backend Optimized**: Designed for server-side usage without UI dependencies

## Installation

```bash
pip install filezen-python
```

## Quick Start

```python
import asyncio
from filezen import ZenStorage

async def main():
    # Initialize storage
    storage = ZenStorage({
        "api_key": "your_api_key_here",  # Optional: can use FILEZEN_API_KEY env var
    })

    # Upload a single file
    with open("my_file.jpg", "rb") as f:
        upload = await storage.upload(f.read(), {
            "name": "my_file.jpg",
            "mime_type": "image/jpeg",
        })
        print(f"File uploaded: {upload.file.url}")

    # Upload multiple files
    uploads = await storage.bulk_upload(
        {"source": file1_content, "options": {"name": "file1.jpg"}},
        {"source": file2_content, "options": {"name": "file2.png"}},
    )

    # Generate a signed URL
    signed_url = storage.generate_signed_url({
        "file_key": "my_file.jpg",
        "expires_in": 3600,  # 1 hour
    })

asyncio.run(main())
```

## Multipart Upload

The SDK automatically uses multipart upload for files larger than 10MB. This provides:

- **Resumable uploads**: Upload can be resumed if interrupted
- **Better performance**: Parallel chunk uploads
- **Progress tracking**: Detailed progress for each chunk
- **Error recovery**: Automatic retry for failed chunks

```python
# Large files are automatically handled with multipart upload
with open("large_video.mp4", "rb") as f:
    upload = await storage.upload(f.read(), {
        "name": "large_video.mp4",
        "mime_type": "video/mp4",
    })
    # Automatically uses multipart upload for files > 10MB
```

## Configuration

```python
storage = ZenStorage({
    "api_key": "your_api_key",  # FileZen API key
    "api_url": "https://api.filezen.dev",  # API base URL
    "keep_uploads": True,  # Whether to track uploads in memory
})
```

## Environment Variables

You can also set configuration via environment variables:

```bash
export FILEZEN_API_KEY="your_api_key_here"
export FILEZEN_API_URL="https://api.filezen.dev"  # Optional
```

## API Reference

### ZenStorage

Main storage class for FileZen operations.

#### Methods

- `upload(source: bytes, options: dict) -> ZenUpload`: Upload a single file
- `bulk_upload(*uploads: dict) -> List[ZenUpload]`: Upload multiple files
- `generate_signed_url(options: dict) -> str`: Generate a signed URL
- `delete_by_url(url: str) -> bool`: Delete a file by URL

### ZenUpload

Represents a file upload operation.

#### Properties

- `file: ZenFile`: Uploaded file information
- `error: ZenError`: Upload error if any
- `is_completed: bool`: Whether upload is completed
- `is_cancelled: bool`: Whether upload is cancelled

#### Methods

- `upload() -> ZenUpload`: Perform the upload operation
- `cancel()`: Cancel the upload

## Examples

See the [FastAPI example app](../../apps/python-fastapi-server) for a complete implementation with web interface.

## Documentation

For detailed documentation, visit [docs.filezen.dev](https://docs.filezen.dev)

## License

MIT License
