libsocial-core 1.0.0__tar.gz

libsocial_core-1.0.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: libsocial-core
+Version: 1.0.0
+Summary: Async core shared by the lib.social site SDKs: api.cdnlibs.org client, caching, titles, chapters and catalog
+Keywords: lib.social,ranobelib,mangalib,cdnlibs,sdk
+Author: LLIJIYAPNIK
+Author-email: LLIJIYAPNIK <kas4wot@yandex.ru>
+License-Expression: MIT
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Requires-Dist: rich>=15.0.0
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/LLIJIYAPNIK/ranobelib-python-sdk
+Project-URL: Repository, https://github.com/LLIJIYAPNIK/ranobelib-python-sdk
+Project-URL: Issues, https://github.com/LLIJIYAPNIK/ranobelib-python-sdk/issues
+Description-Content-Type: text/markdown
+
+# libsocial-core
+
+The site-independent core shared by the async Python SDKs for the lib.social sites
+(ranobelib.me, mangalib.me, ...). They all sit on one backend, `api.cdnlibs.org`, and differ
+mainly in the `Site-Id` they send and in what a chapter contains.
+
+This package is the shared part:
+
+- `ApiClient`: the `api.cdnlibs.org` client, scoped to a site by a `Site` (id + origin).
+  Bounded concurrency, retries with backoff on 429/5xx, and request pacing shared by every
+  client in the process that talks to the same host.
+- `TitleClient`: one title's metadata, table of contents, translations (branches), chapter
+  fetching and whole-title download, with a disk cache.
+- `Catalog`: catalog listing/search and the genre/country/status lists, filtered to the site.
+- Models (`Title`, `Chapter`, `ChapterBranch`, `Volume`, ...) and exceptions.
+
+It's meant to be used through a site package, which sets the site and its chapter model —
+most likely [`ranobelib-python-sdk`](https://pypi.org/project/ranobelib-python-sdk/), not
+directly.
+
+```python
+from libsocial import Site, TitleClient
+from libsocial.models import Chapter, Title, Volume
+
+
+class MyChapter(Chapter):
+    content: str | None = None
+
+
+class MyVolume(Volume[MyChapter]):
+    pass
+
+
+class MySite(TitleClient[Title, MyChapter, MyVolume]):
+    site = Site(id=3, origin="https://ranobelib.me")
+    title_model = Title
+    chapter_model = MyChapter
+    volume_model = MyVolume
+
+
+async with MySite("https://ranobelib.me/ru/book/6712--high-school-dxd-novel") as client:
+    info = await client.get_info()
+```
+
+Repository, documentation and the site packages:
+<https://github.com/LLIJIYAPNIK/ranobelib-python-sdk>.
+
+MIT licensed.

libsocial_core-1.0.0/README.md

@@ -0,0 +1,48 @@
+# libsocial-core
+
+The site-independent core shared by the async Python SDKs for the lib.social sites
+(ranobelib.me, mangalib.me, ...). They all sit on one backend, `api.cdnlibs.org`, and differ
+mainly in the `Site-Id` they send and in what a chapter contains.
+
+This package is the shared part:
+
+- `ApiClient`: the `api.cdnlibs.org` client, scoped to a site by a `Site` (id + origin).
+  Bounded concurrency, retries with backoff on 429/5xx, and request pacing shared by every
+  client in the process that talks to the same host.
+- `TitleClient`: one title's metadata, table of contents, translations (branches), chapter
+  fetching and whole-title download, with a disk cache.
+- `Catalog`: catalog listing/search and the genre/country/status lists, filtered to the site.
+- Models (`Title`, `Chapter`, `ChapterBranch`, `Volume`, ...) and exceptions.
+
+It's meant to be used through a site package, which sets the site and its chapter model —
+most likely [`ranobelib-python-sdk`](https://pypi.org/project/ranobelib-python-sdk/), not
+directly.
+
+```python
+from libsocial import Site, TitleClient
+from libsocial.models import Chapter, Title, Volume
+
+
+class MyChapter(Chapter):
+    content: str | None = None
+
+
+class MyVolume(Volume[MyChapter]):
+    pass
+
+
+class MySite(TitleClient[Title, MyChapter, MyVolume]):
+    site = Site(id=3, origin="https://ranobelib.me")
+    title_model = Title
+    chapter_model = MyChapter
+    volume_model = MyVolume
+
+
+async with MySite("https://ranobelib.me/ru/book/6712--high-school-dxd-novel") as client:
+    info = await client.get_info()
+```
+
+Repository, documentation and the site packages:
+<https://github.com/LLIJIYAPNIK/ranobelib-python-sdk>.
+
+MIT licensed.

libsocial_core-1.0.0/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "libsocial-core"
+version = "1.0.0"
+description = "Async core shared by the lib.social site SDKs: api.cdnlibs.org client, caching, titles, chapters and catalog"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+keywords = [
+    "lib.social",
+    "ranobelib",
+    "mangalib",
+    "cdnlibs",
+    "sdk",
+]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.7",
+    "rich>=15.0.0",
+]
+
+[[project.authors]]
+name = "LLIJIYAPNIK"
+email = "kas4wot@yandex.ru"
+
+[project.urls]
+Homepage = "https://github.com/LLIJIYAPNIK/ranobelib-python-sdk"
+Repository = "https://github.com/LLIJIYAPNIK/ranobelib-python-sdk"
+Issues = "https://github.com/LLIJIYAPNIK/ranobelib-python-sdk/issues"
+
+[build-system]
+requires = ["uv_build>=0.11.26,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "libsocial"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "pytest-cov>=5.0",
+]

libsocial_core-1.0.0/pyproject.toml.orig

@@ -0,0 +1,48 @@
+[project]
+name = "libsocial-core"
+version = "1.0.0"
+description = "Async core shared by the lib.social site SDKs: api.cdnlibs.org client, caching, titles, chapters and catalog"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+    { name = "LLIJIYAPNIK", email = "kas4wot@yandex.ru" }
+]
+keywords = ["lib.social", "ranobelib", "mangalib", "cdnlibs", "sdk"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.7",
+    "rich>=15.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/LLIJIYAPNIK/ranobelib-python-sdk"
+Repository = "https://github.com/LLIJIYAPNIK/ranobelib-python-sdk"
+Issues = "https://github.com/LLIJIYAPNIK/ranobelib-python-sdk/issues"
+
+[build-system]
+requires = ["uv_build>=0.11.26,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "libsocial"
+
+# Test stack for this package only — see packages/ranobelib/pyproject.toml for why it isn't
+# in the workspace root's dev group.
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "pytest-cov>=5.0",
+]

libsocial_core-1.0.0/src/libsocial/__init__.py

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

libsocial_core-1.0.0/src/libsocial/_http.py

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

libsocial_core-1.0.0/src/libsocial/cache.py

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