Skip to content

Client API

Public vgmdb clients composing transport + parsers.

AsyncClient

Asynchronous vgmdb client. Shares path logic and parsers with :class:Client.

Construct with a :class:TransportConfig (an :class:AsyncTransport is created internally) or inject a ready async transport. Exactly one of config/transport is required. Usable as an async context manager that closes the transport on exit.

Source code in src/vgmdb_client/client/async_client.py 
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
class AsyncClient:
    """Asynchronous vgmdb client. Shares path logic and parsers with :class:`Client`.

    Construct with a :class:`TransportConfig` (an :class:`AsyncTransport` is created internally) or
    inject a ready async transport. Exactly one of ``config``/``transport`` is required. Usable as an
    async context manager that closes the transport on exit.
    """

    def __init__(self, config: TransportConfig | None = None, *, transport: AsyncTransport | None = None) -> None:
        if config is not None and transport is not None:
            raise ValueError(_ONE_SOURCE)
        if transport is not None:
            self._transport = transport
        elif config is not None:
            self._transport = AsyncTransport(config)
        else:
            raise ValueError(_ONE_SOURCE)

    @classmethod
    def from_credentials(cls, credentials: Credentials, **config_overrides: Any) -> AsyncClient:
        """Build a client from a :class:`Credentials` pair (initial fill).

        Extra keyword arguments are forwarded to :meth:`Credentials.to_config` as
        :class:`TransportConfig` overrides (e.g. ``timeout``, ``min_interval``, ``proxy``).
        """
        return cls(config=credentials.to_config(**config_overrides))

    def set_credentials(self, credentials: Credentials) -> None:
        """Apply a fresh :class:`Credentials` pair to the live client (renewal).

        Use after a :class:`~vgmdb_client.transport.errors.CloudflareChallengeError`: re-solve in the
        browser, copy a fresh cURL, and swap the pair in without rebuilding the client.
        """
        self._transport.set_cf_clearance(credentials.cf_clearance)
        self._transport.set_user_agent(credentials.user_agent)

    async def get_album(self, album_id: int) -> Album:
        """Fetch and parse an album page."""
        return parse_album(await self._transport.get(_core.album_path(album_id)))

    async def search(self, query: str) -> SearchResults:
        """Fetch and parse a search-results page."""
        return parse_search(await self._transport.get(_core.search_path(query)))

    async def get_artist(self, artist_id: int) -> Artist:
        """Fetch and parse an artist page."""
        return parse_artist(await self._transport.get(_core.artist_path(artist_id)))

    async def get_product(self, product_id: int) -> Product:
        """Fetch and parse a product page."""
        return parse_product(await self._transport.get(_core.product_path(product_id)))

    async def get_organization(self, org_id: int) -> Organization:
        """Fetch and parse an organization page."""
        return parse_organization(await self._transport.get(_core.organization_path(org_id)))

    async def get_event(self, event_id: int) -> Event:
        """Fetch and parse an event page."""
        return parse_event(await self._transport.get(_core.event_path(event_id)))

    async def aclose(self) -> None:
        """Close the underlying transport."""
        await self._transport.aclose()

    async def __aenter__(self) -> AsyncClient:
        return self

    async def __aexit__(
        self,
        exc_type: type[BaseException] | None,
        exc: BaseException | None,
        tb: TracebackType | None,
    ) -> None:
        await self.aclose()

aclose() async

Close the underlying transport.

Source code in src/vgmdb_client/client/async_client.py 
77
78
79
async def aclose(self) -> None:
    """Close the underlying transport."""
    await self._transport.aclose()

from_credentials(credentials, **config_overrides) classmethod

Build a client from a :class:Credentials pair (initial fill).

Extra keyword arguments are forwarded to :meth:Credentials.to_config as :class:TransportConfig overrides (e.g. timeout, min_interval, proxy).

Source code in src/vgmdb_client/client/async_client.py 
35
36
37
38
39
40
41
42
@classmethod
def from_credentials(cls, credentials: Credentials, **config_overrides: Any) -> AsyncClient:
    """Build a client from a :class:`Credentials` pair (initial fill).

    Extra keyword arguments are forwarded to :meth:`Credentials.to_config` as
    :class:`TransportConfig` overrides (e.g. ``timeout``, ``min_interval``, ``proxy``).
    """
    return cls(config=credentials.to_config(**config_overrides))

get_album(album_id) async

Fetch and parse an album page.

Source code in src/vgmdb_client/client/async_client.py 
53
54
55
async def get_album(self, album_id: int) -> Album:
    """Fetch and parse an album page."""
    return parse_album(await self._transport.get(_core.album_path(album_id)))

