almapy 9.1.1__py3-none-any.whl

almapy/__init__.py

@@ -0,0 +1,6 @@
+"""An API wrapper library for Ex Libris' Alma."""
+
+from almapy._client import AlmaClient
+from almapy.exceptions import AlmapyError, ThrottleTimeoutError
+
+__all__ = ["AlmaClient", "AlmapyError", "ThrottleTimeoutError"]

almapy/_acq.py

@@ -0,0 +1,134 @@
+from datetime import date
+from typing import Any, Literal, overload
+
+from almapy._base import BaseNamespace
+from almapy._endpoints import AlmaEndpoint
+from almapy._utils import RESP_TYPE, Body, _ModelT
+
+
+class AlmaClientAcqNS(BaseNamespace):
+    """Namespace for acquisitions functionality."""
+
+    @overload
+    async def get_po_line(self, po_line_id: str, *, model: type[_ModelT]) -> _ModelT: ...
+
+    @overload
+    async def get_po_line(self, po_line_id: str, *, model: None = ...) -> RESP_TYPE: ...
+
+    async def get_po_line(self, po_line_id: str, *, model: Any = None) -> Any:
+        return await self._get(AlmaEndpoint.PO_LINE, {"PO_LINE_ID": po_line_id}, model=model)
+
+    @overload
+    async def update_po_line(
+        self,
+        po_line_id: str,
+        updated_po_line: Body,
+        *,
+        update_inventory: bool = ...,
+        redistribute_funds: bool = ...,
+        model: type[_ModelT],
+    ) -> _ModelT: ...
+
+    @overload
+    async def update_po_line(
+        self,
+        po_line_id: str,
+        updated_po_line: Body,
+        *,
+        update_inventory: bool = ...,
+        redistribute_funds: bool = ...,
+        model: None = ...,
+    ) -> RESP_TYPE: ...
+
+    async def update_po_line(
+        self,
+        po_line_id: str,
+        updated_po_line: Body,
+        *,
+        update_inventory: bool = False,
+        redistribute_funds: bool = False,
+        model: Any = None,
+    ) -> Any:
+        return await self._put(
+            AlmaEndpoint.PO_LINE,
+            {"PO_LINE_ID": po_line_id},
+            model=model,
+            params={"update_inventory": update_inventory, "redistribute_funds": redistribute_funds},
+            json=updated_po_line,
+        )
+
+    @overload
+    async def receive_existing_item(
+        self,
+        po_line_id: str,
+        item_pid: str,
+        *,
+        receive_date: date | None = ...,
+        department: str | None = ...,
+        department_library: str | None = ...,
+        updated_item: Body | None = ...,
+        model: type[_ModelT],
+    ) -> _ModelT: ...
+
+    @overload
+    async def receive_existing_item(
+        self,
+        po_line_id: str,
+        item_pid: str,
+        *,
+        receive_date: date | None = ...,
+        department: str | None = ...,
+        department_library: str | None = ...,
+        updated_item: Body | None = ...,
+        model: None = ...,
+    ) -> RESP_TYPE: ...
+
+    async def receive_existing_item(
+        self,
+        po_line_id: str,
+        item_pid: str,
+        *,
+        receive_date: date | None = None,
+        department: str | None = None,
+        department_library: str | None = None,
+        updated_item: Body | None = None,
+        model: Any = None,
+    ) -> Any:
+        if updated_item is None:
+            updated_item = {}
+        params: dict[str, Any] = {"op": "receive"}
+        if receive_date:
+            params["receive_date"] = receive_date.strftime("%Y-%m-%dZ")
+        if department:
+            params["department"] = department
+        if department_library:
+            params["department_library"] = department_library
+        return await self._post(
+            AlmaEndpoint.PO_LINE_ITEM,
+            {"PO_LINE_ID": po_line_id, "ITEM_PID": item_pid},
+            model=model,
+            params=params,
+            json=updated_item,
+        )
+
+    async def cancel_po_line(
+        self,
+        po_line_id: str,
+        reason_code: str,
+        *,
+        comment: str | None = None,
+        inform_vendor: bool = False,
+        override: bool = False,
+        bib_handling: Literal["retain", "delete", "suppress"] = "retain",
+    ) -> None:
+        params: dict[str, Any] = {
+            "reason": reason_code,
+            "inform_vendor": inform_vendor,
+            "override": override,
+            "bib": bib_handling,
+        }
+        if comment:
+            params["comment"] = comment
+        await self._delete(
+            AlmaEndpoint.PO_LINE, {"PO_LINE_ID": po_line_id}, parser="none", params=params
+        )

almapy/_analytics.py

