ebookerr-sdk 2.30.0__tar.gz

ebookerr_sdk-2.30.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: ebookerr-sdk
+Version: 2.30.0
+Summary: The ebookerr plugin SDK: SPI types, wire codec, Python plugin host, EPUB library and shared helpers.
+Requires-Python: >=3.11
+Requires-Dist: defusedxml>=0.7
+Requires-Dist: tinycss2>=1.3
+Requires-Dist: requests>=2.31
+Requires-Dist: packaging>=24
+Provides-Extra: text
+Requires-Dist: charset-normalizer>=3.3; extra == "text"
+Provides-Extra: generation
+Requires-Dist: pillow>=10; extra == "generation"

ebookerr_sdk-2.30.0/README.md

@@ -0,0 +1,30 @@
+# ebookerr-sdk
+
+The plugin SDK for ebookerr: the plugin SPI (types and the manifest parser), the wire codec, the
+Python plugin host, the EPUB library and the shared helpers every ebookerr plugin uses.
+
+## Install
+
+    pip install ebookerr-sdk==2.30.0
+
+The SDK version is the SPI version plus `.0`: `ebookerr-sdk 2.30.0` speaks SPI `2.30`.
+
+## A plugin's entrypoint
+
+A Python plugin speaks the ebookerr wire protocol through the host; its `entrypoint.py` is three
+lines:
+
+    from ebookerr_sdk.host import run
+    from my_plugin.plugin import MyPlugin
+    run(MyPlugin())
+
+## Packaging and publishing
+
+`python -m ebookerr_sdk.pack` builds and checks a plugin folder's release `.zip`, and turns a
+`registry.toml` plus a folder of built packages into a registry's `index.json`/`README.md` — the
+same tool and the same index-format rules the default registry and the core installer both use.
+See the plugin author's guide's "Packaging & distribution" section for the full walkthrough:
+packaging a release, `CHANGELOG.txt`, and publishing your own registry.
+
+The plugin author's guide (manifest, settings, packaging, testing with `ebookerr_sdk.testing`):
+<https://github.com/ArcCdr/ebookerr-plugins>.

ebookerr_sdk-2.30.0/ebookerr_sdk/__init__.py

@@ -0,0 +1,9 @@
+"""The ebookerr plugin SDK: SPI types, wire codec, Python plugin host, EPUB library and helpers.
+
+The one shared-code home of the ebookerr core and every plugin (``PMG-D22``, ``PMG-D23``): the core
+depends on the exact release and a plugin process imports it from the same interpreter. The SDK
+imports nothing from the core package ``src`` (per ``tests/unit/test_sdk_boundary.py``). Its
+version is the SPI version plus ``.0``.
+"""
+
+__version__ = "2.30.0"

ebookerr_sdk-2.30.0/ebookerr_sdk/domain/__init__.py

@@ -0,0 +1,5 @@
+"""Pure domain helpers shared by the ebookerr core and its plugins.
+
+Includes: ids, dates, metadata text, chapter numbers and naming, adoption, story URLs
+and EPUB metadata (``PMG-D22``).
+"""

ebookerr_sdk-2.30.0/ebookerr_sdk/domain/adoption.py

