doc-cheap 0.1.0__py3-none-any.whl

doc_cheap/__init__.py

@@ -0,0 +1,99 @@
+"""A typed Python client for the doc.cheap document-recognition API.
+
+>>> from doc_cheap import Client, SANDBOX_KEY
+>>> with Client(SANDBOX_KEY) as client:  # doctest: +SKIP
+...     scan = client.recognize(path="passport.jpg")
+...     print(scan["meta"]["status"], scan["holder"])
+"""
+
+from ._client import (
+    API_KEY_ENV,
+    BASE_URL_ENV,
+    DEFAULT_BASE_URL,
+    MAX_IMAGE_BYTES,
+    SANDBOX_KEY,
+    Client,
+)
+from ._errors import (
+    APIConnectionError,
+    APIError,
+    AuthenticationError,
+    ConflictError,
+    DocCheapError,
+    InsufficientCreditsError,
+    InternalServerError,
+    InvalidArgumentError,
+    InvalidRequestError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServiceUnavailableError,
+)
+from ._types import (
+    Confidence,
+    CreditsByKind,
+    FreeAllowance,
+    Scan,
+    ScanAuthenticity,
+    ScanCheck,
+    ScanDeletion,
+    ScanDocument,
+    ScanField,
+    ScanHolder,
+    ScanImages,
+    ScanList,
+    ScanMeta,
+    ScanMRZ,
+    ScanQuality,
+    ScanSummary,
+    ScanTiming,
+    Status,
+    Usage,
+    UsagePeriod,
+    UsageScans,
+)
+from ._version import __version__
+
+__all__ = [
+    "API_KEY_ENV",
+    "BASE_URL_ENV",
+    "DEFAULT_BASE_URL",
+    "MAX_IMAGE_BYTES",
+    "SANDBOX_KEY",
+    "APIConnectionError",
+    "APIError",
+    "AuthenticationError",
+    "Client",
+    "Confidence",
+    "ConflictError",
+    "CreditsByKind",
+    "DocCheapError",
+    "FreeAllowance",
+    "InsufficientCreditsError",
+    "InternalServerError",
+    "InvalidArgumentError",
+    "InvalidRequestError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "Scan",
+    "ScanAuthenticity",
+    "ScanCheck",
+    "ScanDeletion",
+    "ScanDocument",
+    "ScanField",
+    "ScanHolder",
+    "ScanImages",
+    "ScanList",
+    "ScanMRZ",
+    "ScanMeta",
+    "ScanQuality",
+    "ScanSummary",
+    "ScanTiming",
+    "ServiceUnavailableError",
+    "Status",
+    "Usage",
+    "UsagePeriod",
+    "UsageScans",
+    "__version__",
+]

doc_cheap/_client.py

