hn-deepocr-client 0.1.0__tar.gz

hn_deepocr_client-0.1.0/.env.example

@@ -0,0 +1,5 @@
+AK=your_access_key_here
+SK=your_secret_key_here
+PRESIGNED_URL=https://open-sci-datahub.zero2x.org
+LOG_DIR=logs
+LOG_FILE=pdf_parser.log

hn_deepocr_client-0.1.0/.gitignore

@@ -0,0 +1,80 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+*.pyo
+*.pyd
+*.so
+*.dll
+*.dylib
+build/
+dist/
+wheels/
+*.egg-info
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+.python-version
+
+# UV package manager
+.uv/
+
+# IDEs and editors
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Project outputs
+output/
+*.xlsx
+!数据需求*.xlsx
+
+# Logs
+logs/
+*.log
+
+# Temporary files
+*.tmp
+*.bak
+*.log
+~$*.xlsx
+~$*.xls
+~$*.doc*
+
+# Database
+*.db
+*.sqlite
+*.sqlite3
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+*.cover
+.hypothesis/
+
+# Jupyter Notebook
+.ipynb_checkpoints/
+*.ipynb
+
+# MyPy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Ruff
+.ruff_cache/
+
+.claude
+/CLAUDE.md

hn_deepocr_client-0.1.0/AGENTS.md

@@ -0,0 +1,157 @@
+# 项目：OCR 批量处理后台接口
+
+## 项目说明
+基于 uv 包管理器，调用 PDF 解析 API 完成样例 PDF 解析和结果下载。
+
+## 技术栈
+- **包管理器**: uv
+- **Python 版本**: >= 3.10
+- **核心依赖**: requests, pydantic-settings
+
+## 命令指南
+
+### 依赖安装
+```bash
+uv sync
+```
+
+### 运行主程序
+```bash
+python test_online_openapi.py
+```
+
+### 运行工具模块
+```bash
+python utils.py
+```
+
+### 代码质量检查
+```bash
+# 代码格式化
+uv run ruff format .
+
+# 代码检查
+uv run ruff check .
+
+# 自动修复可修复的问题
+uv run ruff check --fix .
+
+# 类型检查
+uv run mypy .
+```
+
+## 代码规范
+
+### 导入组织
+1. 标准库导入
+2. 第三方库导入
+3. 按字母顺序排序
+```python
+import os
+import json
+import time
+import requests
+import utils
+```
+
+### 类型注解
+- 新代码建议添加类型注解以提高可读性
+- 现有代码风格：最小化类型注解使用
+- 简单函数可省略，复杂函数和公共接口应添加类型提示
+```python
+def get_resource_path(resource_name: str) -> str:
+    return os.path.join(os.path.dirname(__file__), "resources", resource_name)
+```
+
+### 命名约定
+- **类名**: PascalCase (如 `ParserPDF`)
+- **函数和变量**: snake_case (如 `get_upload_urls`, `file_path`)
+- **常量**: UPPER_SNAKE_CASE (如 `TIMEOUT`, `API_PATHS`)
+- **私有方法**: 单下划线前缀 `_private_method`
+
+### 注释规范
+- **仅使用文档字符串**: 使用三引号 `"""` 格式
+- **语言**: 英文注释
+- **位置**: 仅在函数和类顶部，严禁代码行内注释
+- **其它**：不用emoji字符，避免无意义的翻译型注释
+```python
+def load_config(config_path="config.json"):
+    """加载配置文件（含AK/SK/接口地址，避免硬编码）"""
+    pass
+```
+
+### 错误处理
+- 使用具体异常类型 (FileNotFoundError, ValueError 等)
+- 使用 `exc_info=True` 记录完整堆栈信息
+- 异常处理后重新抛出
+```python
+try:
+    response = requests.post(url, data, headers=headers, timeout=self.TIMEOUT)
+    response.raise_for_status()
+except requests.exceptions.RequestException as e:
+    self.logger.error(f"请求异常：{str(e)}", exc_info=True)
+    raise
+```
+
+### 日志记录
+- 初始化同时输出到控制台和文件
+- 使用结构化格式: `%(asctime)s - %(levelname)s - %(message)s`
+- 日志级别: INFO, WARNING, ERROR, CRITICAL
+- 重要操作需记录 INFO 级别日志
+```python
+def init_logger():
+    """初始化日志配置：同时输出到控制台和文件"""
+    logger = logging.getLogger("PDFParserLogger")
+    logger.setLevel(logging.INFO)
+    formatter = logging.Formatter("%(asctime)s - %(levelname)s - %(message)s")
+    # 添加 handlers...
+```
+
+### 配置管理
+- 使用 Pydantic Settings 管理配置（支持环境变量和 .env 文件）
+- 敏感信息通过 .env 文件管理（已在 .gitignore 中）
+- 自动类型检查和验证
+```python
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+class Settings(BaseSettings):
+    AK: str
+    SK: str
+    PRESIGNED_URL: str = "https://open-sci-datahub.zero2x.org"
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+    )
+```
+
+### 类设计
+- 常量定义为类属性 (API_PATHS, TIMEOUT)
+- 配置通过 __init__ 传入
+- 方法职责单一，命名清晰描述行为
+```python
+class ParserPDF:
+    API_PATHS = {
+        "GET_UPLOAD_URLS": "/openAPI/deepocr/getUploadUrls",
+    }
+    TIMEOUT = 300
+
+    def __init__(self, ak, sk, presigned_url):
+        self.ak = ak
+        self.sk = sk
+        self.presigned_url = presigned_url.rstrip("/")
+        self.logger = init_logger()
+```
+
+## 依赖管理
+- 仅在必要情况下引入新的外部依赖项
+- 引入新依赖前需评估其对项目体积和维护成本的影响
+- 使用 uv 作为包管理器
+
+## 开发工具
+- **代码格式化和检查**: ruff（已配置在 pyproject.toml 中）
+- **类型检查**: mypy（可选，建议复杂函数添加类型提示）
+
+## 测试
+- 当前无正式测试框架配置
+- 测试方式：运行 `test_online_openapi.py` 执行完整工作流

