python-sysaid 0.1.0__py3-none-any.whl

python_sysaid-0.1.0.dist-info/METADATA

@@ -0,0 +1,205 @@
+Metadata-Version: 2.5
+Name: python-sysaid
+Version: 0.1.0
+Summary: Python wrapper for the SysAid REST API
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,itsm,rest,sysaid
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: requests-oauthlib>=1.3; extra == 'dev'
+Requires-Dist: responses; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Requires-Dist: types-requests; extra == 'dev'
+Requires-Dist: types-requests-oauthlib; extra == 'dev'
+Provides-Extra: oauth
+Requires-Dist: requests-oauthlib>=1.3; extra == 'oauth'
+Description-Content-Type: text/markdown
+
+# python-sysaid
+
+Python wrapper for the SysAid REST API (`/api/v1`, SysAid 15.4+).
+
+> Status: alpha, under development. Requests and paths come from the SysAid
+> documentation and have not been validated against a live server yet.
+
+## Installation
+
+```bash
+pip install python-sysaid
+pip install "python-sysaid[oauth]"   # optional: OAuth 1.0
+```
+
+Requires Python 3.10+.
+
+## Quick start
+
+```python
+from sysaid import SysAid
+
+with SysAid("https://sysaid.example.com", username="sysaid", password="...") as client:
+    sr = client.service_requests.get(273, fields=["title", "status"])
+    sr["title"]            # raw value
+    sr.caption("status")   # display value
+
+    for sr in client.service_requests.iter(type="incident", status=[4, 5]):
+        print(sr.id, sr["title"])
+
+    client.service_requests.update(273, status=2, responsibility=66)
+    client.service_requests.close(273, solution="restarted")
+```
+
+The client logs in on first use (`POST /login`, the `JSESSIONID` cookie is kept by the
+session). The account must be an administrator with mobile-app permission. Pass
+`account_id=` if your installation needs one, and `verify=`/`timeout=`/`session=` to
+control the underlying `requests` session.
+
+## Records
+
+List and get calls return `Record` objects, which behave like a read-only mapping of
+field key to raw value:
+
+```python
+record["status"]               # raw value (an id, ms timestamp or text)
+record.caption("status")       # display value (valueCaption)
+record.fields["status"]        # Field: key_caption, mandatory, editable, type, ...
+record.raw                     # the original dict (canUpdate, name, group, ...)
+```
+
+## Pagination
+
+`list()` returns one page (`limit`/`offset`); `iter()` yields every record and stops at the
+first page shorter than `page_size` (default 100):
+
+```python
+client.service_requests.list(limit=50, offset=100)
+client.service_requests.iter(page_size=200)
+```
+
+## Filters and parameters
+
+Filter ids come from `client.filters`. Pass them as keyword arguments:
+
+```python
+client.service_requests.list(status=[4, 5], request_user=235)   # status=4,5&request_user=235
+client.service_requests.list(archive=True)                      # archive=1
+```
+
+Use `view=` and `fields=` to choose the returned fields, and `sort=`/`direction=`.
+
+## Dates
+
+Datetimes are sent as milliseconds since the epoch in UTC (naive datetimes are taken as
+UTC). A `(from, to)` tuple is a range, with `None` for an open end:
+
+```python
+from datetime import datetime, timezone
+
+since = datetime(2024, 1, 1, tzinfo=timezone.utc)
+client.service_requests.list(due_date=(since, None))        # due_date=<ms>,0
+client.service_requests.update(273, due_date=datetime.now(timezone.utc))
+```
+
+## Writing
+
+Write calls take field values as keywords. For field ids that clash with a method's own
+keywords (the SR field `type`), pass a mapping as the first argument:
+
+```python
+from sysaid.resources.service_requests import make_note, problem_type
+
+client.service_requests.create(
+    {"type": 3},
+    type="incident",             # the SR type query parameter
+    template=39,
+    title="Printer down",
+    problem_type=problem_type("UserWorkstation", "PC", "Password"),
+    notes=[make_note("sysaid", "Created from the API")],
+)
+```
+
+`client.service_requests.template(type="incident")` shows the mandatory fields first.
+
+Numbers, booleans and datetimes are sent as strings, which is the only form the server
+accepts for field values. `add_activity` takes the numeric id of the user.
+
+## Resources
+
+| Attribute | Covers |
+|---|---|
+| `client.users` | list, iter, get, search, photo get/upload, permissions |
+| `client.filters` / `client.lists` | filter definitions, dropdown id/caption pairs |
+| `client.service_requests` | list, iter, get, search, count, template, create, update, close, links, attachments, activities, `send_message` |
+| `client.resource_bundle` | translate |
+
+### Disabled features
+
+These are implemented from the REST guide but have not been verified against a live server
+yet, so calling them raises `UnverifiedFeatureError` before any request is made:
+
+| Attribute | Disabled calls |
+|---|---|
+| `client.service_requests` | delete |
+| `client.action_items` | list, iter, count, approve, reject, complete, reopen |
+| `client.assets` | list, iter, get, search |
+| `client.cis` | list, iter, update, types, view_fields, relation types, relations |
+| `client.addons` | list, get, update, test_connection, refresh |
+| `client.password_services` | domains, permissions, questions, unlock, reset, update_password |
+| `client.reports` | operators, run_preview |
+| OAuth 1.0 | `SysAid.from_oauth` and the `sysaid.oauth` helpers |
+
+## Errors
+
+Every error derives from `SysAidError`. Non-2xx answers raise a subclass of
+`SysAidHTTPError` (`BadRequestError`, `UnauthorizedError`, `ForbiddenError`,
+`NotFoundError`, `ServerError`) carrying `status_code`, `message` and `response`.
+Failed logins raise `AuthenticationError`. Failed CI relation creation raises
+`RelationError` with the per-item `failures`.
+
+```python
+from sysaid import NotFoundError
+
+try:
+    client.service_requests.get(999999)
+except NotFoundError as exc:
+    print(exc.status_code, exc.message)
+```
+
+## OAuth 1.0
+
+Disabled until verified (see [Disabled features](#disabled-features)). The intended flow
+needs `python-sysaid[oauth]` and a consumer key issued by SysAid:
+
+```python
+from sysaid import SysAid, oauth
+
+token = oauth.request_token(url, consumer_key, "https://app/callback")
+print(oauth.authorize_url(url, token["oauth_token"]))
+# ...the user authorizes; SysAid redirects with oauth_verifier...
+access = oauth.access_token(
+    url, consumer_key, token["oauth_token"], token["oauth_token_secret"], verifier
+)
+client = SysAid.from_oauth(url, consumer_key, access["oauth_token"], access["oauth_token_secret"])
+```
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). The endpoint reference is in
+[ANOTATIONS.md](ANOTATIONS.md) and the roadmap in [PLAN.md](PLAN.md).
+
+## License
+
+MIT

python_sysaid-0.1.0.dist-info/RECORD

@@ -0,0 +1,26 @@
+sysaid/__init__.py,sha256=ErK_rfRygwKRSPXMzuaQ8XGC_MWiiNSVVnOGtSnckUA,723
+sysaid/_params.py,sha256=HyIp23Crj5ECFnprui0F2imV9sABmasFEl5OUd5Sy_U,2797
+sysaid/_unverified.py,sha256=wmxcbCg30ZKG-busTFBMVo4ijV_tSc1n6TXJLm-U1bE,968
+sysaid/auth.py,sha256=dzvMgmDn1WrKkNV18wY7ZqhWenFJMXWcJSsTwPbFtQo,2061
+sysaid/client.py,sha256=UiUMo0DwdB3z0MlleGyt553qbP55A2yOmX5tTkpz-8E,5078
+sysaid/exceptions.py,sha256=nxI8csNKcURxe9ZNRDWfrhu-EHUT_WEQ_5xtWh7mOv8,2668
+sysaid/models.py,sha256=2c5qqE-cQCqr-ArydjKwY8ulVl1ZUV5j_9PHWiGZi4w,2490
+sysaid/oauth.py,sha256=WmbK4vilbt1QMnZgv94f-zsQxjz9BJTd_47WymisS-w,2650
+sysaid/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sysaid/resources/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sysaid/resources/_base.py,sha256=dfEu5iBzeuYj5pvIhC7fCzBmCNJerJVLFN4Fw5AZ5wI,2304
+sysaid/resources/action_items.py,sha256=tkVa3rNRGpZUD9ZJQgcQHNOob6KV-iVoXBUvr4gWec0,4097
+sysaid/resources/addons.py,sha256=L1EWLAeRCtmbvkIhYBif2XpcI12Yx3MKI-ISq1P9cRQ,2083
+sysaid/resources/assets.py,sha256=Yeb5lBo3-ntKD53IPiFMnP394O0X3shjJcG3eAkyfYk,2002
+sysaid/resources/cis.py,sha256=a8Akeha_AEt-BvAReu1wzHROQG65pq0hMvLEDWWs0s4,4626
+sysaid/resources/filters.py,sha256=R1ifN9xHt_KhKSo_d7hRt5P_6xPcdyn5GTe9jEqOjIw,1258
+sysaid/resources/lists.py,sha256=65-c8_0JSxtllMQaf09SfDeH8-I9f_JxiWbO3V1zLlM,1624
+sysaid/resources/password_services.py,sha256=F-Gg_MoemF8DS0Si1GpMCexDZtPlA9YxWzLbBQ3QRbU,2868
+sysaid/resources/reports.py,sha256=wlockOuPc71dDcjoZqolINxwSofftVCjAlNJLdwtYV8,1013
+sysaid/resources/resource_bundle.py,sha256=IjnJJPhxobsZk0Vs-WYkjkG49I1Fv6zNbTwyrnzJ9yE,667
+sysaid/resources/service_requests.py,sha256=uFX9h1WMgX6wWiyQnfuCKjn5EEFfH2T-9yCZdnaC-Ws,9842
+sysaid/resources/users.py,sha256=wq_1CX5LlbNnLio9FCj1H1OxlsDGAoXY8i1k0hNmRtw,3756
+python_sysaid-0.1.0.dist-info/METADATA,sha256=ky-d8skM-f7mlCAo_KLQx-k9d94X-rMPrxYBIA62yRA,7106
+python_sysaid-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+python_sysaid-0.1.0.dist-info/licenses/LICENSE,sha256=0oGaM8V0v4y5Af4LIP6awcbtI_Ub_t-wsnfYfsFXhXs,1070
+python_sysaid-0.1.0.dist-info/RECORD,,

python_sysaid-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

python_sysaid-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bruno Martins
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sysaid/__init__.py

@@ -0,0 +1,37 @@
+"""Python wrapper for the SysAid REST API."""
+
+from .auth import LoginResult
+from .client import SysAid
+from .exceptions import (
+    AuthenticationError,
+    BadRequestError,
+    ForbiddenError,
+    NotFoundError,
+    RelationError,
+    ServerError,
+    SysAidError,
+    SysAidHTTPError,
+    UnauthorizedError,
+    UnverifiedFeatureError,
+)
+from .models import Field, Record
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AuthenticationError",
+    "BadRequestError",
+    "Field",
+    "ForbiddenError",
+    "LoginResult",
+    "NotFoundError",
+    "Record",
+    "RelationError",
+    "ServerError",
+    "SysAid",
+    "SysAidError",
+    "SysAidHTTPError",
+    "UnauthorizedError",
+    "UnverifiedFeatureError",
+    "__version__",
+]