@@ -0,0 +1,284 @@
+"""The synchronous client for the doc.cheap API."""
+
+from __future__ import annotations
+
+import base64
+import os
+import re
+from collections.abc import Mapping
+from pathlib import Path
+from types import TracebackType
+from typing import Any, Union, cast
+from urllib.parse import quote
+
+import httpx
+
+from ._errors import APIConnectionError, DocCheapError, InvalidArgumentError, error_from_response
+from ._types import Scan, ScanDeletion, ScanList, Usage
+from ._version import __version__
+
+DEFAULT_BASE_URL = "https://api.doc.cheap"
+"""The API the client talks to unless told otherwise."""
+
+SANDBOX_KEY = "sk_sandbox_public"
+"""A public key that works without an account and never draws credits."""
+
+MAX_IMAGE_BYTES = 25 * 1024 * 1024
+"""The largest image the API accepts, measured before base64 encoding."""
+
+API_KEY_ENV = "DOC_CHEAP_API_KEY"
+BASE_URL_ENV = "DOC_CHEAP_API_BASE"
+
+_MAX_REFERENCE_LENGTH = 128
+_MAX_IDEMPOTENCY_KEY_LENGTH = 255
+_MAX_CURSOR_LENGTH = 256
+_MAX_RETAIN_HOURS = 8760
+_MAX_LIST_LIMIT = 100
+_COUNTRY_CODE = re.compile(r"[A-Z]{3}")
+_DATA_URL_PREFIX = re.compile(r"^data:[^,]*;base64,", re.IGNORECASE)
+
+StrPath = Union[str, "os.PathLike[str]"]
+
+
+def _default_user_agent() -> str:
+    return f"doc-cheap-python/{__version__} (+https://gitlab.com/doccheap/doc-cheap-python)"
+
+
+def _decoded_length(encoded: str) -> int:
+    # The size the API will see after decoding, without decoding a string
+    # that may be tens of megabytes only to measure it.
+    return len(encoded) * 3 // 4
+
+
+class Client:
+    """Calls the doc.cheap API.
+
+    Args:
+        api_key: The API key. When omitted it is read from the
+            ``DOC_CHEAP_API_KEY`` environment variable. A live key starts with
+            ``sk_live_``; :data:`SANDBOX_KEY` works without an account.
+        base_url: The API address. When omitted it is read from
+            ``DOC_CHEAP_API_BASE``, else :data:`DEFAULT_BASE_URL`.
+        timeout: Seconds to wait for an answer. Ignored when ``http_client``
+            is given.
+        http_client: An ``httpx.Client`` to send the requests through, for a
+            proxy, custom transport or shared connection pool. The caller
+            keeps ownership of it: :meth:`close` leaves it open.
+        user_agent: A product token put in front of the client's own
+            ``User-Agent``, so an application's requests can be told apart.
+
+    The client is safe to share between threads, like the ``httpx.Client``
+    under it. Use it as a context manager, or call :meth:`close`, to release
+    its connections.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = 60.0,
+        http_client: httpx.Client | None = None,
+        user_agent: str | None = None,
+    ) -> None:
+        key = api_key if api_key is not None else os.environ.get(API_KEY_ENV)
+        if not key:
+            raise DocCheapError(
+                f"no API key: pass api_key or set {API_KEY_ENV} "
+                f"(the public sandbox key is {SANDBOX_KEY!r})"
+            )
+        self._api_key = key
+        base = base_url or os.environ.get(BASE_URL_ENV) or DEFAULT_BASE_URL
+        self._base_url = base.rstrip("/")
+        agent = _default_user_agent()
+        if user_agent and user_agent.strip():
+            agent = f"{user_agent.strip()} {agent}"
+        self._user_agent = agent
+        self._owns_http_client = http_client is None
+        self._http = http_client if http_client is not None else httpx.Client(timeout=timeout)
+
+    @property
+    def base_url(self) -> str:
+        """The API address requests are sent to."""
+        return self._base_url
+
+    def close(self) -> None:
+        """Releases the connections of the HTTP client this client created."""
+        if self._owns_http_client:
+            self._http.close()
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def recognize(
+        self,
+        *,
+        image: bytes | None = None,
+        image_base64: str | None = None,
+        path: StrPath | None = None,
+        reference: str | None = None,
+        idempotency_key: str | None = None,
+        expect_country: str | None = None,
+        return_portrait: bool | None = None,
+        retain_hours: int | None = None,
+    ) -> Scan:
+        """Sends one image and returns what was read from it.
+
+        Give exactly one of ``image`` (raw JPEG or PNG bytes), ``image_base64``
+        (the same bytes as standard base64, a ``data:`` URL prefix allowed) or
+        ``path`` (a file to read).
+
+        An image that holds no readable document is not an error: the scan
+        comes back with a status other than ``"recognized"`` and
+        ``scan["meta"]["billed"]`` set to ``False``.
+
+        Args:
+            reference: A label of up to 128 characters, stored with the scan
+                and returned with it.
+            idempotency_key: When set, a retried request returns the first
+                answer instead of reading the document twice. Up to 255
+                characters.
+            expect_country: The issuing country you expect, as three
+                upper-case letters (ISO 3166-1 alpha-3).
+            return_portrait: Whether to return the holder's portrait image.
+            retain_hours: How long the API keeps the scan, from 0 to 8760.
+        """
+        body: dict[str, Any] = {"image": self._image(image, image_base64, path)}
+        if reference:
+            if len(reference) > _MAX_REFERENCE_LENGTH:
+                raise InvalidArgumentError(
+                    f"reference is {len(reference)} characters, "
+                    f"the limit is {_MAX_REFERENCE_LENGTH}"
+                )
+            body["reference"] = reference
+        options: dict[str, Any] = {}
+        if expect_country:
+            if not _COUNTRY_CODE.fullmatch(expect_country):
+                raise InvalidArgumentError(
+                    f"expect_country {expect_country!r} is not three upper-case letters"
+                )
+            options["expect_country"] = expect_country
+        if return_portrait is not None:
+            options["return_portrait"] = bool(return_portrait)
+        if retain_hours is not None:
+            if isinstance(retain_hours, bool) or not 0 <= retain_hours <= _MAX_RETAIN_HOURS:
+                raise InvalidArgumentError(
+                    f"retain_hours {retain_hours!r} is outside 0..{_MAX_RETAIN_HOURS}"
+                )
+            options["retain_hours"] = retain_hours
+        if options:
+            body["options"] = options
+        headers: dict[str, str] = {}
+        if idempotency_key:
+            if len(idempotency_key) > _MAX_IDEMPOTENCY_KEY_LENGTH:
+                raise InvalidArgumentError(
+                    f"idempotency_key is {len(idempotency_key)} characters, "
+                    f"the limit is {_MAX_IDEMPOTENCY_KEY_LENGTH}"
+                )
+            headers["Idempotency-Key"] = idempotency_key
+        return cast(Scan, self._request("POST", "/v1/scans", json=body, headers=headers))
+
+    def get_scan(self, scan_id: str) -> Scan:
+        """Returns a stored scan by its id."""
+        return cast(Scan, self._request("GET", self._scan_path(scan_id)))
+
+    def list_scans(self, *, limit: int | None = None, cursor: str | None = None) -> ScanList:
+        """Returns one page of stored scans, newest first.
+
+        Args:
+            limit: The page size, from 1 to 100. The API's default when omitted.
+            cursor: The ``next_cursor`` of the previous page. It is ``None`` on
+                the last page.
+        """
+        params: dict[str, str] = {}
+        if limit is not None:
+            if isinstance(limit, bool) or not 1 <= limit <= _MAX_LIST_LIMIT:
+                raise InvalidArgumentError(f"limit {limit!r} is outside 1..{_MAX_LIST_LIMIT}")
+            params["limit"] = str(limit)
+        if cursor:
+            if len(cursor) > _MAX_CURSOR_LENGTH:
+                raise InvalidArgumentError(
+                    f"cursor is {len(cursor)} characters, the limit is {_MAX_CURSOR_LENGTH}"
+                )
+            params["cursor"] = cursor
+        return cast(ScanList, self._request("GET", "/v1/scans", params=params))
+
+    def delete_scan(self, scan_id: str) -> ScanDeletion:
+        """Deletes a stored scan by its id."""
+        return cast(ScanDeletion, self._request("DELETE", self._scan_path(scan_id)))
+
+    def usage(self) -> Usage:
+        """Returns the account's balance and what was spent in the current period."""
+        return cast(Usage, self._request("GET", "/v1/usage"))
+
+    @staticmethod
+    def _scan_path(scan_id: str) -> str:
+        if not scan_id:
+            raise InvalidArgumentError("a scan id is required")
+        return "/v1/scans/" + quote(scan_id, safe="")
+
+    @staticmethod
+    def _image(image: bytes | None, image_base64: str | None, path: StrPath | None) -> str:
+        given = sum(source is not None for source in (image, image_base64, path))
+        if given != 1:
+            raise InvalidArgumentError("give exactly one of image, image_base64 or path")
+        if path is not None:
+            try:
+                image = Path(path).read_bytes()
+            except OSError as exc:
+                raise InvalidArgumentError(f"cannot read the image file: {exc}") from exc
+        if image is not None:
+            if not image:
+                raise InvalidArgumentError("the image is empty")
+            if len(image) > MAX_IMAGE_BYTES:
+                raise InvalidArgumentError(
+                    f"image is {len(image)} bytes, the limit is {MAX_IMAGE_BYTES}"
+                )
+            return base64.b64encode(image).decode("ascii")
+        encoded = _DATA_URL_PREFIX.sub("", cast(str, image_base64).strip(), count=1)
+        if not encoded:
+            raise InvalidArgumentError("the image is empty")
+        if _decoded_length(encoded) > MAX_IMAGE_BYTES + 2:
+            raise InvalidArgumentError(f"image is larger than {MAX_IMAGE_BYTES} bytes")
+        return encoded
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Mapping[str, Any] | None = None,
+        params: Mapping[str, str] | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> Any:
+        request_headers = {
+            "Accept": "application/json",
+            "Authorization": f"Bearer {self._api_key}",
+            "User-Agent": self._user_agent,
+        }
+        if headers:
+            request_headers.update(headers)
+        try:
+            response = self._http.request(
+                method,
+                self._base_url + path,
+                json=json,
+                params=params or None,
+                headers=request_headers,
+            )
+        except httpx.HTTPError as exc:
+            raise APIConnectionError(f"{method} {path}: {exc}") from exc
+        if not response.is_success:
+            raise error_from_response(response)
+        try:
+            return response.json()
+        except ValueError as exc:
+            raise DocCheapError(f"{method} {path}: the answer is not JSON") from exc

