libsocial-core API reference

import libsocial. Most users get these through ranobelib or mangalib, which re-export the models and exceptions — see libsocial-core.

Building blocks

libsocial.Site dataclass

Site(id: int, origin: str)

One lib.social site, as the shared api.cdnlibs.org API tells them apart.

The core knows no site by itself: each site package defines its own (ranobelib.me is Site(id=3, origin="https://ranobelib.me"), mangalib.me id=1) and passes it in.

Attributes:

Name	Type	Description
id	int	The site's id — sent as the Site-Id header on title/chapter requests and as site_id[] on catalog listings, and used to filter the network-wide /constants lists (genres, types, statuses) down to this site. Without the right one, the API answers 404 for titles that exist (see docs/api-notes.md).
origin	str	The site's web origin, e.g. "https://ranobelib.me" — sent as Origin/Referer so requests look like they come from the site's own pages (see docs/api-notes.md, section "WAF 403"), and the base for site-relative URLs.

libsocial.TitleClient

TitleClient(
    url: str,
    *,
    cache_dir: str | Path | None = None,
    cache_ttl: float | None = None,
    verbosity: Verbosity = False,
    headers: Mapping[str, str] | None = None,
)

Bases: Generic[TitleT, ChapterT, VolumeT]

One title on one lib.social site: metadata, chapters, translations, bulk download.

