libsocial-core 1.0.0__py3-none-any.whl

libsocial/__init__.py

@@ -0,0 +1,81 @@
+"""Site-independent core of the lib.social SDKs (ranobelib.me, mangalib.me, ...)."""
+
+from libsocial._http import browser_headers, browser_headers_for
+from libsocial.cache import CacheStats, cache_stats, clear_cache
+from libsocial.catalog import Catalog
+from libsocial.client import ApiClient
+from libsocial.console import Reporter, Verbosity
+from libsocial.exceptions import (
+    AccessBlockedError,
+    AmbiguousChapter,
+    AuthRequiredError,
+    ChapterNotFoundError,
+    DownloadTitleInterruptedError,
+    LibSocialError,
+    MultipleTitleTranslationsError,
+    MultipleTranslationsError,
+    RateLimitError,
+    TitleNotFoundError,
+    VolumeNotFoundError,
+)
+from libsocial.models import (
+    CatalogPage,
+    Chapter,
+    ChapterBranch,
+    ChapterUser,
+    Country,
+    Cover,
+    Genre,
+    Label,
+    Person,
+    Tag,
+    Team,
+    Title,
+    Volume,
+)
+from libsocial.numbering import parse_slug_url
+from libsocial.pacing import Pacer, shared_pacer
+from libsocial.site import Site
+from libsocial.title import PlannedChapter, TitleClient
+
+__all__ = [
+    "AccessBlockedError",
+    "AmbiguousChapter",
+    "ApiClient",
+    "AuthRequiredError",
+    "CacheStats",
+    "Catalog",
+    "CatalogPage",
+    "Chapter",
+    "ChapterBranch",
+    "ChapterNotFoundError",
+    "ChapterUser",
+    "Country",
+    "Cover",
+    "DownloadTitleInterruptedError",
+    "Genre",
+    "Label",
+    "LibSocialError",
+    "MultipleTitleTranslationsError",
+    "MultipleTranslationsError",
+    "Pacer",
+    "Person",
+    "PlannedChapter",
+    "RateLimitError",
+    "Reporter",
+    "Site",
+    "Tag",
+    "Team",
+    "Title",
+    "TitleClient",
+    "TitleNotFoundError",
+    "Verbosity",
+    "Volume",
+    "VolumeNotFoundError",
+    "browser_headers",
+    "browser_headers_for",
+    "cache_stats",
+    "clear_cache",
+    "parse_slug_url",
+    "shared_pacer",
+]

libsocial/_http.py

@@ -0,0 +1,45 @@
+"""HTTP headers shared by every client the SDKs open (not public API).
+
+Lives in its own module rather than in ``client.py`` because it isn't specific to the
+api.cdnlibs.org JSON API: a site package's image-downloading clients (cover.cdnlibs.org,
+the site's own uploads) need the same headers.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+import httpx
+
+BROWSER_USER_AGENT = (
+    "Mozilla/5.0 (iPhone; CPU iPhone OS 18_5 like Mac OS X) AppleWebKit/605.1.15 "
+    "(KHTML, like Gecko) Version/18.5 Mobile/15E148 Safari/604.1"
+)
+"""A real browser's ``User-Agent``, sent instead of advertising ``python-httpx``."""
+
+
+def browser_headers_for(origin: str) -> dict[str, str]:
+    """Headers a browser on the site at ``origin`` sends, so requests look like the site's.
+
+    The DDoS-Guard edge in front of api.cdnlibs.org and cover.cdnlibs.org rejects requests
+    without a non-empty ``Referer`` with an HTML 403 page (see docs/api-notes.md, section
+    "WAF 403"). Any ``Referer`` value was enough when checked; the site's own one is sent,
+    together with ``Origin`` and a real browser ``User-Agent``, so the request as a whole
+    matches what the site itself sends.
+
+    Args:
+        origin: The site's web origin, e.g. ``"https://ranobelib.me"`` (see ``Site.origin``).
+    """
+    return {"Origin": origin, "Referer": f"{origin}/", "User-Agent": BROWSER_USER_AGENT}
+
+
+def browser_headers(origin: str, overrides: Mapping[str, str] | None = None) -> httpx.Headers:
+    """``browser_headers_for(origin)`` with ``overrides`` merged over them.
+
+    A key in ``overrides`` replaces the default one, matched case-insensitively (``httpx``
+    headers semantics) — the same merge ``ApiClient(headers=...)`` does for API requests.
+    """
+    headers = httpx.Headers(browser_headers_for(origin))
+    if overrides:
+        headers.update(overrides)
+    return headers