@@ -0,0 +1,300 @@
+"""Pure normalisation helpers for adoption heuristic (no I/O, no src.data/src.services).
+
+This module provides pure functions for normalising chapter identifiers
+so they can be compared across different formatting conventions.
+Because these functions are pure (no database, no external dependencies),
+the adoption heuristic is fully unit-testable.
+"""
+
+from __future__ import annotations
+
+import itertools
+import json
+import re
+from dataclasses import dataclass
+from urllib.parse import urlsplit
+
+from ebookerr_sdk.domain.chapter_number import extract_chapter_info
+from ebookerr_sdk.domain.text_encoding import unicode_identity
+
+
+def normalize_key(text: str | None) -> str:
+    """Unicode letters and digits of every script, case- and accent-insensitive (``TXE-TR-1``).
+
+    Args:
+        text: The input string to normalize. None and empty strings are treated as empty.
+
+    Returns:
+        The normalized string: Unicode letters and digits across all scripts, casefolded and
+        deaccented, with all whitespace and punctuation removed.
+        Returns empty string for None, empty input, or all-punctuation input.
+    """
+    return unicode_identity(text or "").replace("_", "")
+
+
+def url_slug_key(url: str | None) -> str:
+    """The normalised last non-empty path segment of *url*.
+
+    Args:
+        url: A URL string or None.
+
+    Returns:
+        The normalized last path segment. Returns empty string for None, empty URL,
+        a URL with no path, or a path that is only slashes.
+    """
+    if not url:
+        return ""
+
+    parsed = urlsplit(url)
+    path = parsed.path.rstrip("/")
+
+    if not path:
+        return ""
+
+    # Extract last segment after the last /
+    last_segment = path.rsplit("/", 1)[-1]
+    return normalize_key(last_segment)
+
+
+def expand_number(raw: str) -> frozenset[int]:
+    """Every integer an F8 chapter-number token covers.
+
+    Parses a chapter number format supporting:
+    - Single numbers: "5" or "05" → {5}
+    - Number with letter suffix: "07a" → {7}
+    - Ranges: "023-025" → {23, 24, 25}
+    - Ranges with spaces: "023 - 025" → {23, 24, 25}
+
+    A range spanning more than 500 chapters is capped to endpoints only.
+    Descending ranges (end <= start) also return only endpoints.
+
+    Args:
+        raw: A chapter number token string to parse.
+
+    Returns:
+        A frozenset of all integers the token represents.
+        Returns empty frozenset if the input doesn't match the pattern.
+    """
+    match = re.match(r"^(\d+)(?:\s*-\s*(\d+))?", raw)
+
+    if not match:
+        return frozenset()
+
+    start = int(match.group(1))
+
+    # No second group: single number
+    if match.group(2) is None:
+        return frozenset({start})
+
+    # Second group present: it's a range
+    end = int(match.group(2))
+
+    # Guard: if span > 500 or descending, return only endpoints
+    if end <= start or end - start > 500:
+        return frozenset({start, end})
+
+    # Normal range: return all integers from start to end (inclusive)
+    return frozenset(range(start, end + 1))
+
+
+@dataclass(frozen=True, slots=True)
+class AdoptionSide:
+    """One side of a candidate adoption pair — everything scoring needs, already read.
+
+    Attributes:
+        book_id: The book's id.
+        title: The book title as stored, e.g. ``"Tending Bar Pt. 05"``.
+        author: The author as stored; ``""`` when unknown.
+        site: The site as stored; ``""`` when unknown.
+        series: The series as stored; ``""`` when unknown.
+        series_url: The series URL as stored; ``""`` when unknown.
+        story_url: The book's own story URL; ``""`` when unknown.
+        numbers: Raw F8 chapter-number tokens. For an orphan this holds exactly the one
+            number parsed from its title; for a target, every number in its EPUB table of
+            contents, in table order.
+    """
+
+    book_id: str
+    title: str
+    author: str
+    site: str
+    series: str
+    series_url: str
+    story_url: str
+    numbers: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class Evidence:
+    """The seven DEC-57 signals for one candidate pair, plus the values behind them."""
+
+    author_match: bool
+    stem_match: bool
+    numbers_disjoint: bool
+    same_site: bool
+    same_series: bool
+    url_affinity: bool
+    adjacent: bool
+    orphan_number: str
+    target_numbers: tuple[str, ...]
+    stem: str
+
+    @property
+    def score(self) -> int:
+        """The optional-signal score: E4 +1, E5 +2, E6 +2, E7 +1 (0..6)."""
+        return (
+            (1 if self.same_site else 0)
+            + (2 if self.same_series else 0)
+            + (2 if self.url_affinity else 0)
+            + (1 if self.adjacent else 0)
+        )
+
+    @property
+    def confidence(self) -> str:
+        """``"strong"`` | ``"probable"`` | ``"weak"``, or ``""`` when mandatory signals missing."""
+        if not (self.author_match and self.stem_match and self.numbers_disjoint):
+            return ""
+
+        if self.score >= 2:
+            return "strong"
+        if self.score == 1:
+            return "probable"
+        return "weak"
+
+
+def _common_prefix_len(a: str, b: str) -> int:
+    """Count the length of the common leading prefix of *a* and *b*."""
+    return sum(1 for _ in itertools.takewhile(lambda p: p[0] == p[1], zip(a, b, strict=False)))
+
+
+def score_pair(orphan: AdoptionSide, target: AdoptionSide) -> Evidence:
+    """Score one candidate adoption pair against the seven DEC-57 signals.
+
+    Args:
+        orphan: The orphan side of the pair (usually the newer, unmatched book).
+        target: The target side of the pair (usually an existing book to merge into).
+
+    Returns:
+        An Evidence object containing the seven scoring signals (E1–E7) plus
+        contextual metadata (orphan_number, target_numbers, stem).
+    """
+    # 1. Extract orphan_number (first number or empty string)
+    orphan_number = orphan.numbers[0] if orphan.numbers else ""
+
+    # 2. Expand all numbers to integers
+    orphan_ints: frozenset[int] = frozenset().union(*(expand_number(n) for n in orphan.numbers))
+    target_ints: frozenset[int] = frozenset().union(*(expand_number(n) for n in target.numbers))
+
+    # 3. Extract book stems (names without chapter numbers)
+    orphan_stem = normalize_key(extract_chapter_info(orphan.title).book_name)
+    target_stem = normalize_key(extract_chapter_info(target.title).book_name)
+
+    # 4. Author match: normalized author must be non-empty and equal
+    author_match = normalize_key(orphan.author) == normalize_key(target.author) != ""
+
+    # 5. Stem match: normalized stem must be non-empty and equal
+    stem_match = orphan_stem == target_stem != ""
+
+    # 6. Numbers disjoint: orphan has numbers AND no overlap with target
+    numbers_disjoint = bool(orphan_ints) and orphan_ints.isdisjoint(target_ints)
+
+    # 7. Same site: normalized site must be non-empty and equal
+    same_site = normalize_key(orphan.site) == normalize_key(target.site) != ""
+
+    # 8. Same series: either series match OR series_url match (both non-empty)
+    same_series = (normalize_key(orphan.series) == normalize_key(target.series) != "") or (
+        orphan.series_url == target.series_url != ""
+    )
+
+    # 9. URL affinity: common prefix of slug keys >= 8 characters
+    a = url_slug_key(orphan.story_url)
+    b = url_slug_key(target.story_url)
+    url_affinity = _common_prefix_len(a, b) >= 8
+
+    # 10. Adjacent: orphan and target numbers are consecutive (both non-empty)
+    adjacent = (
+        bool(orphan_ints)
+        and bool(target_ints)
+        and (min(orphan_ints) == max(target_ints) + 1 or max(orphan_ints) == min(target_ints) - 1)
+    )
+
+    # 11. Return Evidence with all fields
+    return Evidence(
+        author_match=author_match,
+        stem_match=stem_match,
+        numbers_disjoint=numbers_disjoint,
+        same_site=same_site,
+        same_series=same_series,
+        url_affinity=url_affinity,
+        adjacent=adjacent,
+        orphan_number=orphan_number,
+        target_numbers=tuple(target.numbers),
+        stem=orphan_stem,
+    )
+
+
+def evidence_json(evidence: Evidence) -> str:
+    """Serialise *evidence* to the stored JSON form (deterministic key order).
+
+    Args:
+        evidence: The Evidence object to serialize.
+
+    Returns:
+        A JSON string with keys in sorted order, containing the seven signals
+        (E1–E7) and contextual metadata (orphan_number, target_numbers, stem).
+    """
+    data = {
+        "E1": evidence.author_match,
+        "E2": evidence.stem_match,
+        "E3": evidence.numbers_disjoint,
+        "E4": evidence.same_site,
+        "E5": evidence.same_series,
+        "E6": evidence.url_affinity,
+        "E7": evidence.adjacent,
+        "orphan_number": evidence.orphan_number,
+        "target_numbers": list(evidence.target_numbers),
+        "stem": evidence.stem,
+    }
+    return json.dumps(data, sort_keys=True)
+
+
+SIBLING_EVIDENCE_VERSION = 1
+"""Schema version of the sibling-set block inside ``merge_proposals.evidence``.
+
+Bump this when the block's keys change meaning, and update every reader in the same change
+(``EXP-156``/``EXP-157``).
+"""
+
+
+def sibling_evidence_json(
+    evidence: Evidence,
+    *,
+    survivor_book_id: str,
+    set_size: int,
+    story_key: str,
+) -> str:
+    """Serialise a sibling-set proposal's evidence: the seven signals plus the set's own facts.
+
+    The seven ``DEC-57`` signals keep their exact keys and meanings, so a reader written for an
+    adoption proposal reads a sibling proposal correctly. The set's own facts live under a
+    versioned ``sibling`` block, which a reader must check before trusting
+    (``EXP-156``/``EXP-157``).
+
+    Args:
+        evidence: The pair's seven signals, from :func:`score_pair`.
+        survivor_book_id: The ``book_id`` the whole set merges into.
+        set_size: How many books were in the sibling set, survivor included.
+        story_key: ``"<site>|<story_id>"`` when the set also shares an ambiguous story
+            identity, else ``""``. Recorded for the audit trail; never used to score.
+
+    Returns:
+        A JSON string with keys in sorted order.
+    """
+    data = json.loads(evidence_json(evidence))
+    data["sibling"] = {
+        "version": SIBLING_EVIDENCE_VERSION,
+        "survivor_book_id": survivor_book_id,
+        "set_size": set_size,
+        "story_key": story_key,
+    }
+    return json.dumps(data, sort_keys=True)

