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

easyvista_python_client/_transport.py

@@ -0,0 +1,29 @@
+"""Shared request description for the EasyVista client.
+
+``RequestSpec`` is all this module holds, and it stays here permanently. It is
+a frozen dataclass with no I/O, imported by every resource builder in
+``resources/`` (actions, assets, departments, descriptor, documents,
+employees, requests -- seven modules), so it sits at the package root while
+the executors that consume it live in the generated trees. A shared resource
+builder must not import from a tree, and a pure value type with no I/O has no
+business living inside one either.
+
+Everything else EasyVista-specific about talking to the API -- URL building,
+auth headers, error mapping, the executor -- lives in
+``_async/_transport.py`` and its generated ``_sync/`` twin.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class RequestSpec:
+    """A resource-relative HTTP request, independent of sync/async execution."""
+
+    method: str
+    path: str
+    params: dict[str, Any] | None = None
+    json: dict[str, Any] | None = None

easyvista_python_client/config.py

@@ -0,0 +1,71 @@
+"""Connection configuration for the EasyVista client."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class EasyvistaConfig:
+    """Immutable connection settings.
+
+    Provide either ``token`` (Bearer) or ``login`` + ``password`` (Basic).
+    """
+
+    server: str
+    account: str
+    token: str | None = field(default=None, repr=False)
+    login: str | None = None
+    password: str | None = field(default=None, repr=False)
+    timeout: float = 30.0
+    max_retries: int = 0
+    verify_ssl: bool = True
+    default_max_rows: int = 100
+    api_version: str = "v1"
+    _server_normalized: str = field(init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "_server_normalized", self.server.rstrip("/"))
+        if not self.token and not (self.login and self.password):
+            raise ValueError(
+                "An EasyVista credential is required: pass token=... or "
+                "login=... and password=..."
+            )
+
+    @property
+    def api_root(self) -> str:
+        return f"{self._server_normalized}/api/{self.api_version}/{self.account}"
+
+    @property
+    def uses_basic_auth(self) -> bool:
+        return self.token is None
+
+    @classmethod
+    def from_env(cls) -> EasyvistaConfig:
+        """Build config from environment variables.
+
+        Reads ``EASYVISTA_URL`` (or ``EASYVISTA_SERVER``), ``EASYVISTA_ACCOUNT``,
+        then ``EASYVISTA_TOKEN`` or ``EASYVISTA_TOKEN_FILE``, else
+        ``EASYVISTA_LOGIN`` / ``EASYVISTA_PASSWORD``.
+        """
+        server = os.environ.get("EASYVISTA_URL") or os.environ.get("EASYVISTA_SERVER")
+        account = os.environ.get("EASYVISTA_ACCOUNT")
+        if not server or not account:
+            raise ValueError(
+                "EASYVISTA_URL (or EASYVISTA_SERVER) and EASYVISTA_ACCOUNT must be set."
+            )
+
+        token = os.environ.get("EASYVISTA_TOKEN")
+        token_file = os.environ.get("EASYVISTA_TOKEN_FILE")
+        if not token and token_file:
+            with open(token_file, encoding="utf-8") as handle:
+                token = handle.read().strip()
+
+        return cls(
+            server=server,
+            account=account,
+            token=token,
+            login=os.environ.get("EASYVISTA_LOGIN"),
+            password=os.environ.get("EASYVISTA_PASSWORD"),
+        )

easyvista_python_client/context.py

