calendry-client 0.1.0__py3-none-any.whl

calendry_client/__init__.py

@@ -0,0 +1,180 @@
+"""Calendry API client library.
+
+A thin, dependency-light client (:class:`CalendryClient`) plus a set of pure
+functions per resource (persons, groups, rooms, offerings, ...) that build
+request bodies matching the Calendry OpenAPI schema (see ``swagger.json`` in
+the repository root) and call the generic CRUD/relation routes.
+"""
+
+from .client import CalendryClient
+from .exceptions import CalendryAPIError
+
+from .access_roles import add_access_role, delete_access_role, get_access_role, list_access_roles, update_access_role
+from .calendar_periods import add_calendar_period, delete_calendar_period, get_calendar_period, list_calendar_periods, update_calendar_period
+from .constraints import (
+    add_constraint,
+    delete_constraint,
+    get_constraint,
+    get_constraint_scopes,
+    list_constraints,
+    set_constraint_scopes,
+    update_constraint,
+)
+from .equipment import add_equipment, delete_equipment, get_equipment, list_equipment, update_equipment
+from .groups import (
+    add_group,
+    add_subgroup,
+    delete_group,
+    get_group,
+    get_group_availability,
+    get_group_sources,
+    get_group_terms,
+    list_groups,
+    set_group_availability,
+    set_group_sources,
+    set_group_terms,
+    update_group,
+)
+from .offerings import (
+    add_offering,
+    delete_offering,
+    get_offering,
+    get_offering_equipment,
+    get_offering_groups,
+    get_offering_lecturers,
+    list_offerings,
+    set_offering_equipment,
+    set_offering_groups,
+    set_offering_lecturers,
+    update_offering,
+)
+from .persons import (
+    add_lecturer,
+    add_person,
+    delete_person,
+    get_person,
+    get_person_access_roles,
+    get_person_groups,
+    get_person_roles,
+    list_persons,
+    set_person_access_roles,
+    set_person_groups,
+    set_person_roles,
+    update_person,
+)
+from .roles import add_role, delete_role, get_role, list_roles, update_role
+from .rooms import add_room, delete_room, get_room, get_room_equipment, list_rooms, set_room_equipment, update_room
+from .session_kinds import add_session_kind, delete_session_kind, get_session_kind, list_session_kinds, update_session_kind
+from .terms import add_term, delete_term, get_term, list_terms, update_term
+from .time_grids import (
+    add_time_grid,
+    delete_time_grid,
+    get_time_grid,
+    get_time_grid_breaks,
+    list_time_grids,
+    set_time_grid_breaks,
+    update_time_grid,
+)
+
+__all__ = [
+    "CalendryClient",
+    "CalendryAPIError",
+    # access-roles
+    "add_access_role",
+    "delete_access_role",
+    "get_access_role",
+    "list_access_roles",
+    "update_access_role",
+    # calendar-periods
+    "add_calendar_period",
+    "delete_calendar_period",
+    "get_calendar_period",
+    "list_calendar_periods",
+    "update_calendar_period",
+    # constraints
+    "add_constraint",
+    "delete_constraint",
+    "get_constraint",
+    "get_constraint_scopes",
+    "list_constraints",
+    "set_constraint_scopes",
+    "update_constraint",
+    # equipment
+    "add_equipment",
+    "delete_equipment",
+    "get_equipment",
+    "list_equipment",
+    "update_equipment",
+    # groups
+    "add_group",
+    "add_subgroup",
+    "delete_group",
+    "get_group",
+    "get_group_availability",
+    "get_group_sources",
+    "get_group_terms",
+    "list_groups",
+    "set_group_availability",
+    "set_group_sources",
+    "set_group_terms",
+    "update_group",
+    # offerings
+    "add_offering",
+    "delete_offering",
+    "get_offering",
+    "get_offering_equipment",
+    "get_offering_groups",
+    "get_offering_lecturers",
+    "list_offerings",
+    "set_offering_equipment",
+    "set_offering_groups",
+    "set_offering_lecturers",
+    "update_offering",
+    # persons
+    "add_lecturer",
+    "add_person",
+    "delete_person",
+    "get_person",
+    "get_person_access_roles",
+    "get_person_groups",
+    "get_person_roles",
+    "list_persons",
+    "set_person_access_roles",
+    "set_person_groups",
+    "set_person_roles",
+    "update_person",
+    # roles
+    "add_role",
+    "delete_role",
+    "get_role",
+    "list_roles",
+    "update_role",
+    # rooms
+    "add_room",
+    "delete_room",
+    "get_room",
+    "get_room_equipment",
+    "list_rooms",
+    "set_room_equipment",
+    "update_room",
+    # session-kinds
+    "add_session_kind",
+    "delete_session_kind",
+    "get_session_kind",
+    "list_session_kinds",
+    "update_session_kind",
+    # terms
+    "add_term",
+    "delete_term",
+    "get_term",
+    "list_terms",
+    "update_term",
+    # time-grids
+    "add_time_grid",
+    "delete_time_grid",
+    "get_time_grid",
+    "get_time_grid_breaks",
+    "list_time_grids",
+    "set_time_grid_breaks",
+    "update_time_grid",
+]

