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

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

novel_downloader/utils/{fontocr.py → fontocr/core.py}

@@ -1,28 +1,23 @@
 #!/usr/bin/env python3
 """
-novel_downloader.utils.fontocr
-------------------------------
+novel_downloader.utils.fontocr.core
+-----------------------------------
 
 This class provides utility methods for optical character recognition (OCR),
 primarily used for decrypting custom font encryption.
 """
 
-__all__ = [
-    "FontOCR",
-    "get_font_ocr",
-]
-__version__ = "4.0"
-
+import io
 import logging
-from collections.abc import Generator
-from typing import Any, TypeVar
+from pathlib import Path
+from typing import Any
 
 import numpy as np
-from paddleocr import TextRecognition  # takes 5 ~ 12 sec to init
+from fontTools.ttLib import TTFont
+from paddleocr import TextRecognition
 from PIL import Image, ImageDraw, ImageFont
 from PIL.Image import Transpose
 
-T = TypeVar("T")
 logger = logging.getLogger(__name__)
 
 
@@ -39,22 +34,20 @@ class FontOCR:
         device: str | None = None,
         precision: str = "fp32",
         cpu_threads: int = 10,
-        batch_size: int = 32,
-        threshold: float = 0.0,
         **kwargs: Any,
     ) -> None:
         """
         Initialize a FontOCR instance.
 
-        :param batch_size: batch size for OCR inference (minimum 1)
-        :param ocr_weight: weight factor for OCR-based prediction scores
-        :param vec_weight: weight factor for vector-based similarity scores
-        :param threshold: minimum confidence threshold for predictions [0.0-1.0]
+        :param model_name: If set to None, PP-OCRv5_server_rec is used.
+        :param model_dir: Model storage path.
+        :param input_shape: Input image size for the model in the format (C, H, W).
+        :param device: Device for inference.
+        :param precision: Precision for TensorRT.
+        :param cpu_threads: Number of threads to use for inference on CPUs.
         :param kwargs: reserved for future extensions
         """
-        self._batch_size = batch_size
-        self._threshold = threshold
-        self._ocr_model = TextRecognition(
+        self._ocr_model = TextRecognition(  # takes 5 ~ 12 sec to init
             model_name=model_name,
             model_dir=model_dir,
             input_shape=input_shape,
@@ -66,18 +59,18 @@ class FontOCR:
     def predict(
         self,
         images: list[np.ndarray],
-        top_k: int = 1,
-    ) -> list[list[tuple[str, float]]]:
+        batch_size: int = 1,
+    ) -> list[tuple[str, float]]:
         """
         Run OCR on input images.
 
         :param images: list of np.ndarray objects to predict
-        :param top_k: number of top candidates to return per image
-        :return: list of lists containing (character, score)
+        :param batch_size: batch size for OCR inference (minimum 1)
+        :return: list of tuple containing (character, score)
         """
         return [
-            [(pred.get("rec_text"), pred.get("rec_score"))]
-            for pred in self._ocr_model.predict(images, batch_size=self._batch_size)
+            (pred.get("rec_text"), pred.get("rec_score"))
+            for pred in self._ocr_model.predict(images, batch_size=batch_size)
         ]
 
     @staticmethod
@@ -86,7 +79,7 @@ class FontOCR:
         render_font: ImageFont.FreeTypeFont,
         is_reflect: bool = False,
         size: int = 64,
-    ) -> Image.Image | None:
+    ) -> Image.Image:
         """
         Render a single character into an RGB square image.
 
@@ -107,10 +100,6 @@ class FontOCR:
         if is_reflect:
             img = img.transpose(Transpose.FLIP_LEFT_RIGHT)
 
-        img_np = np.array(img)
-        if np.unique(img_np).size == 1:
-            return None
-
         return img
 
     @staticmethod
@@ -119,7 +108,7 @@ class FontOCR:
         render_font: ImageFont.FreeTypeFont,
         is_reflect: bool = False,
         size: int = 64,
-    ) -> np.ndarray | None:
+    ) -> np.ndarray:
         """
         Render a single character into an RGB square image.
 
