floorplan-api 0.5.0__py3-none-any.whl

floorplan_api/client.py

@@ -0,0 +1,502 @@
+"""Synchronous HTTP client for the Floor Plan API (built on ``requests``)."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Mapping
+from typing import Any
+
+import requests
+
+from floorplan_api._input import (
+    ImageInput,
+    ResolvedInput,
+    normalize_content_type,
+    prepare_input,
+)
+from floorplan_api._transport import (
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_PRESIGN_THRESHOLD,
+    DEFAULT_RETRY_BACKOFF,
+    DEFAULT_TIMEOUT,
+    build_headers,
+    build_url,
+    decode_json,
+    error_from_response,
+    job_from_submit,
+    mask_from_response,
+    parse_retry_after,
+    resolve_credentials,
+    retry_delay,
+    should_retry,
+)
+from floorplan_api.exceptions import (
+    ConnectionError as ApiConnectionError,
+)
+from floorplan_api.exceptions import (
+    InvalidRequestError,
+    ServerError,
+)
+from floorplan_api.exceptions import (
+    TimeoutError as ApiTimeoutError,
+)
+from floorplan_api.models import Job, MaskBytes
+
+__all__ = ["Client", "ImageInput"]
+
+
+class Client:
+    """Synchronous Floor Plan API client.
+
+    The Floor Plan API takes a floor plan (PNG, JPEG, WEBP, or one page of
+    a PDF) and returns a binary wall-segmentation PNG mask on the pixel grid
+    of the decoded input, where ``255`` marks wall and ``0`` everything else.
+    Walls follow the *carved* convention: door and window openings are not
+    wall, and walls are as thick as the source linework.
+
+    What the client sends:
+
+    * A raster (PNG, JPEG, WEBP) is uploaded byte for byte; the client never
+      decodes or re-encodes it.
+    * A PDF is not uploaded whole: the requested ``page`` is copied into a
+      new single-page PDF with ``pypdf`` (content stream, resources and
+      annotations kept; other pages, metadata, bookmarks, attachments and
+      forms left out) and that file is uploaded. Nothing is rasterised
+      client-side. With ``upload_key`` the object is already in storage, so
+      ``page`` is sent to the server instead.
+
+    What the server does with the bytes (``docs/IMAGE_PIPELINE.md``):
+
+    * Rasters are decoded with OpenCV: alpha is dropped without compositing
+      (flatten RGBA onto white yourself), grayscale is expanded, 16-bit is
+      reduced to 8-bit, EXIF orientation is applied, ICC profiles ignored.
+      A raster whose longer edge exceeds 8192 px is processed downscaled and
+      the mask is resized back to the input size.
+    * A PDF page is rendered at 200 DPI onto white, reduced so its longer
+      edge is at most 8192 px; the mask has that rendered size. The client
+      records the page's size in points, so :attr:`MaskBytes.pdf_scale`
+      maps PDF coordinates onto the mask.
+    * Inline uploads are capped at 10 MB; presigned uploads have no cap
+      from the API (dev servers cap them at 50 MB).
+
+    Args:
+        api_key: Your API key. If omitted, the value of the
+            ``FLOORPLAN_API_KEY`` environment variable is used.
+        base_url: Override the API base URL (useful for self-hosted
+            deployments or local testing). Defaults to
+            ``https://api.floorplanapi.com``. May also be supplied via the
+            ``FLOORPLAN_BASE_URL`` environment variable.
+        timeout: Per-request timeout in seconds. Default: 60.
+        max_retries: Maximum number of retry attempts for transient
+            errors: network failures, 429s, and 5xx responses that are not
+            the outcome of a queued job. Default: 3.
+        retry_backoff: Base delay in seconds for exponential backoff
+            between retries. A server ``Retry-After`` header takes
+            precedence, capped at 30 s per attempt. Default: 0.5.
+        session: An existing :class:`requests.Session` to reuse. If
+            omitted, a new session is created.
+
+    Raises:
+        AuthenticationError: when no API key is provided.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        retry_backoff: float = DEFAULT_RETRY_BACKOFF,
+        session: requests.Session | None = None,
+    ) -> None:
+        self.api_key, self.base_url = resolve_credentials(api_key, base_url)
+        self.timeout = timeout
+        self.max_retries = max(0, int(max_retries))
+        self.retry_backoff = max(0.0, float(retry_backoff))
+        self._session = session or requests.Session()
+
+    # ----- public API -----
+
+    def extract(
+        self,
+        image: ImageInput | None = None,
+        *,
+        upload_key: str | None = None,
+        page: int | None = None,
+        timeout: float | None = None,
+    ) -> MaskBytes:
+        """Run wall segmentation synchronously and return the mask PNG.
+
+        Args:
+            image: Path, bytes, or open binary file-like: PNG, JPEG, WEBP or
+                PDF. Inline uploads are capped at 10 MB; use
+                :py:meth:`upload_then_extract` for larger files.
+            upload_key: Storage key from :py:meth:`upload`, instead of
+                ``image``. Exactly one of the two must be given.
+            page: For a PDF, the 1-based page to process (default 1). With
+                ``image`` the page is cut out locally and only that page is
+                uploaded; with ``upload_key`` it is passed to the server.
+                Rejected for raster input unless it is 1.
+            timeout: Override the client's default timeout for this call.
+
+        Returns:
+            :class:`~floorplan_api.MaskBytes`: the PNG bytes, with
+            ``width``, ``height``, ``job_id``, ``request_id``, ``mode`` and,
+            for a PDF, ``page_size_pt`` / ``pdf_scale`` attached.
+
+        Raises:
+            TimeoutError: with ``job_id`` set if the worker did not finish
+                within the server's synchronous budget. The job is still
+                running: :py:meth:`wait_for_job` and :py:meth:`download_mask`
+                fetch its result without resubmitting.
+            ProcessingError: if the worker failed the job (not retried).
+            AuthenticationError, RateLimitError, InvalidRequestError,
+            NotFoundError, ServerError, ConnectionError: as documented on
+            each class.
+        """
+
+        return self._submit_for_mask("/v1/extract", image, upload_key, page, timeout)
+
+    def analyze(
+        self,
+        image: ImageInput | None = None,
+        *,
+        upload_key: str | None = None,
+        page: int | None = None,
+        timeout: float | None = None,
+    ) -> MaskBytes:
+        """Synchronous analyze: the same wall mask as :py:meth:`extract`.
+
+        ``analyze`` and ``extract`` currently produce identical output; the
+        two endpoints are kept distinct so future tiers (per-room
+        classification, symbol detection) can attach to ``analyze`` without
+        breaking ``extract``'s simpler contract.
+        """
+
+        return self._submit_for_mask("/v1/analyze", image, upload_key, page, timeout)
+
+    def analyze_async(
+        self,
+        image: ImageInput | None = None,
+        *,
+        upload_key: str | None = None,
+        page: int | None = None,
+        timeout: float | None = None,
+    ) -> Job:
+        """Submit an analyze job and return immediately.
+
+        Returns a :class:`~floorplan_api.Job` you can poll with
+        :py:meth:`get_job` or block on with :py:meth:`wait_for_job`. Once it
+        reaches ``completed``, fetch the PNG via :py:meth:`download_mask`.
+        """
+
+        resolved, files = _multipart(image, upload_key, page, {"async": "true"})
+        try:
+            response = self._request(
+                "POST", "/v1/analyze", files=files, timeout=timeout, rewind=resolved
+            )
+        finally:
+            if resolved is not None:
+                resolved.close()
+        return job_from_submit(response.json())
+
+    def get_job(self, job_id: str, *, timeout: float | None = None) -> Job:
+        """Fetch the latest status of an asynchronous job."""
+
+        response = self._request("GET", f"/v1/status/{job_id}", timeout=timeout)
+        return Job.from_dict(response.json())
+
+    def wait_for_job(
+        self,
+        job_id: str,
+        *,
+        poll_interval: float = 1.0,
+        timeout: float = 300.0,
+    ) -> Job:
+        """Poll a job until it reaches a terminal status.
+
+        Args:
+            job_id: The job ID from :py:meth:`analyze_async`, or from the
+                ``job_id`` attribute of a :class:`~floorplan_api.TimeoutError`
+                raised by a synchronous call.
+            poll_interval: Seconds to wait between polls. Default: 1.0.
+            timeout: Maximum number of seconds to wait. Default: 300.
+
+        Returns:
+            The final :class:`Job` (``completed`` or ``failed``).
+
+        Raises:
+            TimeoutError: if the job does not finish within ``timeout``;
+                ``job_id`` is set and the job keeps running server-side.
+        """
+
+        deadline = time.monotonic() + timeout
+        while True:
+            job = self.get_job(job_id)
+            if job.is_terminal:
+                return job
+            if time.monotonic() > deadline:
+                raise ApiTimeoutError(
+                    f"Job {job_id} did not finish within {timeout} seconds.", job_id=job_id
+                )
+            time.sleep(poll_interval)
+
+    def download_mask(self, job_id: str, *, timeout: float | None = None) -> MaskBytes:
+        """Download the wall mask PNG for a completed job.
+
+        Raises:
+            InvalidRequestError: (409) if the job has not completed yet.
+            NotFoundError: if the job is unknown or has expired.
+        """
+
+        response = self._request("GET", f"/v1/jobs/{job_id}/mask", timeout=timeout)
+        return mask_from_response(response.content, response.headers)
+
+    def create_upload(
+        self,
+        *,
+        content_type: str = "image/png",
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        """Reserve a presigned upload slot.
+
+        Returns ``{upload_url, key, expires_at, content_type}``. PUT the
+        bytes to ``upload_url`` with header ``Content-Type: <content_type>``
+        within 15 minutes, then pass ``key`` as ``upload_key`` to
+        :py:meth:`extract`, :py:meth:`analyze` or :py:meth:`analyze_async`.
+        """
+
+        normalized = normalize_content_type(content_type)
+        if normalized is None:
+            raise InvalidRequestError(
+                f"Unsupported content_type {content_type!r}. Use image/png, image/jpeg, "
+                "image/webp or application/pdf."
+            )
+        response = self._request(
+            "POST", "/v1/uploads", json_body={"content_type": normalized}, timeout=timeout
+        )
+        payload = response.json()
+        if not isinstance(payload, dict):
+            raise ServerError("Unexpected response from /v1/uploads.", status_code=None)
+        return payload
+
+    def upload(
+        self,
+        image: ImageInput,
+        *,
+        page: int | None = None,
+        content_type: str | None = None,
+        timeout: float | None = None,
+    ) -> str:
+        """PUT the file directly to object storage and return its storage key.
+
+        The API server never sees the bytes: the client requests a presigned
+        URL via :py:meth:`create_upload` and uploads straight to storage. Use
+        the returned key as ``upload_key`` on :py:meth:`extract`,
+        :py:meth:`analyze` or :py:meth:`analyze_async`, or use
+        :py:meth:`upload_then_extract` for the one-shot version.
+
+        Args:
+            image: Path, bytes, or open binary file-like.
+            page: For a PDF, the 1-based page to keep (default 1). Only that
+                page is uploaded, so the key refers to a single-page PDF.
+            content_type: Override the detected type (rarely needed).
+            timeout: Timeout for each of the two requests.
+        """
+
+        resolved = prepare_input(image, page)
+        return self._upload_prepared(resolved, content_type, timeout)
+
+    def _upload_prepared(
+        self,
+        resolved: ResolvedInput,
+        content_type: str | None,
+        timeout: float | None,
+    ) -> str:
+        try:
+            ct = normalize_content_type(content_type) or resolved.content_type
+            presigned = self.create_upload(content_type=ct, timeout=timeout)
+            request_timeout = self.timeout if timeout is None else timeout
+            try:
+                put = self._session.put(
+                    presigned["upload_url"],
+                    data=resolved.file,
+                    headers={"Content-Type": ct},
+                    timeout=request_timeout,
+                )
+            except requests.Timeout as exc:
+                raise ApiTimeoutError(str(exc)) from exc
+            except requests.ConnectionError as exc:
+                raise ApiConnectionError(str(exc)) from exc
+            if put.status_code >= 400:
+                raise ServerError(
+                    f"Upload PUT failed ({put.status_code}): {put.text[:200]}",
+                    status_code=put.status_code,
+                )
+        finally:
+            resolved.close()
+        key = presigned.get("key")
+        if not isinstance(key, str) or not key:
+            raise ServerError("Upload response missing `key`.", status_code=None)
+        return key
+
+    def upload_then_extract(
+        self,
+        image: ImageInput,
+        *,
+        page: int | None = None,
+        threshold_bytes: int = DEFAULT_PRESIGN_THRESHOLD,
+        timeout: float | None = None,
+    ) -> MaskBytes:
+        """Extract walls, switching to the presigned flow for large files.
+
+        Files smaller than ``threshold_bytes`` (default 10 MiB, the inline
+        cap) go through :py:meth:`extract` directly. Larger files, or files
+        whose size cannot be determined cheaply, are PUT to object storage
+        via a presigned URL and extracted by storage key.
+        """
+
+        resolved = prepare_input(image, page)
+        size = resolved.size()
+        if size is not None and size < threshold_bytes:
+            return self._submit_prepared("/v1/extract", resolved, {}, timeout)
+        key = self._upload_prepared(resolved, None, timeout)
+        return self._submit_files(
+            "/v1/extract",
+            None,
+            {"upload_key": (None, key)},
+            timeout,
+            page_size_pt=resolved.page_size_pt,
+        )
+
+    def close(self) -> None:
+        """Close the underlying HTTP session."""
+
+        self._session.close()
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    # ----- internals -----
+
+    def _submit_for_mask(
+        self,
+        path: str,
+        image: ImageInput | None,
+        upload_key: str | None,
+        page: int | None,
+        timeout: float | None,
+    ) -> MaskBytes:
+        resolved, files = _multipart(image, upload_key, page, {})
+        return self._submit_files(path, resolved, files, timeout)  # page size rides on resolved
+
+    def _submit_prepared(
+        self,
+        path: str,
+        resolved: ResolvedInput,
+        extra: Mapping[str, str],
+        timeout: float | None,
+    ) -> MaskBytes:
+        files: dict[str, Any] = {name: (None, value) for name, value in extra.items()}
+        files["image"] = resolved.part
+        return self._submit_files(
+            path, resolved, files, timeout, page_size_pt=resolved.page_size_pt
+        )
+
+    def _submit_files(
+        self,
+        path: str,
+        resolved: ResolvedInput | None,
+        files: dict[str, Any],
+        timeout: float | None,
+        page_size_pt: tuple[float, float] | None = None,
+    ) -> MaskBytes:
+        if resolved is not None and page_size_pt is None:
+            page_size_pt = resolved.page_size_pt
+        try:
+            response = self._request("POST", path, files=files, timeout=timeout, rewind=resolved)
+        finally:
+            if resolved is not None:
+                resolved.close()
+        return mask_from_response(response.content, response.headers, page_size_pt)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        files: Mapping[str, Any] | None = None,
+        json_body: Any | None = None,
+        timeout: float | None = None,
+        rewind: ResolvedInput | None = None,
+    ) -> requests.Response:
+        url = build_url(self.base_url, path)
+        request_timeout = self.timeout if timeout is None else timeout
+        attempt = 0
+        while True:
+            if attempt and rewind is not None:
+                rewind.rewind()
+            try:
+                response = self._session.request(
+                    method=method,
+                    url=url,
+                    headers=build_headers(self.api_key),
+                    files=files,
+                    json=json_body,
+                    timeout=request_timeout,
+                )
+            except requests.Timeout as exc:
+                if attempt < self.max_retries:
+                    time.sleep(retry_delay(attempt, self.retry_backoff))
+                    attempt += 1
+                    continue
+                raise ApiTimeoutError(str(exc)) from exc
+            except requests.ConnectionError as exc:
+                if attempt < self.max_retries:
+                    time.sleep(retry_delay(attempt, self.retry_backoff))
+                    attempt += 1
+                    continue
+                raise ApiConnectionError(str(exc)) from exc
+
+            if response.status_code < 400:
+                return response
+
+            body = decode_json(response.text)
+            if attempt < self.max_retries and should_retry(response.status_code, body):
+                retry_after = parse_retry_after(response.headers.get("Retry-After"))
+                time.sleep(retry_delay(attempt, self.retry_backoff, retry_after))
+                attempt += 1
+                continue
+            raise error_from_response(response.status_code, response.headers, body, response.text)
+
+
+def _multipart(
+    image: ImageInput | None,
+    upload_key: str | None,
+    page: int | None,
+    extra: Mapping[str, str],
+) -> tuple[ResolvedInput | None, dict[str, Any]]:
+    """Build the multipart ``files`` mapping for an extract/analyze call.
+
+    Every field, including plain text ones, is passed through ``files`` so
+    the request is always ``multipart/form-data`` regardless of whether an
+    image part is present.
+    """
+
+    if (image is None) == (upload_key is None):
+        raise InvalidRequestError("Pass exactly one of `image` or `upload_key`.")
+    files: dict[str, Any] = {name: (None, value) for name, value in extra.items()}
+    if upload_key is not None:
+        files["upload_key"] = (None, upload_key)
+        if page is not None and page != 1:
+            # The object is already in storage, so the server selects the page.
+            files["page"] = (None, str(page))
+        return None, files
+    # For a file we hold, the page is cut out locally and only it is sent.
+    resolved = prepare_input(image, page)  # type: ignore[arg-type]
+    files["image"] = resolved.part
+    return resolved, files