@@ -0,0 +1,116 @@
+"""Aggregated ticket context and an href-free Markdown renderer."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ._fields import _label, _text
+from ._html import html_to_text
+from .models.action import Action
+from .models.document import Document
+from .models.request import Request
+
+
+def _cell(value: str) -> str:
+    """Make a value safe inside a Markdown table cell."""
+    return value.replace("|", "\\|").replace("\n", " ").strip()
+
+
+@dataclass
+class TicketContext:
+    """A ticket plus its resolved narrative content.
+
+    Holds the *raw* resolved text (``description``/``comment`` may still be HTML);
+    :meth:`to_markdown` does the plain-text reduction and formatting.
+    """
+
+    ticket: Request
+    description: str | None
+    comment: str | None
+    actions: list[Action]
+    documents: list[Document]
+
+    def to_markdown(self) -> str:
+        """Render an href-free Markdown document for this ticket."""
+        data = self.ticket.model_dump(by_alias=True)
+        rfc = self.ticket.rfc_number or "(unknown)"
+        title = _text(data.get("TITLE"))
+        lines: list[str] = [f"# Ticket {rfc}" + (f" — {title}" if title else ""), ""]
+
+        rows: list[tuple[str, str]] = []
+        for label, value in (
+            ("Status", self.ticket.reference("STATUS").display),
+            ("Department", self.ticket.reference("DEPARTMENT").display),
+            ("Location", self.ticket.reference("LOCATION").display),
+            ("Catalog", self.ticket.reference("CATALOG_REQUEST").display),
+            ("Created", _text(data.get("CREATION_DATE_UT"))),
+            ("Updated", _text(data.get("LAST_UPDATE"))),
+        ):
+            if value:
+                rows.append((label, value))
+        if rows:
+            lines.append("| Field | Value |")
+            lines.append("|-------|-------|")
+            lines.extend(f"| {k} | {_cell(v)} |" for k, v in rows)
+            lines.append("")
+
+        # Headings name the ROLE a block plays in this ticket, decided from the
+        # data in hand -- not the EasyVista field it came from.
+        #
+        # Which memo carries a ticket's body is a per-deployment fact. On the
+        # verified instance DESCRIPTION is unused and the body arrives in
+        # COMMENT (0/15 sampled tickets had a non-empty DESCRIPTION, 15/15 had a
+        # COMMENT), and `RequestUpdate.description` writes COMMENT too -- so
+        # this library's own tickets export that way on any instance. Titling
+        # that block "Comment" mislabels the single most important part of the
+        # document for an LLM, or for a RAG chunker splitting on "## ".
+        #
+        # But the opposite hard-coding is just as wrong: an instance that
+        # populates DESCRIPTION properly uses COMMENT for a genuine follow-up
+        # note, and fusing or relabelling the two would destroy a real
+        # distinction. So neither universal is asserted. When only one memo has
+        # text it IS the body, whichever it came from, and is titled
+        # "Description"; when both do, the distinction is real and each keeps
+        # its own heading. An instance where DESCRIPTION works renders exactly
+        # as it did before.
+        description = html_to_text(self.description)
+        comment = html_to_text(self.comment)
+        if description and comment:
+            lines.extend(["## Description", "", description, ""])
+            lines.extend(["## Comment", "", comment, ""])
+        elif description or comment:
+            lines.extend(["## Description", "", description or comment, ""])
+
+        if self.actions:
+            lines.extend(["## Actions", ""])
+            for action in self.actions:
+                adata = action.model_dump(by_alias=True)
+                type_label = _label(adata.get("ACTION_TYPE"), ("NAME_EN", "NAME_FR"))
+                type_label = (
+                    type_label or _text(adata.get("ACTION_LABEL_FR")) or "Action"
+                )
+                author = _text(adata.get("DONE_BY"))
+                heading = type_label + (f" — {author}" if author else "")
+                lines.append(f"### {heading}")
+                # DESCRIPTION carries the note text once get_ticket_context has
+                # resolved it; COMMENT is a separate field that never does
+                # (verified live). Fall back to it only for records that
+                # predate resolution.
+                body = html_to_text(
+                    action.description if isinstance(action.description, str) else None
+                ) or html_to_text(
+                    action.comment if isinstance(action.comment, str) else None
+                )
+                if body:
+                    lines.extend(["", body])
+                lines.append("")
+
+        if self.documents:
+            lines.extend(["## Attachments", ""])
+            for doc in self.documents:
+                name = doc.filename or doc.name
+                if name:
+                    lines.append(f"- {name}")
+            lines.append("")
+
+        return "\n".join(lines).rstrip() + "\n"

easyvista_python_client/directory.py

@@ -0,0 +1,53 @@
+"""Directory aggregation and fuzzy department resolution (client-agnostic helpers)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .models.asset import Asset
+from .models.department import Department
+from .models.employee import Employee
+from .models.request import Request
+from .reporting import TicketStatistics
+
+# O-DIR-1: the descending-sort token for "most recent" is not yet live-confirmed.
+# EasyVista ignores an unknown ``sort`` param (falls back to default order) rather
+# than erroring, so this is safe; adjust once confirmed against the live instance.
+RECENT_TICKETS_SORT = "RFC_NUMBER:DESC"
+
+
+@dataclass
+class DepartmentContext:
+    """A department plus its related directory/ticket/asset context.
+
+    Only ``department`` is guaranteed; every related part degrades to ``[]`` / ``None``
+    / ``0`` when a profile restriction (403) or a missing record (404) blocks it.
+    """
+
+    department: Department
+    employees: list[Employee]
+    manager: Employee | None
+    note: str | None
+    ticket_count: int
+    recent_tickets: list[Request]
+    ticket_statistics: TicketStatistics | None
+    assets: list[Asset]
+
+
+def _normalize_name(value: str) -> str:
+    """Case-, space- and hyphen-insensitive key for fuzzy name matching."""
+    return value.replace("-", "").replace(" ", "").lower()
+
+
+def _department_matches(dept: Department, needle: str) -> bool:
+    """True if ``needle`` (already normalized) is a substring of any string field.
+
+    Scans every localized label + code + path (all string fields), skipping the
+    record's own ``HREF`` so a URL never yields a false positive.
+    """
+    for key, value in dept.model_dump(by_alias=True).items():
+        if isinstance(key, str) and key.upper() == "HREF":
+            continue
+        if isinstance(value, str) and needle in _normalize_name(value):
+            return True
+    return False

