hn-deepocr-client 0.1.0__py3-none-any.whl

hn_deepocr_client/__init__.py

@@ -0,0 +1,26 @@
+from hn_deepocr_client.auth import create_token
+from hn_deepocr_client.config import NetworkConfig
+from hn_deepocr_client.exceptions import (
+    AuthenticationError,
+    ConfigurationError,
+    HNDeepOCRError,
+    ParseError,
+    UploadError,
+)
+from hn_deepocr_client.parser import ParserPDF
+from hn_deepocr_client.settings import Settings, load_config
+
+__all__ = [
+    "Settings",
+    "load_config",
+    "NetworkConfig",
+    "ParserPDF",
+    "create_token",
+    "HNDeepOCRError",
+    "AuthenticationError",
+    "UploadError",
+    "ParseError",
+    "ConfigurationError",
+]
+
+__version__ = "0.1.0"

hn_deepocr_client/auth.py

@@ -0,0 +1,58 @@
+import base64
+import hashlib
+import json
+import time
+import urllib.parse as uri_utils
+
+
+def sign(sign_key: str, base_64_parameters: str, uri, request_body: str = "") -> str:
+    """签名生成
+
+    Args:
+        sign_key: 签名密钥
+        base_64_parameters: Base64 编码的参数
+        uri: 请求 URI
+        request_body: 请求体，默认为空字符串
+
+    Returns:
+        签名字符串（大写）
+    """
+    data = base_64_parameters + get_relative_url(uri) + request_body
+    md5 = hashlib.md5((data + sign_key).encode("utf-8"))
+    return md5.hexdigest().upper()
+
+
+def get_relative_url(uri) -> str:
+    """获取相对 URL
+
+    Args:
+        uri: 解析后的 URI 对象
+
+    Returns:
+        相对路径（包含查询参数，如果存在）
+    """
+    if uri.query is None or len(uri.query) == 0:
+        return uri.path
+    return uri.path + "?" + uri.query
+
+
+def create_token(ak: str, sk: str, url: str = None, request_body: str = "") -> str:
+    """创建认证 Token
+
+    Args:
+        ak: Access Key
+        sk: Secret Key
+        url: 完整请求 URL
+        request_body: 请求体，默认为空字符串
+
+    Returns:
+        认证 Token，格式为：base64_parameters.signature
+    """
+    uri = uri_utils.urlsplit(url, allow_fragments=False)
+    current_time = round(time.time() * 1000)
+    parameters = json.dumps(
+        {"alg": "MD5", "appKey": ak, "timestamp": str(current_time)}, separators=(",", ":")
+    )
+    base64_parameters = str(base64.b64encode(bytes(parameters, "utf-8")), "utf-8")
+    signature = sign(sk, base64_parameters, uri, request_body)
+    return base64_parameters + "." + signature

hn_deepocr_client/config.py

@@ -0,0 +1,35 @@
+"""Configuration management for hn-deepocr-client."""
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class NetworkConfig(BaseSettings):
+    """Network configuration for HTTP client."""
+
+    # Timeout configurations (seconds)
+    timeout_api: int = 30
+    timeout_upload: int = 300
+    timeout_status: int = 10
+    timeout_merge: int = 60
+
+    # Retry configurations
+    max_retries_default: int = 3
+    max_retries_upload: int = 5
+    base_delay: float = 1.0
+
+    # Connection pool configurations
+    connection_pool_size: int = 10
+    connection_maxsize: int = 20
+
+    # File partition configuration (bytes)
+    part_size: int = 10 * 1024 * 1024  # 10MB default
+
+    # SSL verification
+    verify_ssl: bool = True
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        env_prefix="HN_DEEP_OCR_",
+        extra="ignore",
+    )

hn_deepocr_client/exceptions.py

@@ -0,0 +1,31 @@
+"""自定义异常类"""
+
+
+class HNDeepOCRError(Exception):
+    """基础异常类"""
+
+    pass
+
+
+class AuthenticationError(HNDeepOCRError):
+    """认证相关异常"""
+
+    pass
+
+
+class UploadError(HNDeepOCRError):
+    """文件上传相关异常"""
+
+    pass
+
+
+class ParseError(HNDeepOCRError):
+    """文件解析相关异常"""
+
+    pass
+
+
+class ConfigurationError(HNDeepOCRError):
+    """配置相关异常"""
+
+    pass

hn_deepocr_client/http_client.py

