README.md

versedb

The official Python SDK for the VerseDB comic book database API.

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:

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.

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:

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.

Development

The versedb/ package is generated by openapi-python-client from the live User API spec. Don't edit it by hand; regenerate it instead:

./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