easyvista-python-client 0.1.0__py3-none-any.whl

easyvista_python_client/__init__.py

@@ -0,0 +1,74 @@
+"""Typed Python client for the EasyVista Service Manager REST API."""
+
+from easyvista_python_client._async import AsyncEasyvistaClient
+from easyvista_python_client._sync import EasyvistaClient
+
+from .config import EasyvistaConfig
+from .context import TicketContext
+from .directory import DepartmentContext
+from .exceptions import (
+    EasyvistaAuthError,
+    EasyvistaConnectionError,
+    EasyvistaError,
+    EasyvistaNotFound,
+    EasyvistaRateLimitError,
+    EasyvistaServerError,
+    EasyvistaValidationError,
+)
+from .field_model import FieldClassification
+from .filters import (
+    escape_ev_value,
+    ev_equals_filter,
+    ev_in_filter,
+    is_safe_ev_value,
+)
+from .models.action import Action, PostAction
+from .models.asset import Asset, PostAsset
+from .models.department import Department, DepartmentUpdate, PostDepartment
+from .models.document import Document
+from .models.employee import Employee, EmployeeUpdate, PostEmployee
+from .models.request import PostRequest, Request, RequestUpdate
+from .pagination import SearchResult
+from .references import Reference
+from .reporting import TicketStatistics, aggregate_tickets
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Action",
+    "Asset",
+    "AsyncEasyvistaClient",
+    "Department",
+    "DepartmentContext",
+    "DepartmentUpdate",
+    "Document",
+    "EasyvistaAuthError",
+    "EasyvistaClient",
+    "EasyvistaConfig",
+    "EasyvistaConnectionError",
+    "EasyvistaError",
+    "EasyvistaNotFound",
+    "EasyvistaRateLimitError",
+    "EasyvistaServerError",
+    "EasyvistaValidationError",
+    "Employee",
+    "EmployeeUpdate",
+    "FieldClassification",
+    "PostAction",
+    "PostAsset",
+    "PostDepartment",
+    "PostEmployee",
+    "PostRequest",
+    "Reference",
+    "Request",
+    "RequestUpdate",
+    "SearchResult",
+    "TicketContext",
+    "TicketStatistics",
+    "__version__",
+    "aggregate_tickets",
+    "escape_ev_value",
+    "ev_equals_filter",
+    "ev_in_filter",
+    "is_safe_ev_value",
+]

easyvista_python_client/_async/__init__.py

@@ -0,0 +1,13 @@
+"""The client tree: one hand-written async surface, one generated sync twin.
+
+This package exists twice, once per surface. Every module in it except
+``_concurrency.py`` and ``tests/test_concurrency.py`` has a counterpart in the
+other tree that ``unasync_build.py`` produces from the async one -- so the
+async copy is the only place a change belongs, and the sync copy must never be
+edited by hand. Run ``python unasync_build.py`` after any edit; CI's
+``--check`` fails if the two trees have drifted.
+"""
+
+from easyvista_python_client._async.client import AsyncEasyvistaClient
+
+__all__ = ["AsyncEasyvistaClient"]

easyvista_python_client/_async/_concurrency.py

