ebookerr-sdk 3.2.0__tar.gz → 3.4.0__tar.gz

{ebookerr_sdk-3.2.0 → ebookerr_sdk-3.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ebookerr-sdk
-Version: 3.2.0
+Version: 3.4.0
 Summary: The ebookerr plugin SDK: the plugin contract, the plugin host, a test kit, the pack tool and helper kits.
 Author: ArcCdr
 License-Expression: MIT
@@ -41,10 +41,10 @@ validation, library servers and text generation.
 ## Install
 
 ```bash
-pip install "ebookerr-sdk==3.2.*"
+pip install "ebookerr-sdk==3.4.*"
 ```
 
-The SDK's MAJOR.MINOR is the SPI version it speaks: `ebookerr-sdk` 3.2.x speaks SPI 3.2. It needs
+The SDK's MAJOR.MINOR is the SPI version it speaks: `ebookerr-sdk` 3.4.x speaks SPI 3.4. It needs
 Python 3.11 or later.
 
 ## Start a plugin
@@ -66,6 +66,8 @@ or `catalog`. The guide explains what to write next and how to install the zip i
 | 2.24 | 3.0 | 3.0.x |
 | 2.24.1 | 3.1 | 3.1.x |
 | 2.24.7 | 3.2 | 3.2.x |
+| 2.24.9 | 3.3 | 3.3.x |
+| 2.24.10 | 3.4 | 3.4.x |
 
 ebookerr loads a plugin when its `spi_version` has ebookerr's SPI MAJOR and a MINOR not above
 ebookerr's; otherwise it shows the plugin as incompatible and offers a compatible release.
@@ -93,6 +95,18 @@ ebookerr's; otherwise it shows the plugin as incompatible and offers a compatibl
 
 ## Release notes
 
+### 3.4.0
+
+SPI 3.4. The domain and EPUB kits gain the helpers ebookerr's own doors share; later sentences
+of this section name each one. A plugin written for SPI 3.3 needs no change.
+
+`ebookerr_sdk.epub.opf.UNTYPED_IDENTIFIER_SCHEMES` names the identifier schemes a package cannot carry as a book identifier (`url`, `uri`, `uuid`, `calibre`, `http`, `https`, `urn`); `PackageDocument.set_typed_identifiers` no longer writes them, so writing back what `typed_identifiers` read changes nothing. `PackageDocument.set_title` drops a changed title's stale sort key (`calibre:title_sort`, or an EPUB 3 `file-as` refinement), so a reader re-derives it. `ebookerr_sdk.domain.authors` is the one parser of a book's `author` text: `split_authors` and `join_authors` read and write the names joined by `AUTHOR_SEPARATOR` (`" & "`, an `&` with whitespace on both sides), `authors_key` compares two texts whatever the order and case, and `includes_authors` tells whether a book is by given people. `ebookerr_sdk.domain.adoption.author_set` and `score_pair`'s author signal compare the set of names, so co-authors listed in another order match. `ebookerr_sdk.domain.ids.normalise_site`, `ebookerr_sdk.domain.series_rules` (`names_itself`, `without_self_references`) and `ebookerr_sdk.domain.metadata`'s `normalise_token_list`, `IDENTIFIER_RE`, `parse_identifiers` and `format_identifiers` are the helpers ebookerr itself uses for those fields. `ebookerr_sdk.domain.epub_metadata.epub_book_fields` maps what an EPUB says to the library fields every door stores — every author, the publisher unless it only names the site, typed identifiers, series, categories and tags — so a book pulled from a link and the same file uploaded agree. `epub_publisher` (the publisher an EPUB names, unless it only names the site) and `title_or_file_stem` (the title, or the file's name without its extension when the title is blank, `Untitled` or `Unknown`) are the two rules it is built from.
+
+### 3.3.0
+
+SPI 3.3. The EPUB kit gains helpers for the EPUBs ebookerr writes; later sentences of this
+section name each one. A plugin written for SPI 3.2 needs no change. `build_epub` writes its package through `ebookerr_sdk.epub.builder`: the NCX `dtb:uid` is the OPF identifier and the package carries its creation date, so a built book validates without findings. `EpubDocument.set_title` writes a new title into the package and every table of contents (`NcxDocument.set_doc_title`, `NavDocument.set_doc_title`), so a retitled book's OPF and NCX agree. `retitle_built_epub` gives a `build_epub` output a new title in its package, tables of contents and title page; `convert_stage` and `download_convert_stage` use it, so a converted book's file carries the title the book gets. `ebookerr_sdk.epub.text_convert.is_chapter_heading` names the prose chapter-heading rule. `convert_stage` titles an uploaded document after its own title, else its file name unless the name is a placeholder such as `Document1` or `Untitled`, else a first line that is no chapter heading. `Book.front_matter` holds the text above a document's first heading; `build_epub` puts it on the title page, and `parse_text_to_book` fills it instead of making that text a chapter. `parse_text_to_book` keeps each line of a text that has no blank line at all as its own paragraph. `convert_stage` and `download_convert_stage` pass a `user_facing` conversion error's message through unchanged and answer "The file could not be converted." for any other failure, so no library message or path reaches a user. `EpubDocument.drm_protected()` tells a DRM-protected book (a `rights.xml`, or an `encryption.xml` using anything but font obfuscation) from one whose fonts are only obfuscated.
+
 ### 3.2.0
 
 SPI 3.2. A story can name the multi-part work it is one part of: `StoryPatch.work` and

{ebookerr_sdk-3.2.0 → ebookerr_sdk-3.4.0}/README.md

@@ -12,10 +12,10 @@ validation, library servers and text generation.
 ## Install
 
 ```bash
-pip install "ebookerr-sdk==3.2.*"
+pip install "ebookerr-sdk==3.4.*"
 ```
 
-The SDK's MAJOR.MINOR is the SPI version it speaks: `ebookerr-sdk` 3.2.x speaks SPI 3.2. It needs
+The SDK's MAJOR.MINOR is the SPI version it speaks: `ebookerr-sdk` 3.4.x speaks SPI 3.4. It needs
 Python 3.11 or later.
 
 ## Start a plugin
@@ -37,6 +37,8 @@ or `catalog`. The guide explains what to write next and how to install the zip i
 | 2.24 | 3.0 | 3.0.x |
 | 2.24.1 | 3.1 | 3.1.x |
 | 2.24.7 | 3.2 | 3.2.x |
+| 2.24.9 | 3.3 | 3.3.x |
+| 2.24.10 | 3.4 | 3.4.x |
 
 ebookerr loads a plugin when its `spi_version` has ebookerr's SPI MAJOR and a MINOR not above
 ebookerr's; otherwise it shows the plugin as incompatible and offers a compatible release.
@@ -64,6 +66,18 @@ ebookerr's; otherwise it shows the plugin as incompatible and offers a compatibl
 
 ## Release notes
 
+### 3.4.0
+
+SPI 3.4. The domain and EPUB kits gain the helpers ebookerr's own doors share; later sentences
+of this section name each one. A plugin written for SPI 3.3 needs no change.
+
+`ebookerr_sdk.epub.opf.UNTYPED_IDENTIFIER_SCHEMES` names the identifier schemes a package cannot carry as a book identifier (`url`, `uri`, `uuid`, `calibre`, `http`, `https`, `urn`); `PackageDocument.set_typed_identifiers` no longer writes them, so writing back what `typed_identifiers` read changes nothing. `PackageDocument.set_title` drops a changed title's stale sort key (`calibre:title_sort`, or an EPUB 3 `file-as` refinement), so a reader re-derives it. `ebookerr_sdk.domain.authors` is the one parser of a book's `author` text: `split_authors` and `join_authors` read and write the names joined by `AUTHOR_SEPARATOR` (`" & "`, an `&` with whitespace on both sides), `authors_key` compares two texts whatever the order and case, and `includes_authors` tells whether a book is by given people. `ebookerr_sdk.domain.adoption.author_set` and `score_pair`'s author signal compare the set of names, so co-authors listed in another order match. `ebookerr_sdk.domain.ids.normalise_site`, `ebookerr_sdk.domain.series_rules` (`names_itself`, `without_self_references`) and `ebookerr_sdk.domain.metadata`'s `normalise_token_list`, `IDENTIFIER_RE`, `parse_identifiers` and `format_identifiers` are the helpers ebookerr itself uses for those fields. `ebookerr_sdk.domain.epub_metadata.epub_book_fields` maps what an EPUB says to the library fields every door stores — every author, the publisher unless it only names the site, typed identifiers, series, categories and tags — so a book pulled from a link and the same file uploaded agree. `epub_publisher` (the publisher an EPUB names, unless it only names the site) and `title_or_file_stem` (the title, or the file's name without its extension when the title is blank, `Untitled` or `Unknown`) are the two rules it is built from.
+
+### 3.3.0
+
+SPI 3.3. The EPUB kit gains helpers for the EPUBs ebookerr writes; later sentences of this
+section name each one. A plugin written for SPI 3.2 needs no change. `build_epub` writes its package through `ebookerr_sdk.epub.builder`: the NCX `dtb:uid` is the OPF identifier and the package carries its creation date, so a built book validates without findings. `EpubDocument.set_title` writes a new title into the package and every table of contents (`NcxDocument.set_doc_title`, `NavDocument.set_doc_title`), so a retitled book's OPF and NCX agree. `retitle_built_epub` gives a `build_epub` output a new title in its package, tables of contents and title page; `convert_stage` and `download_convert_stage` use it, so a converted book's file carries the title the book gets. `ebookerr_sdk.epub.text_convert.is_chapter_heading` names the prose chapter-heading rule. `convert_stage` titles an uploaded document after its own title, else its file name unless the name is a placeholder such as `Document1` or `Untitled`, else a first line that is no chapter heading. `Book.front_matter` holds the text above a document's first heading; `build_epub` puts it on the title page, and `parse_text_to_book` fills it instead of making that text a chapter. `parse_text_to_book` keeps each line of a text that has no blank line at all as its own paragraph. `convert_stage` and `download_convert_stage` pass a `user_facing` conversion error's message through unchanged and answer "The file could not be converted." for any other failure, so no library message or path reaches a user. `EpubDocument.drm_protected()` tells a DRM-protected book (a `rights.xml`, or an `encryption.xml` using anything but font obfuscation) from one whose fonts are only obfuscated.
+
 ### 3.2.0
 
 SPI 3.2. A story can name the multi-part work it is one part of: `StoryPatch.work` and

{ebookerr_sdk-3.2.0 → ebookerr_sdk-3.4.0}/ebookerr_sdk/__init__.py

@@ -44,4 +44,4 @@ ruff D, pdoc, mutmut and the traceability gate all cover the SDK; it has its own
   ``pack/``, so a fetched index and a built one are validated by exactly the same rules.
 """
 
-__version__ = "3.2.0"
+__version__ = "3.4.0"

{ebookerr_sdk-3.2.0 → ebookerr_sdk-3.4.0}/ebookerr_sdk/domain/__init__.py

@@ -1,6 +1,6 @@
 """Pure domain helpers shared by the ebookerr core and its plugins.
 
-Includes: ids, dates, metadata text, chapter numbers and naming, adoption, story URLs
+Includes: ids, dates, metadata text, chapter numbers and naming, adoption, authors, story URLs
 and EPUB metadata (``PMG-D22``).
 
 **Contents**
@@ -13,6 +13,7 @@ election, text encoding, EPUB hashing.
 
 - ``adoption.py`` — Pure normalisation helpers for adoption heuristic (no I/O, no
   src.data/src.services).
+- ``authors.py`` — Several authors in one ``author`` text — the one parser (``LIB-D6``).
 - ``chapter_naming.py`` — Turn chapter labels into collision-free, human-readable
   filenames (``MR-RENAME-1``).
 - ``chapter_number.py`` — Split a chapter title into its book name and chapter number.
@@ -21,8 +22,11 @@ election, text encoding, EPUB hashing.
 - ``epub_hash.py`` — Canonical hex SHA-256 content hash of .epub files.
 - ``epub_metadata.py`` — What an EPUB says about its book — the OPF package metadata
   plus a labelled title page.
-- ``ids.py`` — Stable, deterministic book-id derivation from a story URL.
-- ``metadata.py`` — Field helpers for book text: sanitising human-readable values.
+- ``ids.py`` — Stable, deterministic book-id derivation from a story URL, and the site's
+  registrable-domain form.
+- ``metadata.py`` — Field helpers for book text: sanitising human-readable values, token lists and
+  typed identifiers.
+- ``series_rules.py`` — A book is never its own series or its own work (``LIB-D45``, ``LIB-D46``).
 - ``story_url.py`` — Pure derivations from a story URL alone — identity, display
   title, listing author.
 - ``survivor.py`` — Pick the representative of a set of books holding one story, by

{ebookerr_sdk-3.2.0 → ebookerr_sdk-3.4.0}/ebookerr_sdk/domain/adoption.py

@@ -6,6 +6,7 @@ Because these functions are pure (no database, no external dependencies),
 the adoption heuristic is fully unit-testable.
 
 It also provides ``same_series``/``same_work`` (the two halves of signal E5).
+``author_set`` compares several authors whatever their order.
 """
 
 from __future__ import annotations
@@ -16,6 +17,7 @@ import re
 from dataclasses import dataclass
 from urllib.parse import urlsplit
 
+from ebookerr_sdk.domain.authors import split_authors
 from ebookerr_sdk.domain.chapter_number import extract_chapter_info
 from ebookerr_sdk.domain.ids import normalise_url
 from ebookerr_sdk.domain.text_encoding import unicode_identity
@@ -35,6 +37,19 @@ def normalize_key(text: str | None) -> str:
     return unicode_identity(text or "").replace("_", "")
 
 
+def author_set(text: str | None) -> frozenset[str]:
+    """Each author's :func:`normalize_key`, whatever their order (``LIB-D6``).
+
+    Args:
+        text: A stored ``author`` value (names joined by ``" & "``).
+
+    Returns:
+        The non-empty keys of the names :func:`~ebookerr_sdk.domain.authors.split_authors`
+        reads; an empty set for a blank value.
+    """
+    return frozenset(key for key in map(normalize_key, split_authors(text)) if key)
+
+
 def url_slug_key(url: str | None) -> str:
     """The normalised last non-empty path segment of *url*.
 
@@ -260,8 +275,9 @@ def score_pair(orphan: AdoptionSide, target: AdoptionSide) -> Evidence:
     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) != ""
+    # 4. Author match: the same non-empty set of authors, in any order
+    orphan_authors = author_set(orphan.author)
+    author_match = bool(orphan_authors) and orphan_authors == author_set(target.author)
 
     # 5. Stem match: normalized stem must be non-empty and equal
     stem_match = orphan_stem == target_stem != ""

ebookerr_sdk-3.4.0/ebookerr_sdk/domain/authors.py

@@ -0,0 +1,83 @@
+"""Several authors in one ``author`` text — the one parser (``LIB-D6``).
+
+ebookerr stores a book's authors as one text, the names joined by ``" & "``. Every reader of that
+text goes through :func:`split_authors` and every writer through :func:`join_authors`, so the
+core and the plugins agree on what a name is. :func:`authors_key` is the order- and case-blind
+form identity comparisons use; :func:`includes_authors` answers "is this book by these people?".
+An ``&`` with whitespace on both sides separates two names; an ``&`` inside a name ("AT&T")
+does not.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+
+from ebookerr_sdk.domain.text_encoding import fold
+
+AUTHOR_SEPARATOR = " & "
+"""The text between two names in a stored ``author`` (``LIB-D6``)."""
+
+_SEPARATOR = re.compile(r"\s+&\s+")
+_SPACES = re.compile(r"\s+")
+
+
+def split_authors(text: str | None) -> list[str]:
+    """The names in *text*, in order: whitespace runs collapsed, a repeated name dropped.
+
+    Args:
+        text: A stored ``author`` value; ``None`` reads as blank.
+
+    Returns:
+        The names; a name repeated in another case keeps its first spelling; ``[]`` for blank.
+    """
+    names: list[str] = []
+    seen: set[str] = set()
+    # Split on an ampersand with whitespace on both sides only, so "AT&T" stays one name.
+    for part in _SEPARATOR.split((text or "").strip()):
+        name = _SPACES.sub(" ", part).strip()
+        key = fold(name)
+        # Keep the first spelling of each name; skip blanks and repeats.
+        if name and key not in seen:
+            seen.add(key)
+            names.append(name)
+    return names
+
+
+def join_authors(names: Iterable[str]) -> str:
+    """The stored ``author`` text for *names*, normalised as :func:`split_authors` reads it.
+
+    Args:
+        names: The names, in order; blank ones are skipped.
+
+    Returns:
+        The names joined by :data:`AUTHOR_SEPARATOR`; ``""`` when none remains.
+    """
+    # Round-trip through split_authors so the written text is exactly what it reads back as.
+    return AUTHOR_SEPARATOR.join(split_authors(AUTHOR_SEPARATOR.join(n for n in names if n)))
+
+
+def authors_key(text: str | None) -> str:
+    """The order- and case-blind form of *text*'s names, for identity comparisons.
+
+    Args:
+        text: A stored ``author`` value.
+
+    Returns:
+        The case-folded names, sorted and joined by :data:`AUTHOR_SEPARATOR`; ``""`` for blank.
+    """
+    return AUTHOR_SEPARATOR.join(sorted(fold(name) for name in split_authors(text)))
+
+
+def includes_authors(text: str | None, wanted: str | None) -> bool:
+    """Whether *text* names every author *wanted* names, in any order and case.
+
+    Args:
+        text: A book's stored ``author`` value.
+        wanted: One name, or several joined by :data:`AUTHOR_SEPARATOR`.
+
+    Returns:
+        ``True`` when every name of *wanted* is one of *text*'s; ``False`` when *wanted* is blank.
+    """
+    want = {fold(name) for name in split_authors(wanted)}
+    return bool(want) and want <= {fold(name) for name in split_authors(text)}

ebookerr_sdk-3.4.0/ebookerr_sdk/domain/epub_metadata.py

@@ -0,0 +1,263 @@
+"""What an EPUB says about its book — the OPF package metadata plus a labelled title page.
+
+:class:`EpubMetadata` is read by :meth:`ebookerr_sdk.epub.EpubDocument.read_metadata`:
+Dublin Core (title, creators, language, dates, publisher, subjects, typed identifiers), the
+series in either OPF form, the ``ebookerr:`` metas the core writes (``LIB-D9``), Calibre's
+custom columns (``LIB-D11``) and the title page's labelled fields (``LIB-D22``). The core
+and the plugins turn it into a book record through :func:`epub_book_fields`; this module is
+pure (no I/O).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from pathlib import PurePosixPath
+from typing import Any
+
+from ebookerr_sdk.domain.authors import join_authors
+from ebookerr_sdk.domain.dates import parse_datetime
+from ebookerr_sdk.domain.ids import normalise_site
+from ebookerr_sdk.domain.metadata import format_identifiers, normalise_token_list, sanitize
+from ebookerr_sdk.domain.series_rules import without_self_references
+
+_LANGUAGE_NAMES = {
+    "en": "English",
+    "fr": "French",
+    "de": "German",
+    "es": "Spanish",
+    "it": "Italian",
+    "nl": "Dutch",
+    "pt": "Portuguese",
+    "ru": "Russian",
+    "ja": "Japanese",
+    "zh": "Chinese",
+}
+
+_LANGUAGE_CODES = {name.lower(): code for code, name in _LANGUAGE_NAMES.items()}
+
+_NATIVE_LANGUAGE_NAMES: dict[str, str] = {
+    "english": "en",
+    "français": "fr",
+    "francais": "fr",
+    "deutsch": "de",
+    "español": "es",
+    "espanol": "es",
+    "italiano": "it",
+    "nederlands": "nl",
+    "português": "pt",
+    "portugues": "pt",
+    "русский": "ru",
+    "日本語": "ja",
+    "中文": "zh",
+}
+"""Languages by native name (with accent-free spellings), all lower-case."""
+
+_LANGUAGE_CODES.update(_NATIVE_LANGUAGE_NAMES)
+
+
+def language_name(code: str | None) -> str | None:
+    """Map OPF language code to English name.
+
+    None/"" -> None; case-insensitive; region stripped ("en-US" -> "en");
+    unknown codes returned as-is.
+    """
+    if not code:
+        return None
+    normalized = code.lower().split("-")[0]
+    return _LANGUAGE_NAMES.get(normalized, normalized)
+
+
+def language_code(name: str | None) -> str:
+    """Map a language display name — English or native — or a code to an OPF code (default 'en')."""
+    if not name:
+        return "en"
+    key = name.strip().lower()
+    return _LANGUAGE_CODES.get(key, key)
+
+
+@dataclass(frozen=True, slots=True)
+class EpubMetadata:
+    """What one EPUB says about its book (``content.opf`` + the title page + chapter count).
+
+    Attributes:
+        source_url: ``dc:source`` (or the URL-scheme ``dc:identifier``) — the source of
+            both ``book_id`` and ``story_id``.
+        title: ``dc:title``.
+        author: ``dc:creator``.
+        language: ``dc:language`` (raw OPF code, e.g. ``"en"``); pass through
+            :func:`language_name` for a display name.
+        date_published: The publication ``dc:date`` (EPUB2 ``opf:event="publication"``, else the
+            first date without an event).
+        date_updated: ``dc:date``, most recent.
+        publisher: ``dc:publisher``.
+        chapter_count: Content-chapter count already computed by the EPUB reader
+            (``navPoints`` minus the title page).
+        section_url: Title-page field (``title_page.xhtml``); ``None`` when the title
+            page is absent or unparseable.
+        author_url: Title-page field; same ``None`` fallback as ``section_url``.
+        description: Title-page field; same ``None`` fallback.
+        category: Title-page field; same ``None`` fallback.
+        tags: Title-page field; same ``None`` fallback.
+        status: Title-page field; same ``None`` fallback.
+        authors: Every ``dc:creator``, in order (``LIB-D6``); empty when none.
+        subjects: Every non-empty ``dc:subject``, stripped, in order.
+        series: The series name (EPUB3 collection or ``calibre:series``), or ``None``.
+        series_index: The book's number in the series, or ``None``.
+        identifiers: Typed ``(scheme, value)`` identifiers, scheme lower-case (``LIB-D6``).
+        ebookerr: The ``ebookerr:`` metas present, key → value (``EBOOKERR_META_KEYS``).
+        calibre_user_metadata: Calibre custom columns, ``"#label"`` → JSON object (``LIB-D11``).
+    """
+
+    source_url: str | None  # dc:source / dc:identifier[scheme=URL] -> book_id + story_url
+    title: str | None
+    author: str | None
+    language: str | None
+    date_published: str | None
+    date_updated: str | None
+    publisher: str | None
+    chapter_count: int
+    # Title-page fields (T3): None when title_page.xhtml is absent or unparseable.
+    section_url: str | None = None
+    author_url: str | None = None
+    description: str | None = None
+    category: str | None = None
+    tags: str | None = None
+    status: str | None = None
+    # Library fields (LIB-D6, D9, D11, D22)
+    authors: tuple[str, ...] = ()
+    subjects: tuple[str, ...] = ()
+    series: str | None = None
+    series_index: float | None = None
+    identifiers: tuple[tuple[str, str], ...] = ()
+    ebookerr: Mapping[str, str] = field(default_factory=dict)
+    calibre_user_metadata: Mapping[str, Mapping[str, Any]] = field(default_factory=dict)
+
+
+def epub_publisher(publisher: str | None, site: str | None) -> str | None:
+    """An EPUB's ``dc:publisher`` as a publisher; ``None`` when it only names the site (``LIB-D9``).
+
+    Some tools write the source site into ``dc:publisher``, and the core's own embed writes
+    the site there for a book with no publisher; neither is a publisher.
+
+    Args:
+        publisher: The ``dc:publisher`` text.
+        site: The book's site (a registrable domain), or ``None``.
+
+    Returns:
+        The sanitised publisher, or ``None``.
+    """
+    value = sanitize(publisher)
+    if not value or (site and normalise_site(value) == site):
+        return None
+    return value
+
+
+def _epub_tags(meta: EpubMetadata) -> str | None:
+    """The book's tags as an EPUB states them (``LIB-D9``).
+
+    A file ebookerr wrote carries ``ebookerr:`` metas and its tags in ``dc:subject``, with its
+    categories named by ``ebookerr:category`` (they are removed from the subjects). Any other
+    file's labelled title page is the more precise source; its subjects are the last resort.
+
+    Args:
+        meta: What the EPUB says.
+
+    Returns:
+        The tags as one comma-separated text, or ``None`` when there are none.
+    """
+    category = meta.ebookerr.get("category")
+    if category:
+        drop = {token.strip().casefold() for token in category.split(",") if token.strip()}
+        kept = [subject for subject in meta.subjects if subject.casefold() not in drop]
+        return normalise_token_list(kept) or None
+    if meta.ebookerr:
+        return normalise_token_list(list(meta.subjects)) or None
+    if meta.tags:
+        return meta.tags
+    return normalise_token_list(list(meta.subjects)) or None
+
+
+_PLACEHOLDER_TITLES: frozenset[str] = frozenset({"untitled", "unknown"})
+"""OPF titles that name no book; the file name stands in for them (``LIB-D22``)."""
+
+
+def title_or_file_stem(title: str | None, file_name: str | None) -> str | None:
+    """*title*, or the stem of *file_name* when *title* is a placeholder or blank (``LIB-D22``).
+
+    Args:
+        title: The sanitised OPF title.
+        file_name: The EPUB's file name as the door knows it (an upload's own name, the library
+            file's name, a download's name), or ``None``.
+
+    Returns:
+        *title* unless it is blank, ``Untitled`` or ``Unknown`` (any case); then the file
+        name's stem when there is one, else *title* unchanged.
+    """
+    if title and title.strip().casefold() not in _PLACEHOLDER_TITLES:
+        return title
+    stem = PurePosixPath(file_name).stem.strip() if file_name else ""
+    return stem or title
+
+
+def epub_book_fields(
+    meta: EpubMetadata, *, source_url: str | None, file_name: str | None = None
+) -> tuple[dict[str, Any], list[str]]:
+    """The library fields an EPUB states, as every door stores them (``LIB-D9``).
+
+    ``ebookerr:`` metas win over standard and Calibre metadata, which win over the labelled
+    title page. ``author`` joins every creator (``LIB-D6``); ``publisher`` is dropped when it only
+    names the site; ``tags`` follow :func:`_epub_tags`. Without *source_url* the book has no site
+    and no URL field; with it, ``site`` is its registrable domain and a work or series whose URL
+    names the book itself is dropped (``LIB-D46``). Strings are sanitised; URLs never are; dates
+    are timezone-aware UTC datetimes.
+
+    Args:
+        meta: What the EPUB says.
+        source_url: The book's story URL as the door knows it, or ``None``.
+        file_name: The EPUB's file name as the door knows it, or ``None``; a placeholder OPF
+            title (``Untitled``, ``Unknown`` or blank) takes its stem (:func:`title_or_file_stem`).
+
+    Returns:
+        ``(fields, dropped)``: book column → value (``None`` when the file states none) for
+        ``title``, ``author``, ``site``, ``publisher``, ``language`` (its display name,
+        :func:`language_name`), ``description``, ``category``, ``tags``,
+        ``status``, ``series``, ``series_index``, ``identifiers``, ``date_published``,
+        ``date_updated``, ``num_chapters``, ``section_url``, ``author_url``, ``series_url`` and
+        ``work_url``; and the URL fields dropped as self-references (``"work_url"``,
+        ``"series_url"``), for the door to log.
+    """
+    ebookerr = meta.ebookerr
+    site = normalise_site(source_url) if source_url else None
+    authors = join_authors(sanitize(name) or "" for name in meta.authors)
+    fields: dict[str, Any] = {
+        "title": title_or_file_stem(sanitize(meta.title), file_name),
+        "author": authors or sanitize(meta.author),
+        "site": site,
+        "publisher": epub_publisher(meta.publisher, site),
+        "language": language_name(meta.language),
+        "description": sanitize(meta.description),
+        "category": sanitize(ebookerr.get("category") or meta.category),
+        "tags": sanitize(_epub_tags(meta)),
+        "status": sanitize(ebookerr.get("status") or meta.status),
+        "series": sanitize(meta.series),
+        "series_index": meta.series_index,
+        "identifiers": format_identifiers(meta.identifiers),
+        "date_published": parse_datetime(meta.date_published),
+        "date_updated": parse_datetime(meta.date_updated),
+        "num_chapters": meta.chapter_count,
+        "section_url": None,
+        "author_url": None,
+        "series_url": None,
+        "work_url": None,
+    }
+    if not source_url:
+        return fields, []
+    fields["section_url"] = meta.section_url  # URL: never sanitised
+    fields["author_url"] = ebookerr.get("author_url") or meta.author_url
+    fields["series_url"] = ebookerr.get("series_url")
+    fields["work_url"] = ebookerr.get("work_url")
+    kept, dropped = without_self_references(
+        fields, story_url=source_url, work_url=fields["work_url"]
+    )
+    return kept, dropped

{ebookerr_sdk-3.2.0 → ebookerr_sdk-3.4.0}/ebookerr_sdk/domain/ids.py

@@ -50,6 +50,62 @@ def site_key(url: str | None) -> str:
     return host.removeprefix("www.")
 
 
+_MULTI_PART_SUFFIXES: frozenset[str] = frozenset(
+    {
+        "ac.uk",
+        "co.jp",
+        "co.in",
+        "co.kr",
+        "co.nz",
+        "co.uk",
+        "co.za",
+        "com.ar",
+        "com.au",
+        "com.br",
+        "com.cn",
+        "com.mx",
+        "com.tr",
+        "gov.uk",
+        "me.uk",
+        "net.au",
+        "org.au",
+        "org.uk",
+    }
+)
+
+
+def normalise_site(value: str | None) -> str | None:
+    """Return the registrable-domain form of ``value``.
+
+    Args:
+        value: A site label, hostname or URL as reported by a plugin, or ``None``.
+
+    Returns:
+        The lowercase registrable domain for a hostname-shaped value; the trimmed input
+        otherwise (``None``, blank, multi-word label, dotless label, IPv4 literal), with
+        its case preserved. Never raises.
+    """
+    if value is None or not value.strip():
+        return value
+    text = value.strip()
+    if "//" in text:
+        text = urlsplit(text).hostname or text
+    elif any(char.isspace() for char in text):
+        # A hand-written label such as "Example Site", not a hostname — leave it alone.
+        return text
+    text = text.split("/", 1)[0].split(":", 1)[0].rstrip(".")
+    if "." not in text:
+        # A bare label such as "examplesite"; its case is the user's, not ours to change.
+        return text
+    text = text.lower()
+    labels = text.split(".")
+    if all(label.isdigit() for label in labels):
+        return text
+    if len(labels) >= 3 and ".".join(labels[-2:]) in _MULTI_PART_SUFFIXES:
+        return ".".join(labels[-3:])
+    return ".".join(labels[-2:])
+
+
 def make_book_id(story_url: str | None, section_url: str | None = None) -> str:
     """Hash the normalised story URL (falling back to the section URL)."""
     source = story_url or section_url or ""