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

easyvista_python_client/reporting.py

@@ -0,0 +1,143 @@
+"""Pure, offline ticket statistics — counts and per-dimension breakdowns.
+
+Network-free by design: it consumes already-fetched :class:`Request` objects so it
+can be unit-tested without a client. The sync/async clients fetch records and
+delegate to :func:`aggregate_tickets`.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any
+
+from .models.request import Request
+from .references import resolve_reference
+
+_FRACTION_RE = re.compile(r"\.(\d+)")
+
+
+def _parse_iso_datetime(value: Any) -> datetime | None:
+    """Parse an EasyVista timestamp to a timezone-aware ``datetime``, or ``None``.
+
+    Accepts a ``datetime`` (returned as-is, naive made UTC) or an ISO-8601 string.
+    Normalizes for Python 3.10's stricter ``fromisoformat``: maps a trailing ``Z``
+    to ``+00:00`` and pads/truncates fractional seconds to 6 digits. A naive result
+    is treated as UTC. Unparseable input returns ``None``.
+    """
+    if isinstance(value, datetime):
+        return value if value.tzinfo else value.replace(tzinfo=timezone.utc)
+    if not isinstance(value, str) or not value.strip():
+        return None
+    text = value.strip()
+    if text.endswith(("Z", "z")):
+        text = text[:-1] + "+00:00"
+    match = _FRACTION_RE.search(text)
+    if match:
+        frac6 = (match.group(1) + "000000")[:6]
+        text = text[: match.start()] + "." + frac6 + text[match.end() :]
+    try:
+        parsed = datetime.fromisoformat(text)
+    except ValueError:
+        return None
+    return parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)
+
+
+DEFAULT_DIMENSIONS: tuple[str, ...] = (
+    "STATUS",
+    "DEPARTMENT",
+    "CATALOG_REQUEST",
+    "URGENCY",
+    "IMPACT",
+)
+
+_UNKNOWN = "(unknown)"
+
+
+@dataclass
+class TicketStatistics:
+    """A ticket count plus per-dimension breakdowns.
+
+    ``total`` is the number of tickets aggregated (after any date window).
+    ``breakdowns`` maps each requested dimension name to ``{label: count}``; for
+    every dimension ``sum(breakdowns[dim].values()) == total``.
+    """
+
+    total: int
+    breakdowns: dict[str, dict[str, int]]
+
+
+def _dimension_value(data: dict[str, Any], name: str) -> str:
+    """Group key for one ticket on one dimension: label, else id, else unknown."""
+    return resolve_reference(data, name).display or _UNKNOWN
+
+
+def fields_for_references(
+    names: Sequence[str], *, include_creation_date: bool
+) -> list[str]:
+    """Search-projection field list covering every reference in ``names``.
+
+    Requests each reference's nested object and its id fields so both label and id
+    are available when aggregating over search results; over-requesting a
+    non-existent field is ignored by the API.
+    """
+    fields: list[str] = ["RFC_NUMBER"]
+    for name in names:
+        for field in (name, f"{name}_ID", f"{name}_GUID"):
+            if field not in fields:
+                fields.append(field)
+    if include_creation_date and "CREATION_DATE_UT" not in fields:
+        fields.append("CREATION_DATE_UT")
+    return fields
+
+
+def _bound(value: datetime | str | None, name: str) -> datetime | None:
+    """Parse a window bound; raise ValueError on a malformed string."""
+    if value is None:
+        return None
+    parsed = _parse_iso_datetime(value)
+    if parsed is None:
+        raise ValueError(f"{name} is not a valid datetime: {value!r}")
+    return parsed
+
+
+def aggregate_tickets(
+    tickets: Iterable[Request],
+    *,
+    dimensions: Sequence[str] = DEFAULT_DIMENSIONS,
+    created_since: datetime | str | None = None,
+    created_until: datetime | str | None = None,
+) -> TicketStatistics:
+    """Aggregate tickets into a total plus per-dimension breakdowns.
+
+    ``dimensions`` selects which breakdowns to compute (default: all of
+    ``DEFAULT_DIMENSIONS``); any field name is valid, including custom ``e_*``.
+    ``created_since`` / ``created_until`` are inclusive bounds on the ticket's
+    ``CREATION_DATE_UT`` (a ``datetime`` or ISO string); a ticket with a
+    missing/unparseable date is excluded when a bound is set. Raises ``ValueError``
+    for a malformed bound string.
+    """
+    since = _bound(created_since, "created_since")
+    until = _bound(created_until, "created_until")
+    filtering = since is not None or until is not None
+
+    total = 0
+    breakdowns: dict[str, dict[str, int]] = {dim: {} for dim in dimensions}
+    for ticket in tickets:
+        data = ticket.model_dump(by_alias=True)
+        if filtering:
+            created = _parse_iso_datetime(data.get("CREATION_DATE_UT"))
+            if created is None:
+                continue
+            if since is not None and created < since:
+                continue
+            if until is not None and created > until:
+                continue
+        total += 1
+        for dim in dimensions:
+            key = _dimension_value(data, dim)
+            counts = breakdowns[dim]
+            counts[key] = counts.get(key, 0) + 1
+    return TicketStatistics(total=total, breakdowns=breakdowns)

easyvista_python_client/resources/__init__.py

@@ -0,0 +1 @@
+"""Resource builders: pure functions returning (RequestSpec, parser)."""

easyvista_python_client/resources/actions.py

@@ -0,0 +1,72 @@
+"""Builders for the ticket ``actions`` sub-resource.
+
+``list_actions`` rides the generic search builder over the top-level ``/actions``
+resource (unwrapping the :class:`SearchResult` to a bare list). ``create_action``
+posts a bare body nested under the parent request, which does not fit the flat-CRUD
+engine, so it stays a small bespoke override alongside the ``ACTIONS`` descriptor.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from .._transport import RequestSpec
+from ..filters import ev_equals_filter
+from ..models.action import Action, PostAction
+from ..pagination import extract_records
+from .descriptor import ResourceDescriptor, build_get, build_search
+
+ACTIONS: ResourceDescriptor[Action] = ResourceDescriptor(
+    path="actions", envelope_key="actions", model=Action
+)
+
+
+def build_create_action(
+    rfc_number: str, payload: PostAction
+) -> tuple[RequestSpec, Callable[[Any], Action]]:
+    # Create is nested under the request, one action per call, with a bare body
+    # (NOT wrapped in an ``actions`` array) — verified against a live instance.
+    spec = RequestSpec("POST", f"requests/{rfc_number}/actions", json=payload.to_api())
+
+    def parse(data: Any) -> Action:
+        records = extract_records(data)
+        return Action.model_validate(records[0] if records else data)
+
+    return spec, parse
+
+
+def build_list_actions(
+    rfc_number: str,
+) -> tuple[RequestSpec, Callable[[Any], list[Action]]]:
+    # Actions are listed via the TOP-LEVEL /actions resource filtered by the
+    # request number, not a nested requests/{rfc}/actions path (which the API
+    # rejects as "Unauthorized Method"). Verified against a live instance.
+    # An unsafe rfc_number raises rather than degrading: ',' is a live combinator,
+    # so a raw value could append conditions and list another ticket's actions. A
+    # blank one must raise too — ev_equals_filter returns None for blank input, and
+    # search=None would list every action just as surely.
+    search = ev_equals_filter("REQUEST.RFC_NUMBER", rfc_number)
+    if search is None:
+        raise ValueError("rfc_number is required to list a ticket's actions")
+    spec, parse_search = build_search(ACTIONS, search=search)
+
+    def parse(data: Any) -> list[Action]:
+        return parse_search(data).records
+
+    return spec, parse
+
+
+def build_get_action(
+    action_id: str | int,
+) -> tuple[RequestSpec, Callable[[Any], Action]]:
+    """Fetch ONE action by id.
+
+    The item-level record is far richer than the list endpoint's: the note text
+    a caller passed as ``PostAction.description`` comes back through a
+    ``DESCRIPTION`` Memo sub-resource that ``list_actions`` does not return at
+    all (verified live). Uses the **top-level** ``actions/{id}`` path — the
+    nested ``requests/{rfc}/actions/{id}`` is rejected with HTTP 403, the same
+    way the nested list path is.
+    """
+    return build_get(ACTIONS, action_id)