@@ -0,0 +1,295 @@
+"""HTTP client for hn-deepocr-client with connection pooling and retry logic."""
+
+import json
+import logging
+import random
+import time
+from typing import Any
+
+import requests
+from requests.adapters import HTTPAdapter
+from requests.exceptions import ConnectionError, HTTPError, Timeout, TooManyRedirects
+
+from hn_deepocr_client.config import NetworkConfig
+from hn_deepocr_client.exceptions import AuthenticationError, ParseError, UploadError
+
+
+class HTTPClient:
+    """HTTP client with connection pooling, retry logic, and standardized error handling."""
+
+    def __init__(self, config: NetworkConfig, session: requests.Session | None = None):
+        """Initialize HTTP client.
+
+        Args:
+            config: Network configuration
+            session: Optional existing session to use
+        """
+        self.config = config
+        self._logger = logging.getLogger(f"{__name__}.{self.__class__.__name__}")
+
+        self._session = session or self._create_session()
+        self._owns_session = session is None
+
+    def _create_session(self) -> requests.Session:
+        """Create and configure a requests session with connection pooling."""
+        session = requests.Session()
+
+        adapter = HTTPAdapter(
+            pool_connections=self.config.connection_pool_size,
+            pool_maxsize=self.config.connection_maxsize,
+            max_retries=0,
+            pool_block=False,
+        )
+        session.mount("http://", adapter)
+        session.mount("https://", adapter)
+
+        session.headers.update(
+            {
+                "User-Agent": "hn-deepocr-client/1.0",
+                "Accept": "application/json",
+            }
+        )
+
+        return session
+
+    def __enter__(self):
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit - close session if we own it."""
+        if self._owns_session:
+            self._session.close()
+
+    def close(self):
+        """Explicitly close the session."""
+        if self._owns_session:
+            self._session.close()
+
+    def _exponential_backoff_delay(self, attempt: int) -> float:
+        """Calculate exponential backoff delay with jitter.
+
+        Args:
+            attempt: Current attempt number (1-based)
+
+        Returns:
+            Delay in seconds, guaranteed non-negative
+        """
+        delay = min(self.config.base_delay * (2 ** (attempt - 1)), 60.0)
+        jitter = random.uniform(-0.25, 0.25)
+        return max(0.0, delay * (1 + jitter))
+
+    def _is_retryable_error(self, error: Exception) -> bool:
+        """Determine if an error is retryable."""
+        if isinstance(error, (ConnectionError, Timeout, TooManyRedirects)):
+            return True
+        if isinstance(error, HTTPError):
+            return 500 <= error.response.status_code < 600
+        return False
+
+    def _handle_api_error(self, response: requests.Response, operation: str) -> None:
+        """Handle API-specific errors with proper categorization.
+
+        Raises:
+            AuthenticationError: 401/403 responses
+            UploadError: 4xx client errors (except 401/403/404)
+            ParseError: 5xx server errors and other HTTP errors
+        """
+        try:
+            response.raise_for_status()
+        except HTTPError as e:
+            status_code = response.status_code
+            if status_code == 401:
+                raise AuthenticationError(f"Authentication failed for {operation}: {e}") from e
+            elif status_code == 403:
+                raise AuthenticationError(f"Access denied for {operation}: {e}") from e
+            elif status_code == 404:
+                raise UploadError(f"Endpoint not found for {operation}: {e}") from e
+            elif 400 <= status_code < 500:
+                raise UploadError(f"Client error {status_code} for {operation}: {e}") from e
+            elif 500 <= status_code < 600:
+                raise ParseError(f"Server error {status_code} for {operation}: {e}") from e
+            else:
+                raise ParseError(f"HTTP error {status_code} for {operation}: {e}") from e
+
+    def _retry_on_failure(
+        self,
+        func,
+        max_retries: int,
+        retryable_errors: set[type[BaseException]] | None = None,
+        operation_name: str = "",
+    ):
+        """Generic retry mechanism with exponential backoff.
+
+        Only retries on network-level errors (ConnectionError, Timeout) and
+        5xx server errors. 4xx client errors (via AuthenticationError, UploadError)
+        are never retried.
+
+        Args:
+            func: Callable to retry
+            max_retries: Maximum number of attempts (must be >= 1)
+            retryable_errors: Set of retryable exception types
+            operation_name: Name for logging
+
+        Raises:
+            ValueError: If max_retries < 1
+            The last exception if all retries exhausted
+        """
+        if max_retries < 1:
+            raise ValueError(f"max_retries must be >= 1, got {max_retries}")
+
+        if retryable_errors is None:
+            retryable_errors = {ConnectionError, Timeout, ParseError, HTTPError}
+
+        last_exception: Exception | None = None
+
+        for attempt in range(1, max_retries + 1):
+            try:
+                result = func()
+                return result
+            except Exception as e:
+                last_exception = e
+
+                if not any(isinstance(e, error_type) for error_type in retryable_errors):
+                    self._logger.warning(f"Non-retryable error in {operation_name}: {str(e)}")
+                    raise
+
+                if attempt == max_retries:
+                    self._logger.error(
+                        f"Max retries exceeded for {operation_name}: {str(e)}",
+                        exc_info=True,
+                    )
+                    break
+
+                delay = self._exponential_backoff_delay(attempt)
+                self._logger.warning(
+                    f"Attempt {attempt}/{max_retries} failed for {operation_name}, "
+                    f"retrying in {delay:.2f}s: {str(e)}"
+                )
+                time.sleep(delay)
+
+        raise last_exception
+
+    def make_request(
+        self,
+        method: str,
+        url: str,
+        timeout_key: str = "api",
+        **kwargs,
+    ) -> requests.Response:
+        """Make HTTP request using the configured session."""
+        timeout_map = {
+            "api": self.config.timeout_api,
+            "upload": self.config.timeout_upload,
+            "status": self.config.timeout_status,
+            "merge": self.config.timeout_merge,
+        }
+        timeout = timeout_map.get(timeout_key, self.config.timeout_api)
+
+        if "timeout" not in kwargs:
+            kwargs["timeout"] = timeout
+
+        if "headers" not in kwargs:
+            kwargs["headers"] = {}
+
+        headers = dict(self._session.headers)
+        headers.update(kwargs["headers"])
+        kwargs["headers"] = headers
+
+        kwargs.setdefault("verify", self.config.verify_ssl)
+
+        self._logger.debug(f"Making {method} request to {url}")
+        return self._session.request(method, url, **kwargs)
+
+    def post_with_retry(
+        self,
+        url: str,
+        data: dict[str, Any] | str,
+        headers: dict[str, str] | None = None,
+        timeout_key: str = "api",
+        max_retries: int | None = None,
+        operation_name: str = "",
+    ) -> requests.Response:
+        """Make POST request with retry logic."""
+        if max_retries is None:
+            max_retries = self.config.max_retries_default
+
+        def _attempt():
+            if isinstance(data, dict):
+                json_data = json.dumps(data, ensure_ascii=False)
+            else:
+                json_data = str(data)
+
+            response = self.make_request(
+                "POST",
+                url=url,
+                data=json_data,
+                headers=headers or {},
+                timeout_key=timeout_key,
+            )
+            self._handle_api_error(response, operation_name)
+            return response
+
+        return self._retry_on_failure(
+            _attempt,
+            max_retries=max_retries,
+            operation_name=operation_name,
+        )
+
+    def get_with_retry(
+        self,
+        url: str,
+        headers: dict[str, str] | None = None,
+        timeout_key: str = "status",
+        max_retries: int | None = None,
+        operation_name: str = "",
+    ) -> requests.Response:
+        """Make GET request with retry logic."""
+        if max_retries is None:
+            max_retries = self.config.max_retries_default
+
+        def _attempt():
+            response = self.make_request(
+                "GET",
+                url=url,
+                headers=headers or {},
+                timeout_key=timeout_key,
+            )
+            self._handle_api_error(response, operation_name)
+            return response
+
+        return self._retry_on_failure(
+            _attempt,
+            max_retries=max_retries,
+            operation_name=operation_name,
+        )
+
+    def put_with_retry(
+        self,
+        url: str,
+        data: bytes,
+        headers: dict[str, str] | None = None,
+        timeout_key: str = "upload",
+        max_retries: int | None = None,
+        operation_name: str = "",
+    ) -> requests.Response:
+        """Make PUT request with retry logic."""
+        if max_retries is None:
+            max_retries = self.config.max_retries_upload
+
+        def _attempt():
+            response = self.make_request(
+                "PUT",
+                url=url,
+                data=data,
+                headers=headers or {},
+                timeout_key=timeout_key,
+            )
+            self._handle_api_error(response, operation_name)
+            return response
+
+        return self._retry_on_failure(
+            _attempt,
+            max_retries=max_retries,
+            operation_name=operation_name,
+        )

hn_deepocr_client/logging_config.py

@@ -0,0 +1,56 @@
+import logging
+import os
+from logging.handlers import RotatingFileHandler
+
+
+def init_logger(
+    logger_name: str | None = None,
+    log_dir: str = "logs",
+    log_file: str = "pdf_parser.log",
+    log_level: int | None = None,
+    max_bytes: int = 10 * 1024 * 1024,
+    backup_count: int = 5,
+):
+    """初始化日志配置：同时输出到控制台和文件
+
+    Args:
+        logger_name: logger 名称，默认为 "hn_deepocr_client"
+        log_dir: 日志目录，默认为 "logs"
+        log_file: 日志文件名，默认为 "pdf_parser.log"
+        log_level: 日志级别，默认为 logging.INFO，支持环境变量 LOG_LEVEL
+        max_bytes: 单个日志文件最大字节数，默认为 10MB
+        backup_count: 保留的备份文件数量，默认为 5
+
+    Returns:
+        配置好的 logger 实例
+    """
+    if logger_name is None:
+        logger_name = "hn_deepocr_client"
+
+    effective_level = log_level
+    if effective_level is None:
+        log_level_str = os.environ.get("LOG_LEVEL", "INFO")
+        effective_level = getattr(logging, log_level_str.upper(), logging.INFO)
+
+    logger = logging.getLogger(logger_name)
+    if logger.handlers:
+        return logger
+
+    logger.setLevel(effective_level)
+    formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+
+    console_handler = logging.StreamHandler()
+    console_handler.setFormatter(formatter)
+    logger.addHandler(console_handler)
+
+    os.makedirs(log_dir, exist_ok=True)
+    file_handler = RotatingFileHandler(
+        filename=os.path.join(log_dir, log_file),
+        maxBytes=max_bytes,
+        backupCount=backup_count,
+        encoding="utf-8",
+    )
+    file_handler.setFormatter(formatter)
+    logger.addHandler(file_handler)
+
+    return logger