Client¶

client ¶

Client ¶

Client(
    token: str | None = None,
    *,
    base_url: str = PROD_BASE_URL,
    timeout: float = DEFAULT_TIMEOUT,
    user_agent: str = DEFAULT_USER_AGENT,
    retry: RetryConfig | None = None,
    http_client: Client | None = None,
    cache_ttl: float | None = None,
    cache_maxsize: int = 128,
)

Synchronous VNDB Kana API client.

The client owns an HTTP transport and exposes one typed query resource per entity (vn, release, producer, character, staff, tag, trait, quote, ulist), plus the simple GET endpoints and user-list write helpers. Use it as a context manager so the underlying connection pool is closed on exit.

Read-only endpoints work without a token; a VNDB API token <https://vndb.org/u/tokens>_ is only required for user-list writes and authinfo.

Example

from vndb_client import Client with Client() as client: ... page = client.vn.query(filters=["id", "=", "v17"]) ... page.results[0].title 'Ever17 -the out of infinity-'

Attributes:

Name	Type	Description
`vn`	`QueryResource[VN]`	Query resource for visual novels (`/vn`).
`release`	`QueryResource[Release]`	Query resource for releases (`/release`).
`producer`	`QueryResource[Producer]`	Query resource for producers (`/producer`).
`character`	`QueryResource[Character]`	Query resource for characters (`/character`).
`staff`	`QueryResource[Staff]`	Query resource for staff (`/staff`).
`tag`	`QueryResource[Tag]`	Query resource for tags (`/tag`).
`trait`	`QueryResource[Trait]`	Query resource for traits (`/trait`).
`quote`	`QueryResource[Quote]`	Query resource for quotes (`/quote`).
`ulist`	`QueryResource[UlistEntry]`	Query resource for user-list entries (`/ulist`).

Create a synchronous client.

Parameters:

Name	Type	Description	Default
`token`	`str \| None`	VNDB API token for authenticated requests. Omit for read-only access.	`None`
`base_url`	`str`	API base URL. Defaults to production (`https://api.vndb.org/kana`); use `SANDBOX_BASE_URL` to target the sandbox.	`PROD_BASE_URL`
`timeout`	`float`	Per-request timeout in seconds.	`DEFAULT_TIMEOUT`
`user_agent`	`str`	`User-Agent` header sent with every request.	`DEFAULT_USER_AGENT`
`retry`	`RetryConfig \| None`	Retry policy for transient failures. `None` uses the default :class:`~vndb_client.config.RetryConfig`.	`None`
`http_client`	`Client \| None`	An existing `httpx.Client` to reuse. When provided, `base_url`/`timeout` on this client are not applied to it and its lifecycle is the caller's responsibility.	`None`
`cache_ttl`	`float \| None`	Time-to-live in seconds for the in-memory read cache. `None` (or a non-positive value) disables caching; reads are not cached by default.	`None`
`cache_maxsize`	`int`	Maximum number of cached read responses before least-recently-used eviction. Only used when `cache_ttl` is set.	`128`

stats ¶

stats() -> Stats

Return database-wide totals from the /stats endpoint.

Returns:

Type	Description
`Stats`	The site-wide entity counts.

authinfo ¶

authinfo() -> AuthInfo

Return identity and permissions for the current token (/authinfo).

Returns:

Type	Description
`AuthInfo`	The authenticated token's id, username, and granted permissions.

get_user ¶

get_user(
    q: str | list[str], *, fields: str | None = None
) -> dict[str, User | None]

Look up users by id or name via the /user endpoint.

Parameters:

Name	Type	Description	Default
`q`	`str \| list[str]`	A single user id/name, or a list of them.	required
`fields`	`str \| None`	Optional comma-separated extra fields to request.	`None`

Returns:

Type	Description
`dict[str, User \| None]`	A mapping from each query term to its `User`, or `None` if unknown.

ulist_labels ¶

ulist_labels(
    user: str | None = None, *, fields: str | None = None
) -> list[UlistLabel]

List the ulist labels for a user (/ulist_labels).

Parameters:

Name	Type	Description	Default
`user`	`str \| None`	The user id whose labels to fetch; defaults to the token's user.	`None`
`fields`	`str \| None`	Optional comma-separated extra fields to request.	`None`

Returns:

Type	Description
`list[UlistLabel]`	The user's labels.

schema ¶

schema() -> dict[str, Any]

Return the raw VNDB API schema document (/schema).

Returns:

Type	Description
`dict[str, Any]`	The schema as a plain JSON-decoded dict.

set_ulist ¶

