easier-acumatica 0.1.0__py3-none-any.whl

easier_acumatica/__init__.py

@@ -0,0 +1,5 @@
+"""easier-acumatica — a typed, predicate-based, ergonomic Python SDK for Laborde's Acumatica tenant."""
+
+from easier_acumatica.client import Acumatica, AcumaticaConfig
+
+__all__ = ["Acumatica", "AcumaticaConfig"]

easier_acumatica/client.py

@@ -0,0 +1,425 @@
+"""Config, login lifecycle, and the pooled session (see docs/architecture.md).
+
+``AcumaticaConfig`` is a frozen, env-driven configuration object.
+``Acumatica`` owns one pooled ``httpx.Client``, logs in exactly once at
+construction, and exposes the frozen ``request_json`` seam that the
+query/verb layers call against.
+"""
+
+from __future__ import annotations
+
+import math
+import os
+from dataclasses import dataclass, field
+from typing import Any, Mapping
+
+import httpx
+
+from . import exceptions
+from .registry import EntityBinding
+from .transport import RateLimitedTransport
+from .verbs import EntityAccessor
+
+#: The two endpoints this tenant has schemas for. A
+#: per-call ``endpoint=`` override in :meth:`Acumatica.request_json` may only
+#: name one of these — each name pins its own fixed version, independent of
+#: whatever the client's own configured default endpoint/version is.
+_ENDPOINT_VERSIONS: dict[str, str] = {
+    "Default": "24.200.001",
+    "LabordeCustom": "1.0",
+}
+
+_DEFAULT_TIMEOUT_SECONDS = 60.0
+_DEFAULT_CONNECT_TIMEOUT_SECONDS = 10.0
+_DEFAULT_RATE_LIMIT = 10.0
+_DEFAULT_ENDPOINT_NAME = "Default"
+_DEFAULT_ENDPOINT_VERSION = "24.200.001"
+
+_REQUIRED_ENV_LABELS: dict[str, str] = {
+    "username": "ACUMATICA_USERNAME",
+    "password": "ACUMATICA_PASSWORD",
+    "tenant": "ACUMATICA_TENANT",
+}
+
+
+def _default_timeout() -> httpx.Timeout:
+    return httpx.Timeout(_DEFAULT_TIMEOUT_SECONDS, connect=_DEFAULT_CONNECT_TIMEOUT_SECONDS)
+
+
+def _parse_positive_float(raw: str, *, var_name: str) -> float:
+    """Parse ``raw`` as a finite, positive float, or raise
+    :class:`~easier_acumatica.exceptions.ConfigError` naming ``var_name``
+    (so bad config gets "a clear error").
+
+    A bare ``float(raw)`` would let a malformed ``ACUMATICA_TIMEOUT``/
+    ``ACUMATICA_RATE_LIMIT`` escape ``from_env`` as a raw ``ValueError``
+    instead of this package's own hierarchy. Non-finite values need their
+    own check even after a successful parse: ``nan`` and ``inf`` both parse
+    fine, but ``nan <= 0`` is ``False`` (NaN compares unequal/false against
+    everything), so a bare non-positive check alone would silently accept
+    ``ACUMATICA_RATE_LIMIT=nan`` — which then disables the token bucket's
+    rate limiting entirely, because ``min(burst, tokens + elapsed*nan)``
+    always evaluates to ``burst`` (the bucket reports itself permanently
+    full).
+    """
+    try:
+        value = float(raw)
+    except ValueError:
+        raise exceptions.ConfigError(f"{var_name}={raw!r} is not a valid number") from None
+    if not math.isfinite(value) or value <= 0:
+        raise exceptions.ConfigError(f"{var_name}={raw!r} must be a finite number greater than 0")
+    return value
+
+
+@dataclass(frozen=True)
+class AcumaticaConfig:
+    """Frozen client configuration.
+
+    Construct directly, or via :meth:`from_env` for the ``ACUMATICA_*``
+    environment-variable contract.
+    """
+
+    url: str
+    username: str
+    password: str
+    tenant: str
+    branch: str | None = None
+    locale: str | None = None
+    endpoint_name: str = _DEFAULT_ENDPOINT_NAME
+    endpoint_version: str = _DEFAULT_ENDPOINT_VERSION
+    timeout: httpx.Timeout = field(default_factory=_default_timeout)
+    rate_limit: float = _DEFAULT_RATE_LIMIT
+
+    @classmethod
+    def from_env(cls, env: Mapping[str, str] | None = None) -> "AcumaticaConfig":
+        """Build a config from ``ACUMATICA_*`` environment variables.
+
+        Base URL: ``ACUMATICA_URL``, falling back to ``ACUMATICA_SITE_URL``
+        (some of the migrated integrations use the ``_SITE_URL`` name). Both
+        set and differing is a :class:`~easier_acumatica.exceptions.ConfigError`;
+        neither set is also a :class:`~easier_acumatica.exceptions.ConfigError`.
+        ``USERNAME``, ``PASSWORD``, ``TENANT`` are required — a
+        :class:`~easier_acumatica.exceptions.ConfigError` raised for missing
+        keys names *every* missing key, not just the first.
+
+        ``env`` defaults to ``os.environ``; pass an explicit mapping for
+        tests that want isolation from the real process environment.
+        """
+        source: Mapping[str, str] = os.environ if env is None else env
+
+        url = source.get("ACUMATICA_URL") or None
+        site_url = source.get("ACUMATICA_SITE_URL") or None
+        if url and site_url and url != site_url:
+            raise exceptions.ConfigError(
+                "ACUMATICA_URL and ACUMATICA_SITE_URL are both set but differ "
+                f"({url!r} vs {site_url!r}); set only one, or make them match."
+            )
+        resolved_url = url or site_url
+
+        values = {key: (source.get(label) or None) for key, label in _REQUIRED_ENV_LABELS.items()}
+
+        missing: list[str] = []
+        if not resolved_url:
+            missing.append("ACUMATICA_URL (or ACUMATICA_SITE_URL)")
+        missing.extend(label for key, label in _REQUIRED_ENV_LABELS.items() if not values[key])
+        if missing:
+            raise exceptions.ConfigError("Missing required Acumatica configuration: " + ", ".join(missing))
+
+        timeout_raw = source.get("ACUMATICA_TIMEOUT")
+        timeout = (
+            httpx.Timeout(
+                _parse_positive_float(timeout_raw, var_name="ACUMATICA_TIMEOUT"),
+                connect=_DEFAULT_CONNECT_TIMEOUT_SECONDS,
+            )
+            if timeout_raw
+            else _default_timeout()
+        )
+        rate_limit_raw = source.get("ACUMATICA_RATE_LIMIT")
+        rate_limit = (
+            _parse_positive_float(rate_limit_raw, var_name="ACUMATICA_RATE_LIMIT")
+            if rate_limit_raw
+            else _DEFAULT_RATE_LIMIT
+        )
+
+        assert resolved_url is not None  # `missing` would have caught this above
+        return cls(
+            url=resolved_url,
+            username=values["username"],  # type: ignore[arg-type]
+            password=values["password"],  # type: ignore[arg-type]
+            tenant=values["tenant"],  # type: ignore[arg-type]
+            branch=source.get("ACUMATICA_BRANCH") or None,
+            locale=source.get("ACUMATICA_LOCALE") or None,
+            endpoint_name=source.get("ACUMATICA_ENDPOINT_NAME") or _DEFAULT_ENDPOINT_NAME,
+            endpoint_version=source.get("ACUMATICA_ENDPOINT_VERSION") or _DEFAULT_ENDPOINT_VERSION,
+            timeout=timeout,
+            rate_limit=rate_limit,
+        )
+
+
+def _resolve_endpoint(config: AcumaticaConfig, endpoint: str | None) -> tuple[str, str]:
+    """Resolve a per-call ``endpoint=`` override to ``(name, version)``.
+
+    ``None`` uses the client's own configured default. ``"Default"``/
+    ``"LabordeCustom"`` are fixed overrides to their own pinned version
+    regardless of the client's configured default — anything else
+    is a caller error, not a server/config problem, so it raises
+    ``ValueError`` rather than :class:`~easier_acumatica.exceptions.ConfigError`.
+    """
+    if endpoint is None:
+        return config.endpoint_name, config.endpoint_version
+    try:
+        return endpoint, _ENDPOINT_VERSIONS[endpoint]
+    except KeyError:
+        raise ValueError(
+            f"Unknown endpoint override {endpoint!r}; expected one of {sorted(_ENDPOINT_VERSIONS)}"
+        ) from None
+
+
+class Acumatica:
+    """One pooled ``httpx.Client``, one login, one place requests flow through.
+
+    Construction performs exactly one login POST. Idle-401
+    recovery on GET is handled by :class:`~easier_acumatica.transport.RateLimitedTransport`,
+    which calls back into :meth:`_relogin` — a *second* login triggered by
+    session expiry, distinct from (and not a violation of) "one login at
+    construction".
+
+    Entity accessors (``acu.service_orders``) are OPT-IN via
+    :meth:`bind_registry` — see that method. Until a registry is bound there
+    are none, which is what keeps `client.py` free of any import of
+    ``profiles/**`` or of generated models.
+    """
+
+    #: Class-level default so :meth:`__getattr__` is safe to call at any
+    #: point during ``__init__`` (before the instance attribute exists) and
+    #: on a partially-constructed instance — otherwise a failed attribute
+    #: lookup there would recurse.
+    _registry: "Mapping[str, EntityBinding]" = {}
+
+    def __init__(self, config: AcumaticaConfig) -> None:
+        self._config = config
+        self._transport = RateLimitedTransport(
+            rate=config.rate_limit,
+            relogin=self._relogin,
+        )
+        # httpx joins `base_url` + a relative request path by straight
+        # concatenation of raw paths (not RFC 3986 "replace last segment"
+        # semantics) — so `base_url` must end with "/" and request paths
+        # must not start with "/", or the join silently mangles the URL.
+        # This also makes a tenant hosted under a sub-path (e.g.
+        # ".../AcumaticaERP/") join correctly, not just a bare-domain one.
+        base_url = config.url if config.url.endswith("/") else config.url + "/"
+        self._http = httpx.Client(
+            base_url=base_url,
+            transport=self._transport,
+            timeout=config.timeout,
+            headers={"Accept": "application/json", "Content-Type": "application/json"},
+        )
+        # httpx.Client's own `cookies=` constructor
+        # argument COPIES a `Cookies` object into a fresh jar rather than
+        # aliasing it (confirmed against httpx 0.28.1) — so building one jar
+        # ourselves and handing the same object to both the transport and
+        # the Client (the old approach) leaves the transport holding a jar
+        # that never receives a single `Set-Cookie`, and every idle-401
+        # replay goes out anonymous. The Client must be constructed first
+        # (it needs `self._transport` already built); only then does its
+        # own `.cookies` — the actual live jar httpx writes `Set-Cookie`
+        # into — exist to hand to the transport, via the late-bind setter.
+        self._transport.cookies = self._http.cookies
+        self._login()
+
+    @classmethod
+    def from_env(cls, env: Mapping[str, str] | None = None) -> "Acumatica":
+        """``Acumatica(AcumaticaConfig.from_env(env))`` — logs in immediately."""
+        return cls(AcumaticaConfig.from_env(env))
+
+    def _login_payload(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "name": self._config.username,
+            "password": self._config.password,
+            "tenant": self._config.tenant,
+        }
+        if self._config.branch:
+            payload["branch"] = self._config.branch
+        if self._config.locale:
+            payload["locale"] = self._config.locale
+        return payload
+
+    def _login(self) -> None:
+        """``POST entity/auth/login``; expect 204. Never raises :class:`Auth`
+        for a transport failure — only for a real
+        401 on this call.
+        """
+        try:
+            response = self._http.post("entity/auth/login", json=self._login_payload())
+        except httpx.HTTPError as exc:
+            # `httpx.HTTPError` (not just its
+            # `httpx.TransportError` subclass) so a login-time
+            # `httpx.DecodingError` (malformed content-encoding) or
+            # `httpx.TooManyRedirects` also classifies as `Server` rather
+            # than escaping this method raw — the intent is that
+            # *no* login-time failure escapes the exception hierarchy.
+            raise exceptions.classify_login_failure(transport_error=exc) from exc
+        if response.status_code != 204:
+            raise exceptions.classify_login_failure(response=response)
+
+    def _relogin(self) -> None:
+        """The callable :class:`~easier_acumatica.transport.RateLimitedTransport`
+        invokes on an idle-session GET 401. Same classification rules as the
+        initial login — a transient failure here is still never :class:`Auth`.
+        """
+        self._login()
+
+    def close(self) -> None:
+        """Best-effort ``POST entity/auth/logout``, then clear the cookie
+        jar and close the pooled client (logout "clears cookies"). The jar is cleared whether
+        or not the logout POST itself succeeded — "best-effort" describes
+        the POST, not the cleanup that follows it.
+        """
+        try:
+            self._http.post("entity/auth/logout")
+        except Exception:
+            pass
+        finally:
+            self._http.cookies.clear()
+            self._http.close()
+
+    def __enter__(self) -> "Acumatica":
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+    def request_json(
+        self,
+        method: str,
+        entity_path: str,
+        *,
+        endpoint: str | None = None,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+    ) -> Any:
+        """The frozen seam — the one entry point the query/verb layers call.
+
+        Builds ``{base}/entity/{endpoint_name}/{endpoint_version}/{entity_path}``,
+        sends ``Accept``/``Content-Type: application/json`` (client
+        defaults), and returns decoded JSON — ``dict | list | None``
+        (``None`` for any 2xx with an empty body, not just ``204``). Raises
+        the :mod:`easier_acumatica.exceptions` hierarchy for every other
+        case a completed response can be in:
+
+        - Any non-2xx/3xx status — via
+          :func:`~easier_acumatica.exceptions.classify_response`.
+        - A 3xx — this client never sets ``follow_redirects=True``, so a
+          completed redirect means something upstream is wrong (e.g. an
+          idle session bounced to a login page); also classified by
+          :func:`~easier_acumatica.exceptions.classify_response`, as
+          :class:`~easier_acumatica.exceptions.Server`.
+        - A 2xx body that isn't valid JSON (and isn't empty) — raises
+          :class:`~easier_acumatica.exceptions.Server` with a short body
+          snippet, rather than letting a raw ``json.JSONDecodeError``
+          escape this package's hierarchy.
+
+        Does not itself catch a transport-level failure (connect
+        error/timeout) — that propagates as a raw ``httpx`` exception,
+        by design ("raises a transport error");
+        only the *login* path wraps transport failures into
+        :class:`~easier_acumatica.exceptions.Server`.
+        """
+        endpoint_name, endpoint_version = _resolve_endpoint(self._config, endpoint)
+        url = f"entity/{endpoint_name}/{endpoint_version}/{entity_path.lstrip('/')}"
+        response = self._http.request(method, url, params=params, json=json)
+
+        error = exceptions.classify_response(response)
+        if error is not None:
+            raise error
+
+        # Every remaining status here is a genuine 2xx (classify_response
+        # now also classifies 3xx, above). A 204 — or any other 2xx an
+        # Acumatica endpoint answers with an empty body, e.g. 200/205 — has
+        # nothing to decode; anything else must be valid JSON, or this
+        # raises rather than letting `response.json()`'s raw
+        # `json.JSONDecodeError` escape the package hierarchy.
+        if not response.content:
+            return None
+        try:
+            return response.json()
+        except ValueError as exc:
+            try:
+                snippet = response.text[:200]
+            except Exception:
+                snippet = "<unreadable body>"
+            raise exceptions.Server(
+                f"Expected a JSON response body but could not decode it "
+                f"(status {response.status_code}): {snippet!r}"
+            ) from exc
+
+    # --- accessor mechanism -------------------------------------------------
+
+    def bind_registry(self, registry: Mapping[str, "EntityBinding"]) -> "Acumatica":
+        """Bind an accessor-name -> :class:`EntityBinding` registry.
+
+        After this, ``acu.<accessor_name>`` returns an
+        :class:`~easier_acumatica.verbs.EntityAccessor` for that binding —
+        the verbs (`get`/`get_or_none`/`get_list`/`put`/`delete`) and the
+        query builders (`where`/`select`/`expand`/`order_by`/`limit`/`all`/
+        `first`) on one object::
+
+            acu = Acumatica(cfg).bind_registry(REGISTRY)
+            acu.service_orders.get(type="IN", nbr="000123")
+            acu.service_orders.where(status="Open").limit(50).all()
+
+        Accessor names are snake_case plural; the CONTENTS are a
+        profile concern (the real Laborde registry ships with the generated
+        models), which is why this takes the registry as an argument
+        rather than importing one — `client.py` never imports `profiles/**`.
+
+        Returns `self`, so it chains off the constructor. Binding twice
+        REPLACES the registry rather than merging, and a name that would
+        shadow a real attribute/method on this class (`close`, `request_json`,
+        anything starting with `_`) is refused loudly here, at bind time,
+        rather than silently never resolving: `__getattr__` only runs after
+        normal lookup FAILS, so such a name would return the method instead
+        of the accessor.
+        """
+        for name in registry:
+            if name.startswith("_"):
+                raise ValueError(
+                    f"bind_registry: accessor name {name!r} may not start with '_' "
+                    "(reserved for internals)"
+                )
+            if hasattr(type(self), name):
+                raise ValueError(
+                    f"bind_registry: accessor name {name!r} shadows an existing "
+                    f"{type(self).__name__} attribute and would never resolve to the "
+                    "binding — rename the accessor"
+                )
+        self._registry = dict(registry)
+        return self
+
+    @property
+    def accessors(self) -> tuple[str, ...]:
+        """The bound accessor names, sorted. Empty until `bind_registry`."""
+        return tuple(sorted(self._registry))
+
+    def __getattr__(self, name: str) -> Any:
+        """Resolve ``acu.<accessor_name>`` against the bound registry.
+
+        Only ever called when normal attribute lookup has already failed, so
+        this can never shadow a real method (and `bind_registry` refuses any
+        name that would try). An unknown name raises `AttributeError` naming
+        the accessors that ARE known — a plain "no attribute" message is
+        useless when the whole surface is registry-driven.
+        """
+        # Dunder/private probes (copy, pickle, IPython, pytest assertion
+        # rewriting) must fail fast and never be answered from the registry.
+        if name.startswith("_"):
+            raise AttributeError(name)
+        registry = type(self)._registry if "_registry" not in self.__dict__ else self._registry
+        binding = registry.get(name)
+        if binding is None:
+            known = ", ".join(sorted(registry)) or "<none — call bind_registry(...) first>"
+            raise AttributeError(
+                f"{type(self).__name__} has no accessor {name!r}; known accessors: {known}"
+            )
+        return EntityAccessor(self, binding)