Not used directly: a site package subclasses it, setting the class attributes below — which site it talks to, and which models a title, a chapter (with the site's own content fields) and a volume are validated as — and adds whatever is specific to the site's content (export, size estimates, ...).

Example

class RanobeLib(TitleClient[Title, Chapter, Volume]):
    site = Site(id=3, origin="https://ranobelib.me")
    title_model = Title
    chapter_model = Chapter
    volume_model = Volume

async with RanobeLib("https://ranobelib.me/ru/book/6712--high-school-dxd-novel") as lib:
    info = await lib.get_info()

Attributes:

Name	Type	Description
site	Site	The site the title is on. Set by the subclass.
title_model	type[TitleT]	The model get_info() returns. Set by the subclass.
chapter_model	type[ChapterT]	The model chapters are validated as — both table-of-contents entries and fetched chapters, so its content fields must be optional. Set by the subclass.
volume_model	type[VolumeT]	The model chapters are grouped into, Volume[chapter_model] or a subclass of it. Set by the subclass.
default_cache_dir	Path	cache_dir used when none is passed.
info_fields	tuple[str, ...]	Extra fields[] get_info() requests on top of the API's default response (see docs/api-notes.md for what each adds).

Initialize the client for a title.

Parameters:

Name	Type	Description	Default
url	str	The title's URL on the site, or a bare {id}--{slug} identifier.	required
cache_dir	str | Path | None	Where to cache raw API responses (title metadata, chapter list, chapter content) on disk, so a repeated export or downloading newly added chapters doesn't re-fetch data already on hand. Defaults to default_cache_dir.	None
cache_ttl	float | None	Seconds after which a cached response is treated as stale and re-fetched. None (the default) means cached responses never expire on their own — see refresh=True on individual methods to force one anyway.	None
verbosity	Verbosity	Console output level. False (default): silent. "progress_only": progress bars for bulk operations (download_title(), ...). "full": the same progress bars, plus a line logged for every title/chapter-list/ chapter fetch, noting whether it was served from the disk cache or the API.	False
headers	Mapping[str, str] | None	Extra HTTP headers merged over the SDK's defaults (browser-like Origin/Referer/User-Agent, see docs/api-notes.md, section "WAF 403") — a key given here replaces the default one, matched case-insensitively. Meant for when the site's edge protection changes which requests it lets through (AccessBlockedError): send what it now expects without waiting for an SDK release. None (the default) sends the defaults as-is.	None

Source code in packages/core/src/libsocial/title.py

def __init__(
    self,
    url: str,
    *,
    cache_dir: str | Path | None = None,
    cache_ttl: float | None = None,
    verbosity: Verbosity = False,
    headers: Mapping[str, str] | None = None,
) -> None:
    """Initialize the client for a title.

    Args:
        url: The title's URL on the site, or a bare ``{id}--{slug}`` identifier.
        cache_dir: Where to cache raw API responses (title metadata, chapter list,
            chapter content) on disk, so a repeated export or downloading newly added
            chapters doesn't re-fetch data already on hand. Defaults to
            ``default_cache_dir``.
        cache_ttl: Seconds after which a cached response is treated as stale and
            re-fetched. ``None`` (the default) means cached responses never expire on
            their own — see ``refresh=True`` on individual methods to force one anyway.
        verbosity: Console output level. ``False`` (default): silent. ``"progress_only"``:
            progress bars for bulk operations (``download_title()``, ...). ``"full"``:
            the same progress bars, plus a line logged for every title/chapter-list/
            chapter fetch, noting whether it was served from the disk cache or the API.
        headers: Extra HTTP headers merged over the SDK's defaults (browser-like
            ``Origin``/``Referer``/``User-Agent``, see docs/api-notes.md, section "WAF
            403") — a key given here replaces the default one, matched
            case-insensitively. Meant for when the site's edge protection changes which
            requests it lets through (``AccessBlockedError``): send what it now expects
            without waiting for an SDK release. ``None`` (the default) sends the
            defaults as-is.
    """
    self._slug_url = parse_slug_url(url)
    self._headers = dict(headers) if headers is not None else None
    self._client = self._create_client(self._headers)
    self._cache = DiskCache(
        cache_dir if cache_dir is not None else self.default_cache_dir, ttl=cache_ttl
    )
    self._reporter = Reporter(verbosity)

slug_url property

slug_url: str

The title's {id}--{slug} identifier.

aclose async

aclose() -> None

Close the underlying HTTP client.

Source code in packages/core/src/libsocial/title.py

async def aclose(self) -> None:
    """Close the underlying HTTP client."""
    await self._client.aclose()

download_title async

download_title(
    *,
    branch_id: int | None = None,
    translation_index: int | None = None,
    chapter_delay: float = 0.0,
    on_chapter: Callable[[int, int], None] | None = None,
    max_rate_limit_retries: int = DEFAULT_RATE_LIMIT_RETRIES,
) -> list[VolumeT]

Download every chapter of the title, across all its volumes.

Fetches the chapter list once, then every chapter's content, sequentially, in the API's own order — same pacing/retry/backoff as any other chapter fetch (see ApiClient), plus chapter_delay on top if given.

Resolving translations is checked for the whole title up front, not chapter by chapter: if any chapters have more than one translation, this fetches nothing and raises MultipleTitleTranslationsError listing all of them at once (unless branch_id or translation_index resolves every one of them), rather than failing partway through a long download on the first ambiguous chapter.

A long title's sequential download can outlast ApiClient's own retry budget for 429s (tuned for a single one-off request, not hundreds/thousands of sequential fetches — see docs/api-notes.md). On top of that, each chapter fetch that still comes back rate-limited is retried again here, up to max_rate_limit_retries times, with its own (coarser) backoff. If a chapter fetch still fails after that — from rate limiting or anything else — the chapters already downloaded are not discarded: they're attached to a raised DownloadTitleInterruptedError instead of being lost.

Parameters:

Name	Type	Description	Default
branch_id	int | None	Translation to use for every chapter that has more than one — same meaning as get_chapter(..., branch_id=...), applied title-wide. Chapters with only one translation are unaffected. Mutually exclusive with translation_index.	None
translation_index	int | None	Alternative to branch_id: pick the translation at this position in each ambiguous chapter's branches list (0 for the first, and so on) — useful when ambiguous chapters don't share one branch_id across the title. Mutually exclusive with branch_id.	None
chapter_delay	float	Extra delay, in seconds, after fetching each chapter, on top of ApiClient's own per-request pacing — to be gentler on the API during a large bulk download. Defaults to no extra delay.	0.0
on_chapter	Callable[[int, int], None] | None	Called with (completed, total) after each chapter is fetched, if given — a programmatic progress hook for callers that aren't printing to a console (e.g. a web app polling/streaming download progress to a browser), who would otherwise have no way to observe anything before this whole await returns. Independent of verbosity: both can be set at once, each drives its own output.	None
max_rate_limit_retries	int	How many extra times to retry a single chapter fetch that comes back rate-limited, on top of ApiClient's own retries, before giving up on the whole download — see above. Each retry honors the API's Retry-After if it sent one, otherwise waits with its own capped exponential backoff. Set to 0 to disable this extra layer and let a persistent RateLimitError end the download immediately (still wrapped in DownloadTitleInterruptedError with whatever was already fetched).	DEFAULT_RATE_LIMIT_RETRIES

Raises:

Type	Description
ValueError	If both branch_id and translation_index are given.
MultipleTitleTranslationsError	If the title has one or more chapters with more than one translation that branch_id/translation_index didn't resolve.
DownloadTitleInterruptedError	If fetching a chapter fails unrecoverably partway through the download — carries every chapter already fetched.

Source code in packages/core/src/libsocial/title.py

async def download_title(
    self,
    *,
    branch_id: int | None = None,
    translation_index: int | None = None,
    chapter_delay: float = 0.0,
    on_chapter: Callable[[int, int], None] | None = None,
    max_rate_limit_retries: int = DEFAULT_RATE_LIMIT_RETRIES,
) -> list[VolumeT]:
    """Download every chapter of the title, across all its volumes.

    Fetches the chapter list once, then every chapter's content, sequentially, in the
    API's own order — same pacing/retry/backoff as any other chapter fetch (see
    ``ApiClient``), plus ``chapter_delay`` on top if given.

    Resolving translations is checked for the whole title up front, not chapter by
    chapter: if any chapters have more than one translation, this fetches nothing and
    raises ``MultipleTitleTranslationsError`` listing *all* of them at once (unless
    ``branch_id`` or ``translation_index`` resolves every one of them), rather than
    failing partway through a long download on the first ambiguous chapter.

    A long title's sequential download can outlast ``ApiClient``'s own retry budget for
    429s (tuned for a single one-off request, not hundreds/thousands of sequential
    fetches — see docs/api-notes.md). On top of that, each chapter fetch that still comes
    back rate-limited is retried again here, up to ``max_rate_limit_retries`` times, with
    its own (coarser) backoff. If a chapter fetch still fails after that — from rate
    limiting or anything else — the chapters already downloaded are not discarded: they're
    attached to a raised ``DownloadTitleInterruptedError`` instead of being lost.

    Args:
        branch_id: Translation to use for every chapter that has more than one — same
            meaning as ``get_chapter(..., branch_id=...)``, applied title-wide. Chapters
            with only one translation are unaffected. Mutually exclusive with
            ``translation_index``.
        translation_index: Alternative to ``branch_id``: pick the translation at this
            position in each ambiguous chapter's ``branches`` list (``0`` for the first,
            and so on) — useful when ambiguous chapters don't share one ``branch_id``
            across the title. Mutually exclusive with ``branch_id``.
        chapter_delay: Extra delay, in seconds, after fetching each chapter, on top of
            ``ApiClient``'s own per-request pacing — to be gentler on the API during a
            large bulk download. Defaults to no extra delay.
        on_chapter: Called with ``(completed, total)`` after each chapter is fetched, if
            given — a programmatic progress hook for callers that aren't printing to a
            console (e.g. a web app polling/streaming download progress to a browser),
            who would otherwise have no way to observe anything before this whole
            ``await`` returns. Independent of ``verbosity``: both can be set at once,
            each drives its own output.
        max_rate_limit_retries: How many extra times to retry a single chapter fetch that
            comes back rate-limited, on top of ``ApiClient``'s own retries, before giving
            up on the whole download — see above. Each retry honors the API's
            ``Retry-After`` if it sent one, otherwise waits with its own capped
            exponential backoff. Set to ``0`` to disable this extra layer and let a
            persistent ``RateLimitError`` end the download immediately (still wrapped in
            ``DownloadTitleInterruptedError`` with whatever was already fetched).

    Raises:
        ValueError: If both ``branch_id`` and ``translation_index`` are given.
        MultipleTitleTranslationsError: If the title has one or more chapters with more
            than one translation that ``branch_id``/``translation_index`` didn't resolve.
        DownloadTitleInterruptedError: If fetching a chapter fails unrecoverably partway
            through the download — carries every chapter already fetched.
    """
    self._check_translation_selectors(branch_id, translation_index)
    raw_chapters = await self._get_chapters()
    planned, unresolved = self._plan_chapters(
        raw_chapters, branch_id=branch_id, translation_index=translation_index
    )
    if unresolved:
        raise MultipleTitleTranslationsError(
            self._slug_url,
            chapters=[
                AmbiguousChapter(
                    volume=item["volume"],
                    number=item["number"],
                    branches=[
                        ChapterBranch.model_validate(branch) for branch in item["branches"]
                    ],
                )
                for item in unresolved
            ],
        )

    chapters: list[ChapterT] = []
    total = len(planned)
    try:
        with self._reporter.progress(f"Downloading {self._slug_url}", total) as advance:
            for index, chapter in enumerate(planned):
                chapters.append(
                    await self._fetch_chapter_riding_out_rate_limits(
                        chapter.volume,
                        chapter.number,
                        chapter.branch_id,
                        max_rate_limit_retries=max_rate_limit_retries,
                    )
                )
                advance()
                if on_chapter is not None:
                    on_chapter(index + 1, total)
                if chapter_delay and index < total - 1:
                    await asyncio.sleep(chapter_delay)
    except LibSocialError as exc:
        raise DownloadTitleInterruptedError(
            self._slug_url,
            volumes=self._group_into_volumes(chapters),
            completed=len(chapters),
            total=total,
        ) from exc
    return self._group_into_volumes(chapters)

get_chapter async

get_chapter(
    volume: int,
    number: str,
    *,
    branch_id: int | None = None,
    refresh: bool = False,
) -> ChapterT

Fetch a single chapter, including its content.

When a chapter has more than one team's translation and branch_id isn't given, this raises MultipleTranslationsError rather than guessing — see get_translations() and docs/api-notes.md for why the API's own default (when branch_id is omitted) isn't relied on. Doing this check costs an extra request to fetch the chapter list, only when branch_id isn't already given.

Parameters:

Name	Type	Description	Default
volume	int	The chapter's volume number.	required
number	str	The chapter number, as returned by the API — may contain a decimal (e.g. "51.6").	required
branch_id	int | None	Which translation to fetch, as returned by get_translations(). Only required when the chapter has more than one.	None
refresh	bool	Bypass the disk cache and re-fetch from the API even if a cached response is on hand.	False

Raises:

Type	Description
MultipleTranslationsError	If the chapter has more than one translation and branch_id wasn't given.

Source code in packages/core/src/libsocial/title.py

async def get_chapter(
    self,
    volume: int,
    number: str,
    *,
    branch_id: int | None = None,
    refresh: bool = False,
) -> ChapterT:
    """Fetch a single chapter, including its content.

    When a chapter has more than one team's translation and ``branch_id`` isn't given,
    this raises ``MultipleTranslationsError`` rather than guessing — see
    ``get_translations()`` and docs/api-notes.md for why the API's own default (when
    ``branch_id`` is omitted) isn't relied on. Doing this check costs an extra request
    to fetch the chapter list, only when ``branch_id`` isn't already given.

    Args:
        volume: The chapter's volume number.
        number: The chapter number, as returned by the API — may contain a decimal
            (e.g. ``"51.6"``).
        branch_id: Which translation to fetch, as returned by ``get_translations()``.
            Only required when the chapter has more than one.
        refresh: Bypass the disk cache and re-fetch from the API even if a cached
            response is on hand.

    Raises:
        MultipleTranslationsError: If the chapter has more than one translation and
            ``branch_id`` wasn't given.
    """
    volume_str = str(volume)
    if branch_id is None:
        raw_chapters = await self._get_chapters(refresh=refresh)
        branch_id = self._resolve_branch_id(volume_str, number, raw_chapters)
    return await self._fetch_chapter(volume_str, number, branch_id, refresh=refresh)

get_chapters async

get_chapters(
    chapters: list[tuple[int, str]],
) -> list[ChapterT]

Fetch several chapters, including their content.

Fetches the chapter list once, shared across all requested chapters (also used to detect chapters with more than one translation — see get_chapter), then each chapter individually and sequentially, in the order given.

Parameters:

Name	Type	Description	Default
chapters	list[tuple[int, str]]	A list of (volume, number) pairs identifying each chapter.	required

Raises:

Type	Description
ChapterNotFoundError	If any requested chapter doesn't exist.
MultipleTranslationsError	If any requested chapter has more than one translation.

Source code in packages/core/src/libsocial/title.py

async def get_chapters(self, chapters: list[tuple[int, str]]) -> list[ChapterT]:
    """Fetch several chapters, including their content.

    Fetches the chapter list once, shared across all requested chapters (also used to
    detect chapters with more than one translation — see ``get_chapter``), then each
    chapter individually and sequentially, in the order given.

    Args:
        chapters: A list of ``(volume, number)`` pairs identifying each chapter.

    Raises:
        ChapterNotFoundError: If any requested chapter doesn't exist.
        MultipleTranslationsError: If any requested chapter has more than one
            translation.
    """
    raw_chapters = await self._get_chapters()
    result = []
    for volume, number in chapters:
        volume_str = str(volume)
        branch_id = self._resolve_branch_id(volume_str, number, raw_chapters)
        result.append(await self._fetch_chapter(volume_str, number, branch_id))
    return result

get_info async

get_info(*, refresh: bool = False) -> TitleT

Fetch title metadata: names, cover, summary, genres, tags, authors, teams.

Parameters:

Name	Type	Description	Default
refresh	bool	Bypass the disk cache and re-fetch from the API even if a cached response is on hand.	False

Source code in packages/core/src/libsocial/title.py

async def get_info(self, *, refresh: bool = False) -> TitleT:
    """Fetch title metadata: names, cover, summary, genres, tags, authors, teams.

    Args:
        refresh: Bypass the disk cache and re-fetch from the API even if a cached
            response is on hand.
    """
    data = await self._get_title(refresh=refresh)
    return self.title_model.model_validate(data)

get_table_of_contents async

get_table_of_contents(
    *, refresh: bool = False
) -> list[VolumeT]

Fetch the title's volumes and chapter names/numbers, without chapter content.

Parameters:

Name	Type	Description	Default
refresh	bool	Bypass the disk cache and re-fetch from the API even if a cached response is on hand — needed to pick up newly published chapters, since otherwise the cached chapter list would keep being reused.	False

Source code in packages/core/src/libsocial/title.py

async def get_table_of_contents(self, *, refresh: bool = False) -> list[VolumeT]:
    """Fetch the title's volumes and chapter names/numbers, without chapter content.

    Args:
        refresh: Bypass the disk cache and re-fetch from the API even if a cached
            response is on hand — needed to pick up newly published chapters, since
            otherwise the cached chapter list would keep being reused.
    """
    raw_chapters = await self._get_chapters(refresh=refresh)
    chapters = [self.chapter_model.model_validate(item) for item in raw_chapters]
    return self._group_into_volumes(chapters)

get_translations async

get_translations(
    volume: int, number: str
) -> list[ChapterBranch]

Fetch the available translations (branches) for a chapter.

Parameters:

Name	Type	Description	Default
volume	int	The chapter's volume number.	required
number	str	The chapter number.	required

Raises:

Type	Description
ChapterNotFoundError	If no chapter exists for this volume/number.

Source code in packages/core/src/libsocial/title.py

async def get_translations(self, volume: int, number: str) -> list[ChapterBranch]:
    """Fetch the available translations (branches) for a chapter.

    Args:
        volume: The chapter's volume number.
        number: The chapter number.

    Raises:
        ChapterNotFoundError: If no chapter exists for this volume/number.
    """
    volume_str = str(volume)
    raw_chapters = await self._get_chapters()
    item = _find_raw_chapter(raw_chapters, volume_str, number)
    if item is None:
        raise ChapterNotFoundError(self._slug_url, volume=volume_str, number=number)
    return [ChapterBranch.model_validate(branch) for branch in item.get("branches") or []]

get_volume async

get_volume(volume: int) -> VolumeT

Fetch a whole volume: all its chapters, each including content.

The API has no bulk "volume content" endpoint (see docs/api-notes.md), so this fetches the chapter list once to find which numbers belong to the volume, then fetches each of those chapters individually and sequentially.

Parameters:

Name	Type	Description	Default
volume	int	The volume number.	required

Raises:

Type	Description
VolumeNotFoundError	If the title has no chapters for this volume.
MultipleTranslationsError	If any of the volume's chapters has more than one translation.

Source code in packages/core/src/libsocial/title.py

async def get_volume(self, volume: int) -> VolumeT:
    """Fetch a whole volume: all its chapters, each including content.

    The API has no bulk "volume content" endpoint (see docs/api-notes.md), so this
    fetches the chapter list once to find which numbers belong to the volume, then
    fetches each of those chapters individually and sequentially.

    Args:
        volume: The volume number.

    Raises:
        VolumeNotFoundError: If the title has no chapters for this volume.
        MultipleTranslationsError: If any of the volume's chapters has more than one
            translation.
    """
    raw_chapters = await self._get_chapters()
    return await self._build_volume(volume, raw_chapters)

get_volumes async

get_volumes(volumes: list[int]) -> list[VolumeT]

Fetch several whole volumes, each including chapter content.

Fetches the chapter list once, shared across all requested volumes, then each chapter individually and sequentially — same approach as get_volume, applied to more than one volume without re-fetching the chapter list per volume.

Parameters:

Name	Type	Description	Default
volumes	list[int]	The volume numbers to fetch.	required

Raises:

Type	Description
VolumeNotFoundError	If the title has no chapters for one of the volumes.
MultipleTranslationsError	If any of the volumes' chapters has more than one translation.

Source code in packages/core/src/libsocial/title.py

async def get_volumes(self, volumes: list[int]) -> list[VolumeT]:
    """Fetch several whole volumes, each including chapter content.

    Fetches the chapter list once, shared across all requested volumes, then each
    chapter individually and sequentially — same approach as ``get_volume``, applied
    to more than one volume without re-fetching the chapter list per volume.

    Args:
        volumes: The volume numbers to fetch.

    Raises:
        VolumeNotFoundError: If the title has no chapters for one of the volumes.
        MultipleTranslationsError: If any of the volumes' chapters has more than one
            translation.
    """
    raw_chapters = await self._get_chapters()
    return [await self._build_volume(volume, raw_chapters) for volume in volumes]

libsocial.Catalog

Catalog(
    *,
    cache_dir: str | Path | None = None,
    cache_ttl: float | None = None,
    headers: Mapping[str, str] | None = None,
)

Bases: 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

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:

Name	Type	Description
site	Site	The site whose catalog is listed. Set by the subclass.
page_model	type[CatalogPage[TitleT]]	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	Path	cache_dir used when none is passed.

Initialize the catalog client.

Parameters:

Name	Type	Description	Default
cache_dir	str | Path | None	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.	None
cache_ttl	float | None	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.	None
headers	Mapping[str, str] | None	Extra HTTP headers merged over the SDK's defaults, same as TitleClient(headers=...) — see there.	None

Source code in packages/core/src/libsocial/catalog.py

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
    )