doc_cheap/_errors.py

@@ -0,0 +1,184 @@
+"""The exceptions the client raises.
+
+Every failure is a :class:`DocCheapError`. An answer from the API with an
+error status is an :class:`APIError`, narrowed to a subclass by the API's own
+error code, so a caller can catch the case it handles (``NotFoundError``,
+``RateLimitError``) and let the rest propagate.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+
+import httpx
+
+# The error body is small JSON; anything larger is not one, and parsing it
+# whole would only hold memory for a message nobody can read.
+_MAX_ERROR_BODY_BYTES = 64 * 1024
+
+
+class DocCheapError(Exception):
+    """Base class of every exception this package raises."""
+
+
+class InvalidArgumentError(DocCheapError, ValueError):
+    """An argument the API would refuse, caught before any request is sent."""
+
+
+class APIConnectionError(DocCheapError):
+    """The request did not get an answer: a network failure or a timeout."""
+
+
+class APIError(DocCheapError):
+    """The API answered with a status outside 2xx.
+
+    Attributes:
+        status_code: The HTTP status, for example 401 or 404.
+        code: The API's machine-readable error code, for example
+            ``"unauthorized"``. When the body carries none it is ``"http_"``
+            followed by the status.
+        message: The API's human-readable explanation.
+        docs_url: The documentation page for ``code``, when the API gave one.
+        request_id: Identifies the request in the API's logs; quote it when
+            asking for help.
+        event_id: Identifies a recorded unexpected failure, or ``None``.
+        retry_after: Seconds to wait before retrying, from the ``Retry-After``
+            header of a 429 or 503 answer, or ``None`` when it is absent.
+    """
+
+    def __init__(
+        self,
+        *,
+        status_code: int,
+        code: str,
+        message: str,
+        docs_url: str | None = None,
+        request_id: str | None = None,
+        event_id: str | None = None,
+        retry_after: int | None = None,
+    ) -> None:
+        super().__init__(f"{status_code} {code}: {message}")
+        self.status_code = status_code
+        self.code = code
+        self.message = message
+        self.docs_url = docs_url
+        self.request_id = request_id
+        self.event_id = event_id
+        self.retry_after = retry_after
+
+
+class InvalidRequestError(APIError):
+    """The request was malformed, failed validation, or carried a bad image."""
+
+
+class AuthenticationError(APIError):
+    """The API key is missing, unknown or revoked."""
+
+
+class PermissionDeniedError(APIError):
+    """The key is valid but may not do this, for example before registration."""
+
+
+class InsufficientCreditsError(APIError):
+    """The account has no credits left for a billable scan."""
+
+
+class NotFoundError(APIError):
+    """The scan does not exist, was deleted, or was never stored."""
+
+
+class ConflictError(APIError):
+    """The request clashes with an earlier one, such as a reused idempotency key."""
+
+
+class RateLimitError(APIError):
+    """Too many requests; wait ``retry_after`` seconds before the next one."""
+
+
+class ServiceUnavailableError(APIError):
+    """The API cannot serve the request right now; retrying later may succeed."""
+
+
+class InternalServerError(APIError):
+    """The API failed unexpectedly; quote ``request_id`` and ``event_id``."""
+
+
+_BY_CODE: Mapping[str, type[APIError]] = {
+    "invalid_request": InvalidRequestError,
+    "validation_failed": InvalidRequestError,
+    "payload_too_large": InvalidRequestError,
+    "unsupported_media_type": InvalidRequestError,
+    "unauthorized": AuthenticationError,
+    "registration_required": PermissionDeniedError,
+    "impersonation_read_only": PermissionDeniedError,
+    "insufficient_credits": InsufficientCreditsError,
+    "not_found": NotFoundError,
+    "idempotency_conflict": ConflictError,
+    "idempotency_in_progress": ConflictError,
+    "idempotency_replay_unavailable": ConflictError,
+    "document_repeated": RateLimitError,
+    "topup_in_progress": ConflictError,
+    "rate_limited": RateLimitError,
+    "engine_unavailable": ServiceUnavailableError,
+    "service_unavailable": ServiceUnavailableError,
+    "maintenance": ServiceUnavailableError,
+    "payment_driver_unavailable": ServiceUnavailableError,
+    "rate_unavailable": ServiceUnavailableError,
+    "internal_error": InternalServerError,
+}
+
+# Used only when the body names no code this package knows, so an error from a
+# proxy in front of the API still lands in the class its status implies.
+_BY_STATUS: Mapping[int, type[APIError]] = {
+    400: InvalidRequestError,
+    401: AuthenticationError,
+    402: InsufficientCreditsError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    413: InvalidRequestError,
+    415: InvalidRequestError,
+    422: InvalidRequestError,
+    429: RateLimitError,
+    503: ServiceUnavailableError,
+}
+
+
+def _text(value: object) -> str | None:
+    return value if isinstance(value, str) and value else None
+
+
+def _retry_after(response: httpx.Response) -> int | None:
+    raw = response.headers.get("retry-after", "").strip()
+    if raw.isdigit() and int(raw) > 0:
+        return int(raw)
+    return None
+
+
+def error_from_response(response: httpx.Response) -> APIError:
+    """Builds the exception for an answer with an error status."""
+    body: object = None
+    content = response.content[:_MAX_ERROR_BODY_BYTES]
+    try:
+        body = json.loads(content)
+    except ValueError:
+        body = None
+    error = body.get("error") if isinstance(body, dict) else None
+    fields: dict[str, object] = error if isinstance(error, dict) else {}
+
+    status = response.status_code
+    code = _text(fields.get("code")) or f"http_{status}"
+    message = _text(fields.get("message")) or response.reason_phrase or f"HTTP {status}"
+    cls = _BY_CODE.get(code) or _BY_STATUS.get(status)
+    if cls is None:
+        cls = InternalServerError if status >= 500 else APIError
+    return cls(
+        status_code=status,
+        code=code,
+        message=message,
+        docs_url=_text(fields.get("docs_url")),
+        request_id=_text(fields.get("request_id")),
+        event_id=_text(fields.get("event_id")),
+        retry_after=_retry_after(response),
+    )

doc_cheap/_types.py

@@ -0,0 +1,177 @@
+"""The shapes of the API's answers, as typed dictionaries.
+
+The client returns the decoded JSON as it came, so every field the API adds
+later is still there; these types describe the fields known today, for editors
+and type checkers. Dates are ISO-8601 strings and country codes are ISO 3166-1
+alpha-3.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, TypedDict
+
+Status = Literal[
+    "recognized",
+    "no_document_found",
+    "unreadable",
+    "unsupported_document",
+    "rejected",
+]
+"""The outcome of one scan. Whether it was charged is ``meta["billed"]``."""
+
+Confidence = Literal["low", "medium", "high"]
+"""How strongly the recognition backs a value: a band rather than a number."""
+
+
+class ScanTiming(TypedDict):
+    upload_ms: int
+    processing_ms: int
+    total_ms: int
+
+
+class ScanMeta(TypedDict):
+    schema_version: str
+    id: str
+    status: Status
+    billed: bool
+    confidence: Confidence
+    timing: ScanTiming | None
+    created_at: str
+    reference: str | None
+
+
+class ScanDocument(TypedDict):
+    kind: str
+    country: str | None
+    country_name: str | None
+    issuing_state: str | None
+    type_name: str | None
+    type_confidence: Confidence
+    number: str | None
+    series: str | None
+    issue_date: str | None
+    expiry_date: str | None
+    is_expired: bool | None
+    days_remaining: int | None
+
+
+class ScanHolder(TypedDict):
+    given_names: str | None
+    surname: str | None
+    full_name: str | None
+    birth_date: str | None
+    sex: str | None
+    nationality: str | None
+
+
+class ScanField(TypedDict):
+    id: str
+    name: str
+    label: str
+    category: str
+    value: str | None
+    language: str | None
+    confidence: Confidence
+
+
+class ScanMRZ(TypedDict):
+    status: Literal["passed", "failed", "absent"]
+    reason: str | None
+    lines: list[str]
+    text: str | None
+
+
+class ScanImages(TypedDict):
+    """Image areas cut from the document, each a ``data:`` URL or ``None``."""
+
+    document_crop: str | None
+    rear: str | None
+    main_photo: str | None
+    signature: str | None
+    watermark_face: str | None
+    barcode: str | None
+    chip: str | None
+
+
+class ScanQuality(TypedDict):
+    overall: str
+
+
+class ScanCheck(TypedDict):
+    name: str
+    label: str
+    result: str
+    detail: str | None
+
+
+class ScanAuthenticity(TypedDict):
+    overall: str
+    checks: list[ScanCheck]
+
+
+class Scan(TypedDict):
+    """The full result of one recognition."""
+
+    meta: ScanMeta
+    document: ScanDocument | None
+    holder: ScanHolder | None
+    fields: list[ScanField]
+    mrz: ScanMRZ
+    images: ScanImages
+    quality: ScanQuality
+    authenticity: ScanAuthenticity
+
+
+class ScanSummary(TypedDict):
+    id: str
+    status: Status
+    billed: bool
+    duration_ms: int
+    reference: str | None
+    created_at: str
+
+
+class ScanList(TypedDict):
+    """One page of stored scans, newest first."""
+
+    scans: list[ScanSummary]
+    next_cursor: str | None
+
+
+class ScanDeletion(TypedDict):
+    id: str
+    deleted: bool
+
+
+class UsagePeriod(TypedDict):
+    start: str
+    end: str
+
+
+class UsageScans(TypedDict):
+    total: int
+    billed: int
+    by_status: dict[str, int]
+
+
+class FreeAllowance(TypedDict):
+    monthly_credits: int
+    remaining_credits: int
+    resets_at: str | None
+
+
+class CreditsByKind(TypedDict):
+    free: int
+    paid: int
+
+
+class Usage(TypedDict):
+    """The account's balance and what was spent in the current period."""
+
+    balance_credits: int | None
+    period: UsagePeriod
+    scans: UsageScans
+    credits_spent: int
+    free_allowance: FreeAllowance | None
+    paid_balance_credits: int | None
+    credits_spent_by_kind: CreditsByKind