get_artist(artist_id) async

Fetch and parse an artist page.

Source code in src/vgmdb_client/client/async_client.py 
61
62
63
async def get_artist(self, artist_id: int) -> Artist:
    """Fetch and parse an artist page."""
    return parse_artist(await self._transport.get(_core.artist_path(artist_id)))

get_event(event_id) async

Fetch and parse an event page.

Source code in src/vgmdb_client/client/async_client.py 
73
74
75
async def get_event(self, event_id: int) -> Event:
    """Fetch and parse an event page."""
    return parse_event(await self._transport.get(_core.event_path(event_id)))

get_organization(org_id) async

Fetch and parse an organization page.

Source code in src/vgmdb_client/client/async_client.py 
69
70
71
async def get_organization(self, org_id: int) -> Organization:
    """Fetch and parse an organization page."""
    return parse_organization(await self._transport.get(_core.organization_path(org_id)))

get_product(product_id) async

Fetch and parse a product page.

Source code in src/vgmdb_client/client/async_client.py 
65
66
67
async def get_product(self, product_id: int) -> Product:
    """Fetch and parse a product page."""
    return parse_product(await self._transport.get(_core.product_path(product_id)))

search(query) async

Fetch and parse a search-results page.

Source code in src/vgmdb_client/client/async_client.py 
57
58
59
async def search(self, query: str) -> SearchResults:
    """Fetch and parse a search-results page."""
    return parse_search(await self._transport.get(_core.search_path(query)))

set_credentials(credentials)

Apply a fresh :class:Credentials pair to the live client (renewal).

Use after a :class:~vgmdb_client.transport.errors.CloudflareChallengeError: re-solve in the browser, copy a fresh cURL, and swap the pair in without rebuilding the client.

Source code in src/vgmdb_client/client/async_client.py 
44
45
46
47
48
49
50
51
def set_credentials(self, credentials: Credentials) -> None:
    """Apply a fresh :class:`Credentials` pair to the live client (renewal).

    Use after a :class:`~vgmdb_client.transport.errors.CloudflareChallengeError`: re-solve in the
    browser, copy a fresh cURL, and swap the pair in without rebuilding the client.
    """
    self._transport.set_cf_clearance(credentials.cf_clearance)
    self._transport.set_user_agent(credentials.user_agent)

Client

Synchronous vgmdb client: fetch + parse album/search pages into M1 models.

Construct with a :class:TransportConfig (a :class:SyncTransport is created internally) or inject a ready transport (e.g. a stub in tests). Exactly one of config/transport is required. Usable as a context manager that closes the transport on exit.

Source code in src/vgmdb_client/client/sync_client.py 
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
class Client:
    """Synchronous vgmdb client: fetch + parse album/search pages into M1 models.

    Construct with a :class:`TransportConfig` (a :class:`SyncTransport` is created internally) or
    inject a ready transport (e.g. a stub in tests). Exactly one of ``config``/``transport`` is
    required. Usable as a context manager that closes the transport on exit.
    """

    def __init__(self, config: TransportConfig | None = None, *, transport: SyncTransport | None = None) -> None:
        if config is not None and transport is not None:
            raise ValueError(_ONE_SOURCE)
        if transport is not None:
            self._transport = transport
        elif config is not None:
            self._transport = SyncTransport(config)
        else:
            raise ValueError(_ONE_SOURCE)

    @classmethod
    def from_credentials(cls, credentials: Credentials, **config_overrides: Any) -> Client:
        """Build a client from a :class:`Credentials` pair (initial fill).

        Extra keyword arguments are forwarded to :meth:`Credentials.to_config` as
        :class:`TransportConfig` overrides (e.g. ``timeout``, ``min_interval``, ``proxy``).
        """
        return cls(config=credentials.to_config(**config_overrides))

    def set_credentials(self, credentials: Credentials) -> None:
        """Apply a fresh :class:`Credentials` pair to the live client (renewal).

        Use after a :class:`~vgmdb_client.transport.errors.CloudflareChallengeError`: re-solve in the
        browser, copy a fresh cURL, and swap the pair in without rebuilding the client.
        """
        self._transport.set_cf_clearance(credentials.cf_clearance)
        self._transport.set_user_agent(credentials.user_agent)

    def get_album(self, album_id: int) -> Album:
        """Fetch and parse an album page."""
        return parse_album(self._transport.get(_core.album_path(album_id)))

    def search(self, query: str) -> SearchResults:
        """Fetch and parse a search-results page."""
        return parse_search(self._transport.get(_core.search_path(query)))

    def get_artist(self, artist_id: int) -> Artist:
        """Fetch and parse an artist page."""
        return parse_artist(self._transport.get(_core.artist_path(artist_id)))

    def get_product(self, product_id: int) -> Product:
        """Fetch and parse a product page."""
        return parse_product(self._transport.get(_core.product_path(product_id)))

    def get_organization(self, org_id: int) -> Organization:
        """Fetch and parse an organization page."""
        return parse_organization(self._transport.get(_core.organization_path(org_id)))

    def get_event(self, event_id: int) -> Event:
        """Fetch and parse an event page."""
        return parse_event(self._transport.get(_core.event_path(event_id)))

    def close(self) -> None:
        """Close the underlying transport."""
        self._transport.close()

    def __enter__(self) -> Client:
        return self

    def __exit__(
        self,
        exc_type: type[BaseException] | None,
        exc: BaseException | None,
        tb: TracebackType | None,
    ) -> None:
        self.close()

