icedcoffee-sync 0.1.0.dev5__py3-none-any.whl

icedcoffee_sync/frappe/errors.py

@@ -0,0 +1,201 @@
+"""Typed exceptions for Frappe's error envelopes.
+
+Frappe reports failures two different ways, and both are live. The v2 API sends
+`{"errors": [{"type": ..., "message": ..., "exception": <traceback>}]}`. Older
+apps and `/api/method/` endpoints send `exc_type` alongside `_server_messages`,
+a JSON string holding a list of JSON strings -- two decodes, frequently absent
+or malformed.
+
+Everything here degrades to a usable exception rather than raising while
+handling an error. A parser that throws while reporting a failure replaces a
+diagnosable problem with a mysterious one.
+"""
+
+import json
+from typing import Any
+
+
+class FrappeError(Exception):
+    """Base for every error returned by a Frappe site."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        error_type: str | None = None,
+        status: int | None = None,
+        messages: list[str] | None = None,
+        server_traceback: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.error_type = error_type
+        self.status = status
+        self.messages = messages or []
+        self.server_traceback = server_traceback
+
+
+class ValidationError(FrappeError):
+    """A document failed Frappe's validation.
+
+    Raised for the named types below and for any error the site answers with
+    417 under a name this module does not know -- apps subclass
+    `frappe.ValidationError` for their own rules, and the status is the part
+    that stays put.
+    """
+
+
+class PermissionError_(FrappeError):
+    """The calling user lacks permission. Trailing underscore avoids the builtin."""
+
+
+class DoesNotExistError(FrappeError):
+    """The named document does not exist."""
+
+
+class DuplicateEntryError(FrappeError):
+    """A document with that name already exists."""
+
+
+class LinkExistsError(FrappeError):
+    """The document is linked from elsewhere and cannot be deleted."""
+
+
+class ChildExistsError(FrappeError):
+    """The document is a node in a tree and still has children.
+
+    Frappe's nested-set model (used by ERPNext's Account, among others)
+    refuses to delete a node with children -- delete or move the children
+    first. Measured against a live site as `error_type ==
+    "NestedSetChildExistsError"`, status 417, message like "Cannot delete
+    X as it has child nodes"; distinct from both `LinkExistsError` (a
+    document elsewhere references this one) and `ValidationError` (nothing
+    to do with the tree at all).
+    """
+
+
+class TimestampMismatchError(FrappeError):
+    """The document changed after it was read.
+
+    Frappe detects conflicts by comparing the `modified` timestamp sent with a
+    write against the stored one. This is optimistic concurrency failing, not a
+    server fault -- callers should re-read and retry.
+    """
+
+
+class RateLimitError(FrappeError):
+    """The site is rate limiting us."""
+
+
+# Frappe's status for a validation failure: `frappe.ValidationError` and every
+# subclass an app defines answer 417 (`http_status_code` on the exception).
+_VALIDATION_STATUS = 417
+
+_BY_TYPE: dict[str, type[FrappeError]] = {
+    "ValidationError": ValidationError,
+    "MandatoryError": ValidationError,
+    "PermissionError": PermissionError_,
+    "DoesNotExistError": DoesNotExistError,
+    "DuplicateEntryError": DuplicateEntryError,
+    "LinkExistsError": LinkExistsError,
+    "NestedSetChildExistsError": ChildExistsError,
+    "TimestampMismatch": TimestampMismatchError,
+    "TimestampMismatchError": TimestampMismatchError,
+}
+
+
+def parse_errors(payload: Any) -> list[dict[str, Any]]:
+    """Extract the v2 `errors` list, or an empty list if there isn't one."""
+    if not isinstance(payload, dict):
+        return []
+    errors = payload.get("errors")
+    if not isinstance(errors, list):
+        return []
+    return [item for item in errors if isinstance(item, dict)]
+
+
+def parse_server_messages(raw: str | None) -> list[str]:
+    """Extract human-readable strings from Frappe's `_server_messages`.
+
+    The value is a JSON string holding a list of JSON strings, each usually an
+    object with a `message` key. Returns an empty list for anything it cannot
+    decode -- a malformed diagnostic must never mask the error it describes.
+    """
+    if not raw:
+        return []
+    try:
+        outer = json.loads(raw)
+    except json.JSONDecodeError, TypeError:
+        return []
+    if not isinstance(outer, list):
+        return []
+
+    messages: list[str] = []
+    for item in outer:
+        if not isinstance(item, str):
+            continue
+        try:
+            inner: Any = json.loads(item)
+        except json.JSONDecodeError:
+            messages.append(item)
+            continue
+        if isinstance(inner, dict) and "message" in inner:
+            messages.append(str(inner["message"]))
+        elif isinstance(inner, str):
+            messages.append(inner)
+    return messages
+
+
+def error_from_response(status: int, body: str) -> FrappeError:
+    """Build the most specific exception the response supports."""
+    payload: dict[str, Any] = {}
+    try:
+        decoded = json.loads(body)
+        if isinstance(decoded, dict):
+            payload = decoded
+    except json.JSONDecodeError:
+        payload = {}
+
+    error_type: str | None = None
+    messages: list[str] = []
+    server_traceback: str | None = None
+
+    errors = parse_errors(payload)
+    if errors:
+        error_type = errors[0].get("type")
+        messages = [str(item["message"]) for item in errors if item.get("message")]
+        # Kept for debugging, deliberately never used as the message: it is a
+        # server-side Python traceback, not something to show a person.
+        raw_traceback = errors[0].get("exception")
+        server_traceback = str(raw_traceback) if raw_traceback else None
+    else:
+        error_type = payload.get("exc_type")
+        messages = parse_server_messages(payload.get("_server_messages"))
+
+    message = messages[0] if messages else str(payload.get("message") or body[:500]).strip()
+
+    if status == 429:
+        cls: type[FrappeError] = RateLimitError
+    else:
+        cls = _BY_TYPE.get(str(error_type), FrappeError)
+        if cls is FrappeError and status == _VALIDATION_STATUS:
+            # Frappe answers a validation failure with 417 whatever the
+            # exception is called, and apps raise their own
+            # `frappe.ValidationError` subclasses freely -- ERPNext's
+            # `StockAccountInvalidTransaction` ("Account: Stock In Hand - AB
+            # can only be updated via Stock Transactions", measured live), and
+            # one per app after that. Naming them all is a losing race, so an
+            # unrecognised name at this status is read as what the status
+            # means. The map still wins where it has an entry: a
+            # `NestedSetChildExistsError` is a 417 that is not a validation
+            # failure, and a `PermissionError` is a 403 that must never
+            # become one.
+            cls = ValidationError
+
+    return cls(
+        message,
+        error_type=error_type,
+        status=status,
+        messages=messages,
+        server_traceback=server_traceback,
+    )