doc_cheap/_version.py

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

doc_cheap-0.1.0.dist-info/METADATA

@@ -0,0 +1,169 @@
+Metadata-Version: 2.5
+Name: doc-cheap
+Version: 0.1.0
+Summary: Typed Python client for the doc.cheap document-recognition API: read passports, ID cards and driver's licences into JSON.
+Project-URL: Homepage, https://doc.cheap
+Project-URL: Documentation, https://doc.cheap/docs
+Project-URL: Source, https://gitlab.com/doccheap/doc-cheap-python
+Project-URL: Changelog, https://gitlab.com/doccheap/doc-cheap-python/-/blob/main/CHANGELOG.md
+Author-email: Teoh Chin Heng <admin@doc.cheap>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: doc.cheap,document-recognition,id-card,kyc,mrz,ocr,passport
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest-cov>=5; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# doc-cheap
+
+[![PyPI](https://img.shields.io/pypi/v/doc-cheap.svg)](https://pypi.org/project/doc-cheap/)
+
+The Python client for [doc.cheap](https://doc.cheap): it sends a photo or scan
+of a passport, national ID card or driving licence to the doc.cheap API and
+returns the printed fields – name, date of birth, document number, expiry, the
+machine-readable zone – as typed dictionaries.
+
+One recognised document costs one credit, $0.01. Registering gives 100 free
+documents every month. An unreadable image, an empty frame or an unsupported
+document type costs nothing, and every answer says whether it was billed.
+
+The package needs Python 3.10 or later and depends only on
+[httpx](https://www.python-httpx.org/).
+
+## Installation
+
+```sh
+pip install doc-cheap
+```
+
+## Quick start
+
+```python
+from doc_cheap import SANDBOX_KEY, Client
+
+with Client(SANDBOX_KEY) as client:
+    scan = client.recognize(path="passport.jpg")
+
+print("status:", scan["meta"]["status"], "billed:", scan["meta"]["billed"])
+if scan["holder"] and scan["holder"]["full_name"]:
+    print("holder:", scan["holder"]["full_name"])
+if scan["document"] and scan["document"]["expiry_date"]:
+    print("expires:", scan["document"]["expiry_date"])
+```
+
+## API keys
+
+- **Live key** – `sk_live_…`, created in the
+  [doc.cheap cabinet](https://doc.cheap/docs/concepts/api-keys-and-sessions).
+- **Sandbox key** – `sk_sandbox_public` (the `doc_cheap.SANDBOX_KEY` constant)
+  works without an account. It gives 10 free recognised documents per address
+  in all, and at most 10 requests per address an hour, whatever their answer.
+
+`Client()` without a key reads it from the `DOC_CHEAP_API_KEY` environment
+variable, which keeps a live key out of source code. The key is sent as a
+Bearer token.
+
+## Methods
+
+| Method | Request | What it does |
+| --- | --- | --- |
+| `recognize` | `POST /v1/scans` | Reads one JPEG or PNG image, from a file (`path`), raw bytes (`image`) or base64 (`image_base64`), with an optional `reference` label, `idempotency_key`, `expect_country`, `return_portrait` and `retain_hours`. |
+| `get_scan` | `GET /v1/scans/{id}` | Returns a stored result. |
+| `list_scans` | `GET /v1/scans` | Returns one page of stored results; pass `next_cursor` back as `cursor` for the next page. |
+| `delete_scan` | `DELETE /v1/scans/{id}` | Deletes a stored result. |
+| `usage` | `GET /v1/usage` | Returns this month's free credits, the paid credits, the credits spent and the scan counters. |
+
+An image that holds no readable document is not an error: the scan comes back
+with a status such as `unreadable` or `no_document_found` and `billed` set to
+`False`.
+
+**Stored results.** A result is stored only when the scan was made with a live
+key under a non-zero retention window, and only until that window ends. Under
+the sandbox key nothing is stored, so `get_scan` and `delete_scan` raise
+`NotFoundError`. None of `get_scan`, `delete_scan` or `usage` charges a credit.
+
+## Errors
+
+Every exception the package raises is a `doc_cheap.DocCheapError`. When the API
+answers with an error status, it is an `APIError` carrying the HTTP status, the
+API's error code and its message, narrowed to a subclass you can catch:
+
+```python
+from doc_cheap import APIError, NotFoundError, RateLimitError
+
+try:
+    scan = client.get_scan(scan_id)
+except NotFoundError:
+    scan = None
+except RateLimitError as err:
+    print("try again in", err.retry_after, "seconds")
+except APIError as err:
+    print(err.status_code, err.code, err.message, err.request_id)
+```
+
+| Exception | When |
+| --- | --- |
+| `InvalidRequestError` | The request was malformed or failed validation (400, 413, 415, 422). |
+| `AuthenticationError` | The key is missing, unknown or revoked (401). |
+| `PermissionDeniedError` | The key may not do this (403). |
+| `InsufficientCreditsError` | The account has no credits left (402). |
+| `NotFoundError` | No such scan (404). |
+| `ConflictError` | An idempotency key is reused or still in progress (409). |
+| `RateLimitError` | Too many requests; `retry_after` says how long to wait (429). |
+| `ServiceUnavailableError` | The service is briefly unavailable (503). |
+| `InternalServerError` | Any other server error (5xx). |
+| `APIConnectionError` | No answer at all: a network failure or a timeout. |
+
+An argument the API would refuse anyway – no image, an image over 25 MiB, a
+reference over 128 characters – raises `InvalidArgumentError` (also a
+`ValueError`) before any request is sent.
+
+## Options
+
+```python
+import httpx
+from doc_cheap import Client
+
+client = Client(
+    timeout=30.0,
+    user_agent="my-app/1.0",
+)
+
+# Or bring your own httpx.Client for a proxy or a shared connection pool;
+# the doc.cheap client leaves it open when it closes.
+client = Client(http_client=httpx.Client(proxy="http://proxy.internal:3128"))
+```
+
+`base_url` (or the `DOC_CHEAP_API_BASE` environment variable) points the client
+at another address, for example a test server.
+
+## Resources
+
+- [doc.cheap documentation](https://doc.cheap/docs)
+- [Your first recognition](https://doc.cheap/docs/start/first-recognition)
+- [From the sandbox to a live key](https://doc.cheap/docs/start/from-sandbox-to-live)
+- [API reference](https://doc.cheap/docs/reference)
+- [Handling errors](https://doc.cheap/docs/guides/handle-errors)
+
+## License
+
+[MIT](LICENSE)

doc_cheap-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+doc_cheap/__init__.py,sha256=bj9ZfRD3KAuIXtM08qMppoYgHrDilGmUuKZuHGK18hU,1988
+doc_cheap/_client.py,sha256=qrfGAfLBHV9On2ucv-dbo5poDeIFAovAKeFFmqc7abs,11258
+doc_cheap/_errors.py,sha256=82McwhzjolDjdirA-a858MbjHQLBXvlCBE81he7CIUk,6238
+doc_cheap/_types.py,sha256=U_pBofvyE7SxG8X0rZVwtTB9KKMjLlPkC5MSUX4ZC8M,3641
+doc_cheap/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+doc_cheap/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+doc_cheap-0.1.0.dist-info/METADATA,sha256=isOj_a_KenK8e0TV5dBm2qRJhat6jQtZrJ3V8clHOT4,6845
+doc_cheap-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+doc_cheap-0.1.0.dist-info/licenses/LICENSE,sha256=6cIUipszzlbgE6uIjGi_fU3qNMHyGdK6PSQ8NGw1Tno,1076
+doc_cheap-0.1.0.dist-info/RECORD,,

doc_cheap-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

doc_cheap-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Document Cheap Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.