easyvista_python_client/resources/assets.py

@@ -0,0 +1,47 @@
+"""Builders for the ``assets`` resource.
+
+Create/get/search ride the generic resource engine (:mod:`.descriptor`); the
+returned ``(RequestSpec, parser)`` pairs are shared by the sync and async clients.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from typing import Any
+
+from .._transport import RequestSpec
+from ..models.asset import Asset, PostAsset
+from ..pagination import SearchResult
+from .descriptor import ResourceDescriptor, build_create, build_get, build_search
+
+ASSETS: ResourceDescriptor[Asset] = ResourceDescriptor(
+    path="assets", envelope_key="assets", model=Asset
+)
+
+
+def build_create_asset(
+    payload: PostAsset,
+) -> tuple[RequestSpec, Callable[[Any], Asset]]:
+    return build_create(ASSETS, payload)
+
+
+def build_get_asset(asset_id: str) -> tuple[RequestSpec, Callable[[Any], Asset]]:
+    return build_get(ASSETS, asset_id)
+
+
+def build_search_assets(
+    *,
+    search: str | None = None,
+    fields: Iterable[str] | str | None = None,
+    sort: str | None = None,
+    max_rows: int | None = None,
+    offset: int | None = None,
+) -> tuple[RequestSpec, Callable[[Any], SearchResult[Asset]]]:
+    return build_search(
+        ASSETS,
+        search=search,
+        fields=fields,
+        sort=sort,
+        max_rows=max_rows,
+        offset=offset,
+    )

easyvista_python_client/resources/departments.py

@@ -0,0 +1,57 @@
+"""Builders for the ``departments`` resource — thin declarations over the engine."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from typing import Any
+
+from .._transport import RequestSpec
+from ..models.department import Department, DepartmentUpdate, PostDepartment
+from ..pagination import SearchResult
+from .descriptor import (
+    ResourceDescriptor,
+    build_create,
+    build_get,
+    build_search,
+    build_update,
+)
+
+DEPARTMENTS: ResourceDescriptor[Department] = ResourceDescriptor(
+    path="departments", envelope_key="departments", model=Department
+)
+
+
+def build_get_department(
+    department_id: str | int,
+) -> tuple[RequestSpec, Callable[[Any], Department]]:
+    return build_get(DEPARTMENTS, department_id)
+
+
+def build_search_departments(
+    *,
+    search: str | None = None,
+    fields: Iterable[str] | str | None = None,
+    sort: str | None = None,
+    max_rows: int | None = None,
+    offset: int | None = None,
+) -> tuple[RequestSpec, Callable[[Any], SearchResult[Department]]]:
+    return build_search(
+        DEPARTMENTS,
+        search=search,
+        fields=fields,
+        sort=sort,
+        max_rows=max_rows,
+        offset=offset,
+    )
+
+
+def build_create_department(
+    payload: PostDepartment,
+) -> tuple[RequestSpec, Callable[[Any], Department]]:
+    return build_create(DEPARTMENTS, payload)
+
+
+def build_update_department(
+    department_id: str | int, update: DepartmentUpdate
+) -> tuple[RequestSpec, Callable[[Any], Department]]:
+    return build_update(DEPARTMENTS, department_id, update)

