novel-downloader 2.0.0__py3-none-any.whl → 2.0.2__py3-none-any.whl

novel_downloader/utils/crypto_utils/rc4.py

@@ -3,62 +3,52 @@
 novel_downloader.utils.crypto_utils.rc4
 ---------------------------------------
 
-RC4 stream cipher for simple text encryption and decryption.
+Minimal RC4 stream cipher implementation.
 """
 
-import base64
 
-
-def rc4_crypt(
-    key: str,
-    data: str,
-    *,
-    mode: str = "encrypt",
-    encoding: str = "utf-8",
-) -> str:
+def rc4_init(key: bytes) -> list[int]:
     """
-    Encrypt or decrypt data using RC4 and Base64.
-
-    :param key: RC4 key (will be encoded using the specified encoding).
-    :param data: Plain-text (for 'encrypt') or Base64 cipher-text (for 'decrypt').
-    :param mode: Operation mode, either 'encrypt' or 'decrypt'. Defaults to 'encrypt'.
-    :param encoding: Character encoding for key and returned string. Defaults 'utf-8'.
-
-    :return: Base64 cipher-text (for encryption) or decoded plain-text (for decryption).
-
-    :raises ValueError: If mode is not 'encrypt' or 'decrypt'.
+    Key-Scheduling Algorithm (KSA)
     """
+    S = list(range(256))
+    j = 0
+    klen = len(key)
+    for i in range(256):
+        j = (j + S[i] + key[i % klen]) & 0xFF
+        S[i], S[j] = S[j], S[i]
+    return S
 
-    def _rc4(key_bytes: bytes, data_bytes: bytes) -> bytes:
-        # Key-Scheduling Algorithm (KSA)
-        S = list(range(256))
-        j = 0
-        for i in range(256):
-            j = (j + S[i] + key_bytes[i % len(key_bytes)]) % 256
-            S[i], S[j] = S[j], S[i]
-
-        # Pseudo-Random Generation Algorithm (PRGA)
-        i = j = 0
-        out: list[int] = []
-        for char in data_bytes:
-            i = (i + 1) % 256
-            j = (j + S[i]) % 256
-            S[i], S[j] = S[j], S[i]
-            K = S[(S[i] + S[j]) % 256]
-            out.append(char ^ K)
-
-        return bytes(out)
 
-    key_bytes = key.encode(encoding)
-
-    if mode == "encrypt":
-        plain_bytes = data.encode(encoding)
-        cipher_bytes = _rc4(key_bytes, plain_bytes)
-        return base64.b64encode(cipher_bytes).decode(encoding)
+def rc4_stream(S_init: list[int], data: bytes) -> bytes:
+    """
+    Pseudo-Random Generation Algorithm (PRGA)
+    """
+    # make a copy of S since it mutates during PRGA
+    S = S_init.copy()
+    i = 0
+    j = 0
+    out = bytearray(len(data))
+    for idx, ch in enumerate(data):
+        i = (i + 1) & 0xFF
+        j = (j + S[i]) & 0xFF
+        S[i], S[j] = S[j], S[i]
+        K = S[(S[i] + S[j]) & 0xFF]
+        out[idx] = ch ^ K
+
+    return bytes(out)
+
+
+def rc4_cipher(key: bytes, data: bytes) -> bytes:
+    """
+    RC4 stream cipher.
 
-    if mode == "decrypt":
-        cipher_bytes = base64.b64decode(data)
-        plain_bytes = _rc4(key_bytes, cipher_bytes)
-        return plain_bytes.decode(encoding, errors="replace")
+    It performs the standard Key-Scheduling Algorithm (KSA) and
+    Pseudo-Random Generation Algorithm (PRGA) to produce the RC4 keystream.
 
-    raise ValueError("Mode must be 'encrypt' or 'decrypt'.")
+    :param key: RC4 key as bytes (must not be empty)
+    :param data: plaintext or ciphertext as bytes
+    :return: XORed bytes (encrypt/decrypt are identical)
+    """
+    S = rc4_init(key)
+    return rc4_stream(S, data)

novel_downloader/utils/epub/__init__.py

@@ -6,9 +6,8 @@ novel_downloader.utils.epub
 Top-level package for EPUB export utilities.
 
 Key components:
-
-- EpubBuilder : orchestrates metadata, manifest, spine, navigation, and resources
-- Chapter, Volume : represent and render content sections and volume intros
+  * EpubBuilder : orchestrates metadata, manifest, spine, navigation, and resources
+  * Chapter, Volume : represent and render content sections and volume intros
 
 Usage example:
 

novel_downloader/utils/epub/builder.py

@@ -4,14 +4,14 @@ novel_downloader.utils.epub.builder
 -----------------------------------
 
 Orchestrates the end-to-end EPUB build process by:
-- Managing metadata (title, author, description, language, etc.)
-- Collecting and deduplicating resources (chapters, images, stylesheets)
-- Registering everything in the OPF manifest and spine
-- Generating nav.xhtml, toc.ncx, content.opf, and the zipped .epub file
+  * Managing metadata (title, author, description, language, etc.)
+  * Collecting and deduplicating resources (chapters, images, stylesheets)
+  * Registering everything in the OPF manifest and spine
+  * Generating nav.xhtml, toc.ncx, content.opf, and the zipped .epub file
 
 Provides:
-- methods to add chapters, volumes, images, and styles
-- a clean `export()` entry point that writes the final EPUB archive
+  * methods to add chapters, volumes, images, and styles
+  * a clean `export()` entry point that writes the final EPUB archive
 """
 
 import zipfile