aclose async

aclose() -> None

Close the underlying HTTP client.

Source code in packages/core/src/libsocial/catalog.py

async def aclose(self) -> None:
    """Close the underlying HTTP client."""
    await self._client.aclose()

list_countries async

list_countries(*, 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.

Parameters:

Name	Type	Description	Default
refresh	bool	Bypass the disk cache and re-fetch from the API even if the country list was already cached.	False

Returns:

Type	Description
list[Country]	Every Country (id, name) that applies to site.

Source code in packages/core/src/libsocial/catalog.py

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)

list_genres async

list_genres(*, 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).

Parameters:

Name	Type	Description	Default
refresh	bool	Bypass the disk cache and re-fetch from the API even if the genre list was already cached.	False

Returns:

Type	Description
list[Genre]	Every Genre (id, name, adult flag) that applies to site.

Source code in packages/core/src/libsocial/catalog.py

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)

list_statuses async

list_statuses(*, 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.

Parameters:

Name	Type	Description	Default
refresh	bool	Bypass the disk cache and re-fetch from the API even if the status list was already cached.	False

Returns:

Type	Description
list[Label]	Every status (Label: id, label) that applies to site.

Source code in packages/core/src/libsocial/catalog.py

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)

list_titles async

list_titles(
    *,
    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.

Parameters:

Name	Type	Description	Default
page	int	1-based page number.	1
per_page	int	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.	30
query	str | None	Free-text search term, matched against name/rus_name/eng_name. None (the default) or an empty string lists without searching.	None
genres	list[int] | None	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.	None
tags	list[int] | None	Tag.ids (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.	None
statuses	list[int] | None	Title.status.ids 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().	None
countries	list[int] | None	Country.ids 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).	None
min_chapters	int | None	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.	None
max_chapters	int | None	Only titles with at most this many chapters (inclusive). None (the default) applies no upper bound.	None
sort	str	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.	DEFAULT_SORT
refresh	bool	Bypass the disk cache and re-fetch from the API even if this exact combination of parameters was already cached.	False

Returns:

Type	Description
CatalogPage[TitleT]	A page_model page: the matching titles plus whether a next page exists.

Raises:

Type	Description
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.

Source code in packages/core/src/libsocial/catalog.py

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)

