python-sysaid 0.1.0__py3-none-any.whl

sysaid/resources/cis.py

@@ -0,0 +1,134 @@
+"""Configuration items: ``/ci``."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator, Mapping, Sequence
+from typing import Any
+
+from .._params import encode_info, quote_segment
+from .._unverified import unverified
+from ..exceptions import BadRequestError, RelationError
+from ..models import Record
+from ._base import DEFAULT_PAGE_SIZE, JSONList, RecordList, Resource, query
+
+Relation = tuple[int, int] | Mapping[str, Any]
+
+
+def _relations_body(relations: Iterable[Relation]) -> list[dict[str, Any]]:
+    """Accept ``(dest, relation_type_id)`` tuples or ready ``{dest, ciRelationType}`` dicts."""
+    return [
+        {"dest": item[0], "ciRelationType": item[1]} if isinstance(item, tuple) else dict(item)
+        for item in relations
+    ]
+
+
+class CIs(Resource):
+    """Configuration items and their relations."""
+
+    @unverified
+    def list(
+        self,
+        *,
+        ids: Sequence[int | 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,
+        support_barcode: bool | None = None,
+        **filters: Any,
+    ) -> RecordList:
+        """One page of CIs. Extra keyword arguments are filters."""
+        params = query(
+            view=view,
+            fields=fields,
+            sort=sort,
+            direction=direction,
+            ids=ids,
+            offset=offset,
+            limit=limit,
+            supportBarcode=support_barcode,
+            **filters,
+        )
+        return self._list("/ci", params)
+
+    @unverified
+    def iter(
+        self,
+        *,
+        ids: Sequence[int | str] | None = None,
+        view: str | None = None,
+        fields: Sequence[str] | None = None,
+        sort: str | None = None,
+        direction: str | None = None,
+        support_barcode: bool | None = None,
+        page_size: int = DEFAULT_PAGE_SIZE,
+        **filters: Any,
+    ) -> Iterator[Record]:
+        """Every matching CI, fetching pages transparently."""
+        params = query(
+            view=view,
+            fields=fields,
+            sort=sort,
+            direction=direction,
+            ids=ids,
+            supportBarcode=support_barcode,
+            **filters,
+        )
+        return self._iter("/ci", params, page_size=page_size)
+
+    @unverified
+    def update(
+        self, ci_id: int | str, values: Mapping[str, Any] | None = None, /, **fields: Any
+    ) -> None:
+        """Update the given fields only."""
+        body = {"id": str(ci_id), "info": encode_info({**(values or {}), **fields})}
+        self._client.request("PUT", f"/ci/{quote_segment(ci_id)}", json=body)
+
+    @unverified
+    def types(self, *, support_barcode: bool | None = None) -> JSONList:
+        """CI types."""
+        result: JSONList = self._client.request(
+            "GET", "/ci/type", params={"supportBarcode": support_barcode}
+        )
+        return result
+
+    @unverified
+    def view_fields(self, ci_type_id: int | str, *, view: str | None = None) -> Any:
+        """Fields of a view for a CI type, as returned by the server."""
+        return self._client.request(
+            "GET", f"/ci/view/{quote_segment(ci_type_id)}", params={"view": view}
+        )
+
+    @unverified
+    def relation_types(self) -> JSONList:
+        """Available relation types."""
+        result: JSONList = self._client.request("GET", "/ci/relationtypes")
+        return result
+
+    @unverified
+    def relations(self, ci_id: int | str) -> JSONList:
+        """Relations whose source is the given CI."""
+        result: JSONList = self._client.request("GET", f"/ci/{quote_segment(ci_id)}/relation")
+        return result
+
+    @unverified
+    def create_relations(self, ci_id: int | str, relations: Iterable[Relation]) -> None:
+        """Create relations; existing ones are not duplicated.
+
+        Raises :class:`RelationError` (HTTP 400) listing each failing item.
+        """
+        try:
+            self._client.request(
+                "POST", f"/ci/{quote_segment(ci_id)}/relation", json=_relations_body(relations)
+            )
+        except BadRequestError as exc:
+            raise RelationError(exc.status_code, exc.message, exc.response) from exc
+
+    @unverified
+    def delete_relations(self, ci_id: int | str, relations: Iterable[Relation]) -> None:
+        """Delete relations; the server answers OK even for relations that do not exist."""
+        self._client.request(
+            "DELETE", f"/ci/{quote_segment(ci_id)}/relation", json=_relations_body(relations)
+        )

sysaid/resources/filters.py

@@ -0,0 +1,44 @@
+"""Filters: ``/filters``."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from .._params import quote_segment
+from ._base import JSONDict, JSONList, Resource, query
+
+
+class Filters(Resource):
+    """Valid query parameters (and their values) for list calls such as ``/sr``."""
+
+    def list(
+        self,
+        *,
+        view: str | None = None,
+        fields: Sequence[str] | None = None,
+        offset: int | None = None,
+        limit: int | None = None,
+    ) -> JSONList:
+        """``offset``/``limit`` page the filter *values*."""
+        result: JSONList = self._client.request(
+            "GET",
+            "/filters",
+            params=query(view=view, fields=fields, offset=offset, limit=limit),
+        )
+        return result
+
+    def get(
+        self,
+        filter_id: str,
+        *,
+        view: str | None = None,
+        offset: int | None = None,
+        limit: int | None = None,
+    ) -> JSONDict:
+        """One filter with its values; ``offset``/``limit`` page the values."""
+        result: JSONDict = self._client.request(
+            "GET",
+            f"/filters/{quote_segment(filter_id)}",
+            params=query(view=view, offset=offset, limit=limit),
+        )
+        return result