ebookerr_sdk-2.30.0/ebookerr_sdk/domain/chapter_naming.py

@@ -0,0 +1,225 @@
+"""Turn chapter labels into collision-free, human-readable filenames (``MR-RENAME-1``).
+
+The label→(book_name, chapter_number) split is delegated to
+:func:`ebookerr_sdk.domain.chapter_number.extract_chapter_info` so the two never drift.
+The module is pure (no I/O, no dependency on gateways).
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Collection, Sequence
+from dataclasses import dataclass
+
+from ebookerr_sdk.domain.chapter_number import extract_chapter_info
+from ebookerr_sdk.domain.text_encoding import unicode_identity
+
+# Non-alphanumeric run → single underscore (after lowercase).
+_NON_ALNUM_RE = re.compile(r"[^a-z0-9]+")
+
+# Extract leading integer and optional letter suffix from a chapter number.
+_NUMBER_RE = re.compile(r"^(\d+)([a-z])?")
+
+
+@dataclass(frozen=True, slots=True)
+class NamedChapter:
+    """One chapter's planned output identity.
+
+    Attributes:
+        label: The chapter label the name was derived from.
+        stem: The filename stem, no extension (also the manifest/nav id).
+        filename: ``stem`` + ``".xhtml"``.
+        number: The chapter's integer number, or ``None`` when the label carries none.
+    """
+
+    label: str
+    stem: str
+    filename: str
+    number: int | None
+
+
+def slugify(text: str, *, max_length: int = 80) -> str:
+    """Lowercase ``text``, replace every non-alphanumeric run with ``_``, trim, truncate.
+
+    Args:
+        text: The input string to slugify.
+        max_length: Maximum slug length (default 80). Trailing underscore is trimmed
+            after truncation to avoid ending on a separator.
+
+    Returns:
+        The slugified string: lowercase, alphanumeric-only (non-runs replaced by
+        single ``_``), with leading/trailing ``_`` stripped.
+        Returns empty string for empty input or all-nonalnum input.
+
+    Examples:
+        >>> slugify("Three Square Meals")
+        'three_square_meals'
+        >>> slugify("  A -- B!!  ")
+        'a_b'
+        >>> slugify("")
+        ''
+    """
+    # 1. Lowercase
+    lower = text.lower()
+    # 2. Replace non-alphanumeric runs with single underscore
+    slugged = _NON_ALNUM_RE.sub("_", lower)
+    # 3. Strip leading/trailing underscores
+    slugged = slugged.strip("_")
+    # 4. Truncate to max_length
+    if len(slugged) > max_length:
+        slugged = slugged[:max_length]
+    # 5. Strip trailing underscores (in case truncation ended on a separator)
+    slugged = slugged.rstrip("_")
+    return slugged
+
+
+def title_slug(text: str, *, max_length: int = 80) -> str:
+    """Slug a chapter title for its identity key, keeping every script (``TXE-D13``).
+
+    Built on :func:`ebookerr_sdk.domain.text_encoding.unicode_identity`: accents are removed and
+    case is folded, but Cyrillic, Greek, CJK and every other script keep their letters, so
+    distinct non-Latin titles get distinct keys instead of collapsing to an ASCII remnant
+    (``"Глава 1"`` → ``"глава_1"``, where :func:`slugify` gives ``"1"``). For an ASCII
+    title the result equals :func:`slugify`'s, which is why switching chapter keys to this
+    slug re-keyed no stored chapter. :func:`slugify` stays the filename slug.
+
+    Args:
+        text: The chapter title.
+        max_length: Maximum slug length (default 80); a trailing separator left by the
+            cut is trimmed.
+
+    Returns:
+        The slug, or ``""`` when the title has no letter or digit.
+    """
+    return unicode_identity(text)[:max_length].rstrip("_")
+
+
+def _compute_base_stem(
+    label: str, number: int | None, letter: str, book_name: str, width: int
+) -> str:
+    """Compute the base stem (before collision resolution) for a chapter.
+
+    Args:
+        label: The original chapter label.
+        number: The extracted chapter number, or None.
+        letter: The optional letter suffix (e.g. 'a', 'b') from the chapter number.
+        book_name: The extracted book name.
+        width: The zero-padding width for numbered chapters.
+
+    Returns:
+        The base stem, potentially starting with a digit (caller adds underscore).
+    """
+    if number is not None:
+        # Numbered: "chapter_NNN{letter}" + book slug if present
+        padded_num = f"chapter_{number:0{width}d}{letter}"
+        book_slug = slugify(book_name)
+        return f"{padded_num}_{book_slug}" if book_slug else padded_num
+    # Unnumbered: slug the full label, or "section" as fallback
+    return slugify(label) or "section"
+
+
+def _resolve_collision(base_stem: str, claimed: set[str]) -> str:
+    """Resolve collisions by appending letter/numeric suffixes.
+
+    Args:
+        base_stem: The desired stem.
+        claimed: The set of already-claimed stems.
+
+    Returns:
+        A collision-free stem derived from base_stem.
+    """
+    stem = base_stem
+    n = 1
+    while stem in claimed:
+        if n <= 25:
+            suffix = chr(ord("a") + n)
+            stem = f"{base_stem}_{suffix}"
+        else:
+            stem = f"{base_stem}_z{n}"
+        n += 1
+    return stem
+
+
+def plan_chapter_filenames(
+    labels: Sequence[str], *, reserved: Collection[str] = ()
+) -> list[NamedChapter]:
+    r"""Plan collision-free filename per label, in input order (``MR-RENAME-1``).
+
+    Algorithm (in two passes):
+
+    1. For each label, extract (book_name, chapter_number) via
+       :func:`ebookerr_sdk.domain.chapter_number.extract_chapter_info`.
+    2. From chapter_number, extract leading integer and optional letter suffix:
+       ``^(\d+)([a-z])?`` → (number: int, letter: str). If no match, number=None.
+    3. Calculate ``width = max(2, len(str(max(numbers))))`` across all numbered
+       labels; when no label is numbered, width is unused.
+    4. First pass: compute base stems and metadata for each label.
+    5. Second pass, seeded with ``reserved`` (stems already taken by something
+       outside this call): resolve collisions by appending ``_b``, ``_c``, ...,
+       ``_z``, then ``_z1``, ``_z2``, ... when 26 letters are exhausted.
+    6. XML NCName guard: if a stem starts with a digit, prefix it with ``_``.
+    7. Return list of :class:`NamedChapter` in input order.
+
+    Args:
+        labels: Chapter labels in order.
+        reserved: Stems already taken by something outside this call (a carried
+            resource, a generated page); a label whose stem collides with one is
+            suffixed exactly as a label-vs-label collision is.
+
+    Returns:
+        A list of :class:`NamedChapter`, one per input label, in the same order.
+        The stem + filename are collision-free and XML-safe (NCName).
+
+    Examples:
+        >>> plan_chapter_filenames(["Title Page", "Chapter 5"])
+        [NamedChapter(label='Title Page', stem='title_page',
+                      filename='title_page.xhtml', number=None),
+         NamedChapter(label='Chapter 5', stem='chapter_05',
+                      filename='chapter_05.xhtml', number=5)]
+    """
+    if not labels:
+        return []
+
+    # Pass 1: Prepare metadata for each label (number, letter, book_name).
+    prepared: list[tuple[str, int | None, str, str]] = []
+    numbers: list[int] = []
+
+    for label in labels:
+        info = extract_chapter_info(label)
+        chapter_number_str = info.chapter_number
+
+        # Extract leading integer and optional letter suffix from chapter_number.
+        number: int | None = None
+        letter = ""
+        if chapter_number_str:
+            match = _NUMBER_RE.match(chapter_number_str)
+            if match:
+                number = int(match.group(1))
+                letter = match.group(2) or ""
+                numbers.append(number)
+
+        prepared.append((label, number, letter, info.book_name))
+
+    # Calculate width for zero-padding numbered chapters.
+    width = 2
+    if numbers:
+        width = max(2, len(str(max(numbers))))
+
+    # Pass 2: Build stems and resolve collisions.
+    claimed: set[str] = set(reserved)
+    planned: list[NamedChapter] = []
+
+    for label, number, letter, book_name in prepared:
+        base_stem = _compute_base_stem(label, number, letter, book_name, width)
+
+        # XML NCName guard: if stem starts with digit, prefix with underscore.
+        if base_stem and base_stem[0].isdigit():
+            base_stem = "_" + base_stem
+
+        # Collision resolution.
+        stem = _resolve_collision(base_stem, claimed)
+        claimed.add(stem)
+        filename = f"{stem}.xhtml"
+        planned.append(NamedChapter(label, stem, filename, number))
+
+    return planned