python-sysaid 0.1.0__py3-none-any.whl

sysaid/exceptions.py

@@ -0,0 +1,95 @@
+"""Exceptions raised by the SysAid client."""
+
+from __future__ import annotations
+
+from http.client import responses
+from typing import Any
+
+import requests
+
+
+class SysAidError(Exception):
+    """Base class for every error raised by this package."""
+
+
+class AuthenticationError(SysAidError):
+    """Login failed, or credentials are missing."""
+
+
+class UnverifiedFeatureError(SysAidError):
+    """The feature is disabled until it has been verified against a live server."""
+
+
+class SysAidHTTPError(SysAidError):
+    """The server answered with a non-2xx status."""
+
+    def __init__(
+        self, status_code: int, message: str, response: requests.Response | None = None
+    ) -> None:
+        super().__init__(f"HTTP {status_code}: {message}")
+        self.status_code = status_code
+        self.message = message
+        self.response = response
+
+
+class BadRequestError(SysAidHTTPError):
+    """HTTP 400."""
+
+
+class RelationError(BadRequestError):
+    """CI relations could not be created; ``failures`` lists each failing item."""
+
+    @property
+    def failures(self) -> list[str]:
+        """The per-item messages from the server's CSV error text."""
+        return [part.strip() for part in self.message.split(",") if part.strip()]
+
+
+class UnauthorizedError(SysAidHTTPError):
+    """HTTP 401."""
+
+
+class ForbiddenError(SysAidHTTPError):
+    """HTTP 403."""
+
+
+class NotFoundError(SysAidHTTPError):
+    """HTTP 404."""
+
+
+class ServerError(SysAidHTTPError):
+    """HTTP 5xx."""
+
+
+_BY_STATUS: dict[int, type[SysAidHTTPError]] = {
+    400: BadRequestError,
+    401: UnauthorizedError,
+    403: ForbiddenError,
+    404: NotFoundError,
+}
+
+
+def _message_from(response: requests.Response) -> str:
+    """Return ``message`` from a ``{"status", "message"}`` body, else the raw text.
+
+    Unrouted or filtered requests get the servlet container's HTML error page; for
+    those the reason phrase is used instead of the markup.
+    """
+    try:
+        body: Any = response.json()
+    except ValueError:
+        if "html" in response.headers.get("Content-Type", ""):
+            return response.reason or responses.get(response.status_code, "")
+        return response.text or response.reason or ""
+    if isinstance(body, dict) and body.get("message") is not None:
+        return str(body["message"])
+    return response.text
+
+
+def error_from_response(response: requests.Response) -> SysAidHTTPError:
+    """Build the typed exception matching a non-2xx response."""
+    status = response.status_code
+    cls = _BY_STATUS.get(status)
+    if cls is None:
+        cls = ServerError if status >= 500 else SysAidHTTPError
+    return cls(status, _message_from(response), response)

sysaid/models.py

