hn-deepocr-client 0.1.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)
• 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,
)

data_id = parser.start(
    file_name="document.pdf",
    file_path="./document.pdf",
)

print(f"Parse completed! DataID: {data_id}")

Advanced Usage

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

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

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

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