dipsac 0.1.1__py3-none-any.whl

dipsac/__init__.py

@@ -0,0 +1,41 @@
+"""The official Python library for the DIPSAC API.
+
+    from dipsac import Dipsac
+
+    client = Dipsac(api_key="dps_...")            # or set DIPSAC_API_KEY
+    client.pdf.merge(["a.pdf", "b.pdf"]).save("merged.pdf")
+
+Docs: https://dipsac.com/dashboard/reference
+"""
+from ._client import DEFAULT_BASE_URL, AsyncDipsac, Dipsac
+from ._errors import (
+    APIConnectionError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    DipsacError,
+    InternalServerError,
+    JobFailedError,
+    JobTimeoutError,
+    NotFoundError,
+    PayloadTooLargeError,
+    PaymentRequiredError,
+    PermissionDeniedError,
+    RateLimitError,
+    UnprocessableEntityError,
+    UnsupportedMediaTypeError,
+)
+from ._files import FileInput
+from ._models import AsyncJob, DipsacFile, Job
+from ._version import __version__
+
+__all__ = [
+    "Dipsac", "AsyncDipsac", "DipsacFile", "Job", "AsyncJob", "FileInput", "DEFAULT_BASE_URL",
+    "DipsacError", "APIConnectionError", "APITimeoutError", "APIStatusError", "BadRequestError",
+    "AuthenticationError", "PaymentRequiredError", "PermissionDeniedError", "NotFoundError",
+    "ConflictError", "PayloadTooLargeError", "UnsupportedMediaTypeError",
+    "UnprocessableEntityError", "RateLimitError", "InternalServerError", "JobFailedError",
+    "JobTimeoutError", "__version__",
+]

dipsac/_client.py