novel_downloader/utils/epub/constants.py

@@ -3,12 +3,7 @@
 novel_downloader.utils.epub.constants
 -------------------------------------
 
-EPUB-specific constants used by the builder, including:
-- Directory names for OEBPS structure
-- XML namespace URIs
-- Package attributes and document-type declarations
-- Media type mappings for images
-- Template strings for container.xml and cover image HTML
+EPUB-specific constants used by the builder.
 """
 
 ROOT_PATH = "OEBPS"

novel_downloader/utils/epub/documents.py

@@ -4,9 +4,9 @@ novel_downloader.utils.epub.documents
 -------------------------------------
 
 Defines the classes that render EPUB navigation and packaging documents:
-- NavDocument: builds the XHTML nav.xhtml (EPUB 3)
-- NCXDocument: builds the NCX XML navigation map (EPUB 2)
-- OpfDocument: builds the content.opf package document
+  * NavDocument: builds the XHTML nav.xhtml (EPUB 3)
+  * NCXDocument: builds the NCX XML navigation map (EPUB 2)
+  * OpfDocument: builds the content.opf package document
 """
 
 from collections.abc import Sequence
@@ -234,10 +234,10 @@ class OpfDocument(EpubResource):
         Generate the content.opf XML, which defines metadata, manifest, and spine.
 
         This function outputs a complete OPF package document that includes:
-        - <metadata>: title, author, language, identifiers, etc.
-        - <manifest>: all resource entries
-        - <spine>: the reading order of the content
-        - <guide>: optional references like cover page
+          * <metadata>: title, author, language, identifiers, etc.
+          * <manifest>: all resource entries
+          * <spine>: the reading order of the content
+          * <guide>: optional references like cover page
 
         :return: A string containing the full OPF XML content.
         """

novel_downloader/utils/epub/models.py

@@ -4,14 +4,14 @@ novel_downloader.utils.epub.models
 ----------------------------------
 
 Defines the core EPUB data models and resource classes used by the builder:
-- Typed entries for table of contents (ChapterEntry, VolumeEntry)
-- Manifest and spine record types (ManifestEntry, SpineEntry)
-- Hierarchical NavPoint for NCX navigation
-- Base resource class (EpubResource) and specializations:
-    - StyleSheet
-    - ImageResource
-    - Chapter (with XHTML serialization)
-- Volume container for grouping chapters with optional intro and cover
+  * Typed entries for table of contents (ChapterEntry, VolumeEntry)
+  * Manifest and spine record types (ManifestEntry, SpineEntry)
+  * Hierarchical NavPoint for NCX navigation
+  * Base resource class (EpubResource) and specializations:
+    * StyleSheet
+    * ImageResource
+    * Chapter (with XHTML serialization)
+  * Volume container for grouping chapters with optional intro and cover
 """
 
 from __future__ import annotations

novel_downloader/utils/epub/utils.py

@@ -4,9 +4,9 @@ novel_downloader.utils.epub.utils
 ---------------------------------
 
 Pure utility functions for EPUB assembly, including:
-- Computing file hashes
-- Generating META-INF/container.xml
-- Constructing HTML snippets for the book intro and volume intro
+  * Computing file hashes
+  * Generating META-INF/container.xml
+  * Constructing HTML snippets for the book intro and volume intro
 """
 
 import hashlib
@@ -59,9 +59,9 @@ def build_book_intro(
     Build the HTML snippet for the overall book introduction.
 
     This includes:
-      - A main heading ("Book Introduction")
-      - A list of metadata items (title, author, categories, word count, status)
-      - A "Summary" subheading and one or more paragraphs of summary text
+      * A main heading ("Book Introduction")
+      * A list of metadata items (title, author, categories, word count, status)
+      * A "Summary" subheading and one or more paragraphs of summary text
 
     :return: A HTML string for inclusion in `intro.xhtml`
     """
