versedb 0.1.0__tar.gz

versedb-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.DS_Store
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+dist/

versedb-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VerseDB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

versedb-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+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

versedb-0.1.0/README.md

@@ -0,0 +1,76 @@
+# 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

versedb-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "versedb"
+version = "0.1.0"
+description = "Official Python SDK for the VerseDB comic book database API."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "VerseDB" }]
+requires-python = ">=3.11"
+dependencies = [
+    "httpx>=0.23.1,<0.29.0",
+    "attrs>=22.2.0",
+]
+keywords = ["versedb", "comics", "comic books", "api", "sdk"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://versedb.com"
+Documentation = "https://versedb.com/api/docs"
+Repository = "https://github.com/versedbcom/versedb-python"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+include = ["/versedb", "/README.md", "/LICENSE"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["versedb"]
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+select = ["F", "I", "UP"]

versedb-0.1.0/versedb/__init__.py

@@ -0,0 +1,8 @@
+"""A client library for accessing VerseDB API Documentation"""
+
+from .client import AuthenticatedClient, Client
+
+__all__ = (
+    "AuthenticatedClient",
+    "Client",
+)

versedb-0.1.0/versedb/api/__init__.py

@@ -0,0 +1 @@
+"""Contains methods for accessing the API"""

versedb-0.1.0/versedb/api/barcode_lookup/__init__.py

@@ -0,0 +1 @@
+"""Contains endpoint functions for accessing the API"""

versedb-0.1.0/versedb/api/barcode_lookup/lookup_by_isbn.py

@@ -0,0 +1,234 @@
+from http import HTTPStatus
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from ... import errors
+from ...client import AuthenticatedClient, Client
+from ...models.lookup_by_isbn_response_200 import LookupByIsbnResponse200
+from ...models.lookup_by_isbn_response_403 import LookupByIsbnResponse403
+from ...models.lookup_by_isbn_response_404 import LookupByIsbnResponse404
+from ...models.too_many_requests_error import TooManyRequestsError
+from ...models.unauthorized_error import UnauthorizedError
+from ...types import Response
+
+
+def _get_kwargs(
+    isbn: str,
+) -> dict[str, Any]:
+
+    _kwargs: dict[str, Any] = {
+        "method": "get",
+        "url": "/api/v1/lookup/isbn/{isbn}".format(
+            isbn=quote(str(isbn), safe=""),
+        ),
+    }
+
+    return _kwargs
+
+
+def _parse_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> (
+    LookupByIsbnResponse200
+    | LookupByIsbnResponse403
+    | LookupByIsbnResponse404
+    | TooManyRequestsError
+    | UnauthorizedError
+    | None
+):
+    if response.status_code == 200:
+        response_200 = LookupByIsbnResponse200.from_dict(response.json())
+
+        return response_200
+
+    if response.status_code == 401:
+        response_401 = UnauthorizedError.from_dict(response.json())
+
+        return response_401
+
+    if response.status_code == 403:
+        response_403 = LookupByIsbnResponse403.from_dict(response.json())
+
+        return response_403
+
+    if response.status_code == 404:
+        response_404 = LookupByIsbnResponse404.from_dict(response.json())
+
+        return response_404
+
+    if response.status_code == 429:
+        response_429 = TooManyRequestsError.from_dict(response.json())
+
+        return response_429
+
+    if client.raise_on_unexpected_status:
+        raise errors.UnexpectedStatus(response.status_code, response.content)
+    else:
+        return None
+
+
+def _build_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> Response[
+    LookupByIsbnResponse200
+    | LookupByIsbnResponse403
+    | LookupByIsbnResponse404
+    | TooManyRequestsError
+    | UnauthorizedError
+]:
+    return Response(
+        status_code=HTTPStatus(response.status_code),
+        content=response.content,
+        headers=response.headers,
+        parsed=_parse_response(client=client, response=response),
+    )
+
+
+def sync_detailed(
+    isbn: str,
+    *,
+    client: AuthenticatedClient | Client,
+) -> Response[
+    LookupByIsbnResponse200
+    | LookupByIsbnResponse403
+    | LookupByIsbnResponse404
+    | TooManyRequestsError
+    | UnauthorizedError
+]:
+    """Lookup by ISBN.
+
+     Find an issue by its ISBN (10 or 13 digits, with or without dashes).
+    Commonly used for trade paperbacks and hardcovers.
+    Returns full issue details including series information.
+
+    Args:
+        isbn (str):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[LookupByIsbnResponse200 | LookupByIsbnResponse403 | LookupByIsbnResponse404 | TooManyRequestsError | UnauthorizedError]
+    """
+
+    kwargs = _get_kwargs(
+        isbn=isbn,
+    )
+
+    response = client.get_httpx_client().request(
+        **kwargs,
+    )
+
+    return _build_response(client=client, response=response)
+
+
+def sync(
+    isbn: str,
+    *,
+    client: AuthenticatedClient | Client,
+) -> (
+    LookupByIsbnResponse200
+    | LookupByIsbnResponse403
+    | LookupByIsbnResponse404
+    | TooManyRequestsError
+    | UnauthorizedError
+    | None
+):
+    """Lookup by ISBN.
+
+     Find an issue by its ISBN (10 or 13 digits, with or without dashes).
+    Commonly used for trade paperbacks and hardcovers.
+    Returns full issue details including series information.
+
+    Args:
+        isbn (str):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        LookupByIsbnResponse200 | LookupByIsbnResponse403 | LookupByIsbnResponse404 | TooManyRequestsError | UnauthorizedError
+    """
+
+    return sync_detailed(
+        isbn=isbn,
+        client=client,
+    ).parsed
+
+
+async def asyncio_detailed(
+    isbn: str,
+    *,
+    client: AuthenticatedClient | Client,
+) -> Response[
+    LookupByIsbnResponse200
+    | LookupByIsbnResponse403
+    | LookupByIsbnResponse404
+    | TooManyRequestsError
+    | UnauthorizedError
+]:
+    """Lookup by ISBN.
+
+     Find an issue by its ISBN (10 or 13 digits, with or without dashes).
+    Commonly used for trade paperbacks and hardcovers.
+    Returns full issue details including series information.
+
+    Args:
+        isbn (str):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[LookupByIsbnResponse200 | LookupByIsbnResponse403 | LookupByIsbnResponse404 | TooManyRequestsError | UnauthorizedError]
+    """
+
+    kwargs = _get_kwargs(
+        isbn=isbn,
+    )
+
+    response = await client.get_async_httpx_client().request(**kwargs)
+
+    return _build_response(client=client, response=response)
+
+
+async def asyncio(
+    isbn: str,
+    *,
+    client: AuthenticatedClient | Client,
+) -> (
+    LookupByIsbnResponse200
+    | LookupByIsbnResponse403
+    | LookupByIsbnResponse404
+    | TooManyRequestsError
+    | UnauthorizedError
+    | None
+):
+    """Lookup by ISBN.
+
+     Find an issue by its ISBN (10 or 13 digits, with or without dashes).
+    Commonly used for trade paperbacks and hardcovers.
+    Returns full issue details including series information.
+
+    Args:
+        isbn (str):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        LookupByIsbnResponse200 | LookupByIsbnResponse403 | LookupByIsbnResponse404 | TooManyRequestsError | UnauthorizedError
+    """
+
+    return (
+        await asyncio_detailed(
+            isbn=isbn,
+            client=client,
+        )
+    ).parsed