ranobelib-python-sdk 0.12.0__tar.gz → 0.13.0__tar.gz

{ranobelib_python_sdk-0.12.0 → ranobelib_python_sdk-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ranobelib-python-sdk
-Version: 0.12.0
+Version: 0.13.0
 Summary: Async Python SDK for ranobelib.me: title metadata, chapter/volume downloads, and export to epub/fb2/txt/pdf
 Keywords: ranobelib,ranobe,novel,webnovel,epub,fb2,sdk
 Author: LLIJIYAPNIK

{ranobelib_python_sdk-0.12.0 → ranobelib_python_sdk-0.13.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ranobelib-python-sdk"
-version = "0.12.0"
+version = "0.13.0"
 description = "Async Python SDK for ranobelib.me: title metadata, chapter/volume downloads, and export to epub/fb2/txt/pdf"
 readme = "README.md"
 license = "MIT"

{ranobelib_python_sdk-0.12.0 → ranobelib_python_sdk-0.13.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "ranobelib-python-sdk"
-version = "0.12.0"
+version = "0.13.0"
 description = "Async Python SDK for ranobelib.me: title metadata, chapter/volume downloads, and export to epub/fb2/txt/pdf"
 readme = "README.md"
 license = "MIT"

{ranobelib_python_sdk-0.12.0 → ranobelib_python_sdk-0.13.0}/src/ranobelib/__init__.py

@@ -1,5 +1,6 @@
 """Async Python SDK for ranobelib.me."""
 
+from ranobelib.cache import CacheStats, cache_stats, clear_cache
 from ranobelib.catalog import Catalog
 from ranobelib.exceptions import (
     AccessBlockedError,
@@ -14,6 +15,7 @@ from ranobelib.exceptions import (
     TitleNotFoundError,
     VolumeNotFoundError,
 )
+from ranobelib.images import chapter_image_urls, rewrite_image_urls
 from ranobelib.models import (
     CatalogPage,
     Chapter,
@@ -25,6 +27,7 @@ from ranobelib.models import (
     Title,
     Volume,
 )
+from ranobelib.paragraphs import chapter_paragraphs
 from ranobelib.sdk import RanobeLib
 from ranobelib.sizing import chapter_size, volume_size
 
@@ -32,6 +35,7 @@ __all__ = [
     "AccessBlockedError",
     "AmbiguousChapter",
     "AuthRequiredError",
+    "CacheStats",
     "Catalog",
     "CatalogPage",
     "Chapter",
@@ -51,6 +55,11 @@ __all__ = [
     "TitleNotFoundError",
     "Volume",
     "VolumeNotFoundError",
+    "cache_stats",
+    "chapter_image_urls",
+    "chapter_paragraphs",
     "chapter_size",
+    "clear_cache",
+    "rewrite_image_urls",
     "volume_size",
 ]

ranobelib_python_sdk-0.13.0/src/ranobelib/cache.py

@@ -0,0 +1,179 @@
+"""Disk cache for raw JSON API responses, keyed by request identity.
+
+Also the public cache-maintenance helpers, ``cache_stats()`` and ``clear_cache()`` — the
+on-disk layout is an SDK internal, so code outside the SDK 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(".ranobelib_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 an SDK 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 ``RanobeLib`` /
+            ``Catalog`` (default: theirs, ``.ranobelib_cache`` in the current directory).
+
+    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 an SDK 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)

{ranobelib_python_sdk-0.12.0 → ranobelib_python_sdk-0.13.0}/src/ranobelib/exporters/_illustrations.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 
 import asyncio
 import html
+from collections.abc import Callable
 from html.parser import HTMLParser
 from pathlib import Path
 from urllib.parse import urlsplit
@@ -62,7 +63,7 @@ def extract_image_urls(html_fragment: str) -> list[str]:
 
 
 class _ImageSrcRewriter(HTMLParser):
-    """Re-emits chapter-content HTML with ``<img src="...">`` URLs replaced per a mapping.
+    """Re-emits chapter-content HTML with each ``<img src="...">`` passed through a function.
 
     Rebuilds the markup tag-by-tag (rather than a targeted regex substitution) for the same
     reason the txt/fb2 exporters use ``HTMLParser`` over regex: HTML-string-format chapters
@@ -71,15 +72,13 @@ class _ImageSrcRewriter(HTMLParser):
     for epub, WeasyPrint's own HTML parser for pdf) are lenient enough not to need strict
     XHTML here.
 
-    An ``<img>`` whose URL isn't in ``url_to_local`` (download failed or was never
-    attempted) is dropped entirely rather than kept pointing at the original external URL —
-    a dangling absolute-URL reference isn't a self-contained embed, just a broken-looking
-    image in most consumers, so "not embedded" reads as "not present" instead.
+    ``replace`` gets each ``<img>``'s ``src`` (``""`` if it has none) and returns the new
+    value, or ``None`` to drop that ``<img>`` entirely.
     """
 
-    def __init__(self, url_to_local: dict[str, str]) -> None:
+    def __init__(self, replace: Callable[[str], str | None]) -> None:
         super().__init__(convert_charrefs=True)
-        self._url_to_local = url_to_local
+        self._replace = replace
         self._output: list[str] = []
 
     def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
@@ -90,10 +89,10 @@ class _ImageSrcRewriter(HTMLParser):
 
     def _emit(self, tag: str, attrs: list[tuple[str, str | None]], *, self_closing: bool) -> None:
         if tag == "img":
-            local_src = self._url_to_local.get(dict(attrs).get("src") or "")
-            if local_src is None:
+            new_src = self._replace(dict(attrs).get("src") or "")
+            if new_src is None:
                 return
-            attrs = [(name, local_src if name == "src" else value) for name, value in attrs]
+            attrs = [(name, new_src if name == "src" else value) for name, value in attrs]
 
         parts = [f"<{tag}"]
         for name, value in attrs:
@@ -115,13 +114,27 @@ class _ImageSrcRewriter(HTMLParser):
         return "".join(self._output)
 
 
-def rewrite_image_srcs(html_fragment: str, url_to_local: dict[str, str]) -> str:
-    """Rewrite ``<img src="...">`` URLs in ``html_fragment`` per ``url_to_local``."""
-    rewriter = _ImageSrcRewriter(url_to_local)
+def replace_image_srcs(html_fragment: str, replace: Callable[[str], str | None]) -> str:
+    """Pass every ``<img src="...">`` in ``html_fragment`` through ``replace``.
+
+    ``replace`` returns the new ``src``, or ``None`` to drop that ``<img>``.
+    """
+    rewriter = _ImageSrcRewriter(replace)
     rewriter.feed(html_fragment)
     return rewriter.get_html()
 
 
+def rewrite_image_srcs(html_fragment: str, url_to_local: dict[str, str]) -> str:
+    """Rewrite ``<img src="...">`` URLs in ``html_fragment`` per ``url_to_local``.
+
+    An ``<img>`` whose URL isn't in ``url_to_local`` (download failed or was never
+    attempted) is dropped entirely rather than kept pointing at the original external URL —
+    a dangling absolute-URL reference isn't a self-contained embed, just a broken-looking
+    image in most consumers, so "not embedded" reads as "not present" instead.
+    """
+    return replace_image_srcs(html_fragment, url_to_local.get)
+
+
 def pick_cover_url(cover: Cover) -> str | None:
     """The best available cover URL, preferring the largest: default, then md, then thumbnail."""
     return cover.default or cover.md or cover.thumbnail

ranobelib_python_sdk-0.13.0/src/ranobelib/images.py

@@ -0,0 +1,73 @@
+"""Listing and rewriting the images a fetched chapter references.
+
+Chapter illustrations are ``<img>`` tags with absolute URLs on ranobelib.me /
+``*.cdnlibs.org`` (see docs/api-notes.md), inside ``Chapter.content`` and, occasionally,
+``Chapter.footnotes``. These helpers expose the same ``<img>`` parsing the epub/pdf
+exporters and ``sizing.chapter_size()`` use internally, so a caller that serves chapters
+itself (e.g. through its own same-origin image proxy, for offline caching) doesn't need a
+second HTML parser of its own.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from ranobelib.exporters._illustrations import extract_image_urls, replace_image_srcs
+from ranobelib.models import Chapter, Footnote
+
+
+def _require_content(chapter: Chapter) -> str:
+    if chapter.content is None:
+        raise ValueError(
+            f"Chapter {chapter.volume}/{chapter.number} has no content — "
+            "fetch it first, e.g. via get_chapter()."
+        )
+    return chapter.content
+
+
+def chapter_image_urls(chapter: Chapter) -> list[str]:
+    """List the image URLs a fetched chapter references.
+
+    Args:
+        chapter: A chapter with content already fetched (e.g. via ``get_chapter()``).
+
+    Returns:
+        Every ``<img src>`` in ``chapter.content`` and then ``chapter.footnotes``, in
+        document order, each URL listed once (its first occurrence).
+
+    Raises:
+        ValueError: If ``chapter.content`` is ``None`` (not yet fetched — see ``Chapter``'s
+            docstring for when that happens).
+    """
+    fragments = [_require_content(chapter), *(footnote.content for footnote in chapter.footnotes)]
+    urls = (url for fragment in fragments for url in extract_image_urls(fragment))
+    return list(dict.fromkeys(urls))
+
+
+def rewrite_image_urls(chapter: Chapter, replace: Callable[[str], str]) -> Chapter:
+    """Return a copy of a fetched chapter with every ``<img src>`` passed through ``replace``.
+
+    Args:
+        chapter: A chapter with content already fetched (e.g. via ``get_chapter()``).
+        replace: Called with each image URL (once per ``<img>``, so possibly more than once
+            for the same URL); its result becomes the new ``src``, HTML-escaped as an
+            attribute value. An ``<img>`` without a ``src`` is left as it is.
+
+    Returns:
+        A new ``Chapter`` whose ``content`` and ``footnotes`` have their ``<img src>``
+        rewritten; every other field is unchanged, and ``chapter`` itself is not modified.
+
+    Raises:
+        ValueError: If ``chapter.content`` is ``None`` — see ``chapter_image_urls()``.
+    """
+    content = _require_content(chapter)
+
+    def rewrite(fragment: str) -> str:
+        return replace_image_srcs(fragment, lambda src: replace(src) if src else src)
+
+    return chapter.model_copy(
+        update={
+            "content": rewrite(content),
+            "footnotes": [Footnote(content=rewrite(f.content)) for f in chapter.footnotes],
+        }
+    )

{ranobelib_python_sdk-0.12.0 → ranobelib_python_sdk-0.13.0}/src/ranobelib/models.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import html
+import re
 from datetime import datetime
 from html.parser import HTMLParser
 from typing import Any
@@ -438,6 +439,28 @@ class Team(BaseModel):
     name: str
 
 
+_FORMAT_WORD = (
+    r"(?:(?:light|lite|web|лайт|веб|вэб)\s*-?\s*)?(?:novel(?:la|l|a)?|новелл?а)"
+    r"|web\s*-?\s*serial|ranobe|ранобэ|ln|wn|лн|quest|квест"
+)
+_FORMAT_SUFFIX = re.compile(
+    rf"[\s,:/]*(?:\(\s*(?:{_FORMAT_WORD})\s*\)|\[\s*(?:{_FORMAT_WORD})\s*\])\s*$",
+    re.IGNORECASE,
+)
+"""A publication-format marker at the end of a title name — ``(Новелла)``, ``(Novel)``,
+``(LN)``, ``[квест]``, ... — plus the separator (``,``/``:``/``/``) sometimes left before it.
+The word list comes from every name in the live catalog (see docs/api-notes.md, "Title
+names without the format suffix"); other bracketed tails (a year, ``(18+)``, ``(Фанфик)``,
+``[LitRPG]``, a franchise) tell titles apart, so they're not on it."""
+
+
+def _strip_format_suffix(name: str) -> str:
+    """``name`` without its trailing format marker(s) — they can stack: ``(LN) (Novel)``."""
+    while (match := _FORMAT_SUFFIX.search(name)) is not None:
+        name = name[: match.start()]
+    return name.strip()
+
+
 class Title(BaseModel):
     """Metadata for a single title (novel)."""
 
@@ -463,12 +486,35 @@ class Title(BaseModel):
     artists: list[Person] = Field(default_factory=list)
     teams: list[Team] = Field(default_factory=list)
     chapter_count: int | None = None
+    """Number of uploaded chapters. Only ``RanobeLib.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: 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 ``RanobeLib.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."""
 
+    @property
+    def base_names(self) -> list[str]:
+        """The title's names without the format suffix ranobelib.me appends to them.
+
+        ``rus_name``, ``eng_name``, ``name`` and ``other_names``, in that order, each with
+        trailing publication-format markers removed — ``"Старшая школа D×D (Новелла)"`` →
+        ``"Старшая школа D×D"``, likewise ``(Novel)``, ``(LN)``, ``(WN)``, ``(Light Novel)``,
+        ``(Ранобэ)``, ``[квест]``, ... (stacked ones too, ``(LN) (Novel)``). Other bracketed
+        tails — a year, ``(18+)``, ``(Фанфик)``, ``[LitRPG]``, a franchise name — distinguish
+        one title from another and are kept. Whitespace is trimmed; empty names and
+        duplicates (keeping the first) are dropped. Nothing else is normalized (case,
+        punctuation, ``×``): that's up to whatever compares the names.
+
+        The original fields are left as they are. On ``Catalog.list_titles()`` items
+        ``other_names`` is empty (the listing doesn't return it), so it contributes nothing.
+        """
+        names = [self.rus_name, self.eng_name, self.name, *self.other_names]
+        stripped = (_strip_format_suffix(name) for name in names if name)
+        return list(dict.fromkeys(name for name in stripped if name))
+
     @model_validator(mode="before")
     @classmethod
     def _flatten_chapter_count(cls, data: Any) -> Any:

ranobelib_python_sdk-0.13.0/src/ranobelib/paragraphs.py

@@ -0,0 +1,85 @@
+"""A fetched chapter's top-level blocks as plain text, indexed like the DOM.
+
+``Chapter.content`` is a flat, sanitized sequence of block-level elements (``<p>``,
+``<hr />``, ``<img>`` — see ``Chapter``), so a client rendering it as HTML sees one child
+element per block. ``chapter_paragraphs()`` gives each of those blocks' text at the same
+index, so e.g. a comment keyed by a paragraph's position in the reader's DOM
+(``content.children[i]``) can be shown next to that paragraph's text without a second HTML
+parser on the caller's side.
+"""
+
+from __future__ import annotations
+
+from html.parser import HTMLParser
+
+from ranobelib.models import Chapter
+
+_VOID_TAGS = frozenset({"br", "hr", "img"})
+
+
+class _TopLevelTextCollector(HTMLParser):
+    """Collects the text of each top-level element of an HTML fragment, in order.
+
+    Every start tag at depth 0 begins a new entry, void ones (``br``/``hr``/``img``)
+    included, since each is an element child in the DOM too. Text outside any element at the
+    top level isn't an entry (it's a text node, not an element child) and is ignored. A
+    ``<br />`` inside an entry separates words, like a space.
+    """
+
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self._depth = 0
+        self.entries: list[list[str]] = []
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        if self._depth == 0:
+            self.entries.append([])
+        if tag in _VOID_TAGS:
+            if self._depth > 0:
+                self.entries[-1].append(" ")
+        else:
+            self._depth += 1
+
+    def handle_startendtag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        self.handle_starttag(tag, attrs)
+        if tag not in _VOID_TAGS:
+            self.handle_endtag(tag)
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag not in _VOID_TAGS and self._depth > 0:
+            self._depth -= 1
+
+    def handle_data(self, data: str) -> None:
+        if self._depth > 0:
+            self.entries[-1].append(data)
+
+
+def chapter_paragraphs(chapter: Chapter) -> list[str]:
+    """A fetched chapter's top-level blocks as plain text, in document order.
+
+    Entry ``i`` is the text of the ``i``-th top-level element of ``chapter.content`` — the
+    same position a browser gives it among the rendered content's element children — so a
+    paragraph index counted in the DOM can be used to look it up directly.
+
+    Args:
+        chapter: A chapter with content already fetched (e.g. via ``get_chapter()``).
+
+    Returns:
+        One string per top-level element: its text with entities decoded and whitespace
+        collapsed to single spaces (``""`` for a block without text, such as ``<hr />`` or
+        an image-only paragraph). ``chapter.footnotes`` aren't included — they're not part
+        of ``content`` (see ``Chapter.footnotes``).
+
+    Raises:
+        ValueError: If ``chapter.content`` is ``None`` (not yet fetched — see ``Chapter``'s
+            docstring for when that happens).
+    """
+    if chapter.content is None:
+        raise ValueError(
+            f"Chapter {chapter.volume}/{chapter.number} has no content — "
+            "fetch it first, e.g. via get_chapter()."
+        )
+    collector = _TopLevelTextCollector()
+    collector.feed(chapter.content)
+    collector.close()
+    return [" ".join("".join(parts).split()) for parts in collector.entries]

ranobelib_python_sdk-0.12.0/src/ranobelib/cache.py

@@ -1,64 +0,0 @@
-"""Disk cache for raw JSON API responses, keyed by request identity."""
-
-from __future__ import annotations
-
-import hashlib
-import json
-import time
-from collections.abc import Callable
-from pathlib import Path
-from typing import Any
-
-DEFAULT_CACHE_DIR = Path(".ranobelib_cache")
-"""Default cache directory, relative to the current working directory."""
-
-
-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 _path_for(self, key: str) -> Path:
-        digest = hashlib.sha256(key.encode("utf-8")).hexdigest()
-        return self._dir / f"{digest}.json"