sysaid/resources/lists.py

@@ -0,0 +1,56 @@
+"""Lists (dropdown id/caption pairs): ``/list``."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from .._params import quote_segment
+from ._base import JSONDict, JSONList, Resource, query
+
+
+class Lists(Resource):
+    """Id/caption pairs behind dropdown fields."""
+
+    def list(
+        self,
+        *,
+        entity: str | None = None,
+        fields: Sequence[str] | None = None,
+        offset: int | None = None,
+        limit: int | None = None,
+    ) -> JSONList:
+        """All lists of an entity (server default ``sr``)."""
+        result: JSONList = self._client.request(
+            "GET",
+            "/list",
+            params=query(entity=entity, fields=fields, offset=offset, limit=limit),
+        )
+        return result
+
+    def get(
+        self,
+        list_id: str,
+        *,
+        entity: str | None = None,
+        entity_id: int | str | None = None,
+        entity_type: int | None = None,
+        fields: Sequence[str] | None = None,
+        offset: int | None = None,
+        limit: int | None = None,
+        key: str | None = None,
+    ) -> JSONDict:
+        """One list. ``entity_id`` applies per-record filtering; ``key`` is ``id`` or ``name``."""
+        result: JSONDict = self._client.request(
+            "GET",
+            f"/list/{quote_segment(list_id)}",
+            params=query(
+                entity=entity,
+                entityId=entity_id,
+                entityType=entity_type,
+                fields=fields,
+                offset=offset,
+                limit=limit,
+                key=key,
+            ),
+        )
+        return result

sysaid/resources/password_services.py

@@ -0,0 +1,74 @@
+"""Password self-service: ``/ps``. None of these calls needs a login."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from .._unverified import unverified
+from ._base import JSONDict, Resource
+
+
+class PasswordServices(Resource):
+    """Flow: :meth:`permissions` -> :meth:`questions` -> :meth:`unlock` or :meth:`reset`
+    (-> :meth:`update_password` when the reset method is ``user``).
+    """
+
+    @unverified
+    def domains(self) -> list[str]:
+        """LDAP domain names."""
+        result: list[str] = self._client.request("GET", "/ps/domain", auth=False)
+        return result
+
+    @unverified
+    def permissions(self) -> JSONDict:
+        """Which self-service features are enabled."""
+        result: JSONDict = self._client.request("GET", "/ps/permission", auth=False)
+        return result
+
+    @unverified
+    def questions(self, method: str, user_name: str, domain_name: str | None = None) -> JSONDict:
+        """Security questions for ``method`` (``reset`` or ``unlock``); keep ``userRefId``."""
+        if method not in ("reset", "unlock"):
+            raise ValueError("method must be 'reset' or 'unlock'")
+        body = {"userName": user_name, "domainName": domain_name}
+        result: JSONDict = self._client.request(
+            "POST",
+            f"/ps/{method}/question",
+            json={key: value for key, value in body.items() if value is not None},
+            auth=False,
+        )
+        return result
+
+    @unverified
+    def unlock(self, user_ref_id: int, questions: Sequence[Mapping[str, Any]]) -> JSONDict:
+        """Unlock an account. ``questions`` are the items returned by :meth:`questions`,
+        each with an added ``answer``."""
+        return self._answered("/ps/unlock", user_ref_id, questions)
+
+    @unverified
+    def reset(self, user_ref_id: int, questions: Sequence[Mapping[str, Any]]) -> JSONDict:
+        """Start a password reset; the response depends on the configured reset method."""
+        return self._answered("/ps/reset", user_ref_id, questions)
+
+    @unverified
+    def update_password(self, user_ref_id: int, new_password: str, token: str) -> JSONDict:
+        """Set the new password using the one-time ``token`` from :meth:`reset`."""
+        result: JSONDict = self._client.request(
+            "POST",
+            "/ps/reset/update",
+            json={"userRefId": user_ref_id, "newPassword": new_password, "token": token},
+            auth=False,
+        )
+        return result
+
+    def _answered(
+        self, path: str, user_ref_id: int, questions: Sequence[Mapping[str, Any]]
+    ) -> JSONDict:
+        result: JSONDict = self._client.request(
+            "POST",
+            path,
+            json={"userRefId": user_ref_id, "userSecurityQuestionsList": list(questions)},
+            auth=False,
+        )
+        return result