icedcoffee_sync/frappe/lifecycle.py

@@ -0,0 +1,30 @@
+"""The draft-submit-cancel lifecycle of submittable doctypes.
+
+A plain insert creates a draft at docstatus 0. Submitting is a separate call,
+which makes "machines draft, humans submit" enforceable rather than merely
+agreed.
+"""
+
+from enum import IntEnum
+
+
+class DocStatus(IntEnum):
+    """Frappe's document states."""
+
+    DRAFT = 0
+    SUBMITTED = 1
+    CANCELLED = 2
+
+
+class SubmitNotPermittedError(RuntimeError):
+    """Raised when a client without submit capability touches the submit path.
+
+    Covers `submit`/`cancel` directly, a `call` naming a known committing
+    method, and an `insert`/`update` whose document body sets `docstatus`.
+
+    Not a server error -- the call is refused locally, before anything is
+    sent. This is a guardrail against an accidental submission from client
+    code, not a security boundary: the real boundary is the API key's role
+    permissions on the server, since a Frappe app can whitelist its own
+    committing methods that this client has no way to know about.
+    """

icedcoffee_sync/frappe/request.py

@@ -0,0 +1,145 @@
+"""Frappe requests as pure data.
+
+Nothing here performs I/O. Both the sync and async clients build their calls
+through these functions, so request shaping is tested once and cannot drift
+between the two.
+"""
+
+import dataclasses
+import json
+import re
+from typing import Any
+from urllib.parse import quote
+
+API_V2 = "/api/v2"
+
+
+@dataclasses.dataclass(frozen=True)
+class Request:
+    """A fully described HTTP call, ready for either client to send.
+
+    `json_body` covers every request but one: Frappe's file upload endpoint
+    takes multipart form data, not JSON. `data` and `files` carry that case --
+    kept as distinct fields rather than overloading `json_body`, so a request
+    is unambiguously either JSON or multipart and the send side can tell which
+    by checking `files`.
+    """
+
+    method: str
+    path: str
+    params: dict[str, str] = dataclasses.field(default_factory=dict)
+    headers: dict[str, str] = dataclasses.field(default_factory=dict)
+    json_body: dict[str, Any] | None = None
+    data: dict[str, Any] | None = None
+    files: dict[str, tuple[str, bytes]] | None = None
+
+
+def auth_header(key: str, secret: str) -> dict[str, str]:
+    """Frappe's API-key scheme: `Authorization: token <key>:<secret>`."""
+    return {"Authorization": f"token {key}:{secret}"}
+
+
+# A dotted path is a Python import path and nothing else. Validating it before
+# it reaches a URL closes a bypass: `frappe.client.submit#x` is not a member of
+# any denylist, but HTTP drops the fragment, so the server sees the bare method.
+# The same holds for a `?query` suffix.
+_DOTTED_PATH = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$")
+
+
+def _document_path(doctype: str, name: str | None = None) -> str:
+    path = f"{API_V2}/document/{quote(doctype, safe='')}"
+    if name is None:
+        return path
+    if not name:
+        # An empty name is falsy, and treating it as absent would silently turn
+        # a single-document request into a list of the whole doctype.
+        raise ValueError("document name must not be empty")
+    return f"{path}/{quote(name, safe='')}"
+
+
+def list_documents(
+    doctype: str,
+    *,
+    fields: list[str] | None = None,
+    filters: list[list[Any]] | dict[str, Any] | None = None,
+    limit: int | None = None,
+    start: int | None = None,
+    order_by: str | None = None,
+) -> Request:
+    """List documents. Absent options are omitted rather than sent empty."""
+    params: dict[str, str] = {}
+    if fields is not None:
+        params["fields"] = json.dumps(fields)
+    if filters is not None:
+        params["filters"] = json.dumps(filters)
+    if limit is not None:
+        params["limit"] = str(limit)
+    if start is not None:
+        params["start"] = str(start)
+    if order_by is not None:
+        params["order_by"] = order_by
+    return Request("GET", _document_path(doctype), params)
+
+
+def get_document(doctype: str, name: str) -> Request:
+    """Fetch one document by name."""
+    return Request("GET", _document_path(doctype, name))
+
+
+def insert_document(doctype: str, doc: dict[str, Any]) -> Request:
+    """Create a document. Submittable doctypes land as drafts at docstatus 0."""
+    return Request("POST", _document_path(doctype), json_body=doc)
+
+
+def update_document(doctype: str, name: str, doc: dict[str, Any]) -> Request:
+    """Update a document in place."""
+    return Request("PUT", _document_path(doctype, name), json_body=doc)
+
+
+def delete_document(doctype: str, name: str) -> Request:
+    """Delete a document."""
+    return Request("DELETE", _document_path(doctype, name))
+
+
+def call_method(dotted_path: str, params: dict[str, Any] | None = None) -> Request:
+    """Call a whitelisted server method.
+
+    Rejects anything that is not a plain dotted identifier path. A URL fragment
+    or query suffix would survive a string comparison against a denylist while
+    HTTP discarded it, so the server would receive a method the caller was
+    supposed to be refused.
+    """
+    # fullmatch, not match: `$` also matches before a trailing newline, so
+    # `frappe.client.submit\n` would pass while failing the exact denylist
+    # comparison the guard makes.
+    if not _DOTTED_PATH.fullmatch(dotted_path):
+        raise ValueError(f"not a dotted method path: {dotted_path!r}")
+    return Request("POST", f"{API_V2}/method/{dotted_path}", json_body=params or {})
+
+
+def upload_file(
+    doctype: str,
+    docname: str,
+    filename: str,
+    content: bytes,
+    *,
+    is_private: bool = True,
+    folder: str | None = None,
+) -> Request:
+    """Attach a file to a document via Frappe's multipart upload endpoint.
+
+    `/api/v2/method/upload_file` is the one server route this client sends
+    multipart to -- everything else is JSON. Confirmed against Frappe's
+    `develop` branch (`frappe/handler.py:upload_file`, routed at
+    `frappe/api/v2.py`): the file must ride in a part literally named `file`
+    (the handler reads it from `frappe.request.files["file"]`), and
+    `doctype`/`docname`/`folder`/`is_private` are plain form fields, not JSON.
+    `is_private` defaults to true here -- Frappe's own server-side default is
+    also private (`frappe.form_dict.get("is_private", 1)`), but a client for
+    financial documents states that choice rather than leaning on the
+    server's default.
+    """
+    data: dict[str, Any] = {"doctype": doctype, "docname": docname, "is_private": 1 if is_private else 0}
+    if folder is not None:
+        data["folder"] = folder
+    return Request("POST", f"{API_V2}/method/upload_file", data=data, files={"file": (filename, content)})