libsocial.ApiClient

ApiClient(
    site: Site,
    *,
    base_url: str = API_BASE_URL,
    timeout: float = 15.0,
    transport: AsyncBaseTransport | None = None,
    headers: Mapping[str, str] | None = None,
    max_concurrency: int = 5,
    request_delay: float | None = None,
    max_retries: int = 3,
    retry_base_delay: float = 1.0,
    sleep: Callable[
        [float], Awaitable[None]
    ] = asyncio.sleep,
    pacer: Pacer | None = None,
)

Thin async wrapper around the undocumented api.cdnlibs.org JSON API, for one site.

The API is shared by the whole lib.social network; site scopes requests to one site (Site-Id header, site_id[] on catalog listings — see docs/api-notes.md).

Bounds concurrency with a semaphore, paces request starts with a small fixed delay, and retries 429/5xx responses with exponential backoff — see docs/api-notes.md for why a manual implementation was chosen over a dependency like tenacity for this. Pacing is shared, by default, with every other ApiClient in the process talking to the same host (see Pacer), so clients for different sites don't add up their request rates.

Every request carries browser-like Origin/Referer/User-Agent headers on top of the API-specific Site-Id/Accept: without a non-empty Referer, the DDoS-Guard edge in front of the API answers every request with an HTML 403 page (see docs/api-notes.md, section "WAF 403").

Attributes:

Name	Type	Description
headers_hint	str	Where AccessBlockedError's message suggests passing different headers. A site package's subclass names its own entry points here.

Initialize the client.

Parameters:

