floorplan-api 0.5.0__py3-none-any.whl

floorplan_api/__init__.py

@@ -0,0 +1,75 @@
+"""Official Python client for the Floor Plan API.
+
+Quickstart::
+
+    from floorplan_api import Client
+
+    client = Client(api_key="fp_test_...")
+    mask_png = client.extract("path/to/floorplan.png")   # PNG, JPEG or WEBP
+    mask_png = client.extract("drawing-set.pdf", page=3) # one page of a PDF
+    open("walls.png", "wb").write(mask_png)
+
+asyncio (``pip install "floorplan-api[async]"``)::
+
+    from floorplan_api import AsyncClient
+
+    async with AsyncClient() as client:
+        mask_png = await client.extract("plan.pdf")
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from floorplan_api._input import SUPPORTED_CONTENT_TYPES, ImageInput, pdf_page_size
+from floorplan_api._version import __version__
+from floorplan_api.client import Client
+from floorplan_api.exceptions import (
+    AuthenticationError,
+    ConnectionError,
+    FloorPlanError,
+    InvalidRequestError,
+    NotFoundError,
+    ProcessingError,
+    RateLimitError,
+    ServerError,
+    TimeoutError,
+)
+from floorplan_api.models import Job, JobStatus, MaskBytes, MaskResult
+
+if TYPE_CHECKING:
+    from floorplan_api.async_client import AsyncClient
+
+__all__ = [
+    "__version__",
+    "Client",
+    "AsyncClient",
+    "ImageInput",
+    "SUPPORTED_CONTENT_TYPES",
+    "pdf_page_size",
+    # Models
+    "Job",
+    "JobStatus",
+    "MaskBytes",
+    "MaskResult",
+    # Errors
+    "FloorPlanError",
+    "AuthenticationError",
+    "RateLimitError",
+    "InvalidRequestError",
+    "NotFoundError",
+    "ProcessingError",
+    "ServerError",
+    "TimeoutError",
+    "ConnectionError",
+]
+
+
+def __getattr__(name: str) -> Any:
+    # AsyncClient needs httpx (the `async` extra); import it only on demand so
+    # `import floorplan_api` keeps working with just `requests` installed.
+    if name == "AsyncClient":
+        from floorplan_api.async_client import AsyncClient
+
+        return AsyncClient
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

floorplan_api/_input.py

@@ -0,0 +1,411 @@
+"""Input handling: turn a path, bytes, or binary file-like into an upload part.
+
+The API accepts PNG, JPEG, WEBP and PDF. The server decides by the
+``Content-Type`` of the multipart part rather than by inspecting the bytes,
+so the client has to label the part correctly. Raw bytes and unnamed
+file-likes carry no name, so the leading magic bytes are sniffed; paths and
+named file-likes are sniffed too and fall back to the file extension.
+"""
+
+from __future__ import annotations
+
+import io
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import IO, Any, Union
+
+from floorplan_api.exceptions import InvalidRequestError
+
+__all__ = [
+    "SUPPORTED_CONTENT_TYPES",
+    "ImageInput",
+    "ResolvedInput",
+    "content_type_from_filename",
+    "input_size",
+    "normalize_content_type",
+    "pdf_page_size",
+    "prepare_input",
+    "resolve_input",
+    "slice_pdf_page",
+    "sniff_content_type",
+]
+
+ImageInput = Union[str, "os.PathLike[str]", bytes, bytearray, memoryview, IO[bytes]]
+"""Accepted input forms: a filesystem path, the raw bytes of a file, or an
+open binary file-like object. PNG, JPEG, WEBP or PDF."""
+
+SUPPORTED_CONTENT_TYPES: tuple[str, ...] = (
+    "image/png",
+    "image/jpeg",
+    "image/webp",
+    "application/pdf",
+)
+
+_EXTENSION_TO_CONTENT_TYPE = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".pdf": "application/pdf",
+}
+_CONTENT_TYPE_TO_EXTENSION = {
+    "image/png": "png",
+    "image/jpeg": "jpg",
+    "image/webp": "webp",
+    "application/pdf": "pdf",
+}
+_SNIFF_LENGTH = 12
+
+
+def sniff_content_type(head: bytes) -> str | None:
+    """Identify PNG, JPEG, WEBP or PDF from the first bytes of a file."""
+
+    if head.startswith(b"\x89PNG\r\n\x1a\n"):
+        return "image/png"
+    if head.startswith(b"\xff\xd8\xff"):
+        return "image/jpeg"
+    if len(head) >= 12 and head[:4] == b"RIFF" and head[8:12] == b"WEBP":
+        return "image/webp"
+    if head.startswith(b"%PDF"):
+        return "application/pdf"
+    return None
+
+
+def content_type_from_filename(filename: str) -> str | None:
+    return _EXTENSION_TO_CONTENT_TYPE.get(Path(filename).suffix.lower())
+
+
+def normalize_content_type(value: str | None) -> str | None:
+    """Map aliases (``image/jpg``, ``application/x-pdf``) onto the canonical
+    types the API accepts; ``None`` for anything else."""
+
+    if value is None:
+        return None
+    lowered = value.lower().split(";", 1)[0].strip()
+    if lowered == "image/jpg":
+        return "image/jpeg"
+    if lowered == "application/x-pdf":
+        return "application/pdf"
+    return lowered if lowered in SUPPORTED_CONTENT_TYPES else None
+
+
+@dataclass
+class ResolvedInput:
+    """An input ready to be sent as the ``image`` multipart part.
+
+    ``page`` is the 1-based PDF page this input was cut down to, and
+    ``page_size_pt`` that page's size in PDF points as it will be rendered;
+    both are ``None`` for raster input.
+    """
+
+    filename: str
+    file: IO[bytes]
+    content_type: str
+    owns_file: bool = False
+    start: int = 0
+    page: int | None = None
+    page_size_pt: tuple[float, float] | None = None
+
+    @property
+    def is_pdf(self) -> bool:
+        return self.content_type == "application/pdf"
+
+    def size(self) -> int | None:
+        """Bytes left to send, or ``None`` if the stream cannot tell."""
+
+        return _stream_size(self.file, self.start)
+
+    def read_all(self) -> bytes:
+        """Read the body from ``start`` and seek back."""
+
+        self.rewind()
+        data = self.file.read()
+        self.rewind()
+        return data
+
+    @property
+    def part(self) -> tuple[str, IO[bytes], str]:
+        return self.filename, self.file, self.content_type
+
+    def rewind(self) -> None:
+        """Seek back to where the upload started, so a retry resends the body."""
+
+        try:
+            self.file.seek(self.start)
+        except (OSError, ValueError, AttributeError):
+            pass
+
+    def close(self) -> None:
+        if self.owns_file:
+            self.file.close()
+
+
+def _unsupported(detail: str) -> InvalidRequestError:
+    return InvalidRequestError(
+        f"Unsupported input: {detail}. Expected a PNG, JPEG, WEBP or PDF file."
+    )
+
+
+def _filename_for(name: str, content_type: str) -> str:
+    base = os.path.basename(name) or "floorplan"
+    if content_type_from_filename(base) == content_type:
+        return base
+    stem = Path(base).stem or "floorplan"
+    return f"{stem}.{_CONTENT_TYPE_TO_EXTENSION[content_type]}"
+
+
+def _name_of(stream: Any) -> str:
+    name = getattr(stream, "name", None)
+    if isinstance(name, bytes):
+        name = name.decode("utf-8", "replace")
+    if not isinstance(name, str):
+        return ""
+    return os.path.basename(name)
+
+
+def _peek(stream: IO[bytes]) -> tuple[bytes, IO[bytes], int]:
+    """Return ``(head, file, start)`` without consuming a seekable stream.
+
+    A stream that cannot seek is read fully into memory, so that the body
+    can be resent on retry.
+    """
+
+    try:
+        seekable = bool(stream.seekable())
+    except Exception:
+        seekable = False
+    if seekable:
+        start = stream.tell()
+        head = stream.read(_SNIFF_LENGTH)
+        stream.seek(start)
+        if isinstance(head, str):
+            raise InvalidRequestError(
+                "Open the file in binary mode ('rb'); text-mode files are not supported."
+            )
+        return head, stream, start
+    data = stream.read()
+    if isinstance(data, str):
+        raise InvalidRequestError(
+            "Open the file in binary mode ('rb'); text-mode files are not supported."
+        )
+    return data[:_SNIFF_LENGTH], io.BytesIO(data), 0
+
+
+def resolve_input(image: ImageInput) -> ResolvedInput:
+    """Validate ``image`` and return the multipart part to upload.
+
+    Raises:
+        InvalidRequestError: if the path does not exist, the stream is not
+            binary, or the bytes are not a PNG, JPEG, WEBP or PDF.
+    """
+
+    if isinstance(image, (str, os.PathLike)):
+        path = Path(image)
+        if not path.is_file():
+            raise InvalidRequestError(f"Image file does not exist: {path!s}")
+        fh = path.open("rb")
+        try:
+            head = fh.read(_SNIFF_LENGTH)
+            fh.seek(0)
+            content_type = sniff_content_type(head) or content_type_from_filename(path.name)
+            if content_type is None:
+                raise _unsupported(f"could not identify {path.name}")
+        except BaseException:
+            fh.close()
+            raise
+        return ResolvedInput(
+            _filename_for(path.name, content_type), fh, content_type, owns_file=True
+        )
+
+    if isinstance(image, (bytes, bytearray, memoryview)):
+        data = bytes(image)
+        content_type = sniff_content_type(data[:_SNIFF_LENGTH])
+        if content_type is None:
+            raise _unsupported("bytes do not start with a PNG, JPEG, WEBP or PDF signature")
+        return ResolvedInput(
+            _filename_for("floorplan", content_type), io.BytesIO(data), content_type, owns_file=True
+        )
+
+    if isinstance(image, io.TextIOBase):
+        raise InvalidRequestError(
+            "Open the file in binary mode ('rb'); text-mode files are not supported."
+        )
+
+    if hasattr(image, "read"):
+        name = _name_of(image)
+        head, file, start = _peek(image)
+        content_type = sniff_content_type(head) or (
+            content_type_from_filename(name) if name else None
+        )
+        if content_type is None:
+            what = name or "stream"
+            raise _unsupported(f"{what} does not start with a PNG, JPEG, WEBP or PDF signature")
+        return ResolvedInput(
+            _filename_for(name or "floorplan", content_type),
+            file,
+            content_type,
+            owns_file=file is not image,
+            start=start,
+        )
+
+    raise InvalidRequestError("image must be a path, bytes, or a binary file-like object")
+
+
+def _stream_size(stream: Any, start: int) -> int | None:
+    if not (hasattr(stream, "seek") and hasattr(stream, "tell")):
+        return None
+    try:
+        current = stream.tell()
+        stream.seek(0, os.SEEK_END)
+        end = stream.tell()
+        stream.seek(current, os.SEEK_SET)
+        return int(end - start)
+    except (OSError, ValueError, AttributeError):
+        return None
+
+
+def input_size(image: ImageInput) -> int | None:
+    """Best-effort size in bytes, or ``None`` if it cannot be determined cheaply."""
+
+    if isinstance(image, (str, os.PathLike)):
+        try:
+            return Path(image).stat().st_size
+        except OSError:
+            return None
+    if isinstance(image, (bytes, bytearray, memoryview)):
+        return len(image)
+    if hasattr(image, "tell"):
+        try:
+            return _stream_size(image, int(image.tell()))
+        except (OSError, ValueError, AttributeError):
+            return None
+    return None
+
+
+def _validate_page(page: int | None) -> int:
+    if page is None:
+        return 1
+    if isinstance(page, bool) or not isinstance(page, int):
+        raise InvalidRequestError("page must be a positive integer (1 = first page).")
+    if page < 1:
+        raise InvalidRequestError(f"page must be >= 1 (got {page}); pages are 1-based.")
+    return page
+
+
+def slice_pdf_page(data: bytes, page: int) -> bytes:
+    """Return a new single-page PDF holding page ``page`` (1-based) of ``data``.
+
+    This is what the client uploads for a PDF. ``pypdf`` copies the page
+    object with its content stream, resources (fonts, images) and
+    annotations into a fresh document; nothing is rasterised or re-rendered.
+    The other pages, document metadata, bookmarks, attachments and form
+    definitions are not included.
+
+    Raises:
+        InvalidRequestError: if the PDF is encrypted, cannot be parsed, or
+            has no page ``page``.
+    """
+
+    from pypdf import PdfReader, PdfWriter
+
+    try:
+        reader = PdfReader(io.BytesIO(data), strict=False)
+        if reader.is_encrypted:
+            raise InvalidRequestError(
+                "PDF is password-protected; remove the password before uploading."
+            )
+        count = len(reader.pages)
+    except InvalidRequestError:
+        raise
+    except Exception as exc:  # pypdf raises a mix of its own and builtin errors
+        text = str(exc).lower()
+        if "encrypt" in text or "password" in text or "cryptography" in text:
+            raise InvalidRequestError(
+                "PDF is password-protected; remove the password before uploading."
+            ) from exc
+        raise InvalidRequestError(f"Could not read PDF: {exc}") from exc
+    if count == 0:
+        raise InvalidRequestError("PDF has no pages.")
+    if page > count:
+        raise InvalidRequestError(f"PDF has {count} page(s); page {page} does not exist.")
+    try:
+        writer = PdfWriter()
+        writer.add_page(reader.pages[page - 1])
+        out = io.BytesIO()
+        writer.write(out)
+    except Exception as exc:
+        raise InvalidRequestError(f"Could not extract page {page} from PDF: {exc}") from exc
+    return out.getvalue()
+
+
+def pdf_page_size(data: bytes, page: int = 1) -> tuple[float, float]:
+    """``(width, height)`` in PDF points of page ``page`` (1-based) as it renders.
+
+    The server renders the page's crop box honouring its ``/Rotate`` entry,
+    so a landscape page stored rotated reports landscape dimensions here.
+    Together with the mask's pixel size this gives the render scale:
+    ``px_per_pt = mask.width / width_pt``.
+
+    Raises:
+        InvalidRequestError: if the PDF cannot be read or has no such page.
+    """
+
+    from pypdf import PdfReader
+
+    try:
+        reader = PdfReader(io.BytesIO(data), strict=False)
+        count = len(reader.pages)
+        if not 1 <= page <= count:
+            raise InvalidRequestError(f"PDF has {count} page(s); page {page} does not exist.")
+        pdf_page = reader.pages[page - 1]
+        box = pdf_page.cropbox
+        width = float(box.width)
+        height = float(box.height)
+        rotation = int(pdf_page.rotation or 0) % 360
+    except InvalidRequestError:
+        raise
+    except Exception as exc:
+        raise InvalidRequestError(f"Could not read PDF: {exc}") from exc
+    if rotation in (90, 270):
+        width, height = height, width
+    return abs(width), abs(height)
+
+
+def prepare_input(image: ImageInput, page: int | None = None) -> ResolvedInput:
+    """Resolve ``image`` and, for a PDF, cut it down to the one page to process.
+
+    Raster input is returned as-is: the bytes are uploaded verbatim. For a
+    PDF only the requested page is uploaded: a single-page PDF is built
+    locally (see :func:`slice_pdf_page`), so a 40-page drawing set costs one
+    page of bandwidth and storage, and the page's size in points is recorded
+    for :attr:`floorplan_api.MaskBytes.page_size_pt`. ``page`` is 1-based and
+    defaults to the first page; passing a page other than 1 for a raster
+    input is an error.
+    """
+
+    wanted = _validate_page(page)
+    resolved = resolve_input(image)
+    try:
+        if not resolved.is_pdf:
+            if wanted != 1:
+                raise InvalidRequestError(
+                    f"page={wanted} was given but {resolved.filename} is not a PDF; "
+                    "page selection applies to PDF input only."
+                )
+            return resolved
+        single = slice_pdf_page(resolved.read_all(), wanted)
+    except BaseException:
+        resolved.close()
+        raise
+    resolved.close()
+    stem = Path(resolved.filename).stem or "floorplan"
+    return ResolvedInput(
+        f"{stem}.pdf",
+        io.BytesIO(single),
+        "application/pdf",
+        owns_file=True,
+        start=0,
+        page=wanted,
+        page_size_pt=pdf_page_size(single, 1),
+    )

floorplan_api/_transport.py

@@ -0,0 +1,175 @@
+"""Pieces shared by the synchronous and asyncio clients: URL and header
+construction, retry policy, and mapping HTTP responses onto models and
+exceptions. Nothing in here performs I/O."""
+
+from __future__ import annotations
+
+import json
+import os
+import random
+from collections.abc import Mapping
+from datetime import datetime, timezone
+from typing import Any
+
+from floorplan_api._version import __version__
+from floorplan_api.exceptions import (
+    AuthenticationError,
+    FloorPlanError,
+    InvalidRequestError,
+    NotFoundError,
+    ProcessingError,
+    RateLimitError,
+    ServerError,
+)
+from floorplan_api.exceptions import (
+    TimeoutError as ApiTimeoutError,
+)
+from floorplan_api.models import Job, MaskBytes
+
+DEFAULT_BASE_URL = "https://api.floorplanapi.com"
+DEFAULT_TIMEOUT = 60.0
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_RETRY_BACKOFF = 0.5
+DEFAULT_PRESIGN_THRESHOLD = 10 * 1024 * 1024
+MAX_RETRY_AFTER = 30.0
+USER_AGENT = f"floorplan-api-python/{__version__}"
+
+
+def resolve_credentials(api_key: str | None, base_url: str | None) -> tuple[str, str]:
+    key = api_key or os.environ.get("FLOORPLAN_API_KEY")
+    if not key:
+        raise AuthenticationError(
+            "An API key is required. Pass api_key=... or set FLOORPLAN_API_KEY in the environment."
+        )
+    url = (base_url or os.environ.get("FLOORPLAN_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+    return key, url
+
+
+def build_headers(api_key: str) -> dict[str, str]:
+    return {"Authorization": f"Bearer {api_key}", "User-Agent": USER_AGENT}
+
+
+def build_url(base_url: str, path: str) -> str:
+    if path.startswith(("http://", "https://")):
+        return path
+    if not path.startswith("/"):
+        path = "/" + path
+    return f"{base_url}{path}"
+
+
+def parse_retry_after(value: str | None) -> float | None:
+    if not value:
+        return None
+    try:
+        return float(value)
+    except ValueError:
+        return None
+
+
+def retry_delay(attempt: int, backoff: float, retry_after: float | None = None) -> float:
+    """Seconds to sleep before retry number ``attempt`` (0-based).
+
+    A server-provided ``Retry-After`` wins, capped at :data:`MAX_RETRY_AFTER`;
+    otherwise exponential backoff with up to 25 % jitter.
+    """
+
+    if retry_after is not None and retry_after > 0:
+        return float(min(retry_after, MAX_RETRY_AFTER))
+    delay = backoff * (2**attempt)
+    return float(delay + delay * 0.25 * random.random())
+
+
+def decode_json(text: str) -> dict[str, Any]:
+    """Decode a JSON object body; anything else (including PNG bytes) is ``{}``."""
+
+    try:
+        body = json.loads(text)
+    except (ValueError, TypeError):
+        return {}
+    return body if isinstance(body, dict) else {}
+
+
+def job_id_from(body: Mapping[str, Any]) -> str | None:
+    value = body.get("job_id")
+    return value if isinstance(value, str) and value else None
+
+
+def should_retry(status: int, body: Mapping[str, Any]) -> bool:
+    """Whether a failed response is transient.
+
+    429 and 5xx are retried, except a 5xx that names a ``job_id``: that is
+    the outcome of a job that was queued (504 = still running, 500 = the
+    worker failed it), and resubmitting would only queue another copy.
+    """
+
+    if status == 429:
+        return True
+    if status >= 500:
+        return job_id_from(body) is None
+    return False
+
+
+def error_from_response(
+    status: int,
+    headers: Mapping[str, str],
+    body: Mapping[str, Any],
+    text: str,
+) -> FloorPlanError:
+    """Map an error response onto the matching :class:`FloorPlanError` subclass."""
+
+    raw_error = body.get("error")
+    error_block: Mapping[str, Any] = raw_error if isinstance(raw_error, dict) else {}
+    message = error_block.get("message") or text or f"HTTP {status}"
+    type_ = error_block.get("type")
+    job_id = job_id_from(body)
+    kwargs: dict[str, Any] = {
+        "status_code": status,
+        "type": type_ if isinstance(type_, str) else None,
+        "request_id": headers.get("X-Request-Id") or None,
+        "job_id": job_id,
+        "response": dict(body) if body else None,
+    }
+
+    if status in (401, 403):
+        return AuthenticationError(message, **kwargs)
+    if status == 404:
+        return NotFoundError(message, **kwargs)
+    if status == 429:
+        retry_after = parse_retry_after(headers.get("Retry-After"))
+        return RateLimitError(message, retry_after=retry_after, **kwargs)
+    if status == 504 and job_id is not None:
+        return ApiTimeoutError(message, **kwargs)
+    if status == 500 and job_id is not None:
+        return ProcessingError(message, **kwargs)
+    if 400 <= status < 500:
+        return InvalidRequestError(message, **kwargs)
+    if status >= 500:
+        return ServerError(message, **kwargs)
+    return FloorPlanError(message, **kwargs)
+
+
+def mask_from_response(
+    content: bytes,
+    headers: Mapping[str, str],
+    page_size_pt: tuple[float, float] | None = None,
+) -> MaskBytes:
+    return MaskBytes.from_response(content, headers, page_size_pt=page_size_pt)
+
+
+def job_from_submit(payload: Mapping[str, Any]) -> Job:
+    """Build a :class:`Job` from the 202 body of an async submission."""
+
+    return Job.from_dict(
+        {
+            "job_id": payload["job_id"],
+            "status": payload["status"],
+            "created_at": payload.get("created_at") or now_iso(),
+            "completed_at": None,
+            "result": None,
+            "error": None,
+        }
+    )
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")

floorplan_api/_version.py

@@ -0,0 +1,3 @@
+"""Single source of truth for the package version (read by hatch at build time)."""
+
+__version__ = "0.5.0"