calendry_client/_generic.py

@@ -0,0 +1,64 @@
+"""Generic helpers shared by every resource module.
+
+These mirror the generic ``/api/{resource}`` and ``/api/{resource}/{id}``
+and ``/api/{resource}/{id}/{relation}`` routes documented in swagger.json.
+Resource-specific modules build their pure functions on top of these.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterable, Optional
+
+from .client import CalendryClient
+
+
+def compact(**kwargs: Any) -> dict:
+    """Drop keys whose value is None, so optional fields are simply omitted."""
+    return {k: v for k, v in kwargs.items() if v is not None}
+
+
+def list_rows(
+    client: CalendryClient,
+    resource: str,
+    *,
+    limit: Optional[int] = None,
+    offset: Optional[int] = None,
+    q: Optional[str] = None,
+    ids: Optional[Iterable[str]] = None,
+    **filters: Any,
+) -> Any:
+    params = compact(
+        limit=limit,
+        offset=offset,
+        q=q,
+        ids=",".join(ids) if ids is not None else None,
+        **filters,
+    )
+    return client.get(f"/api/{resource}", params=params or None)
+
+
+def get_row(client: CalendryClient, resource: str, row_id: str) -> Any:
+    return client.get(f"/api/{resource}/{row_id}")
+
+
+def create_row(client: CalendryClient, resource: str, body: dict) -> Any:
+    return client.post(f"/api/{resource}", json=body)
+
+
+def update_row(client: CalendryClient, resource: str, row_id: str, body: dict) -> Any:
+    return client.patch(f"/api/{resource}/{row_id}", json=body)
+
+
+def delete_row(client: CalendryClient, resource: str, row_id: str) -> Any:
+    return client.delete(f"/api/{resource}/{row_id}")
+
+
+def get_relation(client: CalendryClient, resource: str, row_id: str, relation: str) -> Any:
+    return client.get(f"/api/{resource}/{row_id}/{relation}")
+
+
+def set_relation(
+    client: CalendryClient, resource: str, row_id: str, relation: str, items: list
+) -> Any:
+    """Replace the entire membership set of a relation (PUT, not additive)."""
+    return client.put(f"/api/{resource}/{row_id}/{relation}", json=items)

calendry_client/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

calendry_client/access_roles.py

@@ -0,0 +1,56 @@
+"""Pure functions for the ``access-roles`` resource (authorization roles, not scheduling roles)."""
+
+from __future__ import annotations
+
+from typing import Any, Iterable, Optional
+
+from ._generic import compact, create_row, delete_row, get_row, list_rows, update_row
+from .client import CalendryClient
+
+RESOURCE = "access-roles"
+
+
+def list_access_roles(client: CalendryClient, *, limit=None, offset=None, q=None, ids: Optional[Iterable[str]] = None) -> Any:
+    return list_rows(client, RESOURCE, limit=limit, offset=offset, q=q, ids=ids)
+
+
+def get_access_role(client: CalendryClient, access_role_id: str) -> Any:
+    return get_row(client, RESOURCE, access_role_id)
+
+
+def add_access_role(
+    client: CalendryClient,
+    key: str,
+    name: str,
+    permission_keys: Iterable[str],
+    *,
+    description: Optional[str] = None,
+) -> Any:
+    """Requires ``access_role.manage`` on the server side."""
+    body = {
+        "key": key,
+        "name": name,
+        "permissions": [{"permissionKey": p} for p in permission_keys],
+    }
+    body.update(compact(description=description))
+    return create_row(client, RESOURCE, body)
+
+
+def update_access_role(
+    client: CalendryClient,
+    access_role_id: str,
+    *,
+    name: Optional[str] = None,
+    description: Optional[str] = None,
+    permission_keys: Optional[Iterable[str]] = None,
+) -> Any:
+    body = compact(
+        name=name,
+        description=description,
+        permissions=[{"permissionKey": p} for p in permission_keys] if permission_keys is not None else None,
+    )
+    return update_row(client, RESOURCE, access_role_id, body)
+
+
+def delete_access_role(client: CalendryClient, access_role_id: str) -> Any:
+    return delete_row(client, RESOURCE, access_role_id)

calendry_client/calendar_periods.py

@@ -0,0 +1,48 @@
+"""Pure functions for the ``calendar-periods`` resource (holidays, breaks, exam periods)."""
+
+from __future__ import annotations
+
+from typing import Any, Iterable, Optional
+
+from ._generic import compact, create_row, delete_row, get_row, list_rows, update_row
+from .client import CalendryClient
+
+RESOURCE = "calendar-periods"
+
+
+def list_calendar_periods(client: CalendryClient, *, limit=None, offset=None, q=None, ids: Optional[Iterable[str]] = None) -> Any:
+    return list_rows(client, RESOURCE, limit=limit, offset=offset, q=q, ids=ids)
+
+
+def get_calendar_period(client: CalendryClient, period_id: str) -> Any:
+    return get_row(client, RESOURCE, period_id)
+
+
+def add_calendar_period(
+    client: CalendryClient,
+    term_id: str,
+    kind: str,
+    name: str,
+    start_date: str,
+    end_date: str,
+) -> Any:
+    """``kind`` is one of HOLIDAY, BREAK, EXAM. Dates are ISO 8601."""
+    body = {"termId": term_id, "kind": kind, "name": name, "startDate": start_date, "endDate": end_date}
+    return create_row(client, RESOURCE, body)
+
+
+def update_calendar_period(
+    client: CalendryClient,
+    period_id: str,
+    *,
+    kind: Optional[str] = None,
+    name: Optional[str] = None,
+    start_date: Optional[str] = None,
+    end_date: Optional[str] = None,
+) -> Any:
+    body = compact(kind=kind, name=name, startDate=start_date, endDate=end_date)
+    return update_row(client, RESOURCE, period_id, body)
+
+
+def delete_calendar_period(client: CalendryClient, period_id: str) -> Any:
+    return delete_row(client, RESOURCE, period_id)

calendry_client/client.py

@@ -0,0 +1,113 @@
+"""HTTP client for the Calendry API.
+
+The server URL and the authentication token are both configurable on the
+client instance (constructor args) and, via :meth:`CalendryClient.from_env`,
+through environment variables. Nothing about the target server or the
+credentials is hard-coded.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Optional
+
+import requests
+
+from .exceptions import CalendryAPIError
+
+DEFAULT_TIMEOUT = 30.0
+
+
+class CalendryClient:
+    """Thin HTTP wrapper around the Calendry REST API.
+
+    Parameters
+    ----------
+    base_url:
+        Root URL of the Calendry server, e.g. ``https://calendry.example.com``.
+    token:
+        Bearer token used for the ``Authorization`` header. ``None`` means
+        unauthenticated requests are sent (useful against a server that
+        relies on a different auth mechanism, or for the public routes).
+    timeout:
+        Per-request timeout in seconds.
+    session:
+        Optional pre-configured :class:`requests.Session` (mainly for tests).
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        token: Optional[str] = None,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        session: Optional[requests.Session] = None,
+    ) -> None:
+        if not base_url:
+            raise ValueError("base_url is required")
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.timeout = timeout
+        self.session = session or requests.Session()
+
+    @classmethod
+    def from_env(
+        cls,
+        *,
+        url_var: str = "CALENDRY_SERVER_URL",
+        token_var: str = "CALENDRY_API_TOKEN",
+        **kwargs: Any,
+    ) -> "CalendryClient":
+        """Build a client from environment variables.
+
+        Raises ``RuntimeError`` if the URL variable is not set.
+        """
+        base_url = os.environ.get(url_var)
+        if not base_url:
+            raise RuntimeError(f"Environment variable {url_var} is not set")
+        token = os.environ.get(token_var)
+        return cls(base_url, token, **kwargs)
+
+    def _headers(self) -> dict:
+        headers = {"Accept": "application/json"}
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        return headers
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[dict] = None,
+        json: Any = None,
+    ) -> Any:
+        url = f"{self.base_url}{path}"
+        response = self.session.request(
+            method,
+            url,
+            params=params,
+            json=json,
+            headers=self._headers(),
+            timeout=self.timeout,
+        )
+        if not response.ok:
+            raise CalendryAPIError.from_response(response)
+        if response.status_code == 204 or not response.content:
+            return None
+        return response.json()
+
+    def get(self, path: str, *, params: Optional[dict] = None) -> Any:
+        return self.request("GET", path, params=params)
+
+    def post(self, path: str, *, json: Any = None) -> Any:
+        return self.request("POST", path, json=json)
+
+    def patch(self, path: str, *, json: Any = None) -> Any:
+        return self.request("PATCH", path, json=json)
+
+    def put(self, path: str, *, json: Any = None) -> Any:
+        return self.request("PUT", path, json=json)
+
+    def delete(self, path: str) -> Any:
+        return self.request("DELETE", path)

calendry_client/constraints.py

@@ -0,0 +1,80 @@
+"""Pure functions for the ``constraints`` resource (solver rules)."""
+
+from __future__ import annotations
+
+from typing import Any, Iterable, Optional
+
+from ._generic import compact, create_row, delete_row, get_relation, get_row, list_rows, set_relation, update_row
+from .client import CalendryClient
+
+RESOURCE = "constraints"
+
+
+def list_constraints(client: CalendryClient, *, limit=None, offset=None, q=None, ids: Optional[Iterable[str]] = None) -> Any:
+    return list_rows(client, RESOURCE, limit=limit, offset=offset, q=q, ids=ids)
+
+
+def get_constraint(client: CalendryClient, constraint_id: str) -> Any:
+    return get_row(client, RESOURCE, constraint_id)
+
+
+def add_constraint(
+    client: CalendryClient,
+    constraint_type: str,
+    name: str,
+    severity: str,
+    *,
+    weight: Optional[int] = None,
+    params: Optional[dict] = None,
+    is_enabled: Optional[bool] = None,
+    time_grid_id: Optional[str] = None,
+    scopes: Optional[Iterable[str]] = None,
+    members: Optional[Iterable[str]] = None,
+) -> Any:
+    """``severity`` is HARD or SOFT. ``scopes``/``members`` are id lists (kindIds / offeringIds)."""
+    body = {"type": constraint_type, "name": name, "severity": severity}
+    body.update(
+        compact(
+            weight=weight,
+            params=params,
+            isEnabled=is_enabled,
+            timeGridId=time_grid_id,
+            scopes=[{"kindId": k} for k in scopes] if scopes is not None else None,
+            members=[{"offeringId": o} for o in members] if members is not None else None,
+        )
+    )
+    return create_row(client, RESOURCE, body)
+
+
+def update_constraint(
+    client: CalendryClient,
+    constraint_id: str,
+    *,
+    name: Optional[str] = None,
+    severity: Optional[str] = None,
+    weight: Optional[int] = None,
+    params: Optional[dict] = None,
+    is_enabled: Optional[bool] = None,
+    time_grid_id: Optional[str] = None,
+) -> Any:
+    body = compact(
+        name=name, severity=severity, weight=weight, params=params, isEnabled=is_enabled, timeGridId=time_grid_id
+    )
+    return update_row(client, RESOURCE, constraint_id, body)
+
+
+def delete_constraint(client: CalendryClient, constraint_id: str) -> Any:
+    return delete_row(client, RESOURCE, constraint_id)
+
+
+def get_constraint_scopes(client: CalendryClient, constraint_id: str) -> Any:
+    return get_relation(client, RESOURCE, constraint_id, "scopes")
+
+
+def set_constraint_scopes(client: CalendryClient, constraint_id: str, scopes: Iterable[dict]) -> Any:
+    """Replace the scopes narrowing this constraint.
+
+    Each item is a dict with optional ``offering_id`` and/or ``kind_id`` (at least one required).
+    """
+    items = [compact(offeringId=s.get("offering_id"), kindId=s.get("kind_id")) for s in scopes]
+    return set_relation(client, RESOURCE, constraint_id, "scopes", items)

calendry_client/equipment.py

@@ -0,0 +1,32 @@
+"""Pure functions for the ``equipment`` resource."""
+
+from __future__ import annotations
+
+from typing import Any, Iterable, Optional
+
+from ._generic import compact, create_row, delete_row, get_row, list_rows, update_row
+from .client import CalendryClient
+
+RESOURCE = "equipment"
+
+
+def list_equipment(client: CalendryClient, *, limit=None, offset=None, q=None, ids: Optional[Iterable[str]] = None) -> Any:
+    return list_rows(client, RESOURCE, limit=limit, offset=offset, q=q, ids=ids)
+
+
+def get_equipment(client: CalendryClient, equipment_id: str) -> Any:
+    return get_row(client, RESOURCE, equipment_id)
+
+
+def add_equipment(client: CalendryClient, key: str, name: str, *, description: Optional[str] = None) -> Any:
+    body = {"key": key, "name": name}
+    body.update(compact(description=description))
+    return create_row(client, RESOURCE, body)
+
+
+def update_equipment(client: CalendryClient, equipment_id: str, *, name: Optional[str] = None, description: Optional[str] = None) -> Any:
+    return update_row(client, RESOURCE, equipment_id, compact(name=name, description=description))
+
+
+def delete_equipment(client: CalendryClient, equipment_id: str) -> Any:
+    return delete_row(client, RESOURCE, equipment_id)

calendry_client/exceptions.py

@@ -0,0 +1,26 @@
+"""Exceptions raised by the Calendry client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class CalendryAPIError(Exception):
+    """Raised when the Calendry API returns a non-2xx response."""
+
+    def __init__(self, status_code: int, message: str, payload: Any = None):
+        super().__init__(f"Calendry API error {status_code}: {message}")
+        self.status_code = status_code
+        self.payload = payload
+
+    @classmethod
+    def from_response(cls, response) -> "CalendryAPIError":
+        message = response.text
+        payload = None
+        try:
+            payload = response.json()
+            if isinstance(payload, dict):
+                message = payload.get("message") or payload.get("error") or message
+        except ValueError:
+            pass
+        return cls(response.status_code, message, payload)