Metadata-Version: 2.5
Name: maradocs-sdk-py
Version: 0.2.0
Summary: Python SDK for the MaraDocs API (https://maradocs.io)
Project-URL: Homepage, https://maradocs.io
Project-URL: Repository, https://github.com/maramia/maradocs-sdk-py
Project-URL: Issues, https://github.com/maramia/maradocs-sdk-py/issues
Project-URL: Documentation, https://api.maradocs.io
Author: Maramia GmbH
License-Expression: MIT
License-File: LICENSE.md
Keywords: api,document,maradocs,ocr,pdf,sdk
Classifier: Development Status :: 4 - Beta
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
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Requires-Dist: pydantic<3,>=2.10
Provides-Extra: dev
Requires-Dist: ruff>=0.8; extra == 'dev'
Description-Content-Type: text/markdown

# MaraDocs Python SDK

[![PyPI](https://img.shields.io/pypi/v/maradocs-sdk-py.svg)](https://pypi.org/project/maradocs-sdk-py/)

[MaraDocs](https://maradocs.io) turns photos and scans into clean, usable documents. This is the official Python client for the [MaraDocs API](https://api.maradocs.io), mirroring the public TypeScript and Go SDKs.

## Installation

```bash
pip install maradocs-sdk-py
```

Requires Python 3.10+.

Dependencies: [Pydantic](https://docs.pydantic.dev/) 2.x, [httpx](https://www.python-httpx.org/) 0.27+.

## Quick start (sync)

```python
import os
from pathlib import Path

from maradocs import MaraDocsClient, MaraDocsServer
from maradocs.models.workspace import WorkspaceDeleteRequest

secret_key = os.environ["MARADOCS_SECRET_KEY"]

with MaraDocsServer(secret_key=secret_key) as server:
    ws = server.workspace.create()
    try:
        with MaraDocsClient(workspace_secret=ws.workspace_secret) as client:
            pdf = client.flow.ocr_img(Path("scan.jpg"))
            print(f"OCR PDF pages: {pdf.pages}")
    finally:
        server.workspace.delete(
            WorkspaceDeleteRequest(
                workspace_id=ws.workspace_id,
                subaccount=ws.subaccount,
            )
        )
```

## Quick start (async)

```python
import asyncio
import os
from maradocs import AsyncMaraDocsClient, AsyncMaraDocsServer
from maradocs.models.workspace import WorkspaceDeleteRequest

async def main() -> None:
    async with AsyncMaraDocsServer(secret_key=os.environ["MARADOCS_SECRET_KEY"]) as server:
        ws = await server.workspace.create()
        try:
            async with AsyncMaraDocsClient(workspace_secret=ws.workspace_secret) as client:
                ok = await client.healthcheck.ping()
                print("API reachable:", ok)
        finally:
            await server.workspace.delete(
                WorkspaceDeleteRequest(
                    workspace_id=ws.workspace_id,
                    subaccount=ws.subaccount,
                )
            )

asyncio.run(main())
```

## API surface

- **`MaraDocsClient` / `AsyncMaraDocsClient`** — workspace operations: `data`, `img`, `pdf`, `html`, `email`, `audio`, `video`, `flow`, `healthcheck`, and `info` (`WorkspaceInfo`).
- **`MaraDocsServer` / `AsyncMaraDocsServer`** — account operations: `account`, `workspace`, `webview`, `healthcheck`.

Pydantic models live under `maradocs.models` (e.g. `from maradocs.models.pdf import ok_pdf`).

Upload and flow helpers accept a `pathlib.Path` (name and size inferred) or a binary stream (`name=` required; `size=` inferred when the stream is seekable):

```python
from pathlib import Path

client.data.upload(Path("scan.jpg"))
client.flow.ocr_img(Path("scan.jpg"))

with open("scan.jpg", "rb") as f:
    client.data.upload(f, name="scan.jpg")
```

Per-request timeout override:

```python
from maradocs import RequestOptions

client.pdf.validate(req, request_options=RequestOptions(timeout_ms=120_000))
```

SDK errors subclass `MaraDocsError` (`ApiErrorException`, `ValidationErrorException`, `ValidationVirusException`, `PollTimeoutError`, `TransferError`).

## Development

```bash
pip install -e ".[dev]"
ruff check .
ruff format .
```

## License

MIT — see [LICENSE.md](LICENSE.md).
