ndi-sdk 0.7.0__py3-none-any.whl

ndi_sdk/__init__.py

@@ -0,0 +1,108 @@
+"""Python SDK for NDI (Nace Document Intelligence).
+
+Two API surfaces, one client. The platform API (``/v1``) is where workspaces,
+ingestion, retrieval, and the stateless document operations live; the legacy
+product API (``/api/v1``) is the older one-shot surface, kept whole behind
+``client.legacy``.
+
+    from ndi_sdk import NdiClient, UrlSource
+
+    with NdiClient(api_key="ndi_sk_…") as client:
+        job = client.documents.extract(
+            UrlSource(url="https://example.com/invoice.pdf", file_name="invoice.pdf"),
+            json_schema={"type": "object", "properties": {"total": {"type": "number"}}},
+        )
+        result = client.jobs.wait(job.job_id).result
+
+Every slow method returns a :class:`~ndi_sdk.models.jobs.Job` rather than
+blocking, because the underlying work is a Temporal workflow that can outlive any
+HTTP request. Wait for one with ``client.jobs.wait(job_id)``, follow it with
+``client.jobs.events(job_id)``, or hand a ``wait_seconds=`` to the call itself
+when the work is short enough to finish inline.
+
+Wire models here are hand-written copies of the server's, so this package depends
+only on ``httpx`` and ``pydantic`` and imports nothing else from the monorepo.
+Responses allow unknown fields and unknown enum members (see
+:mod:`ndi_sdk._base`), so a server-side additive change never breaks a client.
+"""
+
+from ndi_sdk import models
+from ndi_sdk._transport import RetryPolicy
+from ndi_sdk.client import DEFAULT_BASE_URL, AsyncNdiClient, NdiClient, UploadAndIngestResult
+from ndi_sdk.errors import (
+    AuthenticationError,
+    ConflictError,
+    ErrorBody,
+    ErrorCode,
+    InvalidRequestError,
+    JobFailedError,
+    JobTimeoutError,
+    NdiConnectionError,
+    NdiError,
+    NdiStatusError,
+    NdiTimeoutError,
+    NotFoundError,
+    NotImplementedByServerError,
+    PermissionDeniedError,
+    QuotaExceededError,
+    RateLimitError,
+    ResultExpiredError,
+    ServerError,
+    SyncWaitTimeoutError,
+)
+from ndi_sdk.models.common import (
+    DocumentSource,
+    IngestionStatus,
+    JobKind,
+    JobStatus,
+    Page,
+    ParseResultSource,
+    UploadSource,
+    UrlSource,
+    WorkspaceFileSource,
+)
+from ndi_sdk.models.jobs import Job, JobEvent
+from ndi_sdk.models.workspaces import Workspace
+
+__version__ = "0.7.0"
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "AsyncNdiClient",
+    "AuthenticationError",
+    "ConflictError",
+    "DocumentSource",
+    "ErrorBody",
+    "ErrorCode",
+    "IngestionStatus",
+    "InvalidRequestError",
+    "Job",
+    "JobEvent",
+    "JobFailedError",
+    "JobKind",
+    "JobStatus",
+    "JobTimeoutError",
+    "NdiClient",
+    "NdiConnectionError",
+    "NdiError",
+    "NdiStatusError",
+    "NdiTimeoutError",
+    "NotFoundError",
+    "NotImplementedByServerError",
+    "Page",
+    "ParseResultSource",
+    "PermissionDeniedError",
+    "QuotaExceededError",
+    "RateLimitError",
+    "ResultExpiredError",
+    "RetryPolicy",
+    "ServerError",
+    "SyncWaitTimeoutError",
+    "UploadAndIngestResult",
+    "UploadSource",
+    "UrlSource",
+    "Workspace",
+    "WorkspaceFileSource",
+    "__version__",
+    "models",
+]

ndi_sdk/_base.py