sysaid/_params.py

@@ -0,0 +1,80 @@
+"""Encoding of Python values into SysAid query parameters and JSON bodies."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from datetime import datetime, timezone
+from typing import Any
+from urllib.parse import quote
+
+
+def to_ms(value: datetime) -> int:
+    """Milliseconds since the epoch, UTC. Naive datetimes are taken as UTC."""
+    if value.tzinfo is None:
+        value = value.replace(tzinfo=timezone.utc)
+    return round(value.timestamp() * 1000)
+
+
+def _is_date_range(value: tuple[Any, ...]) -> bool:
+    return (
+        len(value) == 2
+        and all(item is None or isinstance(item, datetime) for item in value)
+        and any(item is not None for item in value)
+    )
+
+
+def encode_value(value: Any) -> str:
+    """Encode one query value.
+
+    ``bool`` -> ``"true"``/``"false"``; ``datetime`` -> ms; a list or tuple -> CSV;
+    a ``(from, to)`` tuple of datetimes (``None`` = open end) -> ``"from,to"`` with ``0``
+    for the open end.
+    """
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, datetime):
+        return str(to_ms(value))
+    if isinstance(value, tuple) and _is_date_range(value):
+        return ",".join("0" if item is None else str(to_ms(item)) for item in value)
+    if isinstance(value, (list, tuple)):
+        return ",".join(encode_value(item) for item in value)
+    return str(value)
+
+
+def build_params(params: Mapping[str, Any]) -> dict[str, str]:
+    """Encode query parameters, dropping those whose value is ``None``."""
+    return {key: encode_value(value) for key, value in params.items() if value is not None}
+
+
+def encode_json(value: Any) -> Any:
+    """Recursively convert datetimes in a JSON body to ms-epoch integers."""
+    if isinstance(value, datetime):
+        return to_ms(value)
+    if isinstance(value, Mapping):
+        return {key: encode_json(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [encode_json(item) for item in value]
+    return value
+
+
+def encode_info(fields: Mapping[str, Any]) -> list[dict[str, Any]]:
+    """Build the ``info`` array of ``{key, value}`` objects used by write calls.
+
+    The server only accepts scalar values as strings (a JSON number is answered with
+    HTTP 500), so numbers, booleans and datetimes are sent as text. Structured values
+    such as ``notes`` keep their JSON shape.
+    """
+    return [
+        {
+            "key": key,
+            "value": encode_value(value)
+            if isinstance(value, (int, float, datetime))
+            else encode_json(value),
+        }
+        for key, value in fields.items()
+    ]
+
+
+def quote_segment(value: object) -> str:
+    """Percent-encode one URL path segment (asset ids contain ``:``)."""
+    return quote(str(value), safe="")

sysaid/_unverified.py

@@ -0,0 +1,33 @@
+"""Switch-off for features that have not been verified against a live SysAid server."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from functools import wraps
+from typing import ParamSpec, TypeVar
+
+from .exceptions import UnverifiedFeatureError
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+# The test suite sets this to ``False`` to keep exercising the disabled code.
+DISABLED = True
+
+
+def unverified(func: Callable[P, R]) -> Callable[P, R]:
+    """Make ``func`` raise :class:`UnverifiedFeatureError` instead of running.
+
+    Remove the decorator once the call has been verified against a live server.
+    """
+
+    @wraps(func)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        if DISABLED:
+            raise UnverifiedFeatureError(
+                f"{func.__qualname__} is disabled: "
+                "it has not been verified against a live SysAid server"
+            )
+        return func(*args, **kwargs)
+
+    return wrapper

