hn-deepocr-client 0.3.0

Haina Deep OCR API Client SDK

HN Deep OCR Client

Python SDK for Haina Deep OCR API - PDF parsing and document processing made easy.

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)
• Dual algorithm support: DeepOCR (default) and MinerU engines
• 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

pip install hn-deepocr-client

Or using uv:

uv add hn-deepocr-client

Quick Start

1. Get API Credentials

Apply for Access Key (AK) and Secret Key (SK) from Haina Platform.

2. Configure Environment Variables

Create a .env file in your project root:

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:

cp .env.example .env
# Edit .env with your credentials

3. Basic Usage

from hn_deepocr_client import ParserPDF, load_config

config = load_config()

parser = ParserPDF(
    ak=config.AK,
    sk=config.SK,
    presigned_url=config.PRESIGNED_URL,
)

# DeepOCR (default)
result = parser.start(
    file_name="document.pdf",
    file_path="./document.pdf",
)

print(f"Parse completed! DataID: {result['data_id']}")
print(f"Download URLs: {result['download_urls']}")

4. Using MinerU Algorithm

# Use MinerU engine instead of DeepOCR
result = parser.start(
    file_name="document.pdf",
    file_path="./document.pdf",
    algorithm="mineru",
)

print(f"MinerU parse completed! DataID: {result['data_id']}")
for file_type, url in result.get("download_urls", {}).items():
    print(f"  {file_type}: {url}")

Supported File Types by Algorithm

File Type	Description	DeepOCR	MinerU
zip	Full package (all results)	-	Yes
json	JSON format	Yes	Yes
markdown	Markdown (no images)	Yes	Yes
md-figure	Markdown (with images)	Yes	Yes
figure	Image files	Yes	Yes
formula	Formula files	Yes	-
table	Table files	Yes	-

Advanced Usage

Logging Configuration

The SDK automatically initializes logging when creating a ParserPDF instance. By default, logs are written to both console and a rotating file (logs/pdf_parser.log).

Customize log level via constructor:

import logging

parser = ParserPDF(
    ak=config.AK,
    sk=config.SK,
    presigned_url=config.PRESIGNED_URL,
    log_level=logging.DEBUG,       # or "DEBUG" string
    log_dir="custom_logs",
    log_file="my_app.log",
)

Customize log level via environment variable (in .env):

LOG_LEVEL=DEBUG
LOG_DIR=logs
LOG_FILE=pdf_parser.log

Valid log levels: DEBUG, INFO, WARNING, ERROR, CRITICAL.

Customize log level programmatically:

from hn_deepocr_client import init_logger

init_logger(log_level="DEBUG", log_dir="logs", log_file="app.log")

Custom Configuration

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

# DeepOCR with custom file types
result = parser.start(
    "document.pdf", "./document.pdf",
    file_types=["json", "markdown"],
)

# MinerU with custom file types
result = parser.start(
    "document.pdf", "./document.pdf",
    algorithm="mineru",
    file_types=["zip", "markdown"],
)

File Upload Validation

The SDK validates files before upload:

• file_name must match the basename of file_path (e.g., file_name="doc.pdf" with file_path="./doc.pdf")
• Empty files (0 bytes) are rejected with a clear error message
• Only .pdf files are supported
• part_size must be between 1MB and 100MB (configurable via HN_DEEP_OCR_PART_SIZE)

Direct API Usage

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, sk, presigned_url, config=None, http_client=None, log_level=None, log_dir="logs", log_file="pdf_parser.log") - Initialize parser with optional logging configuration
• start(file_name: str, file_path: str, generate_all_formats: bool = True, file_types: list[str] | None = None, parse_timeout: int = 1800, algorithm: str = "deepocr") -> dict - Start full parsing workflow, returns {"data_id": ..., "download_urls": {...}}. algorithm accepts "deepocr" (default) or "mineru".
• 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
• calc_part_count(file_path: str) -> int - Calculate number of chunks for a file

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_LEVEL	str	INFO	Log level (DEBUG/INFO/WARNING/ERROR/CRITICAL)
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, valid range: 1MB~100MB)

All network configuration options can be set via environment variables with the HN_DEEP_OCR_ prefix or in your .env file.

Development

Installation

git clone https://github.com/yourusername/hn-deepocr-client.git
cd hn-deepocr-client
uv sync

Running Tests

uv run pytest

With coverage:

uv run pytest --cov=hn_deepocr_client

Code Quality

# 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
• Examples
• Changelog

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Documentation: https://github.com/yourusername/hn-deepocr-client
• Issues: https://github.com/yourusername/hn-deepocr-client/issues
• Email: [e-mail]

Acknowledgments

• Built with Pydantic
• Code quality powered by Ruff
• Testing with pytest