libsocial/cache.py

@@ -0,0 +1,180 @@
+"""Disk cache for raw JSON API responses, keyed by request identity.
+
+Also the cache-maintenance helpers, ``cache_stats()`` and ``clear_cache()`` — the
+on-disk layout is internal, so code outside the SDKs should go through these rather than
+measure or delete the cache's files itself.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import time
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+DEFAULT_CACHE_DIR = Path(".libsocial_cache")
+"""Default cache directory, relative to the current working directory."""
+
+_ENTRY_NAME = re.compile(r"[0-9a-f]{64}\.json")
+"""Name of a file ``DiskCache`` writes (``_path_for``) — anything else in the directory
+isn't the cache's and is never counted or removed."""
+
+
+@dataclass(frozen=True)
+class CacheStats:
+    """How many cache entries there are (or were removed), and their total size on disk."""
+
+    entries: int
+    bytes: int
+
+
+class DiskCache:
+    """Caches JSON-serializable values to disk, keyed by an arbitrary string.
+
+    One file per key, named by the key's hash (so keys built from slugs, chapter numbers,
+    etc. are always safe filenames), holding the cached value plus the time it was written
+    so ``ttl`` can be checked on read without touching any other entry. Corrupted or
+    unreadable entries are treated as a cache miss rather than raised as an error, since a
+    stale/broken cache file shouldn't stop the SDK from just re-fetching the data.
+    """
+
+    def __init__(
+        self,
+        cache_dir: str | Path,
+        *,
+        ttl: float | None = None,
+        clock: Callable[[], float] = time.time,
+    ) -> None:
+        """Initialize the cache.
+
+        Args:
+            cache_dir: Directory to store cache files in. Created lazily on first write.
+            ttl: Seconds after which a cache entry is treated as a miss. ``None`` (the
+                default) means entries never expire.
+            clock: Time source used to stamp and check entries. Overridable for tests.
+        """
+        self._dir = Path(cache_dir)
+        self._ttl = ttl
+        self._clock = clock
+
+    def get(self, key: str) -> Any | None:
+        """Return the cached value for ``key``, or ``None`` on a miss or expiry."""
+        try:
+            payload = json.loads(self._path_for(key).read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError, KeyError):
+            return None
+        if self._ttl is not None and self._clock() - payload["cached_at"] > self._ttl:
+            return None
+        return payload["data"]
+
+    def set(self, key: str, data: Any) -> None:
+        """Write ``data`` to disk under ``key``, creating the cache directory if needed."""
+        path = self._path_for(key)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        payload = {"cached_at": self._clock(), "data": data}
+        path.write_text(json.dumps(payload), encoding="utf-8")
+
+    def stats(self) -> CacheStats:
+        """Count the cache's entries and their total size. See ``cache_stats()``."""
+        entries = size = 0
+        for path in self._entry_paths():
+            try:
+                size += path.stat().st_size
+            except OSError:  # Removed since it was listed.
+                continue
+            entries += 1
+        return CacheStats(entries=entries, bytes=size)
+
+    def clear(self, *, older_than: float | None = None) -> CacheStats:
+        """Remove the cache's entries, or only those older than ``older_than`` seconds.
+
+        See ``clear_cache()``.
+        """
+        if older_than is not None and older_than < 0:
+            raise ValueError(f"older_than must be >= 0, got {older_than}")
+        now = self._clock()
+        entries = size = 0
+        for path in self._entry_paths():
+            if older_than is not None and not self._is_older_than(path, now - older_than):
+                continue
+            try:
+                entry_size = path.stat().st_size
+                path.unlink()
+            except OSError:
+                # Already removed by someone else, or (on Windows) open in another process
+                # right now — either way, not ours to count as removed.
+                continue
+            entries += 1
+            size += entry_size
+        return CacheStats(entries=entries, bytes=size)
+
+    def _is_older_than(self, path: Path, cutoff: float) -> bool:
+        try:
+            cached_at = float(json.loads(path.read_text(encoding="utf-8"))["cached_at"])
+        except FileNotFoundError:
+            return False
+        except (OSError, ValueError, KeyError, TypeError):
+            # Unreadable/corrupted: get() can never serve it, so it's as good as expired.
+            return True
+        return cached_at < cutoff
+
+    def _entry_paths(self) -> Iterator[Path]:
+        try:
+            children = list(self._dir.iterdir())
+        except (FileNotFoundError, NotADirectoryError):
+            return
+        for path in children:
+            if _ENTRY_NAME.fullmatch(path.name) and path.is_file() and not path.is_symlink():
+                yield path
+
+    def _path_for(self, key: str) -> Path:
+        digest = hashlib.sha256(key.encode("utf-8")).hexdigest()
+        return self._dir / f"{digest}.json"
+
+
+def cache_stats(cache_dir: str | Path = DEFAULT_CACHE_DIR) -> CacheStats:
+    """Count the entries in a disk cache and their total size on disk.
+
+    Only files the cache itself writes are counted, not anything else that happens to be in
+    the directory.
+
+    Args:
+        cache_dir: The cache directory — the same ``cache_dir`` passed to ``TitleClient`` /
+            ``Catalog`` (default: ``DEFAULT_CACHE_DIR``, ``.libsocial_cache`` in the current
+            directory; a site package may use its own default).
+
+    Returns:
+        The number of entries and their total size in bytes. A missing directory is an empty
+        cache, ``CacheStats(entries=0, bytes=0)``, not an error.
+    """
+    return DiskCache(cache_dir).stats()
+
+
+def clear_cache(
+    cache_dir: str | Path = DEFAULT_CACHE_DIR, *, older_than: float | None = None
+) -> CacheStats:
+    """Remove entries from a disk cache.
+
+    Only files the cache itself writes are removed — anything else in the directory, and the
+    directory itself, is left alone. Safe to call while clients are using the same cache: an
+    entry being read as it's removed is just a cache miss, and one written after it's
+    removed is simply recreated.
+
+    Args:
+        cache_dir: The cache directory — see ``cache_stats()``.
+        older_than: If given, only remove entries written more than this many seconds ago
+            (the same age check ``cache_ttl`` uses), plus any corrupted entry, which the
+            cache can't serve anyway. ``None`` (the default) removes every entry.
+
+    Returns:
+        The number of entries removed and the bytes they took. A missing directory removes
+        nothing, ``CacheStats(entries=0, bytes=0)``, rather than raising.
+
+    Raises:
+        ValueError: If ``older_than`` is negative.
+    """
+    return DiskCache(cache_dir).clear(older_than=older_than)