sysaid/auth.py

@@ -0,0 +1,62 @@
+"""Session-cookie login (``POST /login``)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from .exceptions import AuthenticationError, ForbiddenError, UnauthorizedError
+from .models import Record
+
+if TYPE_CHECKING:
+    from .client import SysAid
+
+
+@dataclass(frozen=True)
+class LoginResult:
+    """Outcome of a successful login."""
+
+    logged_in: bool
+    user_id: str | None
+    language: str | None
+    sysaid_version: str | None
+    date_format: str | None
+    error_msg: str | None
+    user: Record | None
+    raw: dict[str, Any]
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> LoginResult:
+        """Build from the ``/login`` response body."""
+        user = Record(data["user"]) if isinstance(data.get("user"), dict) else None
+        user_id = data.get("user_id") or (user.id if user else None)
+        return cls(
+            logged_in=data.get("logged_in", True) is not False,
+            user_id=None if user_id is None else str(user_id),
+            language=data.get("language"),
+            sysaid_version=data.get("sysaid_version"),
+            date_format=data.get("date_format"),
+            error_msg=data.get("error_msg"),
+            user=user,
+            raw=data,
+        )
+
+
+def login(
+    client: SysAid, username: str, password: str, account_id: str | None = None
+) -> LoginResult:
+    """Authenticate; the ``JSESSIONID`` cookie is kept by the client's session."""
+    body = {"user_name": username, "password": password, "account_id": account_id}
+    try:
+        data = client.request(
+            "POST",
+            "/login",
+            json={key: value for key, value in body.items() if value is not None},
+            auth=False,
+        )
+    except (UnauthorizedError, ForbiddenError) as exc:
+        raise AuthenticationError(exc.message) from exc
+    result = LoginResult.from_dict(data if isinstance(data, dict) else {})
+    if not result.logged_in:
+        raise AuthenticationError(result.error_msg or "login failed")
+    return result