easyvista_python_client/exceptions.py

@@ -0,0 +1,53 @@
+"""Exception hierarchy for the EasyVista client."""
+
+from __future__ import annotations
+
+
+class EasyvistaError(Exception):
+    """Base class for all EasyVista client errors."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        ev_code: str | None = None,
+        ev_message: str | None = None,
+        body: bytes | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.ev_code = ev_code
+        self.ev_message = ev_message
+        # The raw response body, for a caller that hit one the transport does
+        # not recognize (an nginx/WAF HTML page, a plain-text 5xx). The
+        # transport deliberately stopped interpolating it into `message` (P2:
+        # nothing redacts exception TEXT, so it would print wherever the
+        # exception surfaces), which would otherwise make it unrecoverable.
+        # NOT passed to `super().__init__`, so it never becomes part of
+        # `.args` -- that is what keeps it out of `str()`/`repr()`.
+        self.body = body
+
+
+class EasyvistaAuthError(EasyvistaError):
+    """401 / 403 — authentication or authorization failed."""
+
+
+class EasyvistaNotFound(EasyvistaError):
+    """404 — resource not found."""
+
+
+class EasyvistaValidationError(EasyvistaError):
+    """400 — request rejected as invalid by EasyVista."""
+
+
+class EasyvistaRateLimitError(EasyvistaError):
+    """429 — rate limited."""
+
+
+class EasyvistaServerError(EasyvistaError):
+    """5xx — EasyVista server error."""
+
+
+class EasyvistaConnectionError(EasyvistaError):
+    """Transport-level failure (timeout, connection refused, etc.)."""

easyvista_python_client/field_model.py

@@ -0,0 +1,74 @@
+"""Generic, config-free classification of EasyVista record fields.
+
+Partitions any record's fields into official / custom (``e_``) / available
+(``available_field_x``) / link (href-only sub-resource) buckets, using the API's
+documented conventions. The model's own declared field aliases are the only
+"registry": a declared field is always official, so official ``E_``-columns like
+``E_MAIL`` are never mistaken for custom.
+
+Leaf module: stdlib only, no model/client imports.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any
+
+_AVAILABLE = re.compile(r"AVAILABLE_FIELD_\d+$")
+
+
+@dataclass(frozen=True)
+class FieldClassification:
+    """A record's fields split into four buckets (each field in exactly one)."""
+
+    official: dict[str, Any]
+    custom: dict[str, Any]
+    available: dict[str, Any]
+    links: dict[str, str]
+
+
+def classify(
+    record: dict[str, Any], declared: set[str] | None = None
+) -> FieldClassification:
+    """Partition ``record`` (a by-alias model dump). ``declared`` is the set of
+    the model's official field aliases, upper-cased; declared fields never count
+    as custom. Never raises; a non-dict yields empty buckets."""
+    declared = declared or set()
+    official: dict[str, Any] = {}
+    custom: dict[str, Any] = {}
+    available: dict[str, Any] = {}
+    links: dict[str, str] = {}
+    if isinstance(record, dict):
+        for key, value in record.items():
+            if not isinstance(key, str):
+                continue
+            upper = key.upper()
+            if upper == "HREF":
+                continue
+            if isinstance(value, dict) and set(value.keys()) == {"HREF"}:
+                links[key] = value["HREF"]
+            elif _AVAILABLE.match(upper):
+                available[key] = value
+            elif upper.startswith("E_") and upper not in declared:
+                custom[key] = value
+            else:
+                official[key] = value
+    return FieldClassification(
+        official=official, custom=custom, available=available, links=links
+    )
+
+
+def parse_memo(data: Any, field: str) -> str | None:
+    """The text of a Memo sub-resource response ``{"<FIELD>": "<text>", "HREF": …}``.
+
+    Matches ``field`` case-insensitively and returns its string value (``""`` for
+    an empty Memo). Returns ``None`` for a missing/non-string field or non-dict.
+    """
+    if not isinstance(data, dict):
+        return None
+    target = field.upper()
+    for key, value in data.items():
+        if isinstance(key, str) and key.upper() == target and isinstance(value, str):
+            return value
+    return None

