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/)