@@ -0,0 +1,76 @@
+"""Light wrappers around the ``{id, info[]}`` objects returned by SysAid."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+
+def _as_bool(value: Any) -> bool | None:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str) and value.lower() in ("true", "false"):
+        return value.lower() == "true"
+    return None
+
+
+@dataclass(frozen=True)
+class Field:
+    """One ``info`` entry. Metadata is only present on form and template calls."""
+
+    key: str
+    value: Any = None
+    key_caption: str | None = None
+    value_caption: Any = None
+    mandatory: bool | None = None
+    editable: bool | None = None
+    type: str | None = None
+    default_value: Any = None
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> Field:
+        """Build from one ``info`` entry (accepts both caption spellings)."""
+        # Assets use snake_case captions, everything else camelCase.
+        return cls(
+            key=str(data["key"]),
+            value=data.get("value"),
+            key_caption=data.get("keyCaption", data.get("key_caption")),
+            value_caption=data.get("valueCaption", data.get("value_caption")),
+            mandatory=_as_bool(data.get("mandatory")),
+            editable=_as_bool(data.get("editable")),
+            type=data.get("type"),
+            default_value=data.get("defaultValue"),
+        )
+
+
+class Record(Mapping[str, Any]):
+    """An entity with an ``id`` and an ``info`` array, read like a mapping of key -> value."""
+
+    def __init__(self, raw: Mapping[str, Any]) -> None:
+        self.raw: dict[str, Any] = dict(raw)
+        self.fields: dict[str, Field] = {
+            field.key: field for field in map(Field.from_dict, self.raw.get("info") or [])
+        }
+
+    @property
+    def id(self) -> str | None:
+        """The record id as a string, if present."""
+        value = self.raw.get("id")
+        return None if value is None else str(value)
+
+    def __getitem__(self, key: str) -> Any:
+        return self.fields[key].value
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self.fields)
+
+    def __len__(self) -> int:
+        return len(self.fields)
+
+    def caption(self, key: str) -> Any:
+        """Display value (``valueCaption``) of a field."""
+        return self.fields[key].value_caption
+
+    def __repr__(self) -> str:
+        return f"Record(id={self.id!r}, fields={list(self.fields)!r})"

sysaid/oauth.py

@@ -0,0 +1,85 @@
+"""OAuth 1.0 helpers (optional extra: ``pip install python-sysaid[oauth]``).
+
+Three-legged flow: :func:`request_token` -> send the user to :func:`authorize_url` ->
+:func:`access_token` with the ``oauth_verifier`` from the callback. Then build a client
+with :meth:`sysaid.SysAid.from_oauth`.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import urlencode
+
+import requests
+
+from ._unverified import unverified
+from .client import api_url_for
+from .exceptions import error_from_response
+
+
+def oauth1(client_key: str, client_secret: str, **kwargs: Any) -> Any:
+    """Build a ``requests_oauthlib.OAuth1`` auth object (HMAC-SHA1)."""
+    try:
+        from requests_oauthlib import OAuth1
+    except ImportError as exc:
+        raise ImportError(
+            "OAuth support needs requests-oauthlib: pip install 'python-sysaid[oauth]'"
+        ) from exc
+    return OAuth1(client_key, client_secret=client_secret, **kwargs)
+
+
+def _post(
+    base_url: str, path: str, auth: Any, verify: bool | str, timeout: float | None
+) -> dict[str, Any]:
+    response = requests.post(
+        api_url_for(base_url) + path, auth=auth, verify=verify, timeout=timeout
+    )
+    if not response.ok:
+        raise error_from_response(response)
+    token: dict[str, Any] = response.json()
+    return token
+
+
+@unverified
+def request_token(
+    base_url: str,
+    consumer_key: str,
+    callback_url: str,
+    consumer_secret: str = "",
+    *,
+    verify: bool | str = True,
+    timeout: float | None = 30,
+) -> dict[str, Any]:
+    """Step 1. Returns ``oauth_token``, ``oauth_token_secret`` and ``oauth_callback_confirmed``."""
+    auth = oauth1(consumer_key, consumer_secret, callback_uri=callback_url)
+    return _post(base_url, "/oauth/request_token", auth, verify, timeout)
+
+
+@unverified
+def authorize_url(base_url: str, request_token: str) -> str:
+    """Step 2. The URL to send the user's browser to."""
+    query = urlencode({"oauth_token": request_token})
+    return f"{api_url_for(base_url)}/oauth/authorize?{query}"
+
+
+@unverified
+def access_token(
+    base_url: str,
+    consumer_key: str,
+    request_token: str,
+    request_token_secret: str,
+    verifier: str,
+    consumer_secret: str = "",
+    *,
+    verify: bool | str = True,
+    timeout: float | None = 30,
+) -> dict[str, Any]:
+    """Step 3. Returns the access ``oauth_token`` and ``oauth_token_secret``."""
+    auth = oauth1(
+        consumer_key,
+        consumer_secret,
+        resource_owner_key=request_token,
+        resource_owner_secret=request_token_secret,
+        verifier=verifier,
+    )
+    return _post(base_url, "/oauth/access_token", auth, verify, timeout)

sysaid/resources/_base.py