set_ulist(
    vn_id: str,
    *,
    vote: int | None | UnsetType = UNSET,
    notes: str | None | UnsetType = UNSET,
    started: str | None | UnsetType = UNSET,
    finished: str | None | UnsetType = UNSET,
    labels: list[int] | None = None,
    labels_set: list[int] | None = None,
    labels_unset: list[int] | None = None,
) -> None

Create or update the authenticated user's ulist entry for a VN.

Each scalar argument defaults to UNSET (the field is omitted from the request); pass None to clear it, or a value to set it.

Parameters:

Name	Type	Description	Default
`vn_id`	`str`	The VN id (e.g. `"v17"`).	required
`vote`	`int \| None \| UnsetType`	Vote in 10-100, `None` to clear, or `UNSET` to leave as-is.	`UNSET`
`notes`	`str \| None \| UnsetType`	Free-text notes, `None` to clear, or `UNSET` to leave as-is.	`UNSET`
`started`	`str \| None \| UnsetType`	Start date `YYYY-MM-DD`, `None` to clear, or `UNSET`.	`UNSET`
`finished`	`str \| None \| UnsetType`	Finish date `YYYY-MM-DD`, `None` to clear, or `UNSET`.	`UNSET`
`labels`	`list[int] \| None`	Replace the entry's labels with this exact list of label ids.	`None`
`labels_set`	`list[int] \| None`	Label ids to add.	`None`
`labels_unset`	`list[int] \| None`	Label ids to remove.	`None`

delete_ulist ¶

delete_ulist(vn_id: str) -> None

Remove the authenticated user's ulist entry for vn_id.

set_rlist ¶

set_rlist(release_id: str, *, status: int) -> None

Set the authenticated user's rlist status for a release.

Parameters:

Name	Type	Description	Default
`release_id`	`str`	The release id (e.g. `"r123"`).	required
`status`	`int`	The rlist status; accepts an `int` or an `RListStatus` value.	required

delete_rlist ¶

delete_rlist(release_id: str) -> None

Remove the authenticated user's rlist entry for release_id.

AsyncClient ¶

AsyncClient(
    token: str | None = None,
    *,
    base_url: str = PROD_BASE_URL,
    timeout: float = DEFAULT_TIMEOUT,
    user_agent: str = DEFAULT_USER_AGENT,
    retry: RetryConfig | None = None,
    http_client: AsyncClient | None = None,
    cache_ttl: float | None = None,
    cache_maxsize: int = 128,
)

Asynchronous VNDB Kana API client.

The async counterpart of :class:Client. It exposes the same entity query resources and helpers, but query and the write/GET methods are coroutines. Use it as an async context manager so the connection pool is closed on exit.

Example

import asyncio from vndb_client import AsyncClient async def main() -> str: ... async with AsyncClient() as client: ... page = await client.vn.query(filters=["id", "=", "v17"]) ... return page.results[0].title asyncio.run(main()) 'Ever17 -the out of infinity-'

Attributes:

Name	Type	Description
`vn`	`AsyncQueryResource[VN]`	Query resource for visual novels (`/vn`).
`release`	`AsyncQueryResource[Release]`	Query resource for releases (`/release`).
`producer`	`AsyncQueryResource[Producer]`	Query resource for producers (`/producer`).
`character`	`AsyncQueryResource[Character]`	Query resource for characters (`/character`).
`staff`	`AsyncQueryResource[Staff]`	Query resource for staff (`/staff`).
`tag`	`AsyncQueryResource[Tag]`	Query resource for tags (`/tag`).
`trait`	`AsyncQueryResource[Trait]`	Query resource for traits (`/trait`).
`quote`	`AsyncQueryResource[Quote]`	Query resource for quotes (`/quote`).
`ulist`	`AsyncQueryResource[UlistEntry]`	Query resource for user-list entries (`/ulist`).

Create an asynchronous client.

Parameters:

Name	Type	Description	Default
`token`	`str \| None`	VNDB API token for authenticated requests. Omit for read-only access.	`None`
`base_url`	`str`	API base URL. Defaults to production (`https://api.vndb.org/kana`); use `SANDBOX_BASE_URL` to target the sandbox.	`PROD_BASE_URL`
`timeout`	`float`	Per-request timeout in seconds.	`DEFAULT_TIMEOUT`
`user_agent`	`str`	`User-Agent` header sent with every request.	`DEFAULT_USER_AGENT`
`retry`	`RetryConfig \| None`	Retry policy for transient failures. `None` uses the default :class:`~vndb_client.config.RetryConfig`.	`None`
`http_client`	`AsyncClient \| None`	An existing `httpx.AsyncClient` to reuse. When provided, its lifecycle is the caller's responsibility.	`None`
`cache_ttl`	`float \| None`	Time-to-live in seconds for the in-memory read cache. `None` (or a non-positive value) disables caching; reads are not cached by default.	`None`
`cache_maxsize`	`int`	Maximum number of cached read responses before least-recently-used eviction. Only used when `cache_ttl` is set.	`128`