@@ -112,10 +112,10 @@ def build_volume_intro(
     Build the HTML snippet for a single-volume introduction.
 
     This includes:
-      - A decorative border image (top and bottom)
-      - A primary heading (volume main title)
-      - An optional secondary line (subtitle)
-      - One or more paragraphs of intro text
+      * A decorative border image (top and bottom)
+      * A primary heading (volume main title)
+      * An optional secondary line (subtitle)
+      * One or more paragraphs of intro text
 
     :param volume_title: e.g. "Volume 1 - The Beginning"
     :param volume_intro_text: multiline intro text for this volume

novel_downloader/utils/file_utils/io.py

@@ -8,99 +8,74 @@ File I/O utilities for reading and writing data.
 
 __all__ = ["write_file"]
 
-import json
-import logging
 import tempfile
 from pathlib import Path
-from typing import Any, Literal
+from typing import Literal
 
 from .sanitize import sanitize_filename
 
-logger = logging.getLogger(__name__)
 
-_JSON_INDENT_THRESHOLD = 50 * 1024  # bytes
-
-
-def _get_non_conflicting_path(path: Path) -> Path:
+def _unique_path(path: Path, max_tries: int = 100) -> Path:
     """
-    If the path exists, generate a new one by appending _1, _2, etc.
+    Return a unique file path by appending _1, _2, ... if needed.
+
+    Falls back to a UUID suffix if all attempts fail.
     """
-    counter = 1
-    new_path = path
-    while new_path.exists():
-        stem = path.stem
-        suffix = path.suffix
-        new_path = path.with_name(f"{stem}_{counter}{suffix}")
-        counter += 1
-    return new_path
+    if not path.exists():
+        return path
+
+    stem = path.stem
+    suffix = path.suffix
+
+    for counter in range(1, max_tries + 1):
+        candidate = path.with_name(f"{stem}_{counter}{suffix}")
+        if not candidate.exists():
+            return candidate
+
+    # fallback: append a random/unique suffix
+    import uuid
+
+    return path.with_name(f"{stem}_{uuid.uuid4().hex}{suffix}")
 
 
 def write_file(
-    content: str | bytes | dict[Any, Any] | list[Any] | Any,
+    content: str | bytes,
     filepath: str | Path,
-    write_mode: str = "w",
     *,
     on_exist: Literal["overwrite", "skip", "rename"] = "overwrite",
-    dump_json: bool = False,
     encoding: str = "utf-8",
-) -> Path | None:
+) -> Path:
     """
-    Write content to a file safely with optional atomic behavior
-    and JSON serialization.
-
-    :param content: The content to write; can be text, bytes, or a
-        JSON-serializable object.
-    :param filepath: Destination path (str or Path).
-    :param mode: File mode ('w', 'wb'). Auto-determined if None.
-    :param on_exist: Behavior if file exists: 'overwrite', 'skip',
-        or 'rename'.
-    :param dump_json: If True, serialize content as JSON.
+    Write content to a file safely with atomic replacement.
+
+    :param content: The content to write; can be text or bytes.
+    :param filepath: Destination path.
+    :param on_exist: Behavior if file exists.
     :param encoding: Text encoding for writing.
-    :return: Path if writing succeeds, None otherwise.
+    :return: The final path where the content was written.
+    :raise: Any I/O error such as PermissionError or OSError
     """
     path = Path(filepath)
     path = path.with_name(sanitize_filename(path.name))
     path.parent.mkdir(parents=True, exist_ok=True)
 
     if path.exists():
-        if on_exist == "skip":
-            logger.debug("[file] '%s' exists, skipping", path)
-            return path
-        if on_exist == "rename":
-            path = _get_non_conflicting_path(path)
-            logger.debug("[file] Renaming target to avoid conflict: %s", path)
-        else:
-            logger.debug("[file] '%s' exists, will overwrite", path)
-
-    # Prepare content and write mode
-    content_to_write: str | bytes
-    if dump_json:
-        # Serialize original object to JSON string
-        json_str = json.dumps(content, ensure_ascii=False, indent=2)
-        if len(json_str.encode(encoding)) > _JSON_INDENT_THRESHOLD:
-            json_str = json.dumps(content, ensure_ascii=False, separators=(",", ":"))
-        content_to_write = json_str
-        write_mode = "w"
-    else:
-        if isinstance(content, (str | bytes)):
-            content_to_write = content
-        else:
-            raise TypeError("Non-JSON content must be str or bytes.")
-        write_mode = "wb" if isinstance(content, bytes) else "w"
-
-    try:
-        with tempfile.NamedTemporaryFile(
-            mode=write_mode,
-            encoding=None if "b" in write_mode else encoding,
-            newline=None if "b" in write_mode else "\n",
-            delete=False,
-            dir=path.parent,
-        ) as tmp:
-            tmp.write(content_to_write)
-            tmp_path = Path(tmp.name)
-        tmp_path.replace(path)
-        logger.debug("[file] '%s' written successfully", path)
-        return path
-    except Exception as exc:
-        logger.warning("[file] Error writing %r: %s", path, exc)
-        return None
+        match on_exist:
+            case "skip":
+                return path
+            case "rename":
+                path = _unique_path(path)
+
+    write_mode = "wb" if isinstance(content, bytes) else "w"
+
+    with tempfile.NamedTemporaryFile(
+        mode=write_mode,
+        encoding=None if "b" in write_mode else encoding,
+        newline=None if "b" in write_mode else "\n",
+        delete=False,
+        dir=path.parent,
+    ) as tmp:
+        tmp.write(content)
+        tmp_path = Path(tmp.name)
+    tmp_path.replace(path)
+    return path