sysaid/client.py

@@ -0,0 +1,160 @@
+"""The :class:`SysAid` client."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import TracebackType
+from typing import Any
+
+import requests
+
+from . import auth as _auth
+from ._params import build_params, encode_json
+from ._unverified import unverified
+from .exceptions import AuthenticationError, error_from_response
+from .resources.action_items import ActionItems
+from .resources.addons import Addons
+from .resources.assets import Assets
+from .resources.cis import CIs
+from .resources.filters import Filters
+from .resources.lists import Lists
+from .resources.password_services import PasswordServices
+from .resources.reports import Reports
+from .resources.resource_bundle import ResourceBundle
+from .resources.service_requests import ServiceRequests
+from .resources.users import Users
+
+API_PATH = "/api/v1"
+
+
+def api_url_for(base_url: str) -> str:
+    """``https://host`` or ``https://host/api/v1`` -> ``https://host/api/v1``."""
+    base = base_url.rstrip("/")
+    return base if base.endswith(API_PATH) else base + API_PATH
+
+
+class SysAid:
+    """Client for the SysAid REST API.
+
+    Credentials are optional: with ``username`` and ``password`` the client logs in
+    on first use; without them only unauthenticated calls (password services) work.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        username: str | None = None,
+        password: str | None = None,
+        account_id: str | None = None,
+        timeout: float | None = 30,
+        verify: bool | str = True,
+        session: requests.Session | None = None,
+    ) -> None:
+        self.api_url = api_url_for(base_url)
+        self.account_id = account_id
+        self.timeout = timeout
+        self.session = session or requests.Session()
+        self.session.verify = verify
+        self._username = username
+        self._password = password
+        self._logged_in = False
+        self.users = Users(self)
+        self.filters = Filters(self)
+        self.lists = Lists(self)
+        self.service_requests = ServiceRequests(self)
+        self.action_items = ActionItems(self)
+        self.assets = Assets(self)
+        self.cis = CIs(self)
+        self.addons = Addons(self)
+        self.resource_bundle = ResourceBundle(self)
+        self.password_services = PasswordServices(self)
+        self.reports = Reports(self)
+
+    @classmethod
+    @unverified
+    def from_oauth(
+        cls,
+        base_url: str,
+        consumer_key: str,
+        access_token: str,
+        access_token_secret: str,
+        consumer_secret: str = "",
+        **kwargs: Any,
+    ) -> SysAid:
+        """A client that signs every request with OAuth 1.0 (needs ``python-sysaid[oauth]``)."""
+        from .oauth import oauth1
+
+        client = cls(base_url, **kwargs)
+        client.session.auth = oauth1(
+            consumer_key,
+            consumer_secret,
+            resource_owner_key=access_token,
+            resource_owner_secret=access_token_secret,
+        )
+        return client
+
+    def __repr__(self) -> str:
+        return f"SysAid({self.api_url!r}, username={self._username!r})"
+
+    def __enter__(self) -> SysAid:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the underlying HTTP session."""
+        self.session.close()
+        self._logged_in = False
+
+    def login(self) -> _auth.LoginResult:
+        """Log in with the configured credentials."""
+        if self._username is None or self._password is None:
+            raise AuthenticationError("username and password are required to log in")
+        result = _auth.login(self, self._username, self._password, self.account_id)
+        self._logged_in = True
+        return result
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json: Any = None,
+        data: Mapping[str, Any] | None = None,
+        files: Any = None,
+        auth: bool = True,
+        raw: bool = False,
+    ) -> Any:
+        """Send a request and return the decoded JSON (text if not JSON, ``None`` if empty).
+
+        With ``raw=True`` the :class:`requests.Response` is returned instead.
+        With ``auth=False`` no login is attempted first.
+        """
+        if auth and not self._logged_in and self._username is not None:
+            self.login()
+        response = self.session.request(
+            method,
+            self.api_url + "/" + path.lstrip("/"),
+            params=build_params(params or {}),
+            json=encode_json(json),
+            data=data,
+            files=files,
+            timeout=self.timeout,
+        )
+        if not response.ok:
+            raise error_from_response(response)
+        if raw:
+            return response
+        if not response.content:
+            return None
+        try:
+            return response.json()
+        except ValueError:
+            return response.text