Metadata-Version: 2.4
Name: synadrive
Version: 1.0.0
Summary: Official Python SDK for the SynaDrive cloud storage API
Author-email: SynaVue Technologies <dev@synavuetechnologies.com>
License: MIT
Project-URL: Homepage, https://drive.synavuetechnologies.com
Project-URL: Documentation, https://docs.synavuetechnologies.com/synadrive/sdk/python
Project-URL: Repository, https://github.com/synavue/synadrive-python
Project-URL: Issues, https://github.com/synavue/synadrive-python/issues
Project-URL: Changelog, https://github.com/synavue/synadrive-python/blob/main/CHANGELOG.md
Keywords: synadrive,cloud-storage,file-upload,sdk,api-client,synavue
Classifier: Development Status :: 5 - Production/Stable
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
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Filesystems
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: httpx
Requires-Dist: httpx>=0.24; extra == "httpx"
Provides-Extra: all
Requires-Dist: httpx>=0.24; extra == "all"
Dynamic: license-file

# SynaDrive Python SDK

Official Python client for the [SynaDrive](https://synavuetechnologies.com/synadrive) cloud storage API.

## Installation

```bash
pip install synadrive
```

For better performance with connection pooling:

```bash
pip install synadrive[httpx]
```

## Quick Start

```python
from synadrive import SynaDriveClient

# Initialize client
client = SynaDriveClient(
    api_key="your-api-key",
    base_url="https://drive.synavue.com"
)

# List files
files = client.list_files()

# Upload a file
result = client.upload_file("/path/to/document.pdf", folder_id="folder-id")

# Download a file
client.download_file("file-id", save_path="./downloaded.pdf")

# Create a folder
folder = client.create_folder("My New Folder")

# Share a file
client.share("file-id", email="colleague@company.com", permission="edit")

# Search
results = client.search("quarterly report")
```

## Authentication

The SDK supports two authentication methods:

```python
# 1. Pass token directly
client = SynaDriveClient(api_key="your-token")

# 2. Environment variable
# export SYNADRIVE_API_KEY=your-token
client = SynaDriveClient()
```

## Context Manager

```python
with SynaDriveClient(api_key="your-key") as client:
    files = client.list_files()
    # Connection is automatically closed
```

## Features

- **Zero required dependencies** — works with Python stdlib (`urllib`)
- **Optional httpx** — install `synadrive[httpx]` for connection pooling & HTTP/2
- **Full API coverage** — files, folders, sharing, search, trash, versions, sync, AI
- **Type hints** — full typing support for IDE autocompletion
- **Cross-platform** — works on macOS, Linux, Windows
- **Python 3.8+** — supports all modern Python versions

## API Reference

### Files

| Method | Description |
|--------|-------------|
| `list_files(folder_id, limit, offset)` | List files in a folder |
| `get_file(file_id)` | Get file metadata |
| `upload_file(file_path, folder_id, tags)` | Upload a file |
| `download_file(file_id, save_path)` | Download a file |
| `delete_file(file_id)` | Move file to trash |
| `move_file(file_id, destination_folder_id)` | Move a file |
| `copy_file(file_id, destination_folder_id)` | Copy a file |

### Folders

| Method | Description |
|--------|-------------|
| `create_folder(name, parent_id)` | Create a new folder |

### Sharing

| Method | Description |
|--------|-------------|
| `share(item_id, email, permission)` | Share a file/folder |
| `get_share_link(item_id)` | Get public share link |

### Search

| Method | Description |
|--------|-------------|
| `search(query, **filters)` | Search files |

### Sync

| Method | Description |
|--------|-------------|
| `sync_delta(cursor, limit)` | Pull remote changes (delta sync) |
| `register_device(device_id, name)` | Register sync device |
| `list_devices()` | List registered devices |
| `revoke_device(device_pk)` | Revoke a device |

### Trash

| Method | Description |
|--------|-------------|
| `list_trash()` | List trashed items |
| `restore_from_trash(file_id)` | Restore from trash |
| `empty_trash()` | Permanently delete all trash |

### AI Features

| Method | Description |
|--------|-------------|
| `auto_tag(file_id)` | AI-generated tags |
| `smart_search(query)` | Semantic search |
| `suggest_folder(filename)` | AI folder suggestion |

## Error Handling

```python
from synadrive import SynaDriveClient, SynaDriveError, AuthenticationError, NotFoundError

try:
    client.get_file("invalid-id")
except AuthenticationError:
    print("Token expired — re-authenticate")
except NotFoundError:
    print("File not found")
except SynaDriveError as e:
    print(f"API error {e.status_code}: {e}")
```

## License

MIT — © 2026 SynaVue Technologies

