Metadata-Version: 2.4
Name: gancio-py
Version: 0.1.0b1
Summary: Python client for the Gancio event platform API
Project-URL: Homepage, https://github.com/tboye/gancio-py
Project-URL: Repository, https://github.com/tboye/gancio-py
Project-URL: Issues, https://github.com/tboye/gancio-py/issues
Author-email: tboye <me@tboye.dev>
License-Expression: MIT
License-File: LICENSE
Keywords: api-client,events,gancio
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: requests
Provides-Extra: dev
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: test
Requires-Dist: pillow; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Requires-Dist: pytest-sugar>=1.1.1; extra == 'test'
Description-Content-Type: text/markdown

# gancio-py

[![Tests](https://github.com/tboye/gancio-py/actions/workflows/test.yml/badge.svg)](https://github.com/tboye/gancio-py/actions/workflows/test.yml)
[![PyPI](https://img.shields.io/pypi/v/gancio-py)](https://pypi.org/project/gancio-py/)
[![Python](https://img.shields.io/pypi/pyversions/gancio-py)](https://pypi.org/project/gancio-py/)

Python client for the [Gancio](https://gancio.org) event platform API.

## Installation

```bash
pip install gancio-py
```

## Usage

```python
from gancio_py import Gancio

# Connect and log in
gancio = Gancio("https://your-gancio-instance.org")
gancio.login("user@example.com", "password")

# Or use a pre-existing token
gancio = Gancio("https://your-gancio-instance.org", access_token="your-token")

# Create an event
event = gancio.create_event(title="My Event",
                            start_datetime=1700000000,
                            place_name="The Venue",
                            place_address="123 Main St",
                            tags=["music", "live"])

# List events
events = gancio.get_events(tags=["music"])

# Get a specific event
event = gancio.get_event("my-event")

# Update an event
gancio.update_event(event_id=1, title="Updated Title")

# Delete an event
gancio.delete_event(event_id=1)

# Search places
places = gancio.search_place("Venue")
```

### Error handling

```python
from gancio_py import Gancio, GancioError

gancio = Gancio("https://your-gancio-instance.org")

try:
    event = gancio.get_event("nonexistent-slug")
except GancioError as e:
    print(e.status_code)     # 404
    print(e.response_body)   # error details from the server
```

## Development

Run integration tests locally with Docker:

```bash
uv sync --extra test

# Fresh container (runs first-time setup automatically):
docker compose down -v && docker compose up -d
uv run pytest -m integration -v --cov

# Or against an existing instance with known credentials:
GANCIO_URL=http://localhost:13120 \
GANCIO_ADMIN_EMAIL=admin \
GANCIO_ADMIN_PASSWORD=yourpassword \
uv run pytest -m integration -v --cov
```

### Linting

```bash
uvx ruff check
uvx ruff check --fix  # auto-fix
```

## License

[MIT](LICENSE)