@@ -0,0 +1,70 @@
+"""Shared plumbing for the resource classes."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping, Sequence
+from os import PathLike
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from ..models import Record
+
+if TYPE_CHECKING:
+    from ..client import SysAid
+
+DEFAULT_PAGE_SIZE = 100
+
+# Resource classes define methods named ``list``/``iter``, which would shadow the
+# builtins in annotations inside the class body; these aliases avoid that.
+RecordList = list[Record]
+JSONDict = dict[str, Any]
+JSONList = list[dict[str, Any]]
+
+
+def query(
+    *,
+    view: str | None = None,
+    fields: Sequence[str] | None = None,
+    sort: str | None = None,
+    direction: str | None = None,
+    **extra: Any,
+) -> dict[str, Any]:
+    """Common list parameters (``dir`` is exposed as ``direction``) plus extras."""
+    return {"view": view, "fields": fields, "sort": sort, "dir": direction, **extra}
+
+
+def read_upload(file: bytes | str | PathLike[str], filename: str | None) -> tuple[str, bytes]:
+    """Resolve an upload given as bytes or a path into ``(filename, content)``."""
+    if isinstance(file, bytes):
+        return filename or "file", file
+    path = Path(file)
+    return filename or path.name, path.read_bytes()
+
+
+class Resource:
+    """Base class: holds the client and the shared GET/list/paginate helpers."""
+
+    def __init__(self, client: SysAid) -> None:
+        self._client = client
+
+    def _get(self, path: str, params: Mapping[str, Any] | None = None) -> Record:
+        return Record(self._client.request("GET", path, params=params))
+
+    def _list(self, path: str, params: Mapping[str, Any] | None = None) -> RecordList:
+        return [Record(item) for item in self._client.request("GET", path, params=params)]
+
+    def _iter(
+        self,
+        path: str,
+        params: Mapping[str, Any] | None = None,
+        *,
+        page_size: int = DEFAULT_PAGE_SIZE,
+        offset: int = 0,
+    ) -> Iterator[Record]:
+        """Yield every record, fetching pages until one is shorter than ``page_size``."""
+        while True:
+            page = self._list(path, {**(params or {}), "offset": offset, "limit": page_size})
+            yield from page
+            if len(page) < page_size:
+                return
+            offset += page_size

sysaid/resources/action_items.py

@@ -0,0 +1,127 @@
+"""Action items: ``/action_item``."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Sequence
+from typing import Any
+
+from .._params import quote_segment
+from .._unverified import unverified
+from ..models import Record
+from ._base import DEFAULT_PAGE_SIZE, RecordList, Resource, query
+
+
+def _filter_params(
+    type: str | Sequence[str] | None,
+    ids: Sequence[int | str] | None,
+    archive: bool | None,
+    static_filter_id: str | None,
+    text: str | None,
+    filters: dict[str, Any],
+) -> dict[str, Any]:
+    params: dict[str, Any] = {
+        "type": type,
+        "ids": ids,
+        "staticFilterId": static_filter_id,
+        "query": text,
+    }
+    if archive is not None:
+        params["archive"] = 1 if archive else 0
+    return {**params, **filters}
+
+
+class ActionItems(Resource):
+    """Action items attached to service requests."""
+
+    @unverified
+    def list(
+        self,
+        *,
+        type: str | Sequence[str] | None = None,
+        ids: Sequence[int | str] | None = None,
+        archive: bool | None = None,
+        static_filter_id: str | None = None,
+        text: str | None = None,
+        view: str | None = None,
+        fields: Sequence[str] | None = None,
+        offset: int | None = None,
+        limit: int | None = None,
+        sort: str | None = None,
+        direction: str | None = None,
+        **filters: Any,
+    ) -> RecordList:
+        """One page of action items. ``ids`` are the *SR* ids whose items to return."""
+        params = query(
+            view=view,
+            fields=fields,
+            sort=sort,
+            direction=direction,
+            offset=offset,
+            limit=limit,
+            **_filter_params(type, ids, archive, static_filter_id, text, filters),
+        )
+        return self._list("/action_item", params)
+
+    @unverified
+    def iter(
+        self,
+        *,
+        type: str | Sequence[str] | None = None,
+        ids: Sequence[int | str] | None = None,
+        archive: bool | None = None,
+        static_filter_id: str | None = None,
+        text: str | None = None,
+        view: str | None = None,
+        fields: Sequence[str] | None = None,
+        sort: str | None = None,
+        direction: str | None = None,
+        page_size: int = DEFAULT_PAGE_SIZE,
+        **filters: Any,
+    ) -> Iterator[Record]:
+        """Every matching action item, fetching pages transparently."""
+        params = query(
+            view=view,
+            fields=fields,
+            sort=sort,
+            direction=direction,
+            **_filter_params(type, ids, archive, static_filter_id, text, filters),
+        )
+        return self._iter("/action_item", params, page_size=page_size)
+
+    @unverified
+    def count(
+        self,
+        *,
+        type: str | Sequence[str] | None = None,
+        ids: Sequence[int | str] | None = None,
+        archive: bool | None = None,
+        static_filter_id: str | None = None,
+        text: str | None = None,
+        **filters: Any,
+    ) -> int:
+        """Number of action items matching the filters."""
+        params = _filter_params(type, ids, archive, static_filter_id, text, filters)
+        return int(self._client.request("GET", "/action_item/count", params=params)["count"])
+
+    @unverified
+    def approve(self, action_item_id: int | str) -> None:
+        """Approve the action item."""
+        self._change_state(action_item_id, "approve")
+
+    @unverified
+    def reject(self, action_item_id: int | str) -> None:
+        """Reject the action item."""
+        self._change_state(action_item_id, "reject")
+
+    @unverified
+    def complete(self, action_item_id: int | str) -> None:
+        """Mark the action item as complete."""
+        self._change_state(action_item_id, "complete")
+
+    @unverified
+    def reopen(self, action_item_id: int | str) -> None:
+        """Reopen the action item."""
+        self._change_state(action_item_id, "reopen")
+
+    def _change_state(self, action_item_id: int | str, action: str) -> None:
+        self._client.request("PUT", f"/action_item/{quote_segment(action_item_id)}/{action}")