@@ -0,0 +1,85 @@
+from typing import Any
+
+import xmltodict
+
+from almapy._base import BaseNamespace
+from almapy._endpoints import AlmaEndpoint
+
+
+def _as_list(value: Any) -> list[Any]:
+    """Normalise xmltodict's repeated-element handling.
+
+    xmltodict returns a list for repeated elements, a bare dict when exactly one
+    is present, and nothing at all when there are none. Every site that iterates
+    rows or columns has to go through here: iterating the dict form yields its
+    keys as strings, which fails later with a confusing AttributeError rather
+    than at the point of the mistake.
+    """
+    if value is None:
+        return []
+    return value if isinstance(value, list) else [value]
+
+
+def headers_to_dict(headers: list[dict[str, Any]] | dict[str, Any]) -> dict[str, Any]:
+    """Map Alma's internal column names to their report headings.
+
+    Accepts the single-column dict form as well as a list — a report with one
+    non-Column0 column previously raised TypeError here.
+    """
+    return {header["@name"]: header["@saw-sql:columnHeading"] for header in _as_list(headers)}
+
+
+class AlmaClientAnalyticsNS(BaseNamespace):
+    """Namespace for analytics functionality."""
+
+    async def get_raw_report(
+        self,
+        path: str,
+        limit: int = 100,
+        *,
+        token: str | None = None,
+        report_filter: str | None = None,
+    ) -> str:
+        params: dict[str, Any] = {"path": path, "limit": limit}
+        if report_filter:
+            params["filter"] = report_filter
+        if token:
+            params["token"] = token
+        return await self._get_text(
+            AlmaEndpoint.REPORTS,
+            params=params,
+            headers={"Accept": "application/xml"},
+        )
+
+    async def get_full_report(
+        self,
+        path: str,
+        limit: int = 100,
+        header_override: dict[str, str] | None = None,
+        report_filter: str | None = None,
+    ) -> list[dict[str, str]]:
+        initial_response = await self.get_raw_report(path, limit, report_filter=report_filter)
+        parsed_resp = xmltodict.parse(initial_response)
+        finished = parsed_resp["report"]["QueryResult"]["IsFinished"]
+        rowset = parsed_resp["report"]["QueryResult"]["ResultXml"]["rowset"]
+        result = _as_list(rowset.get("Row"))
+        headers = headers_to_dict(
+            rowset["xsd:schema"]["xsd:complexType"]["xsd:sequence"]["xsd:element"]
+        )
+        if header_override:
+            headers.update(header_override)
+        token = parsed_resp["report"]["QueryResult"]["ResumptionToken"]
+
+        while finished == "false":
+            resp = await self.get_raw_report(path, limit, token=token, report_filter=report_filter)
+            parsed_resp = xmltodict.parse(resp)
+            finished = parsed_resp["report"]["QueryResult"]["IsFinished"]
+            # Same coercion as the first page. Indexing ["Row"] directly meant a
+            # final page with one row raised AttributeError and one with no rows
+            # raised KeyError — reachable by any report whose total is just over
+            # a multiple of `limit`.
+            page = parsed_resp["report"]["QueryResult"]["ResultXml"]["rowset"]
+            result.extend(_as_list(page.get("Row")))
+
+        data = [{headers[k]: v for k, v in row.items() if k != "Column0"} for row in result]
+        return data

almapy/_base.py