novel_downloader/utils/file_utils/normalize.py

@@ -14,8 +14,6 @@ __all__ = ["normalize_txt_line_endings"]
 import logging
 from pathlib import Path
 
-logger = logging.getLogger(__name__)
-
 
 def normalize_txt_line_endings(folder_path: str | Path) -> None:
     """
@@ -28,7 +26,6 @@ def normalize_txt_line_endings(folder_path: str | Path) -> None:
     """
     path = Path(folder_path).resolve()
     if not path.exists() or not path.is_dir():
-        logger.warning("[file] Invalid folder: %s", path)
         return
 
     count_success, count_fail = 0, 0
@@ -38,13 +35,10 @@ def normalize_txt_line_endings(folder_path: str | Path) -> None:
             content = txt_file.read_text(encoding="utf-8")
             normalized = content.replace("\r\n", "\n").replace("\r", "\n")
             txt_file.write_text(normalized, encoding="utf-8", newline="\n")
-            logger.debug("[file] Normalized: %s", txt_file)
             count_success += 1
-        except (OSError, UnicodeDecodeError) as e:
-            logger.warning("[file] Failed: %s | %s", txt_file, e)
+        except (OSError, UnicodeDecodeError):
             count_fail += 1
 
-    logger.info("[file] Completed. Success: %s, Failed: %s", count_success, count_fail)
     return
 
 

novel_downloader/utils/file_utils/sanitize.py

@@ -9,13 +9,9 @@ on different operating systems.
 
 __all__ = ["sanitize_filename"]
 
-import logging
 import os
 import re
 
-logger = logging.getLogger(__name__)
-
-# Windows 保留名称列表 (忽略大小写)
 _WIN_RESERVED_NAMES = {
     "CON",
     "PRN",
@@ -36,8 +32,8 @@ def sanitize_filename(filename: str, max_length: int | None = 255) -> str:
 
     This function checks the operating system environment and applies the appropriate
     filtering rules:
-      - On Windows, it replaces characters: <>:"/\\|?*
-      - On POSIX systems, it replaces the forward slash '/'
+      * On Windows, it replaces characters: <>:"/\\|?*
+      * On POSIX systems, it replaces the forward slash '/'
 
     :param filename: The input filename to sanitize.
     :param max_length: Optional maximum length of the output filename. Defaults to 255.
@@ -47,7 +43,7 @@ def sanitize_filename(filename: str, max_length: int | None = 255) -> str:
 
     name = pattern.sub("_", filename).strip(" .")
 
-    stem, dot, ext = name.partition(".")
+    stem, dot, ext = name.rpartition(".")
     if os.name == "nt" and stem.upper() in _WIN_RESERVED_NAMES:
         stem = f"_{stem}"
     cleaned = f"{stem}{dot}{ext}" if ext else stem
@@ -59,7 +55,4 @@ def sanitize_filename(filename: str, max_length: int | None = 255) -> str:
         else:
             cleaned = cleaned[:max_length]
 
-    if not cleaned:
-        cleaned = "_untitled"
-    logger.debug("[file] Sanitized filename: %r -> %r", filename, cleaned)
-    return cleaned
+    return cleaned or "_untitled"

novel_downloader/utils/fontocr/__init__.py

@@ -0,0 +1,13 @@
+#!/usr/bin/env python3
+"""
+novel_downloader.utils.fontocr
+------------------------------
+
+Lazy-loading interface for FontOCR. Provides a safe entry point
+to obtain an OCR utility instance if optional dependencies are available.
+"""
+
+__all__ = ["get_font_ocr"]
+__version__ = "4.0"
+
+from .loader import get_font_ocr