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

easyvista_python_client/_fields.py

@@ -0,0 +1,26 @@
+"""Shared helpers for extracting human labels from EasyVista field objects.
+
+EasyVista nests label+href objects (``STATUS``, ``DEPARTMENT``, ``CATALOG_REQUEST``,
+``URGENCY``, ``IMPACT``). Both the Markdown renderer (:mod:`context`) and the
+statistics aggregator (:mod:`reporting`) need to pick the human label and never an
+href, so the logic lives here once.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def _text(value: Any) -> str:
+    """First stripped string form of ``value``; ``""`` if it is not a string."""
+    return value.strip() if isinstance(value, str) else ""
+
+
+def _label(obj: Any, keys: tuple[str, ...]) -> str:
+    """First non-empty string among ``keys`` of a nested object; never an href."""
+    if isinstance(obj, dict):
+        for key in keys:
+            value = obj.get(key)
+            if isinstance(value, str) and value.strip():
+                return value.strip()
+    return ""

easyvista_python_client/_html.py

@@ -0,0 +1,41 @@
+"""Reduce HTML (EasyVista rich-text fields) to plain text, stdlib only."""
+
+from __future__ import annotations
+
+import re
+from html.parser import HTMLParser
+
+_BLOCK_TAGS = {"p", "div", "li", "tr", "h1", "h2", "h3", "h4", "h5", "h6"}
+
+
+class _TextExtractor(HTMLParser):
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)  # entities -> unicode in handle_data
+        self._parts: list[str] = []
+
+    def handle_data(self, data: str) -> None:
+        self._parts.append(data)
+
+    def handle_starttag(self, tag: str, attrs: object) -> None:
+        if tag == "br":
+            self._parts.append("\n")
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag in _BLOCK_TAGS:
+            self._parts.append("\n")
+
+    def text(self) -> str:
+        return "".join(self._parts)
+
+
+def html_to_text(value: str | None) -> str:
+    """Strip HTML tags and unescape entities; plain text passes through; None -> ''."""
+    if value is None:
+        return ""
+    parser = _TextExtractor()
+    parser.feed(value)
+    text = parser.text()
+    # Trim trailing spaces on each line, then collapse 3+ newlines to a blank line.
+    text = "\n".join(line.strip() for line in text.split("\n"))
+    text = re.sub(r"\n{3,}", "\n\n", text)
+    return text.strip()

easyvista_python_client/_sync/__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._sync.client import EasyvistaClient
+
+__all__ = ["EasyvistaClient"]

easyvista_python_client/_sync/_concurrency.py

@@ -0,0 +1,50 @@
+"""Sequential concurrency primitives for the sync client.
+
+Hand-written twin of the async ``_concurrency`` module -- see that module for
+why these two files are the only ones not generated.
+
+**This file is not produced by the codegen and must be edited alongside its
+async twin.** ``unasync_build.py`` excludes it by name.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class Semaphore:
+    """A no-op context manager standing in for :class:`asyncio.Semaphore`.
+
+    The async surface bounds its fan-out width because every branch is in
+    flight at once. Here the branches have already run, one after another, by
+    the time the enclosing ``settle`` is entered -- concurrency is one, so
+    there is nothing to bound. Accepting and ignoring the width keeps the
+    call site identical on both surfaces.
+    """
+
+    def __init__(self, value: int) -> None:
+        self.value = value
+
+    def __enter__(self) -> Semaphore:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        return None
+
+
+def settle(*values: Any) -> list[Any]:
+    """Return ``values`` unchanged, preserving order.
+
+    This looks like a no-op and is doing real work. On the async side the call
+    reads ``await settle(self.a(), self.b())`` and runs the two concurrently.
+    Stripping the ``await`` leaves ``settle(self.a(), self.b())``, where each
+    argument has already been evaluated -- in order -- by the time this is
+    entered. Collecting them is therefore the correct and complete
+    synchronous meaning of the same expression, including its failure
+    behaviour: a raise in an earlier argument prevents the later ones from
+    being evaluated at all.
+    """
+    return list(values)
+
+
+__all__ = ["Semaphore", "settle"]

easyvista_python_client/_sync/_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 (
+    Retrying,
+    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.Client(
+            headers=self.headers(),
+            auth=self.auth(),
+            timeout=config.timeout,
+            verify=config.verify_ssl,
+        )
+
+    def __enter__(self) -> Transport:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._client.close()
+
+    def _do_send(self, spec: RequestSpec) -> Any:
+        response = 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)
+
+    def send(self, spec: RequestSpec) -> Any:
+        retryer = Retrying(
+            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 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
+
+    def _do_get_bytes(self, path_or_url: str) -> bytes:
+        response = 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
+
+    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 = Retrying(
+            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 = 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