floorplan_api/exceptions.py

@@ -0,0 +1,123 @@
+"""Exception hierarchy for the Floor Plan API client.
+
+All exceptions raised by :class:`floorplan_api.Client` and
+:class:`floorplan_api.AsyncClient` derive from :class:`FloorPlanError`.
+Catch the base class to handle every API error::
+
+    from floorplan_api import Client, FloorPlanError
+
+    try:
+        mask = client.extract("plan.png")
+    except FloorPlanError as exc:
+        print(f"API error: {exc}")
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class FloorPlanError(Exception):
+    """Base class for every error raised by the client.
+
+    Attributes:
+        message: Human-readable error message.
+        status_code: HTTP status code returned by the server (if any).
+        type: Server-provided error type (e.g. ``"authentication_error"``).
+        request_id: Server-provided request ID (helpful for support tickets).
+        job_id: The job the server created for this request, when it told
+            us. Set on :class:`TimeoutError` (504) and
+            :class:`ProcessingError` (500) so the caller can still poll
+            :py:meth:`~floorplan_api.Client.get_job` and download the mask.
+        response: Raw decoded JSON response body when available.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        type: str | None = None,
+        request_id: str | None = None,
+        job_id: str | None = None,
+        response: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.type = type
+        self.request_id = request_id
+        self.job_id = job_id
+        self.response = response
+
+    def __str__(self) -> str:
+        parts = [self.message]
+        if self.status_code is not None:
+            parts.append(f"(status={self.status_code})")
+        if self.request_id:
+            parts.append(f"(request_id={self.request_id})")
+        if self.job_id:
+            parts.append(f"(job_id={self.job_id})")
+        return " ".join(parts)
+
+
+class AuthenticationError(FloorPlanError):
+    """Raised when the API key is missing, malformed, expired, or revoked (401),
+    or the resource belongs to another account (403)."""
+
+
+class InvalidRequestError(FloorPlanError):
+    """Raised when the request was malformed or the input unsupported
+    (400, 409, 413, 415), or when the client rejects the input before sending."""
+
+
+class NotFoundError(FloorPlanError):
+    """Raised when a resource does not exist (404)."""
+
+
+class RateLimitError(FloorPlanError):
+    """Raised when the rate limit was exceeded (429) and retries are exhausted.
+
+    Attributes:
+        retry_after: Number of seconds to wait before retrying, when provided
+            by the server's ``Retry-After`` header.
+    """
+
+    def __init__(self, message: str, *, retry_after: float | None = None, **kwargs: Any) -> None:
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+
+
+class ServerError(FloorPlanError):
+    """Raised when the API returns a 5xx response after retries are exhausted.
+
+    A 503 with ``Retry-After`` (queue at capacity) is retried, honouring the
+    header, before this is raised.
+    """
+
+
+class ProcessingError(ServerError):
+    """Raised when the worker failed the job (500 with ``job_id``).
+
+    The input was accepted and queued, but inference on it failed, for
+    example because the bytes could not be decoded. This is not retried:
+    resubmitting the same input would fail the same way. ``job_id`` and
+    ``type`` (``"inference_error"``, ``"storage_error"``, ...) are set.
+    """
+
+
+class TimeoutError(FloorPlanError):  # noqa: A001 — intentional shadowing for API parity
+    """Raised when a request exceeds the configured timeout, when
+    :py:meth:`~floorplan_api.Client.wait_for_job` gives up, or when the server
+    answers 504 because the worker did not finish within its synchronous
+    budget.
+
+    In the 504 case ``job_id`` is set and the job is still running: call
+    ``client.wait_for_job(exc.job_id)`` then ``client.download_mask(exc.job_id)``
+    instead of resubmitting. The client never retries a 504 that carries a
+    ``job_id``, because each retry would queue another copy of the job.
+    """
+
+
+class ConnectionError(FloorPlanError):  # noqa: A001 — intentional shadowing for API parity
+    """Raised when the underlying transport fails (DNS, TCP, TLS)."""