@@ -0,0 +1,78 @@
+"""Asyncio concurrency primitives for the async client.
+
+This module and its sync twin are the only files maintained by hand on both
+sides of the codegen. Everything else in the sync tree is generated from the
+async one by :mod:`unasync`, which strips ``async``/``await`` and substitutes
+whole NAME tokens. That works for syntax; it cannot work here, because
+``asyncio.gather`` and ``asyncio.Semaphore`` are **dotted** names. unasync
+matches single NAME tokens only, and a dotted substitution key is accepted
+*silently and never fires* -- so a generated twin would call
+``asyncio.gather`` from synchronous code and break at runtime.
+
+Keeping both twins tiny is deliberate: hand-maintained duplication is a
+liability, so it is confined to the smallest possible surface.
+
+**Ordering is load-bearing and unenforced.** The sync twin's ``settle``
+returns already-evaluated arguments, so a fan-out's sync meaning is "evaluate
+these expressions left to right". That reproduces the sequential client only
+because each fan-out's arguments are written in the order the sequential code
+used. A future fan-out written out of order will generate sync code that
+issues requests in an order nobody intended, and no test will catch it.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+#: Bounded-concurrency primitive for the async surface.
+#:
+#: An :class:`asyncio.Semaphore`, and the sync twin is a no-op context
+#: manager. Neither substitutes for the other. Note that instances must be
+#: built **per call**, never stored on a client or at module level: an
+#: ``asyncio.Semaphore`` binds to the first event loop that *contends* it --
+#: an uncontended acquire never touches the loop at all -- so a stored one
+#: passes every low-traffic test and then raises ``RuntimeError: bound to a
+#: different event loop`` the first time a second loop contends it, i.e. in
+#: production under load (measured on 3.10).
+Semaphore = asyncio.Semaphore
+
+
+async def settle(*awaitables: Any) -> list[Any]:
+    """Run ``awaitables`` concurrently; return results in **source** order.
+
+    ``return_exceptions=True`` is load-bearing twice over, and removing it is
+    the tempting "simplification" this docstring exists to prevent.
+
+    First, orphans. A bare ``asyncio.gather`` propagates the first exception
+    while its siblings keep running -- it does not cancel them (measured).
+    Those orphaned requests outlive the call and can still be in flight when
+    ``__aexit__`` closes the client, which surfaces as a bare ``RuntimeError``
+    inside a task nobody awaits. Settling every awaitable first means no
+    request outlives the method that issued it.
+
+    Second, *which* exception wins. Collecting the results and re-raising the
+    first failure in source order reproduces the exception the sequential
+    code would have raised. A bare gather instead raises whichever failed
+    soonest on the clock, so the error a caller sees would depend on server
+    timing.
+
+    The cost, accepted deliberately: on a failing bundle every sibling still
+    runs to completion, so an error path can issue more requests than a
+    sequential version would. They are bounded by the fan-out width and they
+    are all reads.
+
+    The sync twin takes already-computed values and returns them. That is not
+    a stub: once unasync strips the ``await`` from a call site, each argument
+    expression evaluates eagerly where it is written, which *is* sequential
+    execution. The same call shape means "concurrently" here and "one after
+    the other" there, with no change to the calling code.
+    """
+    results = await asyncio.gather(*awaitables, return_exceptions=True)
+    for result in results:
+        if isinstance(result, BaseException):
+            raise result
+    return list(results)
+
+
+__all__ = ["Semaphore", "settle"]

easyvista_python_client/_async/_transport.py

@@ -0,0 +1,266 @@
+"""HTTP executor for the EasyVista client.
+
+Owns everything EasyVista-specific about talking to the API -- URL building,
+auth headers, error mapping, and the executor itself -- except
+``RequestSpec``, which stays at the package root because the shared resource
+builders and the probe scripts consume it without executing anything.
+
+This module exists once per client tree, and only the async copy is written by
+hand: ``unasync_build.py`` generates the sync one from it, and CI's
+``--check`` fails if the two have drifted. Edit the async copy and regenerate;
+hand-editing the generated one is a mistake the check will catch. Prose here
+must therefore read true on both surfaces -- never "see the other transport",
+and never a claim that holds on only one of them.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, NoReturn
+from urllib.parse import urlsplit
+
+import httpx
+from tenacity import (
+    AsyncRetrying,
+    retry_if_exception_type,
+    stop_after_attempt,
+    wait_exponential,
+)
+
+from easyvista_python_client._transport import RequestSpec
+from easyvista_python_client.config import EasyvistaConfig
+from easyvista_python_client.exceptions import (
+    EasyvistaAuthError,
+    EasyvistaConnectionError,
+    EasyvistaError,
+    EasyvistaNotFound,
+    EasyvistaRateLimitError,
+    EasyvistaServerError,
+    EasyvistaValidationError,
+)
+
+
+class BaseTransport:
+    """Pure transport logic, independent of how a request is executed (no I/O)."""
+
+    def __init__(self, config: EasyvistaConfig) -> None:
+        self.config = config
+
+    def build_url(self, path: str) -> str:
+        return f"{self.config.api_root}/{path.lstrip('/')}"
+
+    def resolve_url(self, path_or_url: str) -> str:
+        """Return an absolute URL for a resource path or an API-supplied URL.
+
+        Relative paths join to ``api_root`` exactly as :meth:`build_url` does.
+        An absolute URL is passed through **only when its scheme and host match
+        ``config.server``**, and raises otherwise.
+
+        That check is load-bearing, not decoration. Every request this transport
+        makes carries the instance's Bearer token, so following an absolute URL
+        taken out of a response body (an attachment's ``DDL_HREF``, say) would
+        hand that credential to whatever host the body named. The API is trusted
+        to describe its own instance, not to redirect us off it.
+        """
+        parsed = urlsplit(path_or_url)
+        if not parsed.scheme and not parsed.netloc:
+            return self.build_url(path_or_url)
+        server = urlsplit(self.config.server)
+        # Host comparison is case-folded because DNS is case-insensitive and
+        # this API returns mixed-case URLs (live: an upper-case "HTTPS://"
+        # scheme on DDL_HREF). Compare the RAW netloc, not .hostname: that
+        # keeps "https://attacker.test@ev.test/x" rejected, because its netloc
+        # is "attacker.test@ev.test", not "ev.test".
+        if (parsed.scheme, parsed.netloc.lower()) != (
+            server.scheme,
+            server.netloc.lower(),
+        ):
+            raise EasyvistaError(
+                f"refusing to fetch {parsed.scheme}://{parsed.netloc} — it is "
+                f"outside the configured instance "
+                f"({server.scheme}://{server.netloc})"
+            )
+        return path_or_url
+
+    def headers(self) -> dict[str, str]:
+        base = {"Accept": "application/json", "Content-Type": "application/json"}
+        if self.config.token:
+            base["Authorization"] = f"Bearer {self.config.token}"
+        return base
+
+    def auth(self) -> httpx.Auth | None:
+        if self.config.uses_basic_auth:
+            return httpx.BasicAuth(self.config.login or "", self.config.password or "")
+        return None
+
+    @staticmethod
+    def is_retryable_status(status_code: int) -> bool:
+        # 590 is EasyVista's "Internal Easyvista Error" — in practice a *rejected
+        # request* (bad catalog, missing mandatory field), so it is deterministic.
+        if status_code == 590:
+            return False
+        return status_code == 429 or status_code >= 500
+
+    def finish(self, response: httpx.Response) -> Any:
+        """Return parsed JSON for a success, or raise a mapped exception."""
+        if response.is_success:
+            if not response.content:
+                return {}
+            return response.json()
+        return self._raise_for_response(response)
+
+    def _raise_for_response(self, response: httpx.Response) -> NoReturn:
+        status = response.status_code
+        ev_code, ev_message = self._extract_error(response)
+        # Never interpolate the raw body: no layer redacts exception TEXT, and a
+        # short traceback still emits `E <Type>: <msg>` while the `-r` summary
+        # reuses it verbatim -- so an unrecognized body prints wherever the
+        # exception surfaces. The byte count keeps the diagnostic ("the server
+        # said something we do not parse, and it was this big") without the
+        # content; `.ev_message` and `.ev_code` carry the parsed values, and
+        # `.body` (below) carries the raw bytes themselves, for a caller with no
+        # other way to see what an unrecognized response actually said.
+        detail = ev_message or (
+            f"<{len(response.content)}-byte body with no recognized error key>"
+        )
+        message = f"EasyVista request failed ({status}): {detail}"
+        kwargs: dict[str, Any] = {
+            "status_code": status,
+            "ev_code": ev_code,
+            "ev_message": ev_message,
+            "body": response.content,
+        }
+        if status in (401, 403):
+            raise EasyvistaAuthError(message, **kwargs)
+        if status == 404:
+            raise EasyvistaNotFound(message, **kwargs)
+        if status == 400:
+            raise EasyvistaValidationError(message, **kwargs)
+        if status == 590:
+            raise EasyvistaValidationError(
+                f"{message} — EasyVista rejected the request (HTTP 590, code "
+                f"{ev_code}); this usually means a missing mandatory field or an "
+                f"invalid catalog reference for this catalog.",
+                **kwargs,
+            )
+        if status == 429:
+            raise EasyvistaRateLimitError(message, **kwargs)
+        if status >= 500:
+            raise EasyvistaServerError(message, **kwargs)
+        raise EasyvistaError(message, **kwargs)
+
+    @staticmethod
+    def _extract_error(response: httpx.Response) -> tuple[str | None, str | None]:
+        try:
+            data = response.json()
+        except ValueError:
+            return None, None
+        # EasyVista sometimes wraps the real error as a JSON string under "message".
+        if isinstance(data, dict) and isinstance(data.get("message"), str):
+            inner = data["message"].strip()
+            if inner.startswith("{"):
+                try:
+                    data = {**data, **json.loads(inner)}
+                except ValueError:
+                    pass
+        if not isinstance(data, dict):
+            return None, None
+        code = data.get("error_code") or data.get("code")
+        message = data.get("error") or data.get("error_message") or data.get("message")
+        return (
+            str(code) if code is not None else None,
+            str(message) if message is not None else None,
+        )
+
+
+class _RetryableResponse(Exception):  # internal control-flow signal
+    """Raised internally to trigger a tenacity retry on a 429/5xx response."""
+
+    def __init__(self, response: httpx.Response) -> None:
+        super().__init__(f"retryable status {response.status_code}")
+        self.response = response
+
+
+class Transport(BaseTransport):
+    """The executor: runs a :class:`RequestSpec` against the configured instance.
+
+    Blocking in the sync tree and coroutine-returning in the async tree, each
+    backed by the matching ``httpx`` client. Same methods, same arguments,
+    same results.
+    """
+
+    def __init__(self, config: EasyvistaConfig) -> None:
+        super().__init__(config)
+        self._client = httpx.AsyncClient(
+            headers=self.headers(),
+            auth=self.auth(),
+            timeout=config.timeout,
+            verify=config.verify_ssl,
+        )
+
+    async def __aenter__(self) -> Transport:
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def _do_send(self, spec: RequestSpec) -> Any:
+        response = await self._client.request(
+            spec.method, self.build_url(spec.path), params=spec.params, json=spec.json
+        )
+        if self.is_retryable_status(response.status_code):
+            raise _RetryableResponse(response)
+        return self.finish(response)
+
+    async def send(self, spec: RequestSpec) -> Any:
+        retryer = AsyncRetrying(
+            stop=stop_after_attempt(self.config.max_retries + 1),
+            wait=wait_exponential(multiplier=0.5, max=10),
+            retry=retry_if_exception_type((_RetryableResponse, httpx.TransportError)),
+            reraise=True,
+        )
+        try:
+            return await retryer(self._do_send, spec)
+        except _RetryableResponse as exc:
+            return self.finish(exc.response)
+        except httpx.TransportError as exc:
+            raise EasyvistaConnectionError(f"connection failed: {exc}") from exc
+
+    async def _do_get_bytes(self, path_or_url: str) -> bytes:
+        response = await self._client.get(
+            self.resolve_url(path_or_url), follow_redirects=True
+        )
+        if self.is_retryable_status(response.status_code):
+            raise _RetryableResponse(response)
+        if not response.is_success:
+            self._raise_for_response(response)
+        return response.content
+
+    async def get_bytes(self, path_or_url: str) -> bytes:
+        """GET raw bytes (an attachment), not JSON.
+
+        :meth:`BaseTransport.finish` always calls ``response.json()``, so binary
+        responses need their own path. This one reuses the same retry policy and
+        the same error mapping, so a 403 on an attachment still surfaces as
+        :class:`EasyvistaAuthError`. ``follow_redirects`` is on because a
+        download URL commonly redirects to a signed location; httpx strips the
+        ``Authorization`` header on a cross-origin redirect, so a foreign
+        redirect degrades to an unauthenticated fetch rather than leaking the
+        instance token.
+        """
+        retryer = AsyncRetrying(
+            stop=stop_after_attempt(self.config.max_retries + 1),
+            wait=wait_exponential(multiplier=0.5, max=10),
+            retry=retry_if_exception_type((_RetryableResponse, httpx.TransportError)),
+            reraise=True,
+        )
+        try:
+            result: bytes = await retryer(self._do_get_bytes, path_or_url)
+            return result
+        except _RetryableResponse as exc:
+            self._raise_for_response(exc.response)
+        except httpx.TransportError as exc:
+            raise EasyvistaConnectionError(f"connection failed: {exc}") from exc