icedcoffee_sync/frappe/response.py

@@ -0,0 +1,76 @@
+"""Response parsing, shared by both clients.
+
+Frappe's v2 surface includes empty fields in its responses, which makes a
+cleared field distinguishable from one that was never selected. That
+distinction is the difference between "set this to null" and "leave it alone"
+during a sync, so it is preserved rather than flattened onto None.
+"""
+
+import json
+from typing import Any, Final
+
+from icedcoffee_sync.frappe.errors import FrappeError, error_from_response
+
+
+class _Missing:
+    """Sentinel for a key that was not present at all."""
+
+    _instance: _Missing | None = None
+
+    def __new__(cls) -> _Missing:
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __bool__(self) -> bool:
+        return False
+
+    def __repr__(self) -> str:
+        return "MISSING"
+
+
+MISSING: Final[_Missing] = _Missing()
+
+
+def envelope(status: int, body: str) -> Any:
+    """Return the whole parsed payload, or raise a typed error.
+
+    v2 list responses carry pagination alongside the rows --
+    `{"has_next_page": true, "data": [...]}` -- so anything that pages needs
+    the envelope rather than just its contents.
+    """
+    if status >= 400:
+        raise error_from_response(status, body)
+    try:
+        return json.loads(body)
+    except json.JSONDecodeError as exc:
+        raise FrappeError(f"expected JSON, got {body[:200]!r}", status=status) from exc
+
+
+def unwrap(status: int, body: str) -> Any:
+    """Return the response's `data` payload, or raise a typed error."""
+    payload = envelope(status, body)
+    if isinstance(payload, dict) and "data" in payload:
+        return payload["data"]
+    return payload
+
+
+def has_next_page(payload: Any) -> bool | None:
+    """Whether the server says more pages exist.
+
+    Returns None both when the payload carries no such flag -- v1 responses
+    do not -- and when the flag is present but explicitly null. Either way
+    the response cannot answer the question, and treating that as "no more
+    pages" would stop a listing early.
+    """
+    if not isinstance(payload, dict) or "has_next_page" not in payload:
+        return None
+    value = payload["has_next_page"]
+    if value is None:
+        return None
+    return bool(value)
+
+
+def field(doc: dict[str, Any], name: str) -> Any:
+    """Read a field, distinguishing absent (MISSING) from null (None)."""
+    return doc.get(name, MISSING)