Name	Type	Description	Default
site	Site	Which site the requests are made for — its id scopes the API to it, its origin goes into the browser-like Origin/Referer headers.	required
base_url	str	API base URL.	API_BASE_URL
timeout	float	Per-request timeout, in seconds.	15.0
transport	AsyncBaseTransport | None	Custom httpx transport, e.g. a mock transport for tests.	None
headers	Mapping[str, str] | None	Extra headers merged over the defaults (browser-like Origin/ Referer/User-Agent plus the API's Site-Id/Accept); a key given here replaces the default one, matched case-insensitively. Meant for swapping in a different User-Agent if the site's edge protection changes its rules, without waiting for an SDK release. Overriding Site-Id or Accept is possible but breaks the API's contract (see docs/api-notes.md) — only do it knowingly.	None
max_concurrency	int	Maximum number of requests in flight at once.	5
request_delay	float | None	Minimum time, in seconds, between the start of one request and the next, even under max_concurrency — counted across every client sharing pacer. None (the default) uses DEFAULT_REQUEST_DELAY.	None
max_retries	int	How many times to retry a 429 or 5xx response before giving up and raising.	3
retry_base_delay	float	Base delay, in seconds, for exponential backoff between retries (doubled per attempt) — used unless a 429 response's Retry-After header says otherwise.	1.0
sleep	Callable[[float], Awaitable[None]]	Sleep function used for pacing and backoff. Overridable for tests.	sleep
pacer	Pacer | None	Pacer to space request starts with. None (the default) uses the process-wide one for base_url's host (shared_pacer()); pass a separate Pacer to opt out of sharing, or one with a fake clock in tests.	None

Source code in packages/core/src/libsocial/client.py

def __init__(
    self,
    site: Site,
    *,
    base_url: str = API_BASE_URL,
    timeout: float = 15.0,
    transport: httpx.AsyncBaseTransport | None = None,
    headers: Mapping[str, str] | None = None,
    max_concurrency: int = 5,
    request_delay: float | None = None,
    max_retries: int = 3,
    retry_base_delay: float = 1.0,
    sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
    pacer: Pacer | None = None,
) -> None:
    """Initialize the client.

    Args:
        site: Which site the requests are made for — its ``id`` scopes the API to it,
            its ``origin`` goes into the browser-like ``Origin``/``Referer`` headers.
        base_url: API base URL.
        timeout: Per-request timeout, in seconds.
        transport: Custom ``httpx`` transport, e.g. a mock transport for tests.
        headers: Extra headers merged over the defaults (browser-like ``Origin``/
            ``Referer``/``User-Agent`` plus the API's ``Site-Id``/``Accept``); a key
            given here replaces the default one, matched case-insensitively. Meant for
            swapping in a different ``User-Agent`` if the site's edge protection changes
            its rules, without waiting for an SDK release. Overriding ``Site-Id`` or
            ``Accept`` is possible but breaks the API's contract (see
            docs/api-notes.md) — only do it knowingly.
        max_concurrency: Maximum number of requests in flight at once.
        request_delay: Minimum time, in seconds, between the start of one request and
            the next, even under ``max_concurrency`` — counted across every client
            sharing ``pacer``. ``None`` (the default) uses ``DEFAULT_REQUEST_DELAY``.
        max_retries: How many times to retry a 429 or 5xx response before giving up and
            raising.
        retry_base_delay: Base delay, in seconds, for exponential backoff between
            retries (doubled per attempt) — used unless a 429 response's
            ``Retry-After`` header says otherwise.
        sleep: Sleep function used for pacing and backoff. Overridable for tests.
        pacer: Pacer to space request starts with. ``None`` (the default) uses the
            process-wide one for ``base_url``'s host (``shared_pacer()``); pass a
            separate ``Pacer`` to opt out of sharing, or one with a fake clock in tests.
    """
    self.site = site
    self._http = httpx.AsyncClient(
        base_url=base_url,
        timeout=timeout,
        transport=transport,
        headers={
            **browser_headers_for(site.origin),
            "Site-Id": str(site.id),
            "Accept": "application/json",
        },
    )
    if headers is not None:
        self._http.headers.update(headers)
    self._semaphore = asyncio.Semaphore(max_concurrency)
    self._request_delay = DEFAULT_REQUEST_DELAY if request_delay is None else request_delay
    self._max_retries = max_retries
    self._retry_base_delay = retry_base_delay
    self._sleep = sleep
    self._pacer = pacer if pacer is not None else shared_pacer(self._http.base_url.host)

aclose async

aclose() -> None

Close the underlying HTTP connection pool.

Source code in packages/core/src/libsocial/client.py

async def aclose(self) -> None:
    """Close the underlying HTTP connection pool."""
    await self._http.aclose()

get_chapter async

get_chapter(
    slug_url: str,
    *,
    number: str,
    volume: str,
    branch_id: int | None = None,
) -> dict[str, Any]

Fetch a single chapter's metadata and content.

Parameters:

Name	Type	Description	Default
slug_url	str	The title's {id}--{slug} identifier.	required
number	str	The chapter number, as returned by the API (may contain a decimal).	required
volume	str	The volume number.	required
branch_id	int | None	Which translation team's branch to fetch, for chapters with more than one. Defaults to whichever branch the API picks (see docs/api-notes.md — this is not simply the first branch listed).	None

Returns:

Type	Description
dict[str, Any]	The data object from the API response.

Source code in packages/core/src/libsocial/client.py

async def get_chapter(
    self,
    slug_url: str,
    *,
    number: str,
    volume: str,
    branch_id: int | None = None,
) -> dict[str, Any]:
    """Fetch a single chapter's metadata and content.

    Args:
        slug_url: The title's ``{id}--{slug}`` identifier.
        number: The chapter number, as returned by the API (may contain a decimal).
        volume: The volume number.
        branch_id: Which translation team's branch to fetch, for chapters with more
            than one. Defaults to whichever branch the API picks (see
            docs/api-notes.md — this is not simply the first branch listed).

    Returns:
        The ``data`` object from the API response.
    """
    params = {"number": number, "volume": volume}
    if branch_id is not None:
        params["branch_id"] = str(branch_id)
    response = await self._get(f"/manga/{slug_url}/chapter", params=params)
    self._raise_for_status(
        response, not_found=ChapterNotFoundError(slug_url, volume=volume, number=number)
    )
    data: dict[str, Any] = response.json()["data"]
    return data

get_chapters async

get_chapters(slug_url: str) -> list[dict[str, Any]]

Fetch the raw chapter list for slug_url (single request, no pagination).

Parameters:

Name	Type	Description	Default
slug_url	str	The title's {id}--{slug} identifier.	required

Returns:

Type	Description
list[dict[str, Any]]	The data array from the API response.

Source code in packages/core/src/libsocial/client.py

async def get_chapters(self, slug_url: str) -> list[dict[str, Any]]:
    """Fetch the raw chapter list for ``slug_url`` (single request, no pagination).

    Args:
        slug_url: The title's ``{id}--{slug}`` identifier.

    Returns:
        The ``data`` array from the API response.
    """
    response = await self._get(f"/manga/{slug_url}/chapters")
    self._raise_for_status(response, not_found=TitleNotFoundError(slug_url))
    data: list[dict[str, Any]] = response.json()["data"]
    return data

get_title async

get_title(
    slug_url: str, *, fields: list[str] | None = None
) -> dict[str, Any]

Fetch raw title metadata for slug_url.

Parameters:

Name	Type	Description	Default
slug_url	str	The title's {id}--{slug} identifier.	required
fields	list[str] | None	Extra fields[] values to request from the API.	None

Returns:

Type	Description
dict[str, Any]	The data object from the API response.

Source code in packages/core/src/libsocial/client.py

async def get_title(self, slug_url: str, *, fields: list[str] | None = None) -> dict[str, Any]:
    """Fetch raw title metadata for ``slug_url``.

    Args:
        slug_url: The title's ``{id}--{slug}`` identifier.
        fields: Extra ``fields[]`` values to request from the API.

    Returns:
        The ``data`` object from the API response.
    """
    params = httpx.QueryParams([("fields[]", field) for field in fields or []])
    response = await self._get(f"/manga/{slug_url}", params=params)
    self._raise_for_status(response, not_found=TitleNotFoundError(slug_url))
    data: dict[str, Any] = response.json()["data"]
    return data

list_countries async

list_countries() -> list[dict[str, Any]]

Fetch the raw country/type list shared across the whole lib.social network.

Same shape and caveats as list_genres: not site-scoped by any request parameter, returns every "type" known to the network at once, each tagged with the site ids it applies to via site_ids. Named list_countries/fields[]=types mismatch is deliberate — see Catalog.list_countries and docs/api-notes.md for why this reuses the API's own "type" concept rather than the unrelated fields[]=countries field.

Returns:

Type	Description
list[dict[str, Any]]	The raw data.types array from the API response, unfiltered by site.

Source code in packages/core/src/libsocial/client.py

async def list_countries(self) -> list[dict[str, Any]]:
    """Fetch the raw country/type list shared across the whole lib.social network.

    Same shape and caveats as ``list_genres``: not site-scoped by any request parameter,
    returns every "type" known to the network at once, each tagged with the site ids it
    applies to via ``site_ids``. Named ``list_countries``/``fields[]=types`` mismatch is
    deliberate — see ``Catalog.list_countries`` and docs/api-notes.md for why this reuses
    the API's own "type" concept rather than the unrelated ``fields[]=countries`` field.

    Returns:
        The raw ``data.types`` array from the API response, unfiltered by site.
    """
    response = await self._get("/constants", params=httpx.QueryParams([("fields[]", "types")]))
    self._raise_for_status(response, not_found=LibSocialError("Unexpected 404 from type list"))
    data: list[dict[str, Any]] = response.json()["data"]["types"]
    return data

list_genres async

list_genres() -> list[dict[str, Any]]

Fetch the raw genre list shared across the whole lib.social network.

Unlike list_titles, this endpoint isn't site-scoped by any request parameter (confirmed: a Site-Id header changes nothing about the response) — it returns every genre known to the network at once, each tagged with the site ids it applies to via a site_ids field. Callers must filter to their site themselves (see Catalog.list_genres, which drops e.g. site-5-only genres like "Детское" when listing for ranobelib.me).

Returns:

Type	Description
list[dict[str, Any]]	The raw data.genres array from the API response, unfiltered by site.

Source code in packages/core/src/libsocial/client.py

async def list_genres(self) -> list[dict[str, Any]]:
    """Fetch the raw genre list shared across the whole lib.social network.

    Unlike ``list_titles``, this endpoint isn't site-scoped by any request parameter
    (confirmed: a ``Site-Id`` header changes nothing about the response) — it returns
    every genre known to the network at once, each tagged with the site ids it applies
    to via a ``site_ids`` field. Callers must filter to their site themselves (see
    ``Catalog.list_genres``, which drops e.g. site-5-only genres like "Детское" when
    listing for ranobelib.me).

    Returns:
        The raw ``data.genres`` array from the API response, unfiltered by site.
    """
    response = await self._get("/constants", params=httpx.QueryParams([("fields[]", "genres")]))
    self._raise_for_status(response, not_found=LibSocialError("Unexpected 404 from genre list"))
    data: list[dict[str, Any]] = response.json()["data"]["genres"]
    return data

list_statuses async

list_statuses() -> list[dict[str, Any]]

Fetch the raw title status list shared across the whole lib.social network.

Same shape and caveats as list_genres: not site-scoped by any request parameter, returns every status known to the network at once, each tagged with the site ids it applies to via site_ids.

Returns:

Type	Description
list[dict[str, Any]]	The raw data.status array from the API response, unfiltered by site.

Source code in packages/core/src/libsocial/client.py

async def list_statuses(self) -> list[dict[str, Any]]:
    """Fetch the raw title status list shared across the whole lib.social network.

    Same shape and caveats as ``list_genres``: not site-scoped by any request parameter,
    returns every status known to the network at once, each tagged with the site ids it
    applies to via ``site_ids``.

    Returns:
        The raw ``data.status`` array from the API response, unfiltered by site.
    """
    response = await self._get("/constants", params=httpx.QueryParams([("fields[]", "status")]))
    self._raise_for_status(
        response, not_found=LibSocialError("Unexpected 404 from status list")
    )
    data: list[dict[str, Any]] = response.json()["data"]["status"]
    return data

list_titles async

list_titles(
    *,
    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,
) -> dict[str, Any]

Fetch one page of the catalog listing/search results.

Unlike the other ApiClient methods, this returns the whole response body, not just data — callers need meta.has_next_page too, and there's no total count to derive it from otherwise (see docs/api-notes.md).

Parameters:

Name	Type	Description	Default
page	int	1-based page number.	required
per_page	int	Page size. The API only accepts 10..60 (validated by the caller, see Catalog.list_titles); values outside that raise here via a 422.	required
query	str | None	Free-text search term, matched against name/rus_name/eng_name. None or empty omits the q parameter entirely.	required
genres	list[int] | None	Genre ids to filter by. A title must have all of them (AND, not OR — see docs/api-notes.md), not just any one.	required
tags	list[int] | None	Tag ids to filter by. Same AND semantics as genres — a title must have all of them, not just any one (see docs/api-notes.md).	required
statuses	list[int] | None	Title.status.ids to filter by. A title matches if its own status is any of these (OR, like countries — a title only has one status, see docs/api-notes.md). Sent on the wire as repeated status[] parameters.	required
countries	list[int] | None	Country.ids 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, confirmed against the live API, see docs/api-notes.md). Sent on the wire as repeated types[] parameters — the API's own name for this concept is "type", not "country" (see docs/api-notes.md).	required
min_chapters	int | None	Minimum chapter count, inclusive. Sent as chap_count_min.	required
max_chapters	int | None	Maximum chapter count, inclusive. Sent as chap_count_max.	required
sort	str	Forwarded as the API's sort_by parameter, not sort — the API silently ignores an actual sort parameter (see docs/api-notes.md); this mismatch between the SDK's public keyword and the wire parameter name is deliberate, not a typo.	required