easyvista_python_client/filters.py

@@ -0,0 +1,82 @@
+"""Safe builders for EasyVista ``search`` expressions.
+
+EasyVista's search grammar has two traps a caller cannot see, both verified
+against a live instance:
+
+1. An expression it cannot parse is **silently ignored** and every record is
+   returned — a filter that fails yields the whole table, not an error.
+2. ``,`` is a live combinator (OR within one field, AND across fields), so an
+   unescaped value that closes its quote can append conditions and silently
+   widen the result set.
+
+These builders exist so neither can happen. Filters return ``None`` for blank
+input so callers compose without conditionals::
+
+    search = ev_equals_filter("DEPARTMENT_CODE", code)
+    if search is not None:
+        client.search_departments(search=search)
+
+``field`` is expected to be a trusted, developer-supplied constant (e.g.
+``"DEPARTMENT_CODE"``) and is not validated; ``value`` is the untrusted input
+these builders check.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+# A double quote terminates the quoted value, letting a caller reach the ','
+# combinator; no escape for it is known (verified live). ',' itself is NOT
+# rejected: inside quotes it is inert, so without a '"' it cannot combine.
+_UNSAFE_CHARS = ('"',)
+
+
+def is_safe_ev_value(value: str) -> bool:
+    """Whether ``value`` can be rendered inside an EasyVista search expression."""
+    return not any(char in value for char in _UNSAFE_CHARS)
+
+
+def escape_ev_value(value: str) -> str:
+    """Render ``value`` for use inside a quoted EasyVista search value.
+
+    Raises ``ValueError`` if it cannot be rendered safely. ``ValueError`` — not
+    ``EasyvistaValidationError`` — because nothing reached the API: this is a
+    local input fault, not a server rejection.
+    """
+    if not is_safe_ev_value(value):
+        raise ValueError(
+            f"{value!r} cannot be used in an EasyVista search: the double-quote "
+            "character terminates a quoted value and EasyVista provides no escape "
+            "for it."
+        )
+    return value
+
+
+def ev_equals_filter(field: str, value: str | int | None) -> str | None:
+    """Build an exact-match filter: ``FIELD:"value"``."""
+    if value is None:
+        return None
+    text = str(value).strip()
+    if not text:
+        return None
+    return f'{field}:"{escape_ev_value(text)}"'
+
+
+def ev_in_filter(field: str, values: Iterable[str | int | None]) -> str | None:
+    """Build a "field is one of these" filter: ``FIELD:"a",FIELD:"b"``.
+
+    ``,`` is OR when every condition names the same field (verified live).
+    Blank values are skipped; no usable value returns ``None``.
+    """
+    parts = [f for f in (ev_equals_filter(field, v) for v in values) if f]
+    if not parts:
+        return None
+    return ",".join(parts)
+
+
+__all__ = [
+    "escape_ev_value",
+    "ev_equals_filter",
+    "ev_in_filter",
+    "is_safe_ev_value",
+]

easyvista_python_client/models/__init__.py

@@ -0,0 +1 @@
+"""Pydantic models for EasyVista resources."""

easyvista_python_client/models/action.py

@@ -0,0 +1,65 @@
+"""Models for EasyVista actions (≈ ticket followups)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import Field, model_validator
+
+from .common import EasyvistaModel, EasyvistaWriteModel, OptionalInt
+
+
+class Action(EasyvistaModel):
+    """An action recorded against a ticket.
+
+    Two shapes reach this model. ``list_actions`` returns a slim collection
+    record; ``get_action`` returns a much fuller item-level one whose
+    ``DESCRIPTION`` and ``COMMENT`` are Memo href objects. The note text a
+    caller supplied as ``PostAction.description`` comes back through
+    ``DESCRIPTION`` — **not** ``COMMENT``, and not on the list endpoint at all
+    (verified live). ``extra="allow"`` preserves everything else.
+    """
+
+    action_id: OptionalInt = Field(default=None, alias="ACTION_ID")
+    href: str | None = Field(default=None, alias="HREF")
+    comment: str | dict[str, Any] | None = Field(default=None, alias="COMMENT")
+    # Memo href object on the item-level GET; a plain string once resolved.
+    description: str | dict[str, Any] | None = Field(default=None, alias="DESCRIPTION")
+    # The live API returns ACTION_TYPE as a nested object (id/name/...), not a
+    # bare string, so accept either (same polymorphism as Request.description).
+    action_type: str | dict[str, Any] | None = Field(default=None, alias="ACTION_TYPE")
+
+    @model_validator(mode="after")
+    def _derive_action_id_from_href(self) -> Action:
+        """Populate ``action_id`` from ``href`` when the API omits it.
+
+        Defensive, and deliberately narrow: it fires only when ``href``'s
+        trailing segment is numeric. It does **not** fire for a create
+        response — ``POST requests/{rfc}/actions`` returns an HREF naming the
+        **parent request**, not the new action, so its tail is an RFC number
+        and ``.isdigit()`` correctly declines rather than inventing an id
+        (verified live). A created action's id is not recoverable from its
+        create response at all; see :meth:`EasyvistaClient.create_action`.
+        Reads that carry a real ``ACTION_ID`` are left untouched.
+        """
+        if self.action_id is None and isinstance(self.href, str) and self.href:
+            tail = self.href.rstrip("/").rsplit("/", 1)[-1].split("?", 1)[0]
+            if tail.isdigit():
+                self.action_id = int(tail)
+        return self
+
+
+class PostAction(EasyvistaWriteModel):
+    """Payload for creating an action on a ticket.
+
+    Field set follows the documented (and live-verified) create-action body:
+    identify the action type via ``action_type_id`` (or ``action_type_name``) and
+    the assigned group via ``group_id`` (or ``group_name``); ``description`` holds
+    the note text. Inherits ``custom_fields``/``to_api()`` from EasyvistaWriteModel.
+    """
+
+    action_type_id: int | None = None
+    action_type_name: str | None = None
+    group_id: int | None = None
+    group_name: str | None = None
+    description: str | None = None