icedcoffee_sync/site.py

@@ -0,0 +1,65 @@
+"""The checks every ERPNext site URL passes before a credential is sent to it.
+
+No allowlist lives here. A connector that only reaches allowlisted hosts
+connects to nobody; a demo-data tool that reaches any host is a hazard. So
+this module refuses what is always wrong -- a credential in the URL, no
+hostname, plain HTTP, a port that is not 443, anything past the site's root,
+and any host the caller names as refused -- and
+leaves "which hosts may I write to" to the caller.
+
+Refusal order is deliberate: userinfo first, because every later message
+quotes the URL back and a password typed into it must never reach stderr.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import MappingProxyType
+from urllib.parse import urlsplit
+
+HTTPS_PORT = 443
+
+
+class SiteUrlRefusedError(ValueError):
+    """The URL is one no ERPNext credential should be sent to."""
+
+
+def hostname(url: str) -> str:
+    """The URL's host, lowercased, without a trailing dot.
+
+    `host.` resolves to the same site as `host`; an equality check that
+    missed the dot would let a refused host through.
+    """
+    return (urlsplit(url).hostname or "").lower().rstrip(".")
+
+
+def require_safe_site_url(url: str, *, refused_hosts: Mapping[str, str] = MappingProxyType({})) -> None:
+    """Refuse a URL that carries a credential, is not https on 443, or names a refused host.
+
+    Args:
+        url: The site URL as the operator typed it.
+        refused_hosts: Hosts refused by name, ahead of every other check, so
+            the message says why rather than "not allowed". Maps each host to
+            the words that name it in the refusal ("the ledger").
+
+    Raises:
+        SiteUrlRefusedError: With a message that never contains userinfo.
+    """
+    parts = urlsplit(url)
+    if parts.username is not None or parts.password is not None:
+        raise SiteUrlRefusedError("refusing a site URL carrying a credential; pass the key and secret separately")
+    host = hostname(url)
+    if not host:
+        raise SiteUrlRefusedError(f"refusing {url!r}: no hostname")
+    if host in refused_hosts:
+        raise SiteUrlRefusedError(f"refusing {refused_hosts[host]} {host!r}")
+    if parts.scheme != "https":
+        raise SiteUrlRefusedError(f"refusing {url!r}: the API key rides in a header, so the scheme must be https")
+    try:
+        port = parts.port
+    except ValueError:
+        raise SiteUrlRefusedError(f"refusing {url!r}: unreadable port") from None
+    if port not in (None, HTTPS_PORT):
+        raise SiteUrlRefusedError(f"refusing {url!r}: port {port} is not {HTTPS_PORT}")
+    if parts.path not in ("", "/") or parts.query or parts.fragment:
+        raise SiteUrlRefusedError(f"refusing {url!r}: a site URL is the site's root, with no path, query, or fragment")

icedcoffee_sync-0.1.0.dev5.dist-info/METADATA

@@ -0,0 +1,9 @@
+Metadata-Version: 2.5
+Name: icedcoffee-sync
+Version: 0.1.0.dev5
+Summary: Typed sync and async client for the Frappe and ERPNext REST API
+Author-email: Gavin Carothers <gavin@carothers.name>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.14
+Requires-Dist: httpx2>=2.0.0

icedcoffee_sync-0.1.0.dev5.dist-info/RECORD

@@ -0,0 +1,29 @@
+icedcoffee_sync/__init__.py,sha256=bTtUXwyYtPngMUe6sJTqdXDmLqH0yTmppPgWka3eNFE,69
+icedcoffee_sync/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+icedcoffee_sync/site.py,sha256=l7a2zEde67aI5qTort9Ce59Bsf1a5sXTKswlWfe4ZsY,2789
+icedcoffee_sync/apply/__init__.py,sha256=eCNOPTYcIHmxSiasjpJ7uvJxpMC3d3Ezbb3g2Yw2ysg,266
+icedcoffee_sync/apply/diff.py,sha256=OhmX76P6lNsA34pPGMdpgRmQ8AUqxUzVCtiKanSrZKs,21080
+icedcoffee_sync/apply/execute.py,sha256=Fjxh2tPin-a5HRtXgCAxPyYRdEr0D2MDOpb3nT_lay0,7324
+icedcoffee_sync/apply/model.py,sha256=h5WS8NYGf1QcQvNI3r71WzGCfd_OWJ05sVZFnufxpm0,1454
+icedcoffee_sync/apply/order.py,sha256=kTWO7zsiFYJXzMTHOR3k0PWqKvTidDDYspzhcy0foiA,4862
+icedcoffee_sync/apply/park.py,sha256=wdiH2GeXj2M26Xrn76qHWUigJNoRPBzBkgiZPCt_gr0,4309
+icedcoffee_sync/apply/prune.py,sha256=5BBxGTkyKMXfAOkVMECihEzuHXm5bE8ctLclWe1oFDU,7809
+icedcoffee_sync/erpnext/__init__.py,sha256=1QbW1mjO1swPYLaKW1ECn6uuN5pkk3KYH77Gv4emJKY,72
+icedcoffee_sync/erpnext/accounts.py,sha256=J1uoLR6ArRUdPRjxngPnTyK8V6jEJA-EaqVDPFxUKQ4,6335
+icedcoffee_sync/erpnext/comment.py,sha256=CCGI4tdrtVQa9SZ_ftZP3Iokpy3w12PzqOx7XBami9g,2054
+icedcoffee_sync/erpnext/company.py,sha256=W4NoZ94waq0cgmtqPjJGS5HttcEbbXGaSBc3X8cIvpY,3710
+icedcoffee_sync/erpnext/documents.py,sha256=Rz-Qbd1kjKISKR0kq-5LVfZqxkgYzqze6vAqSCGa_QA,6439
+icedcoffee_sync/erpnext/ensure.py,sha256=fNphRV04k7Fr806lEldV_gBfQ-6uHkdPponZvziJ5fo,1131
+icedcoffee_sync/erpnext/purchase.py,sha256=Kfjy786vSWnUvIq6n3mwbKKsPqYto0uqo7SwpYUsyBM,9466
+icedcoffee_sync/erpnext/webhook.py,sha256=856caFbqvP8bSQUuzR-MKQ1u8WiHQpq-9crg_YqBHy0,5320
+icedcoffee_sync/frappe/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+icedcoffee_sync/frappe/access.py,sha256=B7Zcyl_B_WBA1JbieaSmlrVRWnS9TyKq_4n87t6tSMI,15732
+icedcoffee_sync/frappe/client.py,sha256=yNeU2nh_b24J-xcSFy4kPsVW4xa_5nVuTkeEYouLUWE,24341
+icedcoffee_sync/frappe/errors.py,sha256=o4ldcVOAMhexoReS43YfUWVe70bdCd3VQU9DBFL5gBw,7135
+icedcoffee_sync/frappe/lifecycle.py,sha256=Tr6rNeoprp4u1OhBMZM9e6FcQXviDT420GJhQoz6sFQ,1016
+icedcoffee_sync/frappe/request.py,sha256=hAHcMU3aYbsqMqGu_yDiNnKKCWltQHZfa8bfO02IdkY,5557
+icedcoffee_sync/frappe/response.py,sha256=d-OWoA-Xw7ySskKlakrkDr0KABUFut7ZdQcLfa_jwS0,2402
+icedcoffee_sync-0.1.0.dev5.dist-info/METADATA,sha256=2tmno21964o6zgN4sVI-bC7i7kzarvgPsNMD5Qho24Q,296
+icedcoffee_sync-0.1.0.dev5.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+icedcoffee_sync-0.1.0.dev5.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+icedcoffee_sync-0.1.0.dev5.dist-info/RECORD,,

icedcoffee_sync-0.1.0.dev5.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any