fastocr-sdk 0.1.0__py3-none-any.whl

fastocr_sdk/__init__.py

@@ -0,0 +1,53 @@
+"""FastOCR Python SDK for the Document OCR API."""
+
+from ._version import __version__
+from .async_client import AsyncFastOCR
+from .client import FastOCR
+from .errors import (
+    APIConnectionError,
+    AuthenticationError,
+    BadRequestError,
+    DocumentConflictError,
+    DocumentFailedError,
+    DownloadError,
+    FastOCRError,
+    NotFoundError,
+    PartialResultError,
+    PollingTimeoutError,
+    RateLimitError,
+    ServerError,
+    UploadError,
+)
+from .models import (
+    DocumentCreateResponse,
+    DocumentJob,
+    DocumentListResponse,
+    DocumentOutputs,
+    DocumentOutputUrl,
+    JobError,
+)
+
+__all__ = [
+    "__version__",
+    "FastOCR",
+    "AsyncFastOCR",
+    "DocumentJob",
+    "DocumentCreateResponse",
+    "DocumentOutputs",
+    "DocumentOutputUrl",
+    "DocumentListResponse",
+    "JobError",
+    "FastOCRError",
+    "APIConnectionError",
+    "AuthenticationError",
+    "BadRequestError",
+    "DocumentConflictError",
+    "DocumentFailedError",
+    "DownloadError",
+    "NotFoundError",
+    "PartialResultError",
+    "PollingTimeoutError",
+    "RateLimitError",
+    "ServerError",
+    "UploadError",
+]

fastocr_sdk/_core.py