sysaid/resources/addons.py

@@ -0,0 +1,63 @@
+"""Add-ons: ``/addons``."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from .._params import quote_segment
+from .._unverified import unverified
+from ._base import JSONDict, JSONList, Resource
+
+
+def _payload(name: str, active: bool | None, params: Mapping[str, Any] | None) -> JSONDict:
+    body: JSONDict = {"name": name}
+    if active is not None:
+        body["active"] = active
+    if params is not None:
+        body["params"] = [{"name": key, "value": value} for key, value in params.items()]
+    return body
+
+
+class Addons(Resource):
+    """SysAid add-ons and their parameters."""
+
+    @unverified
+    def list(self) -> JSONList:
+        """All add-ons (``params`` is always ``None`` in this list)."""
+        result: JSONList = self._client.request("GET", "/addons")
+        return result
+
+    @unverified
+    def get(self, name: str) -> JSONDict:
+        """The add-on with its ``params``."""
+        result: JSONDict = self._client.request("GET", f"/addons/{quote_segment(name)}")
+        return result
+
+    @unverified
+    def update(
+        self, name: str, *, active: bool | None = None, params: Mapping[str, Any] | None = None
+    ) -> Any:
+        """Set ``active`` and/or parameter values (``{param name: value}``).
+
+        Only these are updated server-side. The server answers with a message.
+        """
+        return self._client.request(
+            "PUT", f"/addons/{quote_segment(name)}", json=_payload(name, active, params)
+        )
+
+    @unverified
+    def test_connection(
+        self, name: str, *, active: bool | None = None, params: Mapping[str, Any] | None = None
+    ) -> Any:
+        """Same payload as :meth:`update`, but only tests; nothing is saved."""
+        return self._client.request(
+            "PUT",
+            f"/addons/{quote_segment(name)}/testConnection",
+            json=_payload(name, active, params),
+        )
+
+    @unverified
+    def refresh(self) -> Any:
+        """Refresh the add-ons list immediately."""
+        return self._client.request("GET", "/addons/refresh")

sysaid/resources/assets.py

@@ -0,0 +1,61 @@
+"""Assets: ``/asset``. Ids look like ``497db453:147bee7ec09:-7ff2`` and are URL-encoded."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Sequence
+
+from .._params import quote_segment
+from .._unverified import unverified
+from ..models import Record
+from ._base import DEFAULT_PAGE_SIZE, RecordList, Resource, query
+
+
+class Assets(Resource):
+    """Read-only access to assets."""
+
+    @unverified
+    def list(
+        self,
+        *,
+        type: str | None = None,
+        view: str | None = None,
+        fields: Sequence[str] | None = None,
+        offset: int | None = None,
+        limit: int | None = None,
+    ) -> RecordList:
+        """``type`` is listed in the Help index only; it is passed through when given."""
+        params = query(view=view, fields=fields, type=type, offset=offset, limit=limit)
+        return self._list("/asset", params)
+
+    @unverified
+    def iter(
+        self,
+        *,
+        type: str | None = None,
+        view: str | None = None,
+        fields: Sequence[str] | None = None,
+        page_size: int = DEFAULT_PAGE_SIZE,
+    ) -> Iterator[Record]:
+        """Every asset, fetching pages transparently."""
+        return self._iter("/asset", query(view=view, fields=fields, type=type), page_size=page_size)
+
+    @unverified
+    def get(
+        self, asset_id: str, *, view: str | None = None, fields: Sequence[str] | None = None
+    ) -> Record:
+        """One asset; ``view`` is an Asset Form view."""
+        return self._get(f"/asset/{quote_segment(asset_id)}", query(view=view, fields=fields))
+
+    @unverified
+    def search(
+        self,
+        text: str,
+        *,
+        view: str | None = None,
+        fields: Sequence[str] | None = None,
+        offset: int | None = None,
+        limit: int | None = None,
+    ) -> RecordList:
+        """Search assets by free text."""
+        params = query(view=view, fields=fields, query=text, offset=offset, limit=limit)
+        return self._list("/asset/search", params)