close()

Close the underlying transport.

Source code in src/vgmdb_client/client/sync_client.py 
77
78
79
def close(self) -> None:
    """Close the underlying transport."""
    self._transport.close()

from_credentials(credentials, **config_overrides) classmethod

Build a client from a :class:Credentials pair (initial fill).

Extra keyword arguments are forwarded to :meth:Credentials.to_config as :class:TransportConfig overrides (e.g. timeout, min_interval, proxy).

Source code in src/vgmdb_client/client/sync_client.py 
35
36
37
38
39
40
41
42
@classmethod
def from_credentials(cls, credentials: Credentials, **config_overrides: Any) -> Client:
    """Build a client from a :class:`Credentials` pair (initial fill).

    Extra keyword arguments are forwarded to :meth:`Credentials.to_config` as
    :class:`TransportConfig` overrides (e.g. ``timeout``, ``min_interval``, ``proxy``).
    """
    return cls(config=credentials.to_config(**config_overrides))

get_album(album_id)

Fetch and parse an album page.

Source code in src/vgmdb_client/client/sync_client.py 
53
54
55
def get_album(self, album_id: int) -> Album:
    """Fetch and parse an album page."""
    return parse_album(self._transport.get(_core.album_path(album_id)))

get_artist(artist_id)

Fetch and parse an artist page.

Source code in src/vgmdb_client/client/sync_client.py 
61
62
63
def get_artist(self, artist_id: int) -> Artist:
    """Fetch and parse an artist page."""
    return parse_artist(self._transport.get(_core.artist_path(artist_id)))

get_event(event_id)

Fetch and parse an event page.

Source code in src/vgmdb_client/client/sync_client.py 
73
74
75
def get_event(self, event_id: int) -> Event:
    """Fetch and parse an event page."""
    return parse_event(self._transport.get(_core.event_path(event_id)))

get_organization(org_id)

Fetch and parse an organization page.

Source code in src/vgmdb_client/client/sync_client.py 
69
70
71
def get_organization(self, org_id: int) -> Organization:
    """Fetch and parse an organization page."""
    return parse_organization(self._transport.get(_core.organization_path(org_id)))

get_product(product_id)

Fetch and parse a product page.

Source code in src/vgmdb_client/client/sync_client.py 
65
66
67
def get_product(self, product_id: int) -> Product:
    """Fetch and parse a product page."""
    return parse_product(self._transport.get(_core.product_path(product_id)))

search(query)

Fetch and parse a search-results page.

Source code in src/vgmdb_client/client/sync_client.py 
57
58
59
def search(self, query: str) -> SearchResults:
    """Fetch and parse a search-results page."""
    return parse_search(self._transport.get(_core.search_path(query)))

set_credentials(credentials)

Apply a fresh :class:Credentials pair to the live client (renewal).

Use after a :class:~vgmdb_client.transport.errors.CloudflareChallengeError: re-solve in the browser, copy a fresh cURL, and swap the pair in without rebuilding the client.

Source code in src/vgmdb_client/client/sync_client.py 
44
45
46
47
48
49
50
51
def set_credentials(self, credentials: Credentials) -> None:
    """Apply a fresh :class:`Credentials` pair to the live client (renewal).

    Use after a :class:`~vgmdb_client.transport.errors.CloudflareChallengeError`: re-solve in the
    browser, copy a fresh cURL, and swap the pair in without rebuilding the client.
    """
    self._transport.set_cf_clearance(credentials.cf_clearance)
    self._transport.set_user_agent(credentials.user_agent)