Metadata-Version: 2.5
Name: versedb
Version: 0.1.0
Summary: Official Python SDK for the VerseDB comic book database API.
Project-URL: Homepage, https://versedb.com
Project-URL: Documentation, https://versedb.com/api/docs
Project-URL: Repository, https://github.com/versedbcom/versedb-python
Author: VerseDB
License-Expression: MIT
License-File: LICENSE
Keywords: api,comic books,comics,sdk,versedb
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: attrs>=22.2.0
Requires-Dist: httpx<0.29.0,>=0.23.1
Description-Content-Type: text/markdown

# versedb

The official Python SDK for the [VerseDB](https://versedb.com) comic book database API.

```sh
pip install versedb
```

Requires Python 3.11 or later.

## Authentication

Create a personal access token from your VerseDB dashboard (**Generate API token**),
then pass it to `AuthenticatedClient`:

```python
from versedb import AuthenticatedClient

client = AuthenticatedClient(base_url="https://versedb.com", token="YOUR_TOKEN")
```

## Usage

Every endpoint is a module under `versedb.api`, grouped by tag. Each module has four
functions: `sync` and `asyncio` return the parsed body, and `sync_detailed` and
`asyncio_detailed` return a `Response` that also carries the status code and headers.

```python
from versedb.api.series import list_series, get_series_details

with client as client:
    page = list_series.sync(client=client, q="Saga")
    series = get_series_details.sync(client=client, series_id=123)
```

Async:

```python
from versedb.api.issues import get_issue_details

async with client as client:
    issue = await get_issue_details.asyncio(client=client, issue_id=5432)
```

Error responses the API documents (401, 404, 422, 429 and so on) come back as typed
models such as `UnauthorizedError`. Pass `raise_on_unexpected_status=True` to the
client to raise `versedb.errors.UnexpectedStatus` on anything undocumented.

The full endpoint reference lives at [versedb.com/api/docs](https://versedb.com/api/docs).

## Development

The `versedb/` package is generated by
[openapi-python-client](https://github.com/openapi-generators/openapi-python-client)
from the live User API spec. Don't edit it by hand; regenerate it instead:

```sh
./scripts/generate.sh
uv run pytest
```

`scripts/prepare_spec.py` patches a few spec shapes the generator can't parse, and
`templates/` overrides one generator template. Both explain why in their own files.
A nightly GitHub Action runs the same script and opens a PR when the spec changes.

### Releasing

1. Bump `version` in `pyproject.toml` and merge it to `main`.
2. Publish a GitHub release tagged `v<version>` (for example `v0.1.0`).

The `Publish to PyPI` workflow checks the tag against `pyproject.toml`, runs the
tests, builds, and uploads to PyPI through trusted publishing.

## License

MIT