@@ -0,0 +1,263 @@
+"""The transport: auth, uploads, errors, retries. One method per endpoint lives in
+_resources.py, which is generated; everything here is what those methods share.
+
+WHAT IS RETRIED, AND WHAT IS DELIBERATELY NOT.
+
+  * A 429 whose Retry-After is short (the per-second limit; the Free plan allows
+    two requests a second) is waited out and sent again. The API refused it
+    before doing any work, so sending it again cannot do the work twice.
+  * A 429 that asks for a long wait is the plan's MONTHLY limit. Waiting a day
+    inside a function call helps nobody, so it is raised at once.
+  * A connection that could not be opened is tried again: nothing was sent.
+  * A GET that got 502, 503 or 504, or lost its connection, is tried again.
+  * A POST that got a 5xx or lost its connection part-way is NOT. The server may
+    have done the work, and some of it (speech) is paid for per call.
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+import random
+import time
+from typing import Any, Dict, List, Mapping, Optional, Tuple
+
+import httpx
+
+from ._errors import APIConnectionError, APITimeoutError, DipsacError, error_for
+from ._files import to_part
+from ._models import AsyncJob, DipsacFile, Job, filename_from
+from ._resources import RESOURCES
+from ._version import __version__
+
+DEFAULT_BASE_URL = "https://api.dipsac.com"
+DEFAULT_TIMEOUT = 300.0
+DEFAULT_MAX_RETRIES = 2
+# The longest Retry-After worth sleeping through. The per-second limit asks for
+# 1; the monthly limit asks for 86400.
+MAX_RETRY_AFTER = 30.0
+
+
+def _scalar(value: Any) -> str:
+    """A form or query value as the API reads it."""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)
+
+
+def _clean(values: Optional[Mapping[str, Any]]) -> Dict[str, Any]:
+    """Without the entries the caller left out, so the server's defaults apply."""
+    return {k: v for k, v in (values or {}).items() if v is not None}
+
+
+class _Core:
+    """What the sync and the async client have in common: everything but the wire."""
+
+    def __init__(self, api_key: Optional[str], base_url: Optional[str], timeout: float,
+                 max_retries: int, default_headers: Optional[Mapping[str, str]]) -> None:
+        api_key = api_key or os.environ.get("DIPSAC_API_KEY")
+        if not api_key:
+            raise DipsacError(
+                "No API key. Pass api_key=\"dps_...\" or set the DIPSAC_API_KEY environment "
+                "variable. Keys are made at https://dipsac.com/dashboard/keys")
+        self.api_key = api_key
+        self.base_url = (base_url or os.environ.get("DIPSAC_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max(0, int(max_retries))
+        self._headers = {"X-API-Key": api_key, "User-Agent": f"dipsac-python/{__version__}",
+                         "Accept": "*/*", **dict(default_headers or {})}
+
+    def _build(self, method: str, path: str, *, query: Optional[Mapping[str, Any]],
+               json: Optional[Mapping[str, Any]], form: Optional[Mapping[str, Any]],
+               files: Optional[Mapping[str, Any]], timeout: Optional[float]) -> Dict[str, Any]:
+        kwargs: Dict[str, Any] = {
+            "method": method,
+            "url": path if path.startswith(("http://", "https://")) else self.base_url + path,
+            "timeout": self.timeout if timeout is None else timeout,
+        }
+        q = {k: _scalar(v) for k, v in _clean(query).items()}
+        if q:
+            kwargs["params"] = q
+        if json is not None:
+            kwargs["json"] = _clean(json)
+        fields = {k: _scalar(v) for k, v in _clean(form).items()}
+        parts: List[Tuple[str, Tuple[str, bytes, str]]] = []
+        for name, value in _clean(files).items():
+            many = value if isinstance(value, (list, tuple)) and not _is_file_tuple(value) else [value]
+            for one in many:
+                parts.append((name, to_part(one, name)))
+        if parts:
+            kwargs["files"] = parts
+        if fields:
+            kwargs["data"] = fields
+        return kwargs
+
+    def _parse(self, response: httpx.Response) -> Tuple[str, Any]:
+        """("json" | "file" | "job" | "none", value), or raise for an error status."""
+        ctype = (response.headers.get("content-type") or "").split(";")[0].strip().lower()
+        is_json = ctype == "application/json" or ctype.endswith("+json")
+        if response.status_code >= 400:
+            body: Any
+            try:
+                body = response.json() if is_json else response.text
+            except ValueError:
+                body = response.text
+            raise error_for(response.status_code, body, response.headers)
+        if is_json:
+            data = response.json()
+            if response.status_code == 202 and isinstance(data, dict) and data.get("job_id"):
+                return "job", data
+            return "json", data
+        if not response.content:
+            return "none", None
+        return "file", DipsacFile(response.content, content_type=ctype or "application/octet-stream",
+                                  filename=filename_from(response.headers), headers=response.headers)
+
+    def _retry_in(self, attempt: int, method: str, *, response: Optional[httpx.Response] = None,
+                  exc: Optional[BaseException] = None) -> Optional[float]:
+        """Seconds to wait before another try, or None to give up. See the header."""
+        if attempt >= self.max_retries:
+            return None
+        backoff = min(8.0, 0.5 * (2 ** attempt)) * (0.75 + random.random() / 2)
+        if exc is not None:
+            never_sent = isinstance(exc, (httpx.ConnectError, httpx.ConnectTimeout))
+            return backoff if never_sent or method == "GET" else None
+        assert response is not None
+        if response.status_code == 429:
+            try:
+                asked = float(response.headers.get("retry-after", "1"))
+            except ValueError:
+                asked = 1.0
+            return max(asked, 0.2) if asked <= MAX_RETRY_AFTER else None
+        if response.status_code in (502, 503, 504) and method == "GET":
+            return backoff
+        return None
+
+
+def _is_file_tuple(value: Any) -> bool:
+    """("name.pdf", content[, type]) is ONE file, not a list of two or three."""
+    return (isinstance(value, tuple) and len(value) in (2, 3) and isinstance(value[0], str)
+            and not isinstance(value[1], (str, os.PathLike)) and (len(value) == 2 or isinstance(value[2], str)))
+
+
+def _wrap(exc: httpx.HTTPError) -> APIConnectionError:
+    if isinstance(exc, httpx.TimeoutException):
+        return APITimeoutError(f"No answer from the API within the timeout ({type(exc).__name__}).")
+    return APIConnectionError(f"Could not reach the API ({type(exc).__name__}: {exc}).")
+
+
+class Dipsac(_Core):
+    """The DIPSAC API.
+
+        from dipsac import Dipsac
+
+        client = Dipsac(api_key="dps_...")       # or set DIPSAC_API_KEY
+        client.pdf.merge(["a.pdf", "b.pdf"]).save("merged.pdf")
+
+    Args:
+        api_key: your key; read from DIPSAC_API_KEY when left out.
+        base_url: the API's address; https://api.dipsac.com unless set.
+        timeout: seconds to wait for an answer (default 300; conversions take time).
+        max_retries: how many times a refused or unsent request is tried again.
+        default_headers: extra headers for every request.
+        http_client: your own httpx.Client, e.g. for a proxy.
+    """
+
+    def __init__(self, api_key: Optional[str] = None, *, base_url: Optional[str] = None,
+                 timeout: float = DEFAULT_TIMEOUT, max_retries: int = DEFAULT_MAX_RETRIES,
+                 default_headers: Optional[Mapping[str, str]] = None,
+                 http_client: Optional[httpx.Client] = None) -> None:
+        super().__init__(api_key, base_url, timeout, max_retries, default_headers)
+        self._http = http_client or httpx.Client(follow_redirects=False)
+        self._owns_http = http_client is None
+        for name, (sync_cls, _async_cls) in RESOURCES.items():
+            setattr(self, name, sync_cls(self))
+
+    def job(self, job_id: str) -> Job:
+        """A handle on a /v1 job you already have the id of. Makes no request."""
+        return Job(self, {"job_id": job_id, "status_url": f"/v1/jobs/{job_id}"})
+
+    def _request(self, method: str, path: str, *, query: Optional[Mapping[str, Any]] = None,
+                 json: Optional[Mapping[str, Any]] = None, form: Optional[Mapping[str, Any]] = None,
+                 files: Optional[Mapping[str, Any]] = None, multipart: bool = False,
+                 timeout: Optional[float] = None) -> Any:
+        kwargs = self._build(method, path, query=query, json=json, form=form, files=files, timeout=timeout)
+        attempt = 0
+        while True:
+            try:
+                response = self._http.request(headers=self._headers, **kwargs)
+            except httpx.HTTPError as exc:
+                wait = self._retry_in(attempt, method, exc=exc)
+                if wait is None:
+                    raise _wrap(exc) from exc
+            else:
+                wait = self._retry_in(attempt, method, response=response)
+                if wait is None:
+                    kind, value = self._parse(response)
+                    return Job(self, value) if kind == "job" else value
+            attempt += 1
+            time.sleep(wait)
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> "Dipsac":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+
+class AsyncDipsac(_Core):
+    """The DIPSAC API, for asyncio. Same methods as Dipsac, awaited.
+
+        async with AsyncDipsac() as client:
+            merged = await client.pdf.merge(["a.pdf", "b.pdf"])
+    """
+
+    def __init__(self, api_key: Optional[str] = None, *, base_url: Optional[str] = None,
+                 timeout: float = DEFAULT_TIMEOUT, max_retries: int = DEFAULT_MAX_RETRIES,
+                 default_headers: Optional[Mapping[str, str]] = None,
+                 http_client: Optional[httpx.AsyncClient] = None) -> None:
+        super().__init__(api_key, base_url, timeout, max_retries, default_headers)
+        self._http = http_client or httpx.AsyncClient(follow_redirects=False)
+        self._owns_http = http_client is None
+        for name, (_sync_cls, async_cls) in RESOURCES.items():
+            setattr(self, name, async_cls(self))
+
+    def job(self, job_id: str) -> AsyncJob:
+        """A handle on a /v1 job you already have the id of. Makes no request."""
+        return AsyncJob(self, {"job_id": job_id, "status_url": f"/v1/jobs/{job_id}"})
+
+    async def _request(self, method: str, path: str, *, query: Optional[Mapping[str, Any]] = None,
+                       json: Optional[Mapping[str, Any]] = None, form: Optional[Mapping[str, Any]] = None,
+                       files: Optional[Mapping[str, Any]] = None, multipart: bool = False,
+                       timeout: Optional[float] = None) -> Any:
+        # Reading the files is blocking work; a large upload would hold the loop.
+        kwargs = await asyncio.to_thread(self._build, method, path, query=query, json=json,
+                                         form=form, files=files, timeout=timeout)
+        attempt = 0
+        while True:
+            try:
+                response = await self._http.request(headers=self._headers, **kwargs)
+            except httpx.HTTPError as exc:
+                wait = self._retry_in(attempt, method, exc=exc)
+                if wait is None:
+                    raise _wrap(exc) from exc
+            else:
+                wait = self._retry_in(attempt, method, response=response)
+                if wait is None:
+                    kind, value = self._parse(response)
+                    return AsyncJob(self, value) if kind == "job" else value
+            attempt += 1
+            await asyncio.sleep(wait)
+
+    async def close(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncDipsac":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()

dipsac/_errors.py

@@ -0,0 +1,182 @@
+"""Everything this library raises.
+
+    DipsacError
+    ├── APIConnectionError        the request never got an answer
+    │   └── APITimeoutError
+    ├── APIStatusError            the API answered with an error
+    │   ├── BadRequestError            400
+    │   ├── AuthenticationError        401  the key is missing or wrong
+    │   ├── PaymentRequiredError       402  an allowance is used up
+    │   ├── PermissionDeniedError      403  the plan does not include this
+    │   ├── NotFoundError              404
+    │   ├── ConflictError              409  e.g. a job that has not finished
+    │   ├── PayloadTooLargeError       413
+    │   ├── UnsupportedMediaTypeError  415  the wrong kind of file
+    │   ├── UnprocessableEntityError   422  a parameter is missing or invalid
+    │   ├── RateLimitError             429
+    │   └── InternalServerError        500 and above
+    ├── JobFailedError            a background job ended in failure
+    └── JobTimeoutError           wait() ran out of time; the job may still finish
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Mapping, Optional
+
+
+class DipsacError(Exception):
+    """Base class of every error raised by this library."""
+
+
+class APIConnectionError(DipsacError):
+    """The API could not be reached, or the connection broke before an answer."""
+
+
+class APITimeoutError(APIConnectionError):
+    """No answer arrived within the timeout."""
+
+
+class APIStatusError(DipsacError):
+    """The API answered with an error status.
+
+    Attributes:
+        status_code: the HTTP status.
+        code: the API's short name for the error, e.g. ``rate_limited``.
+        message: the API's sentence about it.
+        request_id: quote this to DIPSAC support.
+        body: the whole response body, parsed if it was JSON.
+        headers: the response headers (lower-case names).
+    """
+
+    def __init__(self, message: str, *, status_code: int, code: Optional[str] = None,
+                 request_id: Optional[str] = None, body: Any = None,
+                 headers: Optional[Mapping[str, str]] = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.code = code
+        self.request_id = request_id
+        self.body = body
+        self.headers: Dict[str, str] = dict(headers or {})
+
+    def __str__(self) -> str:
+        bits = [f"{self.status_code}"]
+        if self.code:
+            bits.append(self.code)
+        text = f"[{' '.join(bits)}] {self.message}"
+        return f"{text} (request_id {self.request_id})" if self.request_id else text
+
+    def _field(self, name: str) -> Any:
+        return self.body.get(name) if isinstance(self.body, dict) else None
+
+
+class BadRequestError(APIStatusError):
+    pass
+
+
+class AuthenticationError(APIStatusError):
+    pass
+
+
+class PaymentRequiredError(APIStatusError):
+    """An allowance or quota is used up; the body carries the numbers."""
+
+
+class PermissionDeniedError(APIStatusError):
+    """The key's plan does not include this endpoint."""
+
+    @property
+    def required_plan(self) -> Optional[str]:
+        return self._field("required_plan")
+
+    @property
+    def current_plan(self) -> Optional[str]:
+        return self._field("current_plan")
+
+
+class NotFoundError(APIStatusError):
+    pass
+
+
+class ConflictError(APIStatusError):
+    pass
+
+
+class PayloadTooLargeError(APIStatusError):
+    pass
+
+
+class UnsupportedMediaTypeError(APIStatusError):
+    @property
+    def accepted(self) -> Optional[List[str]]:
+        """The file types this endpoint takes."""
+        return self._field("accepted")
+
+
+class UnprocessableEntityError(APIStatusError):
+    @property
+    def fields(self) -> Optional[List[Dict[str, Any]]]:
+        """Which parameters were refused, and why."""
+        return self._field("fields")
+
+
+class RateLimitError(APIStatusError):
+    """Too many requests.
+
+    ``retry_after`` is how many seconds the API asked to wait. A second or two
+    is the per-second limit; a day is the plan's monthly limit, used up.
+    """
+
+    @property
+    def retry_after(self) -> Optional[float]:
+        raw = self.headers.get("retry-after")
+        try:
+            return float(raw) if raw is not None else None
+        except ValueError:
+            return None
+
+
+class InternalServerError(APIStatusError):
+    pass
+
+
+class JobFailedError(DipsacError):
+    """A background job ended in failure. ``job`` is the job, with its last status."""
+
+    def __init__(self, message: str, job: Any = None) -> None:
+        super().__init__(message)
+        self.job = job
+
+
+class JobTimeoutError(DipsacError):
+    """wait() gave up. The job itself was not cancelled and may still finish."""
+
+    def __init__(self, message: str, job: Any = None) -> None:
+        super().__init__(message)
+        self.job = job
+
+
+_BY_STATUS = {
+    400: BadRequestError, 401: AuthenticationError, 402: PaymentRequiredError,
+    403: PermissionDeniedError, 404: NotFoundError, 409: ConflictError,
+    413: PayloadTooLargeError, 415: UnsupportedMediaTypeError,
+    422: UnprocessableEntityError, 429: RateLimitError,
+}
+
+
+def error_for(status_code: int, body: Any, headers: Mapping[str, str]) -> APIStatusError:
+    """The right exception for an error response."""
+    lowered = {k.lower(): v for k, v in headers.items()}
+    code = message = request_id = None
+    if isinstance(body, dict):
+        code = body.get("error") if isinstance(body.get("error"), str) else None
+        for key in ("message", "detail"):
+            if isinstance(body.get(key), str) and body[key]:
+                message = body[key]
+                break
+        request_id = body.get("request_id") if isinstance(body.get("request_id"), str) else None
+    elif isinstance(body, str) and body.strip():
+        message = body.strip()[:500]
+    request_id = request_id or lowered.get("x-request-id")
+    cls = _BY_STATUS.get(status_code) or (InternalServerError if status_code >= 500 else APIStatusError)
+    return cls(message or f"The API answered {status_code}.", status_code=status_code, code=code,
+               request_id=request_id, body=body, headers=lowered)

dipsac/_files.py

@@ -0,0 +1,101 @@
+"""Turning what a caller hands over into one part of an upload.
+
+A file may be given as:
+
+    "report.pdf" or Path("report.pdf")     a path; the file is read
+    open("report.pdf", "rb")               an open binary file
+    b"%PDF-1.7 ..."                        the bytes themselves
+    ("report.pdf", data)                   a name and bytes (or an open file)
+    ("report.pdf", data, "application/pdf")
+
+THE NAME MATTERS. The API decides what a file is by the extension of its name
+and refuses one it does not expect ("'file' has unsupported type"). A path and
+an open file carry their own name. Bare bytes carry none, so their type is read
+from how they begin (PDF, PNG, JPEG, GIF, WebP, WAV, MP3, MP4, OGG, FLAC, WebM
+and GLB are recognised); for anything else, a Word file for one, pass the tuple
+form.
+
+EVERY UPLOAD IS READ INTO MEMORY BEFORE IT IS SENT. The API requires a
+Content-Length on uploads and answers 411 to a chunked body, and a length is
+only certain once the bytes are in hand.
+"""
+from __future__ import annotations
+
+import mimetypes
+import os
+from typing import IO, Any, Optional, Tuple, Union
+
+FileContent = Union[bytes, bytearray, memoryview, IO[bytes]]
+FileInput = Union[
+    str,
+    "os.PathLike[str]",
+    bytes,
+    bytearray,
+    memoryview,
+    IO[bytes],
+    Tuple[str, FileContent],
+    Tuple[str, FileContent, str],
+]
+
+_MAGIC = (
+    (b"%PDF", "pdf"), (b"\x89PNG\r\n\x1a\n", "png"), (b"\xff\xd8\xff", "jpg"),
+    (b"GIF87a", "gif"), (b"GIF89a", "gif"), (b"ID3", "mp3"), (b"\xff\xfb", "mp3"),
+    (b"\xff\xf3", "mp3"), (b"OggS", "ogg"), (b"fLaC", "flac"), (b"glTF", "glb"),
+    (b"\x1a\x45\xdf\xa3", "webm"),
+)
+
+
+def _sniff(head: bytes) -> Optional[str]:
+    """An extension for bytes that came with no name, or None."""
+    for magic, ext in _MAGIC:
+        if head.startswith(magic):
+            return ext
+    if head[:4] == b"RIFF" and head[8:12] == b"WEBP":
+        return "webp"
+    if head[:4] == b"RIFF" and head[8:12] == b"WAVE":
+        return "wav"
+    if head[4:8] == b"ftyp":
+        return "mp4"
+    return None
+
+
+def _read(content: Any) -> bytes:
+    if isinstance(content, (bytes, bytearray, memoryview)):
+        return bytes(content)
+    if hasattr(content, "read"):
+        data = content.read()
+        if isinstance(data, str):
+            raise TypeError("a file must be opened in binary mode ('rb'), not text mode")
+        return bytes(data)
+    raise TypeError(f"cannot upload a {type(content).__name__}; pass a path, bytes, "
+                    f"an open binary file, or a (filename, content) tuple")
+
+
+def to_part(value: Any, field: str = "file") -> Tuple[str, bytes, str]:
+    """(filename, bytes, content type) for one uploaded file."""
+    filename: Optional[str] = None
+    content_type: Optional[str] = None
+    if isinstance(value, tuple):
+        if len(value) == 2:
+            filename, content = value
+        elif len(value) == 3:
+            filename, content, content_type = value
+        else:
+            raise TypeError("a file tuple is (filename, content) or (filename, content, content_type)")
+        data = _read(content)
+    elif isinstance(value, (str, os.PathLike)):
+        path = os.fspath(value)
+        with open(path, "rb") as fh:
+            data = fh.read()
+        filename = os.path.basename(path)
+    else:
+        data = _read(value)
+        name = getattr(value, "name", None)
+        if isinstance(name, str) and name and not name.startswith("<"):
+            filename = os.path.basename(name)
+    if not filename:
+        ext = _sniff(data[:16])
+        filename = f"{field}.{ext}" if ext else field
+    if not content_type:
+        content_type = mimetypes.guess_type(filename)[0] or "application/octet-stream"
+    return str(filename), data, content_type