hn_deepocr_client-0.1.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-01-21
+
+### Added
+- Initial release of Haina Deep OCR Client SDK
+- PDF file upload and parsing functionality
+- Authentication token generation and signing
+- Support for chunked file uploads
+- Parsing status polling
+- Multi-format result generation (zip, json, markdown, image, formula, table)
+- Comprehensive error handling with custom exception classes
+- Logging configuration with console and file output
+- Pydantic Settings for configuration management
+- Example code for basic and advanced usage
+- Unit tests for core functionality
+- Full documentation and README
+
+### Changed
+- Migration from JSON configuration to Pydantic Settings + .env
+- Restructured project to follow standard Python SDK layout
+- Improved error messages and logging

hn_deepocr_client-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Haina
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hn_deepocr_client-0.1.0/PKG-INFO

@@ -0,0 +1,267 @@
+Metadata-Version: 2.4
+Name: hn-deepocr-client
+Version: 0.1.0
+Summary: Haina Deep OCR API Client SDK
+Project-URL: Homepage, https://github.com/yourusername/hn-deepocr-client
+Project-URL: Documentation, https://github.com/yourusername/hn-deepocr-client#readme
+Project-URL: Repository, https://github.com/yourusername/hn-deepocr-client.git
+Project-URL: Issues, https://github.com/yourusername/hn-deepocr-client/issues
+Author-email: Haina <support@haina.com>
+License: MIT
+License-File: LICENSE
+Keywords: api,client,ocr,parser,pdf
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: pydantic-settings>=2.12.0
+Requires-Dist: requests>=2.32.5
+Description-Content-Type: text/markdown
+
+# HN Deep OCR Client
+
+Python SDK for Haina Deep OCR API - PDF parsing and document processing made easy.
+
+[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Code Style](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
+
+## Features
+
+- PDF file upload with automatic chunking (configurable chunk size)
+- Parsing status polling with optimized timeouts
+- Multi-format result generation (ZIP, JSON, Markdown, Image, Formula, Table)
+- Comprehensive error handling with custom exception classes
+- Built-in logging configuration
+- Type hints for better IDE support
+- Pydantic Settings for configuration management
+- Connection pooling and HTTP session reuse
+- Intelligent retry mechanism with exponential backoff
+- Granular timeout configuration per operation type
+- Full test coverage
+
+## Installation
+
+```bash
+pip install hn-deepocr-client
+```
+
+Or using uv:
+
+```bash
+uv add hn-deepocr-client
+```
+
+## Quick Start
+
+### 1. Get API Credentials
+
+Apply for Access Key (AK) and Secret Key (SK) from [Haina Platform](https://mkxzg8.yuque.com/hoq002/ilbssv/qmgptn6gltudphik#LoSlF).
+
+### 2. Configure Environment Variables
+
+Create a `.env` file in your project root:
+
+```env
+AK=your_access_key_here
+SK=your_secret_key_here
+PRESIGNED_URL=https://open-sci-datahub.zero2x.org
+```
+
+Or use `.env.example` as a template:
+
+```bash
+cp .env.example .env
+# Edit .env with your credentials
+```
+
+### 3. Basic Usage
+
+```python
+from hn_deepocr_client import ParserPDF, load_config
+
+config = load_config()
+
+parser = ParserPDF(
+    ak=config.AK,
+    sk=config.SK,
+    presigned_url=config.PRESIGNED_URL,
+)
+
+data_id = parser.start(
+    file_name="document.pdf",
+    file_path="./document.pdf",
+)
+
+print(f"Parse completed! DataID: {data_id}")
+```
+
+## Advanced Usage
+
+### Custom Configuration
+
+```python
+from hn_deepocr_client import ParserPDF, load_config, ConfigurationError
+
+try:
+    config = load_config()
+    parser = ParserPDF(ak=config.AK, sk=config.SK, presigned_url=config.PRESIGNED_URL)
+    data_id = parser.start("document.pdf", "./document.pdf")
+except ConfigurationError as e:
+    print(f"Configuration error: {e}")
+except UploadError as e:
+    print(f"Upload failed: {e}")
+except ParseError as e:
+    print(f"Parse failed: {e}")
+```
+
+### Generate Specific Formats Only
+
+```python
+data_id = parser.start("document.pdf", "./document.pdf", generate_all_formats=False)
+
+# Generate only formats you need
+zip_url = parser.generate_zips(data_id, "zip")
+json_url = parser.generate_zips(data_id, "json")
+markdown_url = parser.generate_zips(data_id, "markdown")
+```
+
+### Direct API Usage
+
+```python
+from hn_deepocr_client import create_token
+
+token = create_token(
+    ak="your_ak",
+    sk="your_sk",
+    url="https://api.example.com/upload",
+    request_body='{"file":"test.pdf"}',
+)
+```
+
+## API Reference
+
+### ParserPDF
+
+Main class for PDF parsing operations.
+
+#### Methods
+
+- `__init__(ak: str, sk: str, presigned_url: str)` - Initialize parser
+- `start(file_name: str, file_path: str, generate_all_formats: bool = True) -> str` - Start full parsing workflow
+- `get_parsing_status(data_id: str) -> int` - Query parsing status (1=parsing, 2=success, 3=failed)
+- `generate_zips(data_id: str, file_type: str) -> str` - Generate download link for specific format
+
+### Exception Classes
+
+- `HNDeepOCRError` - Base exception class
+- `ConfigurationError` - Configuration related errors
+- `AuthenticationError` - Authentication failures
+- `UploadError` - File upload failures
+- `ParseError` - Parsing failures
+
+### Configuration
+
+Configuration is managed via Pydantic Settings. Available options:
+
+#### Core Configuration
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| AK | str | (required) | Access Key |
+| SK | str | (required) | Secret Key |
+| PRESIGNED_URL | str | https://open-sci-datahub.zero2x.org | API base URL |
+| LOG_DIR | str | logs | Log directory |
+| LOG_FILE | str | pdf_parser.log | Log filename |
+
+#### Network Configuration
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| HN_DEEP_OCR_TIMEOUT_API | int | 30 | API call timeout (seconds) |
+| HN_DEEP_OCR_TIMEOUT_UPLOAD | int | 300 | File upload timeout (seconds) |
+| HN_DEEP_OCR_TIMEOUT_STATUS | int | 10 | Status query timeout (seconds) |
+| HN_DEEP_OCR_TIMEOUT_MERGE | int | 60 | Merge operation timeout (seconds) |
+| HN_DEEP_OCR_MAX_RETRIES_DEFAULT | int | 3 | Default retry count |
+| HN_DEEP_OCR_MAX_RETRIES_UPLOAD | int | 5 | Upload retry count |
+| HN_DEEP_OCR_BASE_DELAY | float | 1.0 | Base delay for retry backoff |
+| HN_DEEP_OCR_CONNECTION_POOL_SIZE | int | 10 | Connection pool size |
+| HN_DEEP_OCR_CONNECTION_MAXSIZE | int | 20 | Maximum connections per pool |
+| HN_DEEP_OCR_PART_SIZE | int | 10485760 | File chunk size in bytes (10MB) |
+
+All network configuration options can be set via environment variables with the `HN_DEEP_OCR_` prefix or in your `.env` file.
+
+## Development
+
+### Installation
+
+```bash
+git clone https://github.com/yourusername/hn-deepocr-client.git
+cd hn-deepocr-client
+uv sync
+```
+
+### Running Tests
+
+```bash
+uv run pytest
+```
+
+With coverage:
+
+```bash
+uv run pytest --cov=hn_deepocr_client
+```
+
+### Code Quality
+
+```bash
+# Format code
+uv run ruff format .
+
+# Lint code
+uv run ruff check .
+
+# Fix linting issues
+uv run ruff check --fix .
+
+# Type check
+uv run mypy .
+```
+
+### Examples
+
+See the `examples/` directory for usage examples:
+
+- `basic_usage.py` - Basic usage example
+- `advanced_usage.py` - Advanced features and error handling
+
+## Documentation
+
+For more detailed documentation, see:
+
+- [API Reference](docs/api.md)
+- [Examples](docs/examples.md)
+- [Changelog](CHANGELOG.md)
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Support
+
+- Documentation: [https://github.com/yourusername/hn-deepocr-client](https://github.com/yourusername/hn-deepocr-client)
+- Issues: [https://github.com/yourusername/hn-deepocr-client/issues](https://github.com/yourusername/hn-deepocr-client/issues)
+- Email: support@haina.com
+
+## Acknowledgments
+
+- Built with [Pydantic](https://pydantic-docs.helpmanual.io/)
+- Code quality powered by [Ruff](https://github.com/astral-sh/ruff)
+- Testing with [pytest](https://docs.pytest.org/)