stats `async` ¶

stats() -> Stats

Return database-wide totals from the /stats endpoint.

Returns:

Type	Description
`Stats`	The site-wide entity counts.

authinfo `async` ¶

authinfo() -> AuthInfo

Return identity and permissions for the current token (/authinfo).

Returns:

Type	Description
`AuthInfo`	The authenticated token's id, username, and granted permissions.

get_user `async` ¶

get_user(
    q: str | list[str], *, fields: str | None = None
) -> dict[str, User | None]

Look up users by id or name via the /user endpoint.

Parameters:

Name	Type	Description	Default
`q`	`str \| list[str]`	A single user id/name, or a list of them.	required
`fields`	`str \| None`	Optional comma-separated extra fields to request.	`None`

Returns:

Type	Description
`dict[str, User \| None]`	A mapping from each query term to its `User`, or `None` if unknown.

ulist_labels `async` ¶

ulist_labels(
    user: str | None = None, *, fields: str | None = None
) -> list[UlistLabel]

List the ulist labels for a user (/ulist_labels).

Parameters:

Name	Type	Description	Default
`user`	`str \| None`	The user id whose labels to fetch; defaults to the token's user.	`None`
`fields`	`str \| None`	Optional comma-separated extra fields to request.	`None`

Returns:

Type	Description
`list[UlistLabel]`	The user's labels.

schema `async` ¶

schema() -> dict[str, Any]

Return the raw VNDB API schema document (/schema).

Returns:

Type	Description
`dict[str, Any]`	The schema as a plain JSON-decoded dict.

set_ulist `async` ¶

set_ulist(
    vn_id: str,
    *,
    vote: int | None | UnsetType = UNSET,
    notes: str | None | UnsetType = UNSET,
    started: str | None | UnsetType = UNSET,
    finished: str | None | UnsetType = UNSET,
    labels: list[int] | None = None,
    labels_set: list[int] | None = None,
    labels_unset: list[int] | None = None,
) -> None

Create or update the authenticated user's ulist entry for a VN.

Each scalar argument defaults to UNSET (the field is omitted from the request); pass None to clear it, or a value to set it.

Parameters:

Name	Type	Description	Default
`vn_id`	`str`	The VN id (e.g. `"v17"`).	required
`vote`	`int \| None \| UnsetType`	Vote in 10-100, `None` to clear, or `UNSET` to leave as-is.	`UNSET`
`notes`	`str \| None \| UnsetType`	Free-text notes, `None` to clear, or `UNSET` to leave as-is.	`UNSET`
`started`	`str \| None \| UnsetType`	Start date `YYYY-MM-DD`, `None` to clear, or `UNSET`.	`UNSET`
`finished`	`str \| None \| UnsetType`	Finish date `YYYY-MM-DD`, `None` to clear, or `UNSET`.	`UNSET`
`labels`	`list[int] \| None`	Replace the entry's labels with this exact list of label ids.	`None`
`labels_set`	`list[int] \| None`	Label ids to add.	`None`
`labels_unset`	`list[int] \| None`	Label ids to remove.	`None`

delete_ulist `async` ¶

delete_ulist(vn_id: str) -> None

Remove the authenticated user's ulist entry for vn_id.

set_rlist `async` ¶

set_rlist(release_id: str, *, status: int) -> None

Set the authenticated user's rlist status for a release.

Parameters:

Name	Type	Description	Default
`release_id`	`str`	The release id (e.g. `"r123"`).	required
`status`	`int`	The rlist status; accepts an `int` or an `RListStatus` value.	required

delete_rlist `async` ¶

delete_rlist(release_id: str) -> None

Remove the authenticated user's rlist entry for release_id.

Client¶

client ¶

Client ¶

stats ¶

authinfo ¶

get_user ¶

ulist_labels ¶

schema ¶

set_ulist ¶

delete_ulist ¶

set_rlist ¶

delete_rlist ¶

AsyncClient ¶

stats async ¶

authinfo async ¶

get_user async ¶

ulist_labels async ¶

schema async ¶

set_ulist async ¶

delete_ulist async ¶

set_rlist async ¶

delete_rlist async ¶

stats `async` ¶

authinfo `async` ¶

get_user `async` ¶

ulist_labels `async` ¶

schema `async` ¶

set_ulist `async` ¶

delete_ulist `async` ¶

set_rlist `async` ¶

delete_rlist `async` ¶