@@ -0,0 +1,223 @@
+"""Base namespace for Alma API client namespaces."""
+
+from collections.abc import Callable, Mapping
+from typing import TYPE_CHECKING, Any, Literal, Protocol, cast, overload
+
+from almapy._endpoints import AlmaEndpoint
+from almapy._utils import RESP_TYPE, _ModelT
+
+if TYPE_CHECKING:
+    import niquests
+
+Parser = Literal["json", "xml", "none", "text"]
+
+
+class _AlmaExecutable(Protocol):
+    """Protocol for the execute method AlmaClient provides."""
+
+    _gateway: str
+    """Regional gateway root (e.g. https://api-eu.hosted.exlibrisgroup.com)."""
+
+    @overload
+    async def execute(
+        self, method: str, url: str, *, parser: Parser, model: type[_ModelT], **kwargs: Any
+    ) -> _ModelT: ...
+
+    @overload
+    async def execute(
+        self, method: str, url: str, *, parser: Parser, model: None = ..., **kwargs: Any
+    ) -> RESP_TYPE: ...
+
+    async def execute(
+        self,
+        method: str,
+        url: str,
+        *,
+        parser: Parser,
+        model: Any = None,
+        validate: "Callable[[niquests.Response], None]" = ...,
+        retry: bool | None = None,
+        **kwargs: Any,
+    ) -> Any: ...
+
+
+class BaseNamespace:  # ruff: ignore[class-as-data-structure]
+    """Base class for AlmaClient namespace objects.
+
+    Owns URL building via AlmaEndpoint.build() and delegates HTTP execution to
+    AlmaClient.execute(). Namespace methods pass ``retry=`` straight through to
+    control whether a write is replayed on an ambiguous transport failure.
+    """
+
+    def __init__(self, client: _AlmaExecutable) -> None:
+        self._client = client
+
+    @overload
+    async def _get(
+        self,
+        endpoint: AlmaEndpoint,
+        path: Mapping[str, str] | None = None,
+        *,
+        model: type[_ModelT],
+        parser: Parser = ...,
+        **kwargs: Any,
+    ) -> _ModelT: ...
+
+    @overload
+    async def _get(
+        self,
+        endpoint: AlmaEndpoint,
+        path: Mapping[str, str] | None = None,
+        *,
+        model: None = ...,
+        parser: Parser = ...,
+        **kwargs: Any,
+    ) -> RESP_TYPE: ...
+
+    async def _get(
+        self,
+        endpoint: AlmaEndpoint,
+        path: Mapping[str, str] | None = None,
+        *,
+        model: Any = None,
+        parser: Parser = "json",
+        **kwargs: Any,
+    ) -> Any:
+        return await self._client.execute(
+            "GET", endpoint.build(path), parser=parser, model=model, **kwargs
+        )
+
+    @overload
+    async def _post(
+        self,
+        endpoint: AlmaEndpoint,
+        path: Mapping[str, str] | None = None,
+        *,
+        model: type[_ModelT],
+        parser: Parser = ...,
+        **kwargs: Any,
+    ) -> _ModelT: ...
+
+    @overload
+    async def _post(
+        self,
+        endpoint: AlmaEndpoint,
+        path: Mapping[str, str] | None = None,
+        *,
+        model: None = ...,
+        parser: Parser = ...,
+        **kwargs: Any,
+    ) -> RESP_TYPE: ...
+
+    async def _post(
+        self,
+        endpoint: AlmaEndpoint,
+        path: Mapping[str, str] | None = None,
+        *,
+        model: Any = None,
+        parser: Parser = "json",
+        **kwargs: Any,
+    ) -> Any:
+        return await self._client.execute(
+            "POST", endpoint.build(path), parser=parser, model=model, **kwargs
+        )
+
+    @overload
+    async def _put(
+        self,
+        endpoint: AlmaEndpoint,
+        path: Mapping[str, str] | None = None,
+        *,
+        model: type[_ModelT],
+        parser: Parser = ...,
+        **kwargs: Any,
+    ) -> _ModelT: ...
+
+    @overload
+    async def _put(
+        self,
+        endpoint: AlmaEndpoint,
+        path: Mapping[str, str] | None = None,
+        *,
+        model: None = ...,
+        parser: Parser = ...,
+        **kwargs: Any,
+    ) -> RESP_TYPE: ...
+
+    async def _put(
+        self,
+        endpoint: AlmaEndpoint,
+        path: Mapping[str, str] | None = None,
+        *,
+        model: Any = None,
+        parser: Parser = "json",
+        **kwargs: Any,
+    ) -> Any:
+        return await self._client.execute(
+            "PUT", endpoint.build(path), parser=parser, model=model, **kwargs
+        )
+
+    @overload
+    async def _delete(
+        self,
+        endpoint: AlmaEndpoint,
+        path: Mapping[str, str] | None = None,
+        *,
+        model: type[_ModelT],
+        parser: Parser = ...,
+        **kwargs: Any,
+    ) -> _ModelT: ...
+
+    @overload
+    async def _delete(
+        self,
+        endpoint: AlmaEndpoint,
+        path: Mapping[str, str] | None = None,
+        *,
+        model: None = ...,
+        parser: Parser = ...,
+        **kwargs: Any,
+    ) -> RESP_TYPE: ...
+
+    async def _delete(
+        self,
+        endpoint: AlmaEndpoint,
+        path: Mapping[str, str] | None = None,
+        *,
+        model: Any = None,
+        parser: Parser = "json",
+        **kwargs: Any,
+    ) -> Any:
+        return await self._client.execute(
+            "DELETE", endpoint.build(path), parser=parser, model=model, **kwargs
+        )
+
+    async def _get_text(
+        self,
+        endpoint: AlmaEndpoint,
+        path: Mapping[str, str] | None = None,
+        **kwargs: Any,
+    ) -> str:
+        """GET returning raw response text (e.g., MARC XML records)."""
+        result: Any = await self._get(endpoint, path, parser="text", **kwargs)
+        return cast(str, result)
+
+    async def _post_text(
+        self,
+        endpoint: AlmaEndpoint,
+        path: Mapping[str, str] | None = None,
+        **kwargs: Any,
+    ) -> str:
+        """POST returning raw response text."""
+        result: Any = await self._post(endpoint, path, parser="text", **kwargs)
+        return cast(str, result)
+
+    async def _put_text(
+        self,
+        endpoint: AlmaEndpoint,
+        path: Mapping[str, str] | None = None,
+        **kwargs: Any,
+    ) -> str:
+        """PUT returning raw response text."""
+        result: Any = await self._put(endpoint, path, parser="text", **kwargs)
+        return cast(str, result)