python-sysaid 0.1.0__tar.gz

python_sysaid-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+.env
+
+# Local credentials, never commit
+token
+temp.sh

python_sysaid-0.1.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-09
+
+### Added
+
+- Initial release.

python_sysaid-0.1.0/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.

python_sysaid-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,174 @@
+# 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/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "python-sysaid"
+dynamic = ["version"]
+description = "Python wrapper for the SysAid REST API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["sysaid", "api", "itsm", "rest"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = ["requests>=2.31"]
+
+[project.optional-dependencies]
+oauth = ["requests-oauthlib>=1.3"]
+dev = [
+    "build",
+    "mypy",
+    "pytest",
+    "requests-oauthlib>=1.3",
+    "responses",
+    "ruff",
+    "twine",
+    "types-requests",
+    "types-requests-oauthlib",
+]
+
+[tool.hatch.version]
+path = "src/sysaid/__init__.py"
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "CHANGELOG.md"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sysaid"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+extend-exclude = ["*.md"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+strict = true
+files = ["src", "tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "integration: live tests against a SysAid instance (needs SYSAID_* env vars)",
+    "destructive: live tests that write data (also needs SYSAID_ALLOW_WRITES=1)",
+]

python_sysaid-0.1.0/src/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__",
+]

python_sysaid-0.1.0/src/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="")

python_sysaid-0.1.0/src/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