Returns:

Type	Description
dict[str, Any]	The full JSON response: {"data": [...], "meta": {...}, "links": {...}}.

Source code in packages/core/src/libsocial/client.py

async def list_titles(
    self,
    *,
    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,
) -> dict[str, Any]:
    """Fetch one page of the catalog listing/search results.

    Unlike the other ``ApiClient`` methods, this returns the *whole* response body, not
    just ``data`` — callers need ``meta.has_next_page`` too, and there's no total count
    to derive it from otherwise (see docs/api-notes.md).

    Args:
        page: 1-based page number.
        per_page: Page size. The API only accepts ``10..60`` (validated by the caller,
            see ``Catalog.list_titles``); values outside that raise here via a 422.
        query: Free-text search term, matched against name/rus_name/eng_name. ``None``
            or empty omits the ``q`` parameter entirely.
        genres: Genre ids to filter by. A title must have *all* of them (AND, not OR —
            see docs/api-notes.md), not just any one.
        tags: Tag ids to filter by. Same AND semantics as ``genres`` — a title must have
            *all* of them, not just any one (see docs/api-notes.md).
        statuses: ``Title.status.id``s to filter by. A title matches if its own status
            is *any* of these (OR, like ``countries`` — a title only has one status, see
            docs/api-notes.md). Sent on the wire as repeated ``status[]`` parameters.
        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, confirmed against the live API, see docs/api-notes.md). Sent on the
            wire as repeated ``types[]`` parameters — the API's own name for this concept
            is "type", not "country" (see docs/api-notes.md).
        min_chapters: Minimum chapter count, inclusive. Sent as ``chap_count_min``.
        max_chapters: Maximum chapter count, inclusive. Sent as ``chap_count_max``.
        sort: Forwarded as the API's ``sort_by`` parameter, not ``sort`` — the API
            silently ignores an actual ``sort`` parameter (see docs/api-notes.md); this
            mismatch between the SDK's public keyword and the wire parameter name is
            deliberate, not a typo.

    Returns:
        The full JSON response: ``{"data": [...], "meta": {...}, "links": {...}}``.
    """
    params: list[tuple[str, str | int | float | bool | None]] = [
        ("site_id[]", str(self.site.id)),
        ("page", str(page)),
        ("limit", str(per_page)),
        ("sort_by", sort),
    ]
    if query:
        params.append(("q", query))
    for genre_id in genres or []:
        params.append(("genres[]", str(genre_id)))
    for tag_id in tags or []:
        params.append(("tags[]", str(tag_id)))
    for status_id in statuses or []:
        params.append(("status[]", str(status_id)))
    for country_id in countries or []:
        params.append(("types[]", str(country_id)))
    if min_chapters is not None:
        params.append(("chap_count_min", str(min_chapters)))
    if max_chapters is not None:
        params.append(("chap_count_max", str(max_chapters)))

    response = await self._get("/manga", params=httpx.QueryParams(params))
    self._raise_for_status(
        response,
        not_found=LibSocialError(f"Unexpected 404 from catalog listing (page={page})"),
    )
    result: dict[str, Any] = response.json()
    return result

libsocial.Pacer

Pacer(*, clock: Callable[[], float] = time.monotonic)

Spaces out request starts: each one at least its delay after the previous one.

Every ApiClient talking to the same host shares one Pacer by default (see shared_pacer()), so two clients for different sites in one process — say ranobelib and mangalib, both on api.cdnlibs.org — pace against each other instead of each sending at its own full rate and doubling the load on the API between them.

Works by reservation: a caller takes the next free start slot under a plain threading.Lock, held only for that bookkeeping and never across an await, then sleeps until the slot outside of it. So a single Pacer is safe to share across event loops and threads, which an asyncio.Lock (bound to the loop that first used it) is not.