sysaid/resources/reports.py

@@ -0,0 +1,30 @@
+"""Reports: ``/reports``."""
+
+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 JSONList, Resource
+
+
+class Reports(Resource):
+    """Report metadata and preview runs."""
+
+    @unverified
+    def operators(self, type: str | None = None) -> JSONList:
+        """Field operators, optionally for one data type (``string``, ``date``, ``int``...)."""
+        result: JSONList = self._client.request("GET", "/reports/operators", params={"type": type})
+        return result
+
+    @unverified
+    def run_preview(self, report_id: int | str, definition: Mapping[str, Any]) -> Any:
+        """Run a report in preview mode and return the raw JSON.
+
+        ``definition`` is the report body (``entity``, ``select``, ``filter``, ``layout``).
+        """
+        return self._client.request(
+            "POST", f"/reports/{quote_segment(report_id)}/runPreview", json=definition
+        )

sysaid/resources/resource_bundle.py

@@ -0,0 +1,18 @@
+"""Resource bundle translations: ``/rb``."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from .._params import quote_segment
+from ._base import Resource
+
+
+class ResourceBundle(Resource):
+    """Resource-bundle key translation."""
+
+    def translate(self, keys: Sequence[str], locale: str | None = None) -> dict[str, str]:
+        """Translate resource-bundle keys, for the account locale or the given one."""
+        path = "/rb" if locale is None else f"/rb/{quote_segment(locale)}"
+        result = self._client.request("POST", path, json=[{"key": key} for key in keys])
+        return {item["key"]: item["value"] for item in result}

sysaid/resources/service_requests.py

@@ -0,0 +1,260 @@
+"""Service requests (incident, request, problem, change): ``/sr``."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator, Mapping, Sequence
+from datetime import datetime, timezone
+from os import PathLike
+from typing import Any
+
+from .._params import encode_info, encode_value, quote_segment
+from .._unverified import unverified
+from ..models import Record
+from ._base import DEFAULT_PAGE_SIZE, RecordList, Resource, query, read_upload
+
+SrType = str | Sequence[str]
+
+
+def make_note(user_name: str, text: str, created: datetime | None = None) -> dict[str, Any]:
+    """An entry for the ``notes`` field."""
+    return {
+        "userName": user_name,
+        "createDate": created or datetime.now(timezone.utc),
+        "text": text,
+    }
+
+
+def problem_type(*levels: str) -> str:
+    """Join up to three category levels into the ``problem_type`` value."""
+    if not 1 <= len(levels) <= 3:
+        raise ValueError("problem_type takes one to three category levels")
+    return "_".join(levels)
+
+
+class ServiceRequests(Resource):
+    """Service requests: incidents, requests, problems and changes."""
+
+    def list(
+        self,
+        *,
+        type: SrType | None = None,
+        ids: Sequence[int | str] | None = None,
+        archive: bool | 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 SRs. Extra keyword arguments are filters from ``client.filters``."""
+        params = self._list_params(type, ids, archive, view, fields, sort, direction, filters)
+        return self._list("/sr", {**params, "offset": offset, "limit": limit})
+
+    def iter(
+        self,
+        *,
+        type: SrType | None = None,
+        ids: Sequence[int | str] | None = None,
+        archive: bool | 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 SR, fetching pages transparently."""
+        params = self._list_params(type, ids, archive, view, fields, sort, direction, filters)
+        return self._iter("/sr", params, page_size=page_size)
+
+    def get(
+        self, sr_id: int | str, *, view: str | None = None, fields: Sequence[str] | None = None
+    ) -> Record:
+        """The SR as a form: fields carry ``mandatory``/``editable``/``type`` metadata."""
+        return self._get(f"/sr/{quote_segment(sr_id)}", query(view=view, fields=fields))
+
+    def search(
+        self,
+        text: str,
+        *,
+        type: SrType | None = None,
+        archive: bool | 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:
+        """Search SRs; the server defaults ``type`` to ``incident`` here."""
+        params = self._list_params(type, None, archive, view, fields, sort, direction, filters)
+        return self._list("/sr/search", {**params, "query": text, "offset": offset, "limit": limit})
+
+    def count(self, **filters: Any) -> int:
+        """Number of SRs matching the filters."""
+        result = self._client.request("GET", "/sr/count", params=filters)
+        return int(result["count"])
+
+    def template(
+        self,
+        *,
+        type: str | None = None,
+        template: int | str | None = None,
+        view: str | None = None,
+        fields: Sequence[str] | None = None,
+    ) -> Record:
+        """A blank SR (``id`` ``"0"``) showing mandatory fields and defaults."""
+        return self._get(
+            "/sr/template", query(view=view, fields=fields, type=type, template=template)
+        )
+
+    @staticmethod
+    def _list_params(
+        type: SrType | None,
+        ids: Sequence[int | str] | None,
+        archive: bool | None,
+        view: str | None,
+        fields: Sequence[str] | None,
+        sort: str | None,
+        direction: str | None,
+        filters: Mapping[str, Any],
+    ) -> dict[str, Any]:
+        params = query(view=view, fields=fields, sort=sort, direction=direction, type=type, ids=ids)
+        if archive is not None:
+            params["archive"] = 1 if archive else 0
+        return {**params, **filters}
+
+    def create(
+        self,
+        values: Mapping[str, Any] | None = None,
+        /,
+        *,
+        type: str | None = None,
+        template: int | str | None = None,
+        view: str | None = None,
+        return_fields: Sequence[str] | None = None,
+        **fields: Any,
+    ) -> Record:
+        """Create an SR from field values, given as keywords and/or a mapping.
+
+        Use the mapping for field ids that clash with this method's own keywords
+        (e.g. the SR field ``type``). ``type`` and ``template`` select the SR type and
+        template; ``view`` and ``return_fields`` shape the returned record.
+        """
+        body = {"info": encode_info({**(values or {}), **fields})}
+        params = query(view=view, fields=return_fields, type=type, template=template)
+        return Record(self._client.request("POST", "/sr", params=params, json=body))
+
+    def update(
+        self, sr_id: int | str, values: Mapping[str, Any] | None = None, /, **fields: Any
+    ) -> None:
+        """Update the given fields only. Datetimes become ms-epoch UTC."""
+        body = {"id": str(sr_id), "info": encode_info({**(values or {}), **fields})}
+        self._client.request("PUT", f"/sr/{quote_segment(sr_id)}", json=body)
+
+    def close(self, sr_id: int | str, solution: str | None = None) -> None:
+        """Set the SR to the default *Close* status."""
+        body = None if solution is None else {"solution": solution}
+        self._client.request("PUT", f"/sr/{quote_segment(sr_id)}/close", json=body)
+
+    @unverified
+    def delete(self, ids: int | str | Sequence[int | str]) -> None:
+        """Delete one or more SRs."""
+        id_list = [ids] if isinstance(ids, (int, str)) else ids
+        self._client.request("DELETE", "/sr", params={"ids": id_list})
+
+    def add_link(self, sr_id: int | str, name: str, link: str) -> None:
+        """Add a named link to the SR."""
+        self._client.request(
+            "POST", f"/sr/{quote_segment(sr_id)}/link", json={"name": name, "link": link}
+        )
+
+    def delete_link(self, sr_id: int | str, name: str) -> None:
+        """Delete a link from the SR by name."""
+        self._client.request("DELETE", f"/sr/{quote_segment(sr_id)}/link", json={"name": name})
+
+    def add_attachment(
+        self, sr_id: int | str, file: bytes | str | PathLike[str], filename: str | None = None
+    ) -> None:
+        """Attach a file, given as bytes or a path (multipart part ``file``)."""
+        name, content = read_upload(file, filename)
+        self._client.request(
+            "POST", f"/sr/{quote_segment(sr_id)}/attachment", files={"file": (name, content)}
+        )
+
+    def delete_attachment(self, sr_id: int | str, file_id: str) -> None:
+        """Delete an attachment by its file id."""
+        self._client.request(
+            "DELETE", f"/sr/{quote_segment(sr_id)}/attachment", json={"fileId": file_id}
+        )
+
+    def add_activity(
+        self,
+        sr_id: int | str,
+        user_id: int | str,
+        from_time: datetime | int,
+        to_time: datetime | int,
+        description: str,
+    ) -> None:
+        """Log an activity for the user with the given numeric id.
+
+        Times are datetimes or ms-epoch integers.
+        """
+        body = {
+            "userId": user_id,
+            "fromTime": from_time,
+            "toTime": to_time,
+            "description": description,
+        }
+        self._client.request("POST", f"/sr/{quote_segment(sr_id)}/activity", json=body)
+
+    def delete_activity(self, sr_id: int | str, activity_id: int) -> None:
+        """Delete an activity by id."""
+        self._client.request(
+            "DELETE", f"/sr/{quote_segment(sr_id)}/activity", json={"id": activity_id}
+        )
+
+    def send_message(
+        self,
+        sr_id: int | str,
+        to_users: str | Sequence[int | str],
+        *,
+        from_user_id: int | str,
+        subject: str | None = None,
+        body: str | None = None,
+        cc_users: str | Sequence[int | str] | None = None,
+        method: str | None = None,
+        add_attachment_to_sr: bool | None = None,
+        add_sr_details: bool | None = None,
+        attachments: Sequence[bytes | str | PathLike[str]] = (),
+    ) -> None:
+        """Send a message from the SR.
+
+        Recipients are user ids; a group id goes in brackets, e.g. ``"[3]"``. ``method`` is
+        ``email`` (default), ``sms``, ``broadcast`` or ``im``.
+        """
+        message = {
+            "fromUserId": str(from_user_id),
+            "toUsers": encode_value(to_users),
+            "ccUsers": None if cc_users is None else encode_value(cc_users),
+            "msgSubject": subject,
+            "msgBody": body,
+        }
+        parts: list[tuple[str, tuple[str | None, Any]]] = [
+            ("message", (None, json.dumps({k: v for k, v in message.items() if v is not None})))
+        ]
+        parts += [("file", read_upload(attachment, None)) for attachment in attachments]
+        self._client.request(
+            "POST",
+            f"/sr/{quote_segment(sr_id)}/message",
+            params={
+                "method": method,
+                "addAttachmentToSr": add_attachment_to_sr,
+                "addSrDetails": add_sr_details,
+            },
+            files=parts,
+        )