@@ -0,0 +1,47 @@
+"""Base behaviour shared by every wire model in this SDK.
+
+Two deliberate differences from the schemas the server validates against:
+
+* ``extra="allow"`` — the server may add a field to a response at any time, and a
+  client that rejects unknown fields turns every additive change into an outage.
+* :class:`OpenEnum` — the same reasoning for enum members. NDI documents its
+  status, kind, and error-code enums as open (spec 12 §9), so an unrecognised
+  member arrives as a usable string instead of a validation error.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+
+class NdiModel(BaseModel):
+    """Base for request and response models.
+
+    ``serialize_by_alias`` matters for the handful of fields whose wire name is a
+    Python keyword or shadows a ``BaseModel`` attribute (``schema``, ``class``):
+    the alias is the contract, the attribute name is an implementation detail.
+    """
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True, serialize_by_alias=True)
+
+
+class OpenEnum(StrEnum):
+    """A string enum that keeps values added to the API after this SDK shipped.
+
+    An unknown value becomes a member carrying that string, so comparisons
+    against known members work as usual and ``str(value)`` is always the wire
+    value. Compare with ``==`` rather than ``is``: two pseudo-members built from
+    the same string are equal but not identical.
+    """
+
+    @classmethod
+    def _missing_(cls, value: object) -> Any:
+        if not isinstance(value, str):
+            return None
+        unknown = str.__new__(cls, value)
+        unknown._name_ = value
+        unknown._value_ = value
+        return unknown

ndi_sdk/_files.py

@@ -0,0 +1,56 @@
+"""Turning what a caller has into what a multipart upload needs.
+
+Upload methods accept a path, raw bytes, or an open binary file, because those
+are the three things callers actually hold. Everything converges on the
+``(file_name, bytes, content_type)`` triple ``httpx`` wants for its ``files=``
+argument.
+"""
+
+from __future__ import annotations
+
+import mimetypes
+from os import PathLike
+from pathlib import Path
+from typing import IO, Any, TypeAlias
+
+#: Anything an upload method accepts as the document itself.
+FileContent: TypeAlias = "str | PathLike[str] | bytes | IO[bytes]"
+
+_DEFAULT_CONTENT_TYPE = "application/octet-stream"
+
+
+def read_file_content(content: FileContent, *, file_name: str | None = None) -> tuple[str, bytes, str]:
+    """Normalise an upload argument into ``(file_name, data, content_type)``.
+
+    Raises:
+        ValueError: When raw bytes or a nameless stream is passed without a
+            ``file_name``. NDI infers the document format from that name, so
+            guessing one here would silently pick the wrong parser.
+    """
+    if isinstance(content, bytes | bytearray):
+        if not file_name:
+            raise ValueError("file_name is required when uploading raw bytes: NDI infers the format from it")
+        return file_name, bytes(content), guess_content_type(file_name)
+
+    if isinstance(content, str | PathLike):
+        path = Path(content)
+        name = file_name or path.name
+        return name, path.read_bytes(), guess_content_type(name)
+
+    data = content.read()
+    if isinstance(data, str):  # a text-mode handle: the bytes are already lossy
+        raise ValueError("open the file in binary mode ('rb'): a text handle re-encodes the document")
+    name = file_name or _stream_name(content)
+    if not name:
+        raise ValueError("file_name is required when uploading a stream with no name")
+    return name, data, guess_content_type(name)
+
+
+def guess_content_type(file_name: str) -> str:
+    guessed, _ = mimetypes.guess_type(file_name)
+    return guessed or _DEFAULT_CONTENT_TYPE
+
+
+def _stream_name(stream: Any) -> str | None:
+    name = getattr(stream, "name", None)
+    return Path(name).name if isinstance(name, str) else None

ndi_sdk/_pagination.py

@@ -0,0 +1,58 @@
+"""Cursor pagination as iterators.
+
+Every ``/v1`` list method returns one :class:`~ndi_sdk.models.common.Page` with a
+``next_cursor``. The paired ``iter_*`` methods on each resource wrap that in an
+iterator so a caller who wants every row does not write the cursor loop by hand.
+
+Pages are still returned as-is by the plain ``list`` methods: ``total_count`` and
+``next_cursor`` are real answers, and an iterator that hides them would make the
+common "how many are there" question unanswerable without draining the list.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Awaitable, Callable, Iterator
+from typing import TypeVar
+
+from ndi_sdk.models.common import Page
+
+ItemT = TypeVar("ItemT")
+
+#: Fetches one page given the previous page's ``next_cursor`` (``None`` = first).
+AsyncPageFetcher = Callable[[str | None], Awaitable[Page[ItemT]]]
+SyncPageFetcher = Callable[[str | None], Page[ItemT]]
+
+
+async def aiter_pages(fetch: AsyncPageFetcher[ItemT]) -> AsyncIterator[Page[ItemT]]:
+    """Yield pages until the server stops handing back a cursor."""
+    cursor: str | None = None
+    while True:
+        page = await fetch(cursor)
+        yield page
+        if page.next_cursor is None:
+            return
+        cursor = page.next_cursor
+
+
+async def aiter_items(fetch: AsyncPageFetcher[ItemT]) -> AsyncIterator[ItemT]:
+    """Yield every item across every page."""
+    async for page in aiter_pages(fetch):
+        for item in page.items:
+            yield item
+
+
+def iter_pages(fetch: SyncPageFetcher[ItemT]) -> Iterator[Page[ItemT]]:
+    """Yield pages until the server stops handing back a cursor."""
+    cursor: str | None = None
+    while True:
+        page = fetch(cursor)
+        yield page
+        if page.next_cursor is None:
+            return
+        cursor = page.next_cursor
+
+
+def iter_items(fetch: SyncPageFetcher[ItemT]) -> Iterator[ItemT]:
+    """Yield every item across every page."""
+    for page in iter_pages(fetch):
+        yield from page.items