libsocial/catalog.py

@@ -0,0 +1,350 @@
+"""Catalog listing/search: the ``Catalog`` class.
+
+Unlike ``TitleClient`` (scoped to one title via its URL/slug), catalog listing isn't scoped
+to any title at all — see CLAUDE.md's roadmap entry for why this is a separate entry point
+with its own ``ApiClient``/``DiskCache`` rather than a method on the title client.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from types import TracebackType
+from typing import Any, Generic, Self, TypeVar
+
+from libsocial.cache import DEFAULT_CACHE_DIR, DiskCache
+from libsocial.client import ApiClient
+from libsocial.models import CatalogPage, Country, Genre, Label, TitleT
+from libsocial.site import Site
+
+DEFAULT_SORT = "last_chapter_at"
+"""Default sort order: title's last-chapter timestamp — the closest real equivalent to
+"recently updated" (the API has no ``updated_at`` sort value, see docs/api-notes.md)."""
+
+MIN_PER_PAGE = 10
+MAX_PER_PAGE = 60
+
+
+class Catalog(Generic[TitleT]):
+    """Listing/searching one site's catalog.
+
+    Not used directly: a site package subclasses it, setting ``site`` and ``page_model``
+    (and optionally ``default_cache_dir``) as class attributes — so its own ``Catalog``
+    keeps a plain constructor and returns its own page and ``Title`` models.
+
+    Example:
+        ```python
+        class RanobeLibCatalog(Catalog[Title]):
+            site = Site(id=3, origin="https://ranobelib.me")
+            page_model = CatalogPage[Title]
+
+        async with RanobeLibCatalog() as catalog:
+            page = await catalog.list_titles(query="dxd", genres=[34], statuses=[1])
+            for title in page.items:
+                print(title.name)
+        ```
+
+    Attributes:
+        site: The site whose catalog is listed. Set by the subclass.
+        page_model: The model a listing page is validated as — ``CatalogPage[ItsTitle]``
+            or a subclass of it, which also decides the model of its items. Set by the
+            subclass.
+        default_cache_dir: ``cache_dir`` used when none is passed.
+    """
+
+    site: Site
+    page_model: type[CatalogPage[TitleT]]
+    default_cache_dir: Path = DEFAULT_CACHE_DIR
+
+    def __init__(
+        self,
+        *,
+        cache_dir: str | Path | None = None,
+        cache_ttl: float | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> None:
+        """Initialize the catalog client.
+
+        Args:
+            cache_dir: Where to cache raw API responses on disk, one entry per distinct set
+                of listing parameters (page/filters/sort) — same disk cache as
+                ``TitleClient`` uses (``cache.py``), just keyed by listing parameters instead
+                of a title's slug. Defaults to ``default_cache_dir``.
+            cache_ttl: Seconds after which a cached page is treated as stale and re-fetched.
+                ``None`` (the default) means cached pages never expire on their own — see
+                ``refresh=True`` on ``list_titles()`` to force one anyway.
+            headers: Extra HTTP headers merged over the SDK's defaults, same as
+                ``TitleClient(headers=...)`` — see there.
+        """
+        self._client = self._create_client(headers)
+        self._cache = DiskCache(
+            cache_dir if cache_dir is not None else self.default_cache_dir, ttl=cache_ttl
+        )
+
+    def _create_client(self, headers: Mapping[str, str] | None) -> ApiClient:
+        """The ``ApiClient`` requests go through — a site package may return its own subclass.
+
+        Args:
+            headers: The ``headers`` passed to the constructor.
+        """
+        return ApiClient(self.site, headers=headers)
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP client."""
+        await self._client.aclose()
+
+    async def list_titles(
+        self,
+        *,
+        page: int = 1,
+        per_page: int = 30,
+        query: str | None = None,
+        genres: list[int] | None = None,
+        tags: list[int] | None = None,
+        statuses: list[int] | None = None,
+        countries: list[int] | None = None,
+        min_chapters: int | None = None,
+        max_chapters: int | None = None,
+        sort: str = DEFAULT_SORT,
+        refresh: bool = False,
+    ) -> CatalogPage[TitleT]:
+        """Fetch one page of catalog listing/search results.
+
+        Args:
+            page: 1-based page number.
+            per_page: How many titles per page. Must be between ``MIN_PER_PAGE`` (10) and
+                ``MAX_PER_PAGE`` (60) — the API's own limits (see docs/api-notes.md);
+                anything outside that range raises here instead of a confusing 422 from
+                the API.
+            query: Free-text search term, matched against name/rus_name/eng_name. ``None``
+                (the default) or an empty string lists without searching.
+            genres: Genre ids to filter by. A title must have *all* of them, not just one
+                (AND, not OR — see docs/api-notes.md). Not validated against ``list_genres()``
+                before sending — an unrecognized id just matches nothing rather than erroring.
+            tags: ``Tag.id``s (from ``Title.tags``) to filter by. Same AND semantics as
+                ``genres`` — a title must have *all* of them, not just any one (confirmed
+                against the live API, see docs/api-notes.md; not the OR some might expect
+                from tags being more numerous/specific than genres). Also not validated
+                before sending, same as ``genres``.
+            statuses: ``Title.status.id``s to filter by (e.g. ongoing, completed). A title
+                matches if its own status is *any* of these (OR, same as ``countries`` — a
+                title only has one status, see docs/api-notes.md). ``None`` or an empty list
+                applies no status filter. Ids come from ``list_statuses()``.
+            countries: ``Country.id``s to filter by. A title matches if its own country is
+                *any* of these (OR, not AND like ``genres``/``tags`` — a title only has one
+                country of origin, so requiring all of them could never match past the first,
+                see docs/api-notes.md). ``None`` or an empty list applies no country filter.
+                Ids come from ``list_countries()``. Sent on the wire as the API's ``types[]``
+                parameter, not a ``country``/``countries[]`` one — see docs/api-notes.md for
+                why (``Country`` mirrors the API's own "type" concept, which isn't strictly
+                limited to literal countries).
+            min_chapters: Only titles with at least this many chapters (inclusive). Counts
+                the same number as ``Title.chapter_count`` (uploaded chapters). ``None``
+                (the default) applies no lower bound.
+            max_chapters: Only titles with at most this many chapters (inclusive). ``None``
+                (the default) applies no upper bound.
+            sort: Sort order. Despite the name, this is sent as the API's ``sort_by``
+                parameter — an actual ``sort`` parameter exists but is silently ignored by
+                the API (see docs/api-notes.md). Known accepted values: ``"name"``,
+                ``"created_at"``, ``"views"``, ``"chap_count"``, ``"last_chapter_at"``
+                (the default), ``"rate_avg"``, ``"random"`` — this list isn't guaranteed
+                exhaustive.
+            refresh: Bypass the disk cache and re-fetch from the API even if this exact
+                combination of parameters was already cached.
+
+        Returns:
+            A ``page_model`` page: the matching titles plus whether a next page exists.
+
+        Raises:
+            ValueError: If ``page`` is less than 1, ``per_page`` is outside
+                ``MIN_PER_PAGE..MAX_PER_PAGE``, ``min_chapters``/``max_chapters`` is
+                negative, or ``min_chapters`` is greater than ``max_chapters``.
+        """
+        if page < 1:
+            raise ValueError(f"page must be at least 1, got {page}.")
+        if not MIN_PER_PAGE <= per_page <= MAX_PER_PAGE:
+            raise ValueError(
+                f"per_page must be between {MIN_PER_PAGE} and {MAX_PER_PAGE}, got {per_page}."
+            )
+        for name, value in (("min_chapters", min_chapters), ("max_chapters", max_chapters)):
+            if value is not None and value < 0:
+                raise ValueError(f"{name} must be at least 0, got {value}.")
+        if min_chapters is not None and max_chapters is not None and min_chapters > max_chapters:
+            # The API itself silently swaps the bounds instead (see docs/api-notes.md) —
+            # raising here rather than relying on that undocumented behavior.
+            raise ValueError(
+                f"min_chapters ({min_chapters}) must not be greater than "
+                f"max_chapters ({max_chapters})."
+            )
+
+        key = _cache_key(
+            site_id=self.site.id,
+            page=page,
+            per_page=per_page,
+            query=query,
+            genres=genres,
+            tags=tags,
+            statuses=statuses,
+            countries=countries,
+            min_chapters=min_chapters,
+            max_chapters=max_chapters,
+            sort=sort,
+        )
+        if not refresh:
+            cached = self._cache.get(key)
+            if cached is not None:
+                return self._build_page(cached)
+
+        data = await self._client.list_titles(
+            page=page,
+            per_page=per_page,
+            query=query,
+            genres=genres,
+            tags=tags,
+            statuses=statuses,
+            countries=countries,
+            min_chapters=min_chapters,
+            max_chapters=max_chapters,
+            sort=sort,
+        )
+        self._cache.set(key, data)
+        return self._build_page(data)
+
+    async def list_genres(self, *, refresh: bool = False) -> list[Genre]:
+        """Fetch the full list of catalog genres (id → name), for use as filter options
+        with ``list_titles(genres=[...])``.
+
+        The underlying endpoint (``GET /api/constants?fields[]=genres``) has no site-scoping
+        parameter — it returns the full genre list shared across the whole lib.social
+        network in one shot, each tagged with the site ids it applies to (see
+        docs/api-notes.md). This filters that down to genres tagged for ``site`` before
+        returning, so callers don't get filter options that could never match any of the
+        site's titles (e.g. "Детское", tagged only for site 5, on ranobelib.me).
+
+        Args:
+            refresh: Bypass the disk cache and re-fetch from the API even if the genre list
+                was already cached.
+
+        Returns:
+            Every ``Genre`` (id, name, adult flag) that applies to ``site``.
+        """
+        # No site in the key, unlike list_titles(): the response is the whole network's
+        # list, and _for_site() filters it on every read, cached or not.
+        key = "catalog:genres"
+        if not refresh:
+            cached = self._cache.get(key)
+            if cached is not None:
+                return _for_site(Genre, cached, self.site)
+
+        data = await self._client.list_genres()
+        self._cache.set(key, data)
+        return _for_site(Genre, data, self.site)
+
+    async def list_countries(self, *, refresh: bool = False) -> list[Country]:
+        """Fetch the full list of catalog countries (id → name), for use as filter options
+        with ``list_titles(countries=...)``.
+
+        Mirrors ``list_genres()`` exactly, down to the network-wide, not-site-scoped shape
+        of the underlying endpoint (``GET /api/constants?fields[]=types`` — the API's own
+        name for what this SDK calls "country" is "type", see docs/api-notes.md and
+        ``Country``'s docstring). This filters that down to entries tagged for ``site`` before
+        returning, same as ``list_genres()`` does for genres.
+
+        Args:
+            refresh: Bypass the disk cache and re-fetch from the API even if the country
+                list was already cached.
+
+        Returns:
+            Every ``Country`` (id, name) that applies to ``site``.
+        """
+        key = "catalog:countries"
+        if not refresh:
+            cached = self._cache.get(key)
+            if cached is not None:
+                return _for_site(Country, cached, self.site)
+
+        data = await self._client.list_countries()
+        self._cache.set(key, data)
+        return _for_site(Country, data, self.site)
+
+    async def list_statuses(self, *, refresh: bool = False) -> list[Label]:
+        """Fetch the full list of title statuses (id → label), for use as filter options
+        with ``list_titles(statuses=...)``.
+
+        Mirrors ``list_genres()``/``list_countries()``: the underlying endpoint
+        (``GET /api/constants?fields[]=status``) isn't site-scoped, so entries not tagged for
+        ``site`` are dropped before returning (see docs/api-notes.md). Returns the same
+        ``Label`` model as ``Title.status``, so a title's status can be compared against
+        these directly.
+
+        Args:
+            refresh: Bypass the disk cache and re-fetch from the API even if the status list
+                was already cached.
+
+        Returns:
+            Every status (``Label``: id, label) that applies to ``site``.
+        """
+        key = "catalog:statuses"
+        if not refresh:
+            cached = self._cache.get(key)
+            if cached is not None:
+                return _for_site(Label, cached, self.site)
+
+        data = await self._client.list_statuses()
+        self._cache.set(key, data)
+        return _for_site(Label, data, self.site)
+
+    def _build_page(self, data: dict[str, Any]) -> CatalogPage[TitleT]:
+        meta = data["meta"]
+        return self.page_model.model_validate(
+            {
+                "items": data["data"],
+                "page": meta["current_page"],
+                "has_next_page": meta["has_next_page"],
+            }
+        )
+
+
+def _cache_key(
+    *,
+    site_id: int,
+    page: int,
+    per_page: int,
+    query: str | None,
+    genres: list[int] | None,
+    tags: list[int] | None,
+    statuses: list[int] | None,
+    countries: list[int] | None,
+    min_chapters: int | None,
+    max_chapters: int | None,
+    sort: str,
+) -> str:
+    genres_part = ",".join(str(genre_id) for genre_id in genres or [])
+    tags_part = ",".join(str(tag_id) for tag_id in tags or [])
+    statuses_part = ",".join(str(status_id) for status_id in statuses or [])
+    countries_part = ",".join(str(country_id) for country_id in countries or [])
+    # The listing is scoped to the site (site_id[]), so catalogs for different sites sharing
+    # a cache_dir must not read each other's pages.
+    return (
+        f"catalog:{site_id}:{page}:{per_page}:{query or ''}:{genres_part}:{tags_part}:"
+        f"{statuses_part}:{countries_part}:{min_chapters}:{max_chapters}:{sort}"
+    )
+
+
+_ConstantT = TypeVar("_ConstantT", Genre, Country, Label)
+
+
+def _for_site(model: type[_ConstantT], data: list[dict[str, Any]], site: Site) -> list[_ConstantT]:
+    """Validate a raw ``/constants`` list as ``model``, keeping entries tagged for ``site``."""
+    return [model.model_validate(item) for item in data if site.id in item.get("site_ids", [])]