@@ -0,0 +1,318 @@
+"""Logic shared by the sync and async clients. No I/O happens here."""
+import asyncio
+import os
+import random
+import re
+import uuid
+from pathlib import Path
+from typing import Any, AsyncIterator, BinaryIO, Dict, FrozenSet, Iterator, Optional, Tuple, Union
+from urllib.parse import quote
+
+import httpx
+
+from ._version import __version__
+from .errors import (
+    AuthenticationError,
+    BadRequestError,
+    DocumentConflictError,
+    DocumentFailedError,
+    DownloadError,
+    FastOCRError,
+    NotFoundError,
+    PartialResultError,
+    RateLimitError,
+    ServerError,
+    UploadError,
+)
+from .models import DocumentJob, JobError
+
+DEFAULT_BASE_URL = "https://api.fastocr.org"
+DEFAULT_MAX_RETRIES = 2
+MAX_RETRY_DELAY = 60.0
+BACKOFF_BASE = 0.5
+THROTTLE_BACKOFF_BASE = 1.0
+BACKOFF_CAP = 8.0
+CHUNK_SIZE = 1024 * 1024
+TRANSFER_TIMEOUT = httpx.Timeout(120.0, connect=10.0)
+
+API_RETRY_STATUSES: FrozenSet[int] = frozenset({429, 502, 503, 504})
+TRANSFER_RETRY_STATUSES: FrozenSet[int] = frozenset({500, 502, 503, 504})
+
+FileInput = Union[str, Path, bytes, BinaryIO]
+
+
+def resolve_api_key(api_key: Optional[str]) -> str:
+    key = (api_key or os.environ.get("FASTOCR_API_KEY") or "").strip()
+    if not key:
+        raise AuthenticationError("API key must be provided or set via FASTOCR_API_KEY environment variable")
+    return key
+
+
+def resolve_base_url(base_url: Optional[str]) -> str:
+    return (base_url or os.environ.get("FASTOCR_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+
+
+def default_headers(api_key: str) -> Dict[str, str]:
+    return {
+        "Authorization": f"Bearer {api_key}",
+        "User-Agent": f"fastocr-python/{__version__}",
+    }
+
+
+def new_idempotency_key() -> str:
+    return str(uuid.uuid4())
+
+
+def check_pdf_filename(filename: str) -> None:
+    if not filename.lower().endswith(".pdf"):
+        raise ValueError("FastOCR Document API accepts PDF files only (.pdf)")
+
+
+def check_output_format(file_format: str) -> None:
+    if file_format not in ("text", "pdf"):
+        raise ValueError("file_format must be either 'text' or 'pdf'")
+
+
+def create_payload(
+    filename: str, size_bytes: int, external_id: Optional[str], sha256: Optional[str]
+) -> Dict[str, Any]:
+    check_pdf_filename(filename)
+    payload: Dict[str, Any] = {"filename": filename, "size_bytes": size_bytes}
+    if external_id is not None:
+        payload["external_id"] = external_id
+    if sha256 is not None:
+        payload["sha256"] = sha256
+    return payload
+
+
+def list_params(
+    limit: Optional[int], status: Optional[str], cursor: Optional[str], updated_since: Optional[str]
+) -> Dict[str, Any]:
+    values = {"limit": limit, "status": status, "cursor": cursor, "updated_since": updated_since}
+    return {name: value for name, value in values.items() if value is not None}
+
+
+def document_path(document_id: str, suffix: str = "") -> str:
+    return f"/v1/documents/{quote(document_id, safe='')}{suffix}"
+
+
+def parse_json(response: httpx.Response) -> Dict[str, Any]:
+    if not response.content:
+        return {}
+    try:
+        body = response.json()
+    except ValueError as exc:
+        raise ServerError(
+            "FastOCR returned a response that is not valid JSON",
+            status_code=response.status_code,
+        ) from exc
+    if not isinstance(body, dict):
+        raise ServerError(
+            "FastOCR returned a response that is not a JSON object",
+            status_code=response.status_code,
+        )
+    return body
+
+
+def parse_retry_after(value: Optional[str]) -> Optional[float]:
+    try:
+        seconds = float(value) if value is not None else None
+    except ValueError:
+        return None
+    return seconds if seconds is not None and seconds >= 0 else None
+
+
+def error_from_response(response: httpx.Response) -> FastOCRError:
+    """Build the right exception from a non-2xx API response.
+
+    Handlers send {"error": {type, code, message, request_id}}. API Gateway sends
+    {"message": ...} (an `error` object may be added next to it).
+    """
+    status = response.status_code
+    try:
+        body = response.json()
+    except ValueError:
+        body = None
+    details = body if isinstance(body, dict) else {}
+    nested = details.get("error")
+    fields = nested if isinstance(nested, dict) else {}
+    message = (
+        fields.get("message")
+        or details.get("message")
+        or (nested if isinstance(nested, str) else None)
+        or (response.text[:200].strip() if body is None else "")
+        or f"HTTP {status}"
+    )
+    options: Dict[str, Any] = {
+        "status_code": status,
+        "code": fields.get("code") or details.get("code"),
+        "type": fields.get("type"),
+        "request_id": fields.get("request_id") or response.headers.get("x-amzn-requestid"),
+        "details": details,
+    }
+    message = str(message)
+    if status == 429:
+        retry_after = parse_retry_after(response.headers.get("Retry-After"))
+        return RateLimitError(message, retry_after=retry_after, **options)
+    if status in (401, 403):
+        return AuthenticationError(message, **options)
+    error_class = {400: BadRequestError, 404: NotFoundError, 409: DocumentConflictError}.get(status)
+    if error_class is None:
+        error_class = ServerError if status >= 500 else FastOCRError
+    return error_class(message, **options)
+
+
+def transfer_error(error_class: type, action: str, response: httpx.Response) -> FastOCRError:
+    code = re.search(r"<Code>([^<]+)</Code>", response.text[:2000])
+    detail = f" ({code.group(1)})" if code else ""
+    return error_class(
+        f"Failed to {action}: status {response.status_code}{detail}",
+        status_code=response.status_code,
+        code=code.group(1) if code else None,
+    )
+
+
+def upload_error_from_response(response: httpx.Response) -> FastOCRError:
+    return transfer_error(UploadError, "upload the document to the presigned URL", response)
+
+
+def download_error_from_response(response: httpx.Response) -> FastOCRError:
+    return transfer_error(DownloadError, "download the result from the presigned URL", response)
+
+
+def retry_delay(
+    error: FastOCRError, attempt: int, max_retries: int, statuses: FrozenSet[int]
+) -> Optional[float]:
+    """Seconds to wait before retrying, or None if this error must be raised."""
+    if attempt >= max_retries:
+        return None
+    if error.status_code is not None and error.status_code not in statuses:
+        return None
+    retry_after = getattr(error, "retry_after", None)
+    if retry_after is not None:
+        return retry_after if retry_after <= MAX_RETRY_DELAY else None
+    base = THROTTLE_BACKOFF_BASE if error.status_code == 429 else BACKOFF_BASE
+    ceiling = min(BACKOFF_CAP, base * 2 ** attempt)
+    return ceiling / 2 + random.uniform(0, ceiling / 2)
+
+
+def upload_headers(size: int, sha256: Optional[str]) -> Dict[str, str]:
+    # S3 rejects chunked uploads, so Content-Length is always explicit.
+    headers = {"Content-Type": "application/pdf", "Content-Length": str(size)}
+    if sha256 is not None:
+        headers["x-amz-checksum-sha256"] = sha256
+    return headers
+
+
+def failed_error(job: DocumentJob) -> DocumentFailedError:
+    error = job.error or JobError(code="processing_failed", message="Document processing failed", retryable=True)
+    return DocumentFailedError(
+        error.message or "Document processing failed",
+        document_id=job.id,
+        code=error.code,
+        retryable=error.retryable,
+        type=error.type or None,
+        details=job.raw.get("error") if isinstance(job.raw.get("error"), dict) else None,
+    )
+
+
+def partial_error(job: DocumentJob) -> PartialResultError:
+    done = job.pages_billed if job.pages_billed is not None else job.pages_processed
+    scope = "only partly processed"
+    if done is not None:
+        scope = f"only {done}" + (f" of {job.pages_total}" if job.pages_total is not None else "") + " pages were processed"
+    return PartialResultError(
+        f"Document {job.id} is partial: {scope} because the account ran out of pages. "
+        "Use documents.get_text() for the partial text, or pass allow_partial=True.",
+        document_id=job.id,
+        pages_processed=job.pages_processed,
+        pages_billed=job.pages_billed,
+        pages_total=job.pages_total,
+    )
+
+
+class UploadSource:
+    """A file to upload: its size, and a fresh body for every attempt.
+
+    Paths and seekable streams are read in chunks, never loaded whole. A stream
+    that cannot seek has no known size, so it is read into memory.
+    """
+
+    def __init__(self, file: FileInput):
+        self._data: Optional[bytes] = None
+        self._path: Optional[Path] = None
+        self._stream: Optional[BinaryIO] = None
+        self._start = 0
+        if isinstance(file, (str, Path)):
+            self._path = Path(file)
+            self.size = self._path.stat().st_size
+        elif isinstance(file, (bytes, bytearray)):
+            self._data = bytes(file)
+            self.size = len(self._data)
+        elif hasattr(file, "read"):
+            self._init_stream(file)
+        else:
+            raise TypeError("Expected file path, bytes, or file-like object")
+
+    def _init_stream(self, stream: BinaryIO) -> None:
+        if getattr(stream, "seekable", lambda: False)():
+            self._stream = stream
+            self._start = stream.tell()
+            self.size = stream.seek(0, os.SEEK_END) - self._start
+            stream.seek(self._start)
+        else:
+            self._data = stream.read()
+            self.size = len(self._data)
+
+    def _open(self) -> Tuple[BinaryIO, bool]:
+        if self._path is not None:
+            return open(self._path, "rb"), True
+        assert self._stream is not None
+        self._stream.seek(self._start)
+        return self._stream, False
+
+    def sync_body(self) -> Union[bytes, Iterator[bytes]]:
+        if self._data is not None:
+            return self._data
+        return self._read_sync()
+
+    def async_body(self) -> Union[bytes, AsyncIterator[bytes]]:
+        if self._data is not None:
+            return self._data
+        return self._read_async()
+
+    def _read_sync(self) -> Iterator[bytes]:
+        source, owned = self._open()
+        try:
+            remaining = self.size
+            while remaining > 0:
+                chunk = source.read(min(CHUNK_SIZE, remaining))
+                if not chunk:
+                    return
+                remaining -= len(chunk)
+                yield chunk
+        finally:
+            if owned:
+                source.close()
+
+    async def _read_async(self) -> AsyncIterator[bytes]:
+        source, owned = self._open()
+        try:
+            remaining = self.size
+            while remaining > 0:
+                chunk = await asyncio.to_thread(source.read, min(CHUNK_SIZE, remaining))
+                if not chunk:
+                    return
+                remaining -= len(chunk)
+                yield chunk
+        finally:
+            if owned:
+                source.close()
+
+
+def filename_for(file: FileInput, filename: Optional[str]) -> str:
+    if filename:
+        return filename
+    if isinstance(file, (str, Path)):
+        return Path(file).name
+    return "document.pdf"

fastocr_sdk/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

fastocr_sdk/async_client.py

@@ -0,0 +1,290 @@
+"""Asynchronous FastOCR client. Behaves exactly like the sync client."""
+import asyncio
+import os
+import time
+from pathlib import Path
+from typing import Any, BinaryIO, Awaitable, Callable, Dict, FrozenSet, Optional, TypeVar, Union
+
+import httpx
+
+from . import _core
+from .errors import (
+    APIConnectionError,
+    DownloadError,
+    FastOCRError,
+    PollingTimeoutError,
+    UploadError,
+)
+from .models import (
+    DocumentCreateResponse,
+    DocumentJob,
+    DocumentListResponse,
+    DocumentOutputUrl,
+)
+
+T = TypeVar("T")
+
+
+class AsyncDocumentsResource:
+    """Document OCR operations (`/v1/documents`)."""
+
+    def __init__(self, client: "AsyncFastOCR"):
+        self._client = client
+
+    async def create(
+        self,
+        filename: str,
+        size_bytes: int,
+        idempotency_key: Optional[str] = None,
+        external_id: Optional[str] = None,
+        sha256: Optional[str] = None,
+    ) -> DocumentCreateResponse:
+        """Create a document and get a presigned upload URL.
+
+        The same `idempotency_key` is sent on every retry of this call, so a retry
+        can never create a second document.
+        """
+        payload = _core.create_payload(filename, size_bytes, external_id, sha256)
+        headers = {"Idempotency-Key": idempotency_key or _core.new_idempotency_key()}
+        resp = await self._client._request("POST", "/v1/documents", json=payload, headers=headers)
+        return DocumentCreateResponse.from_dict(resp)
+
+    async def upload(
+        self,
+        upload_url: str,
+        file: Union[str, Path, bytes, BinaryIO],
+        sha256: Optional[str] = None,
+    ) -> None:
+        """PUT the file to the presigned URL. Paths and seekable streams are streamed from disk.
+
+        `sha256` (base64 of the raw 32-byte digest) is only needed if you passed it to `create`;
+        S3 checks it on upload.
+        """
+        await self._upload_source(upload_url, _core.UploadSource(file), sha256)
+
+    async def _upload_source(self, upload_url: str, source: _core.UploadSource, sha256: Optional[str]) -> None:
+        headers = _core.upload_headers(source.size, sha256)
+
+        async def attempt() -> None:
+            try:
+                async with httpx.AsyncClient(timeout=_core.TRANSFER_TIMEOUT) as uploader:
+                    res = await uploader.put(upload_url, content=source.async_body(), headers=headers)
+            except httpx.RequestError as exc:
+                raise UploadError(f"Network error while uploading the document: {exc}") from exc
+            if not res.is_success:
+                raise _core.upload_error_from_response(res)
+
+        await self._client._retry(attempt, _core.TRANSFER_RETRY_STATUSES)
+
+    async def start(self, document_id: str) -> Dict[str, Any]:
+        """Start OCR on an uploaded document, or run a `buy_pages` failure again after adding pages."""
+        return await self._client._request("POST", _core.document_path(document_id, "/start"))
+
+    async def get(self, document_id: str) -> DocumentJob:
+        resp = await self._client._request("GET", _core.document_path(document_id))
+        return DocumentJob.from_dict(resp)
+
+    async def list(
+        self,
+        limit: Optional[int] = None,
+        status: Optional[str] = None,
+        cursor: Optional[str] = None,
+        updated_since: Optional[str] = None,
+    ) -> DocumentListResponse:
+        params = _core.list_params(limit, status, cursor, updated_since)
+        resp = await self._client._request("GET", "/v1/documents", params=params)
+        return DocumentListResponse.from_dict(resp)
+
+    async def delete(self, document_id: str) -> Dict[str, Any]:
+        """Delete a document and its files. Cleanup is asynchronous."""
+        return await self._client._request("DELETE", _core.document_path(document_id))
+
+    async def get_output_url(self, document_id: str, file_format: str = "text") -> DocumentOutputUrl:
+        """Get a presigned download URL (valid one hour) for `text` or `pdf`."""
+        _core.check_output_format(file_format)
+        resp = await self._client._request(
+            "GET", _core.document_path(document_id, "/output"), params={"format": file_format}
+        )
+        return DocumentOutputUrl.from_dict(resp)
+
+    async def get_text(self, document_id: str) -> str:
+        """Download the extracted text."""
+        url = (await self.get_output_url(document_id, "text")).url
+
+        async def attempt() -> bytes:
+            try:
+                async with httpx.AsyncClient(timeout=_core.TRANSFER_TIMEOUT) as downloader:
+                    res = await downloader.get(url)
+            except httpx.RequestError as exc:
+                raise DownloadError(f"Network error while downloading the text: {exc}") from exc
+            if not res.is_success:
+                raise _core.download_error_from_response(res)
+            return res.content
+
+        return (await self._client._retry(attempt, _core.TRANSFER_RETRY_STATUSES)).decode("utf-8")
+
+    async def download_searchable_pdf(self, document_id: str, destination: Union[str, Path, BinaryIO]) -> None:
+        """Download the searchable PDF to a path or a writable binary stream.
+
+        A path is written atomically and retried on transient failures. A stream is
+        tried once, because a partial write cannot be undone.
+        """
+        url = (await self.get_output_url(document_id, "pdf")).url
+        if isinstance(destination, (str, Path)):
+            await self._download_to_path(url, Path(destination))
+        else:
+            await self._stream_pdf(url, destination)
+
+    async def _stream_pdf(self, url: str, sink: BinaryIO) -> None:
+        try:
+            async with httpx.AsyncClient(timeout=_core.TRANSFER_TIMEOUT) as downloader:
+                async with downloader.stream("GET", url) as response:
+                    if not response.is_success:
+                        await response.aread()
+                        raise _core.download_error_from_response(response)
+                    async for chunk in response.aiter_bytes():
+                        sink.write(chunk)
+        except httpx.RequestError as exc:
+            raise DownloadError(f"Network error while downloading the PDF: {exc}") from exc
+
+    async def _download_to_path(self, url: str, destination: Path) -> None:
+        partial = destination.with_name(destination.name + ".part")
+
+        async def attempt() -> None:
+            with open(partial, "wb") as sink:
+                await self._stream_pdf(url, sink)
+
+        try:
+            await self._client._retry(attempt, _core.TRANSFER_RETRY_STATUSES)
+            os.replace(partial, destination)
+        finally:
+            partial.unlink(missing_ok=True)
+
+    async def wait_for_completion(
+        self,
+        document_id: str,
+        timeout: float = 300.0,
+        poll_interval: float = 2.0,
+    ) -> DocumentJob:
+        """Poll until the document is `completed` or `partial`.
+
+        Raises DocumentFailedError if it fails and PollingTimeoutError on timeout.
+        An unrecognized status counts as still processing.
+        """
+        deadline = time.monotonic() + timeout
+        while True:
+            job = await self.get(document_id)
+            if job.is_completed:
+                return job
+            if job.is_failed:
+                raise _core.failed_error(job)
+            if time.monotonic() >= deadline:
+                raise PollingTimeoutError(
+                    f"Document {document_id} did not finish processing within {timeout} seconds",
+                    document_id=document_id,
+                    last_status=job.status,
+                )
+            await self._client._sleep(poll_interval)
+
+    async def process(
+        self,
+        file: Union[str, Path, bytes, BinaryIO],
+        filename: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+        external_id: Optional[str] = None,
+        sha256: Optional[str] = None,
+        timeout: float = 300.0,
+        poll_interval: float = 2.0,
+    ) -> DocumentJob:
+        """Create, upload, start, and wait. Returns the finished job.
+
+        One idempotency key covers the whole call. Pass your own to make a repeated
+        `process()` for the same file safe: it finds the same document and, if that
+        document was already uploaded or started, just waits for it.
+        """
+        source = _core.UploadSource(file)
+        name = _core.filename_for(file, filename)
+        key = idempotency_key or _core.new_idempotency_key()
+        created = await self.create(name, source.size, idempotency_key=key, external_id=external_id, sha256=sha256)
+        if idempotency_key and (await self.get(created.id)).status != "awaiting_upload":
+            return await self.wait_for_completion(created.id, timeout=timeout, poll_interval=poll_interval)
+        await self._upload_source(created.upload_url, source, sha256)
+        await self.start(created.id)
+        return await self.wait_for_completion(created.id, timeout=timeout, poll_interval=poll_interval)
+
+
+class AsyncFastOCR:
+    """Asynchronous FastOCR API client.
+
+    `max_retries` bounds retries of connection errors, 429 (honoring Retry-After)
+    and 502/503/504. Other errors are raised immediately.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+        max_retries: int = _core.DEFAULT_MAX_RETRIES,
+    ):
+        self.api_key = _core.resolve_api_key(api_key)
+        self.base_url = _core.resolve_base_url(base_url)
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._sleep: Callable[[float], Awaitable[None]] = asyncio.sleep
+        self._http = httpx.AsyncClient(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers=_core.default_headers(self.api_key),
+        )
+        self.documents = AsyncDocumentsResource(self)
+
+    async def extract_text(
+        self,
+        file: Union[str, Path, bytes, BinaryIO],
+        timeout: float = 300.0,
+        allow_partial: bool = False,
+    ) -> str:
+        """Process a PDF and return its text.
+
+        Raises PartialResultError if the account ran out of pages partway through, so
+        truncated text is never returned silently. Pass `allow_partial=True` to get the
+        text of the processed pages instead.
+        """
+        job = await self.documents.process(file, timeout=timeout)
+        if job.is_partial and not allow_partial:
+            raise _core.partial_error(job)
+        return await self.documents.get_text(job.id)
+
+    async def _retry(self, attempt: Callable[[], Awaitable[T]], statuses: FrozenSet[int]) -> T:
+        retries = 0
+        while True:
+            try:
+                return await attempt()
+            except FastOCRError as error:
+                delay = _core.retry_delay(error, retries, self.max_retries, statuses)
+                if delay is None:
+                    raise
+                retries += 1
+                await self._sleep(delay)
+
+    async def _request(self, method: str, path: str, **kwargs: Any) -> Dict[str, Any]:
+        async def attempt() -> Dict[str, Any]:
+            try:
+                res = await self._http.request(method, path, **kwargs)
+            except httpx.RequestError as exc:
+                raise APIConnectionError(f"Network request to FastOCR API failed: {exc}") from exc
+            if res.is_success:
+                return _core.parse_json(res)
+            raise _core.error_from_response(res)
+
+        return await self._retry(attempt, _core.API_RETRY_STATUSES)
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncFastOCR":
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        await self.close()