crafvy 0.3.1__py3-none-any.whl

crafvy/__init__.py

@@ -0,0 +1,42 @@
+"""The official Python SDK of the Crafvy API.
+
+::
+
+    from crafvy import Crafvy
+
+    crafvy = Crafvy("pb_...")
+    for project in crafvy.projects.list():
+        print(project["name"])
+"""
+from ._client import DEFAULT_BASE_URL, Crafvy, Transport, paginate, urllib_transport
+from ._errors import (
+    AuthenticationError,
+    AuthorizationError,
+    ConflictError,
+    CrafvyError,
+    NotFoundError,
+    RateLimitError,
+    ValidationError,
+)
+from ._generated.operations import API_VERSION, OPERATIONS
+from ._runtime import RequestOptions
+
+__version__ = API_VERSION
+
+__all__ = [
+    "API_VERSION",
+    "AuthenticationError",
+    "AuthorizationError",
+    "ConflictError",
+    "Crafvy",
+    "CrafvyError",
+    "DEFAULT_BASE_URL",
+    "NotFoundError",
+    "OPERATIONS",
+    "RateLimitError",
+    "RequestOptions",
+    "Transport",
+    "ValidationError",
+    "paginate",
+    "urllib_transport",
+]

crafvy/_client.py

@@ -0,0 +1,199 @@
+"""The client: authentication, the HTTP transport, retries and errors."""
+from __future__ import annotations
+
+import json
+import os
+import random
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from typing import Any, Callable, Dict, Iterator, List, Mapping, Optional, Tuple
+
+from ._errors import CrafvyError, error_for
+from ._generated.operations import API_VERSION
+from ._generated.resources import Resources
+from ._runtime import RequestOptions
+
+# (method, url, headers, body bytes or None, timeout seconds) -> (status, headers, body bytes)
+Transport = Callable[[str, str, Dict[str, str], Optional[bytes], Optional[float]], Tuple[int, Mapping[str, str], bytes]]
+
+DEFAULT_BASE_URL = "https://app.crafvy.com"
+_IDEMPOTENT = {"GET", "HEAD", "PUT", "DELETE"}
+_RETRYABLE_5XX = {500, 502, 503, 504}
+
+
+def urllib_transport(method: str, url: str, headers: Dict[str, str], body: Optional[bytes], timeout: Optional[float]) -> Tuple[int, Mapping[str, str], bytes]:
+    """The default transport: the standard library's urllib, no dependencies."""
+    req = urllib.request.Request(url, data=body, method=method, headers=headers)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as res:
+            return res.status, dict(res.headers.items()), res.read()
+    except urllib.error.HTTPError as err:
+        return err.code, dict(err.headers.items()) if err.headers else {}, err.read() or b""
+    except TimeoutError as err:
+        raise CrafvyError(f"Request timed out after {timeout}s", 408) from err
+    except urllib.error.URLError as err:
+        if isinstance(err.reason, TimeoutError):
+            raise CrafvyError(f"Request timed out after {timeout}s", 408) from err
+        raise
+
+
+class Crafvy(Resources):
+    """The Crafvy API.
+
+    ::
+
+        from crafvy import Crafvy
+
+        crafvy = Crafvy("pb_...")  # or the CRAFVY_TOKEN environment variable
+        projects = crafvy.projects.list(workspace_id="...")
+
+    A token acts as its owner: their roles, workspaces, feature gates and plan
+    limits apply exactly as in the dashboard. Create one under Settings →
+    Integrations → API Access Tokens.
+    """
+
+    def __init__(
+        self,
+        token: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: Optional[float] = 60.0,
+        retries: int = 3,
+        transport: Optional[Transport] = None,
+    ) -> None:
+        token = token or os.environ.get("CRAFVY_TOKEN")
+        if not token:
+            raise ValueError("Crafvy: pass a token, or set CRAFVY_TOKEN")
+        self._token = token
+        self._base_url = (base_url or os.environ.get("CRAFVY_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self._timeout = timeout
+        self._retries = retries
+        self._transport = transport or urllib_transport
+        super().__init__(self._call)
+
+    def raw(self, method: str, path: str, *, query: Optional[Dict[str, Any]] = None, body: Any = None, options: Optional[RequestOptions] = None) -> Any:
+        """Calls any path of the API directly — for an endpoint this SDK version has no method for yet."""
+        return self._call(method.upper(), path, query=query, body=body, options=options)
+
+    def _call(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Dict[str, Any]] = None,
+        body: Any = None,
+        multipart: bool = False,
+        options: Optional[RequestOptions] = None,
+    ) -> Any:
+        options = options or {}
+        url = self._base_url + path
+        if query:
+            pairs = [(k, _query_value(v)) for k, v in query.items() if v is not None]
+            if pairs:
+                url += "?" + urllib.parse.urlencode(pairs)
+        headers = {
+            "Authorization": f"Bearer {self._token}",
+            "Accept": "application/json",
+            "User-Agent": f"crafvy-python/{API_VERSION}",
+        }
+        data: Optional[bytes] = None
+        if body is not None:
+            if multipart:
+                data, content_type = _multipart(body)
+                headers["Content-Type"] = content_type
+            else:
+                data = json.dumps(body).encode("utf-8")
+                headers["Content-Type"] = "application/json"
+        headers.update(options.get("headers", {}))
+        retries = options.get("retries", self._retries)
+        timeout = options.get("timeout", self._timeout)
+
+        attempt = 0
+        while True:
+            status, res_headers, raw = self._transport(method, url, headers, data, timeout)
+            retryable = status == 429 or (status in _RETRYABLE_5XX and method in _IDEMPOTENT)
+            if retryable and attempt < retries:
+                time.sleep(_delay(attempt, _header(res_headers, "Retry-After")))
+                attempt += 1
+                continue
+            parsed: Any = None
+            if raw:
+                try:
+                    parsed = json.loads(raw.decode("utf-8"))
+                except ValueError:
+                    parsed = raw.decode("utf-8", errors="replace")
+            if status >= 400:
+                ra = _header(res_headers, "Retry-After")
+                raise error_for(status, parsed, float(ra) if ra and ra.replace(".", "", 1).isdigit() else None)
+            return parsed
+
+
+def _query_value(v: Any) -> str:
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    if isinstance(v, (dict, list)):
+        return json.dumps(v)
+    return str(v)
+
+
+def _header(headers: Mapping[str, str], name: str) -> Optional[str]:
+    for k, v in headers.items():
+        if k.lower() == name.lower():
+            return v
+    return None
+
+
+def _delay(attempt: int, retry_after: Optional[str]) -> float:
+    if retry_after:
+        try:
+            return float(retry_after)
+        except ValueError:
+            pass
+    return 0.5 * (2**attempt) + random.random() * 0.1
+
+
+def _multipart(fields: Mapping[str, Any]) -> Tuple[bytes, str]:
+    boundary = f"crafvy-{uuid.uuid4().hex}"
+    out: List[bytes] = []
+    for key, value in fields.items():
+        if value is None:
+            continue
+        if isinstance(value, (bytes, bytearray)):
+            out.append(f'--{boundary}\r\nContent-Disposition: form-data; name="{key}"; filename="{key}"\r\nContent-Type: application/octet-stream\r\n\r\n'.encode())
+            out.append(bytes(value))
+            out.append(b"\r\n")
+        elif isinstance(value, tuple) and len(value) >= 2:
+            filename, content = value[0], value[1]
+            ctype = value[2] if len(value) > 2 else "application/octet-stream"
+            out.append(f'--{boundary}\r\nContent-Disposition: form-data; name="{key}"; filename="{filename}"\r\nContent-Type: {ctype}\r\n\r\n'.encode())
+            out.append(content if isinstance(content, bytes) else str(content).encode())
+            out.append(b"\r\n")
+        else:
+            text = json.dumps(value) if isinstance(value, (dict, list)) else _query_value(value)
+            out.append(f'--{boundary}\r\nContent-Disposition: form-data; name="{key}"\r\n\r\n{text}\r\n'.encode())
+    out.append(f"--{boundary}--\r\n".encode())
+    return b"".join(out), f"multipart/form-data; boundary={boundary}"
+
+
+def paginate(fetch: Callable[..., Any], *, limit: int = 50, start_page: int = 1, **kwargs: Any) -> Iterator[Any]:
+    """Every item of a page-based list, one page at a time behind the scenes.
+
+    ::
+
+        for project in paginate(crafvy.projects.list, workspace_id=ws):
+            ...
+    """
+    page = start_page
+    while True:
+        items = fetch(page=page, limit=limit, **kwargs)
+        if isinstance(items, dict):
+            items = next((v for v in items.values() if isinstance(v, list)), [])
+        if not items:
+            return
+        yield from items
+        if len(items) < limit:
+            return
+        page += 1

crafvy/_errors.py

@@ -0,0 +1,79 @@
+"""Errors the SDK raises.
+
+Every refusal the API sends is ``{"success": false, "error": "...", "code": "..."}``.
+The SDK raises one of the classes below, carrying the HTTP ``status``, the API's
+machine-readable ``code`` (``tokenPermissionMissing``, ``crmSpaceNotFound``, ...)
+and the whole response ``body`` — branch on the code, not on the English text::
+
+    try:
+        crafvy.tasks.create({"workspaceId": ws, "title": "Call Anna"})
+    except CrafvyError as err:
+        if err.code == "tasksSpaceRequired":
+            ...
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class CrafvyError(Exception):
+    """Any error answer of the API (and a timeout, as status 408)."""
+
+    def __init__(self, message: str, status: int, body: Any = None, code: Optional[str] = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.body = body
+        if code is None and isinstance(body, dict) and isinstance(body.get("code"), str):
+            code = body["code"]
+        self.code = code
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(status={self.status}, code={self.code!r}, message={self.message!r})"
+
+
+class ValidationError(CrafvyError):
+    """400 — the request was refused as invalid."""
+
+
+class AuthenticationError(CrafvyError):
+    """401 — no token, or one that is not valid (any more)."""
+
+
+class AuthorizationError(CrafvyError):
+    """403 — not allowed: the owner's roles, or the token's permissions (``tokenPermissionMissing``, ``tokenScopeInsufficient``)."""
+
+
+class NotFoundError(CrafvyError):
+    """404 — nothing there, or nothing the token's owner may see."""
+
+
+class ConflictError(CrafvyError):
+    """409 — it clashes with what is there now (a name taken, a field changed meanwhile)."""
+
+
+class RateLimitError(CrafvyError):
+    """429 — too many requests, after the SDK's own retries. ``retry_after`` is in seconds, when the API said."""
+
+    def __init__(self, message: str, body: Any = None, retry_after: Optional[float] = None) -> None:
+        super().__init__(message, 429, body)
+        self.retry_after = retry_after
+
+
+_BY_STATUS = {
+    400: ValidationError,
+    401: AuthenticationError,
+    403: AuthorizationError,
+    404: NotFoundError,
+    409: ConflictError,
+}
+
+
+def error_for(status: int, body: Any, retry_after: Optional[float] = None) -> CrafvyError:
+    message = body.get("error") if isinstance(body, dict) and isinstance(body.get("error"), str) else f"HTTP {status}"
+    if status == 429:
+        return RateLimitError(message, body, retry_after)
+    cls = _BY_STATUS.get(status, CrafvyError)
+    if cls is CrafvyError:
+        return CrafvyError(message, status, body)
+    return cls(message, status, body)

crafvy/_generated/__init__.py

@@ -0,0 +1 @@
+"""Generated from sdks/openapi.json — do not edit."""