easyvista_python_client/resources/descriptor.py

@@ -0,0 +1,99 @@
+"""Generic resource engine.
+
+A documented flat-CRUD EasyVista resource is data (a :class:`ResourceDescriptor`),
+not a bespoke module: a descriptor + these four builders produce the same
+``(RequestSpec, parser)`` pairs the hand-written builders did. Resource-specific
+quirks that do not fit the flat shape — the ticket ``close`` body, ``create_action``'s
+bare nested POST, and the whole ``documents`` sub-resource (a per-ticket nested path) —
+stay as small overrides alongside their descriptor.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+from typing import Any, Generic, TypeVar
+
+from .._transport import RequestSpec
+from ..models.common import EasyvistaModel, EasyvistaWriteModel
+from ..pagination import SearchResult, build_search_result, extract_records
+
+M = TypeVar("M", bound=EasyvistaModel)
+
+
+@dataclass(frozen=True)
+class ResourceDescriptor(Generic[M]):
+    """A documented EasyVista resource.
+
+    Holds its path, create/list envelope key, and read model.
+    """
+
+    path: str
+    envelope_key: str
+    model: type[M]
+
+
+def _first_record_parser(desc: ResourceDescriptor[M]) -> Callable[[Any], M]:
+    """Build a parser that validates the first extracted record (or bare ``data``).
+
+    Shared by :func:`build_get`, :func:`build_create` and :func:`build_update` —
+    all three parse a single record, either wrapped in the resource's envelope
+    (or ``records``) or returned bare (e.g. a create's ``HREF``-only body).
+    """
+
+    def parse(data: Any) -> M:
+        records = extract_records(data, desc.envelope_key)
+        return desc.model.model_validate(records[0] if records else data)
+
+    return parse
+
+
+def build_get(
+    desc: ResourceDescriptor[M], record_id: Any
+) -> tuple[RequestSpec, Callable[[Any], M]]:
+    return RequestSpec("GET", f"{desc.path}/{record_id}"), _first_record_parser(desc)
+
+
+def build_search(
+    desc: ResourceDescriptor[M],
+    *,
+    search: str | None = None,
+    fields: Iterable[str] | str | None = None,
+    sort: str | None = None,
+    max_rows: int | None = None,
+    offset: int | None = None,
+) -> tuple[RequestSpec, Callable[[Any], SearchResult[M]]]:
+    params: dict[str, Any] = {}
+    if search is not None:
+        params["search"] = search
+    if fields is not None:
+        params["fields"] = fields if isinstance(fields, str) else ",".join(fields)
+    if sort is not None:
+        params["sort"] = sort
+    if max_rows is not None:
+        params["max_rows"] = max_rows
+    if offset is not None:
+        params["offset"] = offset
+
+    def parse(data: Any) -> SearchResult[M]:
+        records = [
+            desc.model.model_validate(r)
+            for r in extract_records(data, desc.envelope_key)
+        ]
+        return build_search_result(data, records)
+
+    return RequestSpec("GET", desc.path, params=params), parse
+
+
+def build_create(
+    desc: ResourceDescriptor[M], payload: EasyvistaWriteModel
+) -> tuple[RequestSpec, Callable[[Any], M]]:
+    spec = RequestSpec("POST", desc.path, json={desc.envelope_key: [payload.to_api()]})
+    return spec, _first_record_parser(desc)
+
+
+def build_update(
+    desc: ResourceDescriptor[M], record_id: Any, payload: EasyvistaWriteModel
+) -> tuple[RequestSpec, Callable[[Any], M]]:
+    spec = RequestSpec("PUT", f"{desc.path}/{record_id}", json=payload.to_api())
+    return spec, _first_record_parser(desc)

easyvista_python_client/resources/documents.py

@@ -0,0 +1,78 @@
+"""Builders for the ticket ``documents`` sub-resource.
+
+Documents are uploaded as base64 inside a JSON body, so no special multipart
+transport handling is needed. The list endpoint shape is a best guess pending
+live validation (spec open item O5).
+"""
+
+from __future__ import annotations
+
+import base64
+from collections.abc import Callable
+from typing import Any
+
+from .._transport import RequestSpec
+from ..models.document import Document
+from ..pagination import extract_records
+
+
+def _first_document(data: Any) -> Document:
+    records = extract_records(data)
+    return Document.model_validate(records[0] if records else data)
+
+
+def _document_records(data: Any) -> list[dict[str, Any]]:
+    """Find the list of document dicts in a list response.
+
+    The live list wraps items under a capital-D ``Documents`` key (verified live),
+    which the generic ``extract_records`` (lowercase ``documents``/``records``) does
+    not match; check any case-insensitive ``documents`` key first, then fall back.
+    """
+    if isinstance(data, dict):
+        for key, value in data.items():
+            if key.lower() == "documents" and isinstance(value, list):
+                return [r for r in value if isinstance(r, dict)]
+    return extract_records(data)
+
+
+def _all_documents(data: Any) -> list[Document]:
+    return [Document.model_validate(r) for r in _document_records(data)]
+
+
+def build_add_document(
+    rfc_number: str, *, filename: str, content: bytes
+) -> tuple[RequestSpec, Callable[[Any], Document]]:
+    filedata = base64.b64encode(content).decode("ascii")
+    spec = RequestSpec(
+        "POST",
+        f"requests/{rfc_number}/documents",
+        json={"documents": [{"filename": filename, "filedata": filedata}]},
+    )
+    return spec, _first_document
+
+
+def build_list_documents(
+    rfc_number: str,
+) -> tuple[RequestSpec, Callable[[Any], list[Document]]]:
+    return RequestSpec("GET", f"requests/{rfc_number}/documents"), _all_documents
+
+
+def download_href(document: Document | str) -> str:
+    """The URL to fetch a document's bytes.
+
+    Accepts a :class:`Document` or a raw href/path. Prefers ``DDL_HREF`` (the
+    direct-download URL) and falls back to ``HREF``. Lives here, not on either
+    client, so the sync and async ``download_document`` share one definition of
+    which field carries the URL -- the same reason every other request/response
+    decision lives in this package.
+    """
+    href = (
+        document
+        if isinstance(document, str)
+        else (document.download_href or document.href)
+    )
+    if not href:
+        raise ValueError(
+            "document has no download URL (neither DDL_HREF nor HREF is set)"
+        )
+    return href

easyvista_python_client/resources/employees.py

@@ -0,0 +1,57 @@
+"""Builders for the ``employees`` resource — thin declarations over the engine."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from typing import Any
+
+from .._transport import RequestSpec
+from ..models.employee import Employee, EmployeeUpdate, PostEmployee
+from ..pagination import SearchResult
+from .descriptor import (
+    ResourceDescriptor,
+    build_create,
+    build_get,
+    build_search,
+    build_update,
+)
+
+EMPLOYEES: ResourceDescriptor[Employee] = ResourceDescriptor(
+    path="employees", envelope_key="employees", model=Employee
+)
+
+
+def build_get_employee(
+    employee_id: str | int,
+) -> tuple[RequestSpec, Callable[[Any], Employee]]:
+    return build_get(EMPLOYEES, employee_id)
+
+
+def build_search_employees(
+    *,
+    search: str | None = None,
+    fields: Iterable[str] | str | None = None,
+    sort: str | None = None,
+    max_rows: int | None = None,
+    offset: int | None = None,
+) -> tuple[RequestSpec, Callable[[Any], SearchResult[Employee]]]:
+    return build_search(
+        EMPLOYEES,
+        search=search,
+        fields=fields,
+        sort=sort,
+        max_rows=max_rows,
+        offset=offset,
+    )
+
+
+def build_create_employee(
+    payload: PostEmployee,
+) -> tuple[RequestSpec, Callable[[Any], Employee]]:
+    return build_create(EMPLOYEES, payload)
+
+
+def build_update_employee(
+    employee_id: str | int, update: EmployeeUpdate
+) -> tuple[RequestSpec, Callable[[Any], Employee]]:
+    return build_update(EMPLOYEES, employee_id, update)

easyvista_python_client/resources/requests.py

@@ -0,0 +1,91 @@
+"""Builders for the ``requests`` (ticket) resource.
+
+Get/search/create/update ride the generic resource engine (:mod:`.descriptor`);
+only the resource-specific ``close`` override stays bespoke. The clients execute the
+returned spec and feed the JSON to the parser, so all request/response logic lives
+here and is shared by the sync and async clients.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from typing import Any
+
+from .._transport import RequestSpec
+from ..models.request import PostRequest, Request, RequestUpdate
+from ..pagination import SearchResult, extract_records
+from .descriptor import (
+    ResourceDescriptor,
+    build_create,
+    build_get,
+    build_search,
+    build_update,
+)
+
+REQUESTS: ResourceDescriptor[Request] = ResourceDescriptor(
+    path="requests", envelope_key="requests", model=Request
+)
+
+
+def build_create_ticket(
+    payload: PostRequest,
+) -> tuple[RequestSpec, Callable[[Any], Request]]:
+    return build_create(REQUESTS, payload)
+
+
+def build_get_ticket(rfc_number: str) -> tuple[RequestSpec, Callable[[Any], Request]]:
+    return build_get(REQUESTS, rfc_number)
+
+
+def build_search_tickets(
+    *,
+    search: str | None = None,
+    fields: Iterable[str] | str | None = None,
+    sort: str | None = None,
+    max_rows: int | None = None,
+    offset: int | None = None,
+) -> tuple[RequestSpec, Callable[[Any], SearchResult[Request]]]:
+    return build_search(
+        REQUESTS,
+        search=search,
+        fields=fields,
+        sort=sort,
+        max_rows=max_rows,
+        offset=offset,
+    )
+
+
+def build_update_ticket(
+    rfc_number: str, update: RequestUpdate
+) -> tuple[RequestSpec, Callable[[Any], Request]]:
+    return build_update(REQUESTS, rfc_number, update)
+
+
+def build_close_ticket(
+    rfc_number: str,
+    *,
+    status_guid: str | None = None,
+    delete_actions: int | None = None,
+    comment: str | None = None,
+) -> tuple[RequestSpec, Callable[[Any], Request]]:
+    """Build a close (PUT) spec.
+
+    ``status_guid`` is the instance's "closed" status GUID (EasyVista
+    ``status_GUID``); without it the API may not actually transition the ticket.
+    ``delete_actions=1`` drops the ticket's actions on close. Shapes follow the
+    documented close body (``docs/API_Info.md``), verified live.
+    """
+    closed: dict[str, Any] = {}
+    if status_guid is not None:
+        closed["status_GUID"] = status_guid
+    if delete_actions is not None:
+        closed["delete_actions"] = delete_actions
+    if comment is not None:
+        closed["comment"] = comment
+    spec = RequestSpec("PUT", f"requests/{rfc_number}", json={"closed": closed})
+
+    def parse(data: Any) -> Request:
+        records = extract_records(data)
+        return Request.model_validate(records[0] if records else data)
+
+    return spec, parse