Metadata-Version: 2.4
Name: openavaban
Version: 1.0.0
Summary: Python SDK for openavaban - image gallery and profile management via REST API
Author-email: Pratik <pratik@example.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/the-ripper77/openavaban
Project-URL: Repository, https://github.com/the-ripper77/openavaban
Project-URL: Issues, https://github.com/the-ripper77/openavaban/issues
Keywords: avatar,banner,profile,image,gallery,upload
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
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: Topic :: Multimedia :: Graphics
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# openavaban

Python SDK for [openavaban-api](https://github.com/the-ripper77/openavaban-api) — image gallery and profile management.

No API keys or database credentials needed. Just install and use.

## Installation

```bash
pip install openavaban
```

## Quick Start

```python
from openavaban import OpenavaBan

client = OpenavaBan()

# Upload an image
result = client.upload("photo.jpg", name="Profile Photo", class_type="avatar")
print(result["url"])

# Search images
results = client.search(class_type="avatar", category="profile")
for img in results["results"]:
    print(img["name"], img["url"])

# Get random images
random_imgs = client.random(category="profile", count=5)

# Get image by ID
image = client.get("image_id_here")

# Update image
client.update("image_id_here", name="New Name", tags=["new", "tag"])

# Delete image
client.delete("image_id_here")

# Bulk upload from CSV
result = client.bulk_upload("images.csv")
print(f"Uploaded {result['success']}/{result['total']}")
```

## API Reference

### `OpenavaBan(base_url=None)`

Create a client. Defaults to the hosted API at `https://openavaban-api.giripratik.com.np`.

```python
client = OpenavaBan()  # uses hosted API
client = OpenavaBan(base_url="http://localhost:3000")  # local dev
```

### Methods

| Method | Description |
|---|---|
| `upload(file, name, class_type, category="", tags=None, metadata=None)` | Upload an image file |
| `bulk_upload(csv_path)` | Bulk upload from CSV |
| `search(q=None, class_type=None, category=None, tags=None, mime_type=None, limit=30, offset=0)` | Search images |
| `random(category=None, count=1)` | Get random images |
| `get(image_id)` | Get image by ID |
| `update(image_id, **kwargs)` | Update image fields |
| `delete(image_id)` | Delete an image |

### Parameters

- **file**: File path string or file-like object
- **class_type**: `"avatar"` or `"banner"`
- **category**: Free-text category string
- **tags**: List of strings or comma-separated string
- **mime_type**: Filter by `"image"` or `"gif"`
- **limit/max results**: Capped at 100 for search, 20 for random

### CSV Format (for bulk upload)

```csv
file_url,name,class_type,category,tags
https://example.com/photo1.jpg,Profile Photo,avatar,profile,"main,profile"
https://example.com/banner1.png,Social Banner,banner,social,"banner,v2"
```

## Exceptions

| Exception | Description |
|---|---|
| `APIError` | API request failed |
| `InvalidClassError` | Invalid class_type (must be "avatar" or "banner") |
| `NotFoundError` | Image not found |
| `ValidationError` | Invalid file type, file too large, or missing fields |

## License

MIT