Initialize the pacer.

Parameters:

Name	Type	Description	Default
clock	Callable[[], float]	Monotonic time source, in seconds. Overridable for tests.	monotonic

Source code in packages/core/src/libsocial/pacing.py

def __init__(self, *, clock: Callable[[], float] = time.monotonic) -> None:
    """Initialize the pacer.

    Args:
        clock: Monotonic time source, in seconds. Overridable for tests.
    """
    self._clock = clock
    self._lock = threading.Lock()
    self._next_at: float | None = None

wait async

wait(
    delay: float,
    *,
    sleep: Callable[[float], Awaitable[None]],
) -> None

Wait for this request's start slot, and reserve delay seconds after it.

Parameters:

Name	Type	Description	Default
delay	float	Minimum time, in seconds, before the next request (from any client sharing this pacer) may start after this one. Each caller passes its own, so clients with different delays can share a pacer.	required
sleep	Callable[[float], Awaitable[None]]	Sleep function to wait with — the calling client's, so tests that inject a fake one don't actually wait.	required

Source code in packages/core/src/libsocial/pacing.py

async def wait(self, delay: float, *, sleep: Callable[[float], Awaitable[None]]) -> None:
    """Wait for this request's start slot, and reserve ``delay`` seconds after it.

    Args:
        delay: Minimum time, in seconds, before the next request (from any client
            sharing this pacer) may start after this one. Each caller passes its own,
            so clients with different delays can share a pacer.
        sleep: Sleep function to wait with — the calling client's, so tests that
            inject a fake one don't actually wait.
    """
    with self._lock:
        now = self._clock()
        start = now if self._next_at is None else max(now, self._next_at)
        self._next_at = start + delay
    if start > now:
        await sleep(start - now)

libsocial.shared_pacer

shared_pacer(host: str) -> Pacer

The process-wide Pacer for host, created on first use.

Parameters:

Name	Type	Description	Default
host	str	The API host, e.g. "api.cdnlibs.org" — matched case-insensitively.	required

Source code in packages/core/src/libsocial/pacing.py

def shared_pacer(host: str) -> Pacer:
    """The process-wide ``Pacer`` for ``host``, created on first use.

    Args:
        host: The API host, e.g. ``"api.cdnlibs.org"`` — matched case-insensitively.
    """
    key = host.lower()
    with _shared_lock:
        pacer = _shared.get(key)
        if pacer is None:
            pacer = _shared[key] = Pacer()
        return pacer

libsocial.PlannedChapter

Bases: NamedTuple

A chapter a bulk operation will fetch, with the translation to fetch it in.

Attributes:

Name	Type	Description
volume	str	The chapter's volume number.
number	str	The chapter number.
branch_id	int | None	The branch to request, or None to let the API pick — only for chapters with a single translation, where there's nothing to pick between.

Models

libsocial.Title

Bases: BaseModel

Metadata for a single title.

chapter_count class-attribute instance-attribute

chapter_count: int | None = None

Number of uploaded chapters. Only TitleClient.get_info() fills it in: the catalog listing endpoint doesn't return it (see docs/api-notes.md), so it's None on Catalog.list_titles() items.

last_chapter_at class-attribute instance-attribute

last_chapter_at: datetime | None = Field(
    default=None, alias="last_item_at"
)

When the most recent chapter was published — the value the catalog's sort="last_chapter_at" orders by. Only TitleClient.get_info() fills it in: the catalog listing endpoint doesn't return it (see docs/api-notes.md), so it's None on Catalog.list_titles() items, and on a title with no chapters yet.

libsocial.Chapter

Bases: BaseModel

A chapter: volume, number, name and available translations — not its content.

index/item_number/branches_count/branches come from the chapter-list endpoint (see TitleClient.get_table_of_contents()) and are None/empty when a Chapter instead comes from fetching a single chapter, which has a different response shape (see docs/api-notes.md). What the chapter contains is site-specific: a site package subclasses this with its content fields and parsing.

libsocial.ChapterBranch

Bases: BaseModel

A single team's (or solo uploader's) translation of a chapter.

A chapter has more than one branch when several teams have translated it independently; see Chapter.branches_count.

libsocial.Volume

Bases: BaseModel, Generic[ChapterT]

A volume: its number and the chapters it contains, in title order.

Generic over the chapter model — a site package uses Volume[ItsChapter] (or a subclass of it) so its chapters keep their content fields.

libsocial.CatalogPage

Bases: BaseModel, Generic[TitleT]

One page of catalog listing/search results, as returned by Catalog.list_titles().

items reuses the title model as-is — a catalog list item has every field Title requires, the ones it doesn't send (genres, summary, chapter_count, last_chapter_at, ...) just come back at their defaults, same as any other partially-populated Title (see docs/api-notes.md).

Exceptions

libsocial.LibSocialError

Bases: Exception

Base class for all errors raised by libsocial-core and the site SDKs built on it.

libsocial.TitleNotFoundError

TitleNotFoundError(slug_url: str)

Bases: LibSocialError

Raised when a title cannot be found on the site.

Attributes:

Name	Type	Description
slug_url		The title's {id}--{slug} identifier that couldn't be found.

Source code in packages/core/src/libsocial/exceptions.py

def __init__(self, slug_url: str) -> None:
    self.slug_url = slug_url
    super().__init__(f"Title not found: {slug_url!r}")

libsocial.ChapterNotFoundError

ChapterNotFoundError(
    slug_url: str, *, volume: str, number: str
)

Bases: LibSocialError

Raised when a chapter cannot be found for a given volume/number.

Attributes:

Name	Type	Description
slug_url		The title's {id}--{slug} identifier.
volume		The volume number that was requested.
number		The chapter number that was requested.

Source code in packages/core/src/libsocial/exceptions.py

def __init__(self, slug_url: str, *, volume: str, number: str) -> None:
    self.slug_url = slug_url
    self.volume = volume
    self.number = number
    super().__init__(f"Chapter not found: {slug_url!r} volume={volume!r} number={number!r}")

libsocial.VolumeNotFoundError

VolumeNotFoundError(slug_url: str, *, volume: str)

Bases: LibSocialError

Raised when a title has no chapters for a given volume number.

Attributes:

Name	Type	Description
slug_url		The title's {id}--{slug} identifier.
volume		The volume number that was requested.

Source code in packages/core/src/libsocial/exceptions.py

def __init__(self, slug_url: str, *, volume: str) -> None:
    self.slug_url = slug_url
    self.volume = volume
    super().__init__(f"Volume not found: {slug_url!r} volume={volume!r}")

libsocial.MultipleTranslationsError

MultipleTranslationsError(
    slug_url: str,
    *,
    volume: str,
    number: str,
    branches: list[ChapterBranch],
)

Bases: LibSocialError

Raised when a chapter has more than one team's translation and none was selected.

The SDK does not guess a default: the API's own default when branch_id is omitted is not simply the first branch listed, and the actual rule it uses isn't documented (see docs/api-notes.md) — returning it silently would be unpredictable. Call TitleClient.get_translations() to list the available branches, then pass one's branch_id explicitly.

Attributes:

Name	Type	Description
slug_url		The title's {id}--{slug} identifier.
volume		The chapter's volume number.
number		The chapter number.
branches		The chapter's available translations, as returned by TitleClient.get_translations().

Source code in packages/core/src/libsocial/exceptions.py