@@ -140,11 +129,7 @@ class FontOCR:
         if is_reflect:
             img = img.transpose(Transpose.FLIP_LEFT_RIGHT)
 
-        img_np = np.array(img)
-        if np.unique(img_np).size == 1:
-            return None
-
-        return img_np
+        return np.array(img)
 
     @staticmethod
     def render_text_image(
@@ -176,32 +161,56 @@ class FontOCR:
         return img
 
     @staticmethod
-    def _chunked(seq: list[T], size: int) -> Generator[list[T], None, None]:
+    def load_image_array_from_bytes(data: bytes) -> np.ndarray:
         """
-        Yield successive chunks of `seq` of length `size`.
+        Decode image bytes into an RGB NumPy array.
+
+        Reads common image formats (e.g. PNG/JPEG/WebP) from an
+        in-memory byte buffer using Pillow, converts the image to RGB,
+        and returns a NumPy array suitable for OCR inference.
+
+        :param data: Image file content as raw bytes.
+        :return: NumPy array of shape (H, W, 3), dtype=uint8, in RGB order.
+        :raises PIL.UnidentifiedImageError, OSError: If input bytes cannot be decoded.
         """
-        for i in range(0, len(seq), size):
-            yield seq[i : i + size]
+        with Image.open(io.BytesIO(data)) as im:
+            im = im.convert("RGB")
+            return np.asarray(im)
 
+    @staticmethod
+    def load_render_font(
+        font_path: Path | str, char_size: int = 52
+    ) -> ImageFont.FreeTypeFont:
+        """
+        Load a FreeType font face at the given pixel size for rendering helpers.
 
-_font_ocr: FontOCR | None = None
+        :param font_path: Path to a TTF/OTF font file.
+        :param char_size: Target glyph size in pixels (e.g. 52).
+        :return: A PIL `ImageFont.FreeTypeFont` instance.
+        :raises OSError: If the font file cannot be opened by PIL.
+        """
+        return ImageFont.truetype(str(font_path), char_size)
 
+    @staticmethod
+    def extract_font_charset(font_path: Path | str) -> set[str]:
+        """
+        Extract the set of Unicode characters encoded by a TrueType/OpenType font.
 
-def get_font_ocr(
-    model_name: str | None = None,
-    model_dir: str | None = None,
-    input_shape: tuple[int, int, int] | None = None,
-    batch_size: int = 32,
-) -> FontOCR:
-    """
-    Return the singleton FontOCR, initializing it on first use.
-    """
-    global _font_ocr
-    if _font_ocr is None:
-        _font_ocr = FontOCR(
-            model_name=model_name,
-            model_dir=model_dir,
-            input_shape=input_shape,
-            batch_size=batch_size,
-        )
-    return _font_ocr
+        This reads the font's best available character map (cmap) and returns the
+        corresponding set of characters.
+
+        :param font_path: Path to a TTF/OTF font file.
+        :return: A set of Unicode characters present in the font's cmap.
+        """
+        with TTFont(font_path) as font_ttf:
+            cmap = font_ttf.getBestCmap() or {}
+
+        charset: set[str] = set()
+        for cp in cmap:
+            # guard against invalid/surrogate code points
+            if 0 <= cp <= 0x10FFFF and not (0xD800 <= cp <= 0xDFFF):
+                try:
+                    charset.add(chr(cp))
+                except ValueError:
+                    continue
+        return charset

novel_downloader/utils/fontocr/loader.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+"""
+novel_downloader.utils.fontocr.loader
+-------------------------------------
+
+Lazily load the FontOCR class.
+"""
+
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .core import FontOCR
+
+logger = logging.getLogger(__name__)
+
+_FONT_OCR: "FontOCR | None" = None
+
+
+def get_font_ocr(
+    model_name: str | None = None,
+    model_dir: str | None = None,
+    input_shape: tuple[int, int, int] | None = None,
+) -> "FontOCR | None":
+    """
+    Try to initialize and return a singleton FontOCR instance.
+    Returns None if FontOCR or its dependencies are not available.
+    """
+    global _FONT_OCR
+    if _FONT_OCR is None:
+        try:
+            from .core import FontOCR
+
+            _FONT_OCR = FontOCR(
+                model_name=model_name,
+                model_dir=model_dir,
+                input_shape=input_shape,
+            )
+        except ImportError:
+            logger.warning(
+                "FontOCR dependency not available "
+                "(paddleocr / numpy / pillow / fonttools). "
+                "Font decoding will be skipped."
+            )
+            return None
+        except Exception as e:
+            logger.warning("FontOCR initialization failed: %s", e, exc_info=True)
+            return None
+
+    return _FONT_OCR

novel_downloader/utils/logger.py

@@ -4,17 +4,17 @@ novel_downloader.utils.logger
 -----------------------------
 
 Provides a configurable logging setup for Python applications.
-Log files are rotated daily and named with the given logger name and current date.
 """
 
+from __future__ import annotations
+
 __all__ = ["setup_logging"]
 
 import logging
-from datetime import datetime
 from logging.handlers import TimedRotatingFileHandler
 from pathlib import Path
 
-from .constants import LOGGER_DIR, LOGGER_NAME
+from .constants import LOGGER_DIR, PACKAGE_NAME
 
 LOG_LEVELS: dict[str, int] = {
     "DEBUG": logging.DEBUG,
@@ -22,75 +22,99 @@ LOG_LEVELS: dict[str, int] = {
     "WARNING": logging.WARNING,
     "ERROR": logging.ERROR,
 }
+_MUTE_LOGGERS: set[str] = {
+    "fontTools.ttLib.tables._p_o_s_t",
+}
+
+
+def _normalize_level(level: int | str) -> int:
+    if isinstance(level, int):
+        return level
+    if isinstance(level, str):
+        lvl = LOG_LEVELS.get(level.upper())
+        if isinstance(lvl, int):
+            return lvl
+    return logging.INFO
 
 
 def setup_logging(
-    log_filename_prefix: str | None = None,
-    log_level: str | None = None,
+    log_filename: str | None = None,
+    console_level: int | str = "INFO",
+    file_level: int | str = "DEBUG",
     log_dir: str | Path | None = None,
+    *,
+    console: bool = True,
+    file: bool = True,
+    backup_count: int = 7,
+    when: str = "midnight",
 ) -> logging.Logger:
     """
-    Create and configure a logger for both console and rotating file output.
+    Create and configure a package logger with optional console and file handlers.
 
-    :param log_filename_prefix: Prefix for the log file name.
-    :param log_level: Minimum log level to show in console
-                        ("DEBUG", "INFO", "WARNING", "ERROR")
+    :param log_filename: Base log file name (without date suffix).
+    :param console_level: Minimum level for the console handler (string or int).
+    :param file_level: Minimum level for the file handler (string or int).
     :param log_dir: Directory where log files will be saved.
-    :return: A fully configured logger instance.
+    :param console: Add a console handler.
+    :param file: Add a file handler.
+    :param backup_count: How many rotated files to keep.
+    :param when: Rotation interval for TimedRotatingFileHandler (e.g., "midnight").
+    :return: The configured logger.
     """
-    ft_logger = logging.getLogger("fontTools.ttLib.tables._p_o_s_t")
-    ft_logger.setLevel(logging.ERROR)
-    ft_logger.propagate = False
-
-    # Determine console level (default INFO)
-    level_str: str = log_level or "INFO"
-    console_level: int = LOG_LEVELS.get(level_str) or logging.INFO
-
-    # Resolve log file path
-    log_path = Path(log_dir) if log_dir else LOGGER_DIR
-    log_path.mkdir(parents=True, exist_ok=True)
-
-    # Resolve log file name
-    if not log_filename_prefix:
-        log_filename_prefix = LOGGER_NAME
-    date_str = datetime.now().strftime("%Y-%m-%d")
-    log_filename = log_path / f"{log_filename_prefix}_{date_str}.log"
+    # Tame noisy third-party loggers
+    for name in _MUTE_LOGGERS:
+        ml = logging.getLogger(name)
+        ml.setLevel(logging.ERROR)
+        ml.propagate = False
 
-    # Create or retrieve logger
-    logger = logging.getLogger(LOGGER_NAME)
-    logger.setLevel(logging.DEBUG)  # Capture everything, filter by handlers
-    logger.propagate = False
+    logger = logging.getLogger(PACKAGE_NAME)
+    logger.setLevel(logging.DEBUG)
+    logger.propagate = False  # otherwise may affected by PaddleOCR
 
     # Clear existing handlers to avoid duplicate logs
     if logger.hasHandlers():
         logger.handlers.clear()
 
-    # File handler: rotates at midnight, keeps 7 days of logs
-    file_handler = TimedRotatingFileHandler(
-        filename=str(log_filename),
-        when="midnight",
-        interval=1,
-        backupCount=7,
-        encoding="utf-8",
-        utc=False,
-    )
-    file_formatter = logging.Formatter(
-        fmt="%(asctime)s [%(levelname)s] %(name)s.%(funcName)s: %(message)s",
-        datefmt="%Y-%m-%d %H:%M:%S",
-    )
-    file_handler.setFormatter(file_formatter)
-    file_handler.setLevel(logging.DEBUG)
-    logger.addHandler(file_handler)
+    # File handler (rotates daily)
+    if file:
+        file_level = _normalize_level(file_level)
+
+        base_dir = Path(log_dir) if log_dir else LOGGER_DIR
+        base_dir.mkdir(parents=True, exist_ok=True)
+        base_name = log_filename or PACKAGE_NAME
+        log_path = base_dir / f"{base_name}.log"
+
+        fh = TimedRotatingFileHandler(
+            filename=log_path,
+            when=when,
+            interval=1,
+            backupCount=backup_count,
+            encoding="utf-8",
+            utc=False,
+            delay=True,
+        )
+
+        file_formatter = logging.Formatter(
+            fmt="%(asctime)s [%(levelname)s] %(name)s.%(funcName)s: %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S",
+        )
+        fh.setFormatter(file_formatter)
+        fh.setLevel(file_level)
+        logger.addHandler(fh)
+
+        print(f"Logging to {log_path}")
 
     # Console handler
-    console_handler = logging.StreamHandler()
-    console_formatter = logging.Formatter(
-        fmt="%(asctime)s [%(levelname)s] %(message)s", datefmt="%H:%M:%S"
-    )
-    console_handler.setFormatter(console_formatter)
-    console_handler.setLevel(console_level)
-    logger.addHandler(console_handler)
-
-    print(f"Logging to {log_path}")
+    if console:
+        console_level = _normalize_level(console_level)
+
+        console_handler = logging.StreamHandler()
+        console_formatter = logging.Formatter(
+            fmt="%(asctime)s [%(levelname)s] %(message)s",
+            datefmt="%H:%M:%S",
+        )
+        console_handler.setFormatter(console_formatter)
+        console_handler.setLevel(console_level)
+        logger.addHandler(console_handler)
 
     return logger

novel_downloader/utils/network.py

@@ -8,7 +8,6 @@ Utilities for handling HTTP requests and downloading remote resources.
 
 __all__ = ["download"]
 
-import logging
 from pathlib import Path
 from typing import Literal
 from urllib.parse import unquote, urlparse
@@ -19,10 +18,7 @@ from urllib3.util.retry import Retry
 
 from .constants import DEFAULT_HEADERS
 from .file_utils import sanitize_filename
-from .file_utils.io import _get_non_conflicting_path, write_file
-
-logger = logging.getLogger(__name__)
-_DEFAULT_CHUNK_SIZE = 8192  # 8KB per chunk for streaming downloads
+from .file_utils.io import _unique_path, write_file
 
 
 def _normalize_url(url: str) -> str:
@@ -37,8 +33,8 @@ def _normalize_url(url: str) -> str:
 
 
 def _build_filepath(
-    folder: Path,
     url: str,
+    folder: Path,
     filename: str | None,
     default_suffix: str,
     on_exist: Literal["overwrite", "skip", "rename"],
@@ -48,20 +44,18 @@ def _build_filepath(
 
     raw_name = filename or url_path.name or "unnamed"
     name = sanitize_filename(raw_name)
-    suffix = default_suffix or url_path.suffix
-    if suffix and not suffix.startswith("."):
-        suffix = "." + suffix
 
-    file_path = folder / name
-    if not file_path.suffix and suffix:
-        file_path = file_path.with_suffix(suffix)
+    if "." not in name and (url_path.suffix or default_suffix):
+        name += url_path.suffix or default_suffix
 
+    file_path = folder / name
     if on_exist == "rename":
-        file_path = _get_non_conflicting_path(file_path)
+        file_path = _unique_path(file_path)
+
     return file_path
 
 
-def _make_session(
+def _new_session(
     retries: int,
     backoff: float,
     headers: dict[str, str] | None,
@@ -72,7 +66,7 @@ def _make_session(
     retry = Retry(
         total=retries,
         backoff_factor=backoff,
-        status_forcelist=[429, 500, 502, 503, 504],
+        status_forcelist=[413, 429, 500, 502, 503, 504],
         allowed_methods={"GET", "HEAD", "OPTIONS"},
     )
     adapter = HTTPAdapter(max_retries=retry)
@@ -90,10 +84,8 @@ def download(
     retries: int = 3,
     backoff: float = 0.5,
     headers: dict[str, str] | None = None,
-    stream: bool = False,
     on_exist: Literal["overwrite", "skip", "rename"] = "overwrite",
     default_suffix: str = "",
-    chunk_size: int = _DEFAULT_CHUNK_SIZE,
 ) -> Path | None:
     """
     Download a URL to disk, with retries, optional rename/skip, and cleanup on failure.
@@ -105,10 +97,8 @@ def download(
     :param retries: GET retry count.
     :param backoff: exponential backoff base.
     :param headers: optional headers.
-    :param stream: Whether to stream the response.
     :param on_exist: if 'skip', return filepath; if 'rename', auto-rename.
     :param default_suffix: used if no suffix in URL or filename.
-    :param chunk_size: streaming chunk size.
     :return: path to the downloaded file.
     """
     url = _normalize_url(url)
@@ -117,8 +107,8 @@ def download(
     folder.mkdir(parents=True, exist_ok=True)
 
     save_path = _build_filepath(
-        folder,
         url,
+        folder,
         filename,
         default_suffix,
         on_exist,
@@ -126,34 +116,20 @@ def download(
 
     # Handle existing file
     if save_path.exists() and on_exist == "skip":
-        logger.debug("Skipping download; file exists: %s", save_path)
         return save_path
 
-    with _make_session(retries, backoff, headers) as session:
+    with _new_session(retries, backoff, headers) as session:
         try:
-            resp = session.get(url, timeout=timeout, stream=stream)
+            resp = session.get(url, timeout=timeout)
             resp.raise_for_status()
-        except Exception as e:
-            logger.warning("[download] request failed: %s", e)
-            return None
 
-        # Write to disk
-        if stream:
-            try:
-                with open(save_path, "wb") as f:
-                    for chunk in resp.iter_content(chunk_size=chunk_size):
-                        if chunk:
-                            f.write(chunk)
-                return save_path
-            except Exception as e:
-                logger.warning("[download] write failed: %s", e)
-                save_path.unlink(missing_ok=True)
-                return None
-        else:
+            # Write to disk
             return write_file(
                 content=resp.content,
                 filepath=save_path,
-                write_mode="wb",
                 on_exist=on_exist,
             )
+        except Exception:
+            return None
+
     return None