easyvista_python_client/models/asset.py

@@ -0,0 +1,36 @@
+"""Models for the EasyVista ``assets`` resource.
+
+Field sets are the documented/common AM_ASSET fields; ``extra="allow"`` on the
+read model preserves any others. Exact field names pending live validation.
+"""
+
+from __future__ import annotations
+
+from pydantic import Field
+
+from .common import EasyvistaModel, EasyvistaWriteModel
+
+
+class Asset(EasyvistaModel):
+    """An asset as returned by the API."""
+
+    asset_id: int | None = Field(default=None, alias="ASSET_ID")
+    asset_tag: str | None = Field(default=None, alias="ASSET_TAG")
+    serial_number: str | None = Field(default=None, alias="SERIAL_NUMBER")
+    status_id: int | None = Field(default=None, alias="STATUS_ID")
+    href: str | None = Field(default=None, alias="HREF")
+
+
+class PostAsset(EasyvistaWriteModel):
+    """Payload for creating an asset.
+
+    ``catalog_id`` is required by EasyVista (identifies the equipment model).
+    ``custom_fields`` are serialized with an ``e_`` prefix (see EasyvistaWriteModel).
+    """
+
+    catalog_id: int
+    asset_tag: str | None = None
+    serial_number: str | None = None
+    status_id: int | None = None
+    comment_asset: str | None = None
+    installation_date: str | None = None