def __init__(
    self, slug_url: str, *, volume: str, number: str, branches: list[ChapterBranch]
) -> None:
    self.slug_url = slug_url
    self.volume = volume
    self.number = number
    self.branches = branches
    options = ", ".join(
        f"branch_id={branch.branch_id} ({_describe_branch(branch)})" for branch in branches
    )
    super().__init__(
        f"Multiple translations for {slug_url!r} volume={volume!r} number={number!r}: "
        f"{options}. Pass branch_id to select one (see get_translations())."
    )

libsocial.MultipleTitleTranslationsError

MultipleTitleTranslationsError(
    slug_url: str, *, chapters: list[AmbiguousChapter]
)

Bases: LibSocialError

Raised by download_title() when one or more chapters have an unresolved translation.

Unlike MultipleTranslationsError (one chapter), this can list several: a title-wide bulk download checks every chapter up front rather than stopping at the first ambiguous one, so a caller doesn't have to fix one chapter, rerun, hit the next, and rerun again. Pass branch_id or translation_index to download_title() to resolve them, or fetch the listed chapters individually with get_chapter(..., branch_id=...).

Attributes:

Name	Type	Description
slug_url		The title's {id}--{slug} identifier.
chapters		The ambiguous chapters and their available translations.

Source code in packages/core/src/libsocial/exceptions.py

def __init__(self, slug_url: str, *, chapters: list[AmbiguousChapter]) -> None:
    self.slug_url = slug_url
    self.chapters = chapters
    lines = [
        f"  volume={chapter.volume!r} number={chapter.number!r}: "
        + ", ".join(
            f"branch_id={branch.branch_id} ({_describe_branch(branch)})"
            for branch in chapter.branches
        )
        for chapter in chapters
    ]
    super().__init__(
        f"{len(chapters)} chapter(s) in {slug_url!r} have more than one translation "
        "unresolved by the given branch_id/translation_index. Pass branch_id or "
        "translation_index to download_title() to select one for every chapter listed, "
        "or fetch them individually with get_chapter(..., branch_id=...):\n" + "\n".join(lines)
    )

libsocial.AuthRequiredError

AuthRequiredError(url: str)

Bases: LibSocialError

Raised when the requested content requires authorization (paid or early access).

Attributes:

Name	Type	Description
url		The request URL that returned 403.

Source code in packages/core/src/libsocial/exceptions.py

def __init__(self, url: str) -> None:
    self.url = url
    super().__init__(f"Authorization required to access: {url}")

libsocial.AccessBlockedError

AccessBlockedError(
    url: str, *, headers_hint: str = DEFAULT_HEADERS_HINT
)

Bases: LibSocialError

Raised when the site's edge protection rejects a request before it reaches the API.

Not an authorization problem, unlike AuthRequiredError: the DDoS-Guard edge in front of api.cdnlibs.org answers with an HTML 403 page (the API's own 403 is JSON) when it doesn't like the request — so far, a missing or empty Referer (see docs/api-notes.md, section "WAF 403"). The SDK already sends browser-like headers, so seeing this means either the edge changed its rules — check for an SDK update, or send what it now expects via headers= on the title client/Catalog (or ApiClient, if using it directly) — or the edge is blocking the network/IP itself, which no header fixes. Not retried: resending the same request gets the same answer.

Attributes:

Name	Type	Description
url		The request URL that returned 403.

Initialize the error.

Parameters:

Name	Type	Description	Default
url	str	The request URL that returned 403.	required
headers_hint	str	Where to pass different headers, as the message suggests it — a site package names its own entry points (see ApiClient.headers_hint).	DEFAULT_HEADERS_HINT

Source code in packages/core/src/libsocial/exceptions.py

def __init__(self, url: str, *, headers_hint: str = DEFAULT_HEADERS_HINT) -> None:
    """Initialize the error.

    Args:
        url: The request URL that returned 403.
        headers_hint: Where to pass different headers, as the message suggests it — a
            site package names its own entry points (see ``ApiClient.headers_hint``).
    """
    self.url = url
    super().__init__(
        f"Request blocked by the site's protection (not an authorization issue): {url}. "
        "The site may have changed which requests it accepts: check for an SDK update, "
        f"or send different headers via {headers_hint}. "
        "If the same URL doesn't open in a browser on this network "
        "either, the IP itself is blocked and no header change will help."
    )

libsocial.RateLimitError

RateLimitError(retry_after: float | None = None)

Bases: LibSocialError

Raised when the API responds with 429 Too Many Requests.

Attributes:

Name	Type	Description
retry_after		The response's Retry-After value, in seconds, if it sent one.

Source code in packages/core/src/libsocial/exceptions.py

def __init__(self, retry_after: float | None = None) -> None:
    self.retry_after = retry_after
    suffix = f" (retry after {retry_after}s)" if retry_after is not None else ""
    super().__init__(f"Rate limited by the API{suffix}")

libsocial.DownloadTitleInterruptedError

DownloadTitleInterruptedError(
    slug_url: str,
    *,
    volumes: Sequence[Volume[Any]],
    completed: int,
    total: int,
)

Bases: LibSocialError

Raised by download_title() when a chapter fetch fails unrecoverably partway through.

download_title() fetches hundreds-to-thousands of chapters sequentially for a long title, which can outlast even the extra, bulk-specific rate-limit retry budget described in download_title()'s max_rate_limit_retries — or hit some other unrecoverable error (e.g. AuthRequiredError on a chapter that turns out to need a paywall/auth token). Rather than letting that error propagate on its own and silently discard every chapter already fetched, it's wrapped in this exception instead, carrying what was already downloaded — so a caller can keep that partial result, or simply call download_title() again: the SDK's disk cache means already-fetched chapters aren't re-requested, so a retry resumes close to where this one stopped rather than restarting the whole title. See docs/api-notes.md's "Rate limiting и retry" section and issue #41.

Attributes:

Name	Type	Description
slug_url		The title's {id}--{slug} identifier.
volumes	list[Volume[Any]]	Chapters fetched before the failure, grouped into volumes the same way a successful download_title() call would return them.
completed		How many chapters were fetched before the failure.
total		How many chapters download_title() had planned to fetch in total.

Source code in packages/core/src/libsocial/exceptions.py

def __init__(
    self, slug_url: str, *, volumes: Sequence[Volume[Any]], completed: int, total: int
) -> None:
    self.slug_url = slug_url
    self.volumes: list[Volume[Any]] = list(volumes)
    self.completed = completed
    self.total = total
    super().__init__(
        f"download_title() for {slug_url!r} was interrupted after {completed}/{total} "
        "chapter(s) fetched — see __cause__ for why, .volumes for what was already fetched."
    )

Cache maintenance

libsocial.cache_stats

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.

Parameters:

Name	Type	Description	Default
cache_dir	str | Path	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).	DEFAULT_CACHE_DIR

Returns:

Type	Description
CacheStats	The number of entries and their total size in bytes. A missing directory is an empty
CacheStats	cache, CacheStats(entries=0, bytes=0), not an error.

Source code in packages/core/src/libsocial/cache.py

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()

libsocial.clear_cache

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.

Parameters:

Name	Type	Description	Default
cache_dir	str | Path	The cache directory — see cache_stats().	DEFAULT_CACHE_DIR
older_than	float | None	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.	None

Returns:

Type	Description
CacheStats	The number of entries removed and the bytes they took. A missing directory removes
CacheStats	nothing, CacheStats(entries=0, bytes=0), rather than raising.

Raises:

Type	Description
ValueError	If older_than is negative.

Source code in packages/core/src/libsocial/cache.py

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.CacheStats dataclass

CacheStats(entries: int, bytes: int)

How many cache entries there are (or were removed), and their total size on disk.