easyvista_python_client/models/common.py

@@ -0,0 +1,78 @@
+"""Shared Pydantic base models for EasyVista resources."""
+
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+from pydantic import BaseModel, BeforeValidator, ConfigDict, Field
+
+from ..field_model import FieldClassification, classify
+from ..references import Reference, resolve_reference
+
+
+def _empty_str_to_none(value: Any) -> Any:
+    """Coerce the API's empty-string sentinel for an absent scalar to ``None``.
+
+    EasyVista returns ``""`` for numeric columns that carry no value (e.g.
+    ``MANAGER_ID`` / ``FUNCTION_ID`` on the single-record directory GETs); without
+    this an ``int`` field would fail validation. Any non-empty or non-string value
+    passes through untouched.
+    """
+    if isinstance(value, str) and not value.strip():
+        return None
+    return value
+
+
+OptionalInt = Annotated[int | None, BeforeValidator(_empty_str_to_none)]
+"""An ``int | None`` field that treats the API's ``""`` sentinel as ``None``."""
+
+
+class EasyvistaModel(BaseModel):
+    """Base for read models.
+
+    Tolerates the API's ``ALL_CAPS`` field names (via aliases on subclasses) and
+    preserves unknown / custom ``e_*`` fields so they round-trip unchanged.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    def reference(self, name: str) -> Reference:
+        """Resolve a reference attribute (``STATUS``, ``URGENCY``, custom ``e_*``…)
+        to a normalized :class:`~easyvista_python_client.references.Reference`."""
+        return resolve_reference(self.model_dump(by_alias=True), name)
+
+    def classify_fields(self) -> FieldClassification:
+        """Partition this record's fields into official / custom (``e_*``) /
+        available / link buckets.
+
+        See :class:`~easyvista_python_client.field_model.FieldClassification`.
+        """
+        declared = {
+            (f.alias or name).upper() for name, f in type(self).model_fields.items()
+        }
+        return classify(self.model_dump(by_alias=True), declared)
+
+
+class EasyvistaWriteModel(BaseModel):
+    """Base for write payloads (create/update).
+
+    Rejects unknown fields (``extra="forbid"``) to catch caller typos, and
+    serializes ``custom_fields`` with an ``e_`` prefix (unless already prefixed).
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    custom_fields: dict[str, Any] = Field(default_factory=dict)
+
+    def to_api(self) -> dict[str, Any]:
+        """Return the API body: known fields (``None`` dropped) plus ``e_``-prefixed
+        custom fields.
+
+        Booleans may be sent as native JSON ``true``/``false`` (EasyVista also
+        accepts ``0``/``1`` and the strings ``"true"``/``"false"``).
+        """
+        data = self.model_dump(exclude_none=True, exclude={"custom_fields"})
+        for key, value in self.custom_fields.items():
+            api_key = key if key.startswith("e_") else f"e_{key}"
+            data[api_key] = value
+        return data