PAWpy 0.1.0__py3-none-any.whl

PAWpy/Exceptions/Exceptions.py

@@ -0,0 +1,63 @@
+"""Exception hierarchy for PAWpy.
+
+Mirrors the spirit of TM1py's exception design: a single base exception
+(`PAWException`) with specialised subclasses so callers can catch broadly or
+narrowly. HTTP failures carry the status code, the request method/url, and the
+(possibly truncated) response body to make debugging against a remote PAW
+instance practical.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class PAWException(Exception):
+    """Base class for every error raised by PAWpy."""
+
+
+class PAWConfigException(PAWException):
+    """Raised when PAWpy is constructed with an invalid/incomplete configuration."""
+
+
+class PAWAuthenticationException(PAWException):
+    """Raised when login / token acquisition fails."""
+
+
+class PAWTimeoutException(PAWException):
+    """Raised when a request exceeds the configured timeout."""
+
+    def __init__(self, method: str, url: str, timeout: float):
+        self.method = method
+        self.url = url
+        self.timeout = timeout
+        super().__init__(f"Request '{method} {url}' timed out after {timeout}s")
+
+
+class PAWRestException(PAWException):
+    """Raised when PAW returns a non-2xx HTTP status code."""
+
+    def __init__(
+        self,
+        status_code: int,
+        reason: str,
+        method: str,
+        url: str,
+        response_body: Optional[str] = None,
+    ):
+        self.status_code = status_code
+        self.reason = reason
+        self.method = method
+        self.url = url
+        self.response_body = response_body
+        body_preview = ""
+        if response_body:
+            body_preview = response_body if len(response_body) <= 2000 else response_body[:2000] + "…"
+            body_preview = f"\nResponse body: {body_preview}"
+        super().__init__(
+            f"PAW REST request failed: {method} {url} -> {status_code} {reason}{body_preview}"
+        )
+
+
+class PAWNotFoundException(PAWRestException):
+    """Raised on HTTP 404 — the requested asset/resource does not exist."""

PAWpy/Exceptions/__init__.py

@@ -0,0 +1,17 @@
+from PAWpy.Exceptions.Exceptions import (
+    PAWException,
+    PAWRestException,
+    PAWAuthenticationException,
+    PAWConfigException,
+    PAWNotFoundException,
+    PAWTimeoutException,
+)
+
+__all__ = [
+    "PAWException",
+    "PAWRestException",
+    "PAWAuthenticationException",
+    "PAWConfigException",
+    "PAWNotFoundException",
+    "PAWTimeoutException",
+]

PAWpy/Objects/Asset.py

@@ -0,0 +1,51 @@
+"""Asset — a node in the PAW content store (folder, book/dashboard, view…).
+
+Maps the properties documented for the Content Services API
+(``/pacontent/v1/Assets``): ``id``, ``type``, ``name``, ``path``,
+``description``, ``content``, ``custom_properties`` plus the read-only system
+timestamps.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from PAWpy.Objects.TM1Object import PAWObject
+
+
+class Asset(PAWObject):
+    @property
+    def id(self) -> Optional[str]:
+        return self._body.get("id")
+
+    @property
+    def type(self) -> Optional[str]:
+        return self._body.get("type")
+
+    @property
+    def name(self) -> Optional[str]:
+        return self._body.get("name")
+
+    @property
+    def path(self) -> Optional[str]:
+        return self._body.get("path")
+
+    @property
+    def description(self) -> Optional[str]:
+        return self._body.get("description")
+
+    @property
+    def content(self) -> Any:
+        return self._body.get("content")
+
+    @property
+    def custom_properties(self) -> Dict[str, Any]:
+        return self._body.get("custom_properties") or {}
+
+    @property
+    def is_folder(self) -> bool:
+        return (self._body.get("type") or "").lower() == "folder"
+
+    @property
+    def is_book(self) -> bool:
+        return (self._body.get("type") or "").lower() in ("book", "dashboard")

PAWpy/Objects/TM1Object.py

@@ -0,0 +1,29 @@
+"""Base object — a light wrapper around the raw JSON body PAW returns.
+
+Like TM1py's object layer, every concrete object keeps the original ``body``
+dict around (``raw``) so nothing the API returns is ever lost, while exposing
+the common fields as typed properties.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+
+class PAWObject:
+    def __init__(self, body: Dict[str, Any]):
+        self._body: Dict[str, Any] = dict(body or {})
+
+    @property
+    def raw(self) -> Dict[str, Any]:
+        """The untouched JSON dict PAW returned for this resource."""
+        return self._body
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self._body.get(key, default)
+
+    def __getitem__(self, key: str) -> Any:
+        return self._body[key]
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self._body!r})"

PAWpy/Objects/__init__.py

@@ -0,0 +1,4 @@
+from PAWpy.Objects.TM1Object import PAWObject
+from PAWpy.Objects.Asset import Asset
+
+__all__ = ["PAWObject", "Asset"]

PAWpy/PAWService.py

@@ -0,0 +1,99 @@
+"""PAWService — the top-level entry point (mirrors TM1py's ``TM1Service``).
+
+Construct one ``PAWService`` with connection + auth parameters and reach every
+sub-service through it::
+
+    with PAWService(host="paw.acme.com", auth_mode="oauth",
+                    client_id="id", client_secret="secret",
+                    token_url="https://idp/token") as paw:
+        books   = paw.books.get_all("/shared/FP&A")
+        url     = paw.books.get_embed_url("/shared/FP&A/Monthly Report")
+        servers = paw.admin.get_tm1_servers()
+        data    = paw.tm1("Global FPA").execute_mdx("SELECT ...")
+        embed   = paw.ui.cube_viewer_url("Global FPA", "Revenue Cube", "Monthly View")
+
+All keyword arguments are forwarded to :class:`RestService`, which performs
+authentication on construction (unless ``connect=False``).
+"""
+
+from __future__ import annotations
+
+from typing import Dict
+
+from PAWpy.Services.AdminService import AdminService, DEFAULT_ADMIN_BASE
+from PAWpy.Services.BookService import BookService
+from PAWpy.Services.ContentService import ContentService, DEFAULT_CONTENT_BASE
+from PAWpy.Services.RestService import RestService
+from PAWpy.Services.TM1ProxyService import TM1ProxyService
+from PAWpy.Services.UIService import UIService
+from PAWpy.Services.ViewService import ViewService
+
+
+class PAWService:
+    def __init__(
+        self,
+        host: str,
+        *,
+        database: str = None,
+        content_base: str = DEFAULT_CONTENT_BASE,
+        admin_base: str = DEFAULT_ADMIN_BASE,
+        **rest_kwargs,
+    ):
+        """
+        :param host: PAW hostname (no scheme), e.g. ``paw.acme.com``.
+        :param database: default TM1 database/server for :meth:`tm1` when called
+            with no argument.
+        :param content_base: base path of the content services API.
+        :param admin_base: base path of the admin API.
+        :param rest_kwargs: forwarded to :class:`RestService` (auth_mode,
+            client_id, port, ssl, verify, timeout, tenant_id, …).
+        """
+        self._default_database = database
+        self._rest = RestService(host=host, **rest_kwargs)
+
+        # Core services
+        self.content = ContentService(self._rest, content_base=content_base)
+        self.ui = UIService(self._rest)
+        self.books = BookService(self._rest, self.content, self.ui)
+        self.views = ViewService(self._rest, self.content, self.ui)
+        self.admin = AdminService(self._rest, admin_base=admin_base)
+
+        # Cache of per-database TM1 proxy services.
+        self._tm1_cache: Dict[str, TM1ProxyService] = {}
+
+    # ------------------------------------------------------------------ #
+    # TM1 proxy access
+    # ------------------------------------------------------------------ #
+    def tm1(self, database: str = None) -> TM1ProxyService:
+        """Return a :class:`TM1ProxyService` for *database* (or the default).
+
+        Instances are cached per database name so repeated calls are cheap.
+        """
+        db = database or self._default_database
+        if not db:
+            raise ValueError(
+                "No TM1 database specified and no default 'database' was set on PAWService"
+            )
+        if db not in self._tm1_cache:
+            self._tm1_cache[db] = TM1ProxyService(self._rest, db)
+        return self._tm1_cache[db]
+
+    # ------------------------------------------------------------------ #
+    # Lifecycle
+    # ------------------------------------------------------------------ #
+    @property
+    def rest(self) -> RestService:
+        return self._rest
+
+    @property
+    def base_url(self) -> str:
+        return self._rest.base_url
+
+    def logout(self) -> None:
+        self._rest.logout()
+
+    def __enter__(self) -> "PAWService":
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.logout()

PAWpy/Services/AdminService.py

@@ -0,0 +1,39 @@
+"""AdminService — PAW administration REST surface (``/api/v1/admin``).
+
+Covers the administrative endpoints exposed by recent PAW builds: the list of
+registered TM1 / database servers, users and groups. IBM documents the broad
+shape (``/api/v1/admin/...``) but the per-build resource names vary, so this
+service offers typed helpers for the common resources **and** a generic
+:meth:`get` escape hatch for anything not yet wrapped.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from PAWpy.Services.ObjectService import ObjectService
+from PAWpy.Services.RestService import RestService
+from PAWpy.Utils.Utils import odata_value_list
+
+DEFAULT_ADMIN_BASE = "/api/v1/admin"
+
+
+class AdminService(ObjectService):
+    def __init__(self, rest: RestService, admin_base: str = DEFAULT_ADMIN_BASE):
+        super().__init__(rest)
+        self._base = "/" + admin_base.strip("/")
+
+    def get(self, resource: str, params: Optional[Dict[str, Any]] = None) -> Any:
+        """Generic GET against an admin sub-resource (e.g. ``"servers"``)."""
+        resp = self._rest.GET(f"{self._base}/{resource.lstrip('/')}", params=params)
+        return resp.json()
+
+    def get_tm1_servers(self) -> List[Dict[str, Any]]:
+        """List the TM1 / database servers registered with this PAW instance."""
+        return odata_value_list(self.get("servers"))
+
+    def get_users(self) -> List[Dict[str, Any]]:
+        return odata_value_list(self.get("users"))
+
+    def get_groups(self) -> List[Dict[str, Any]]:
+        return odata_value_list(self.get("groups"))

PAWpy/Services/BookService.py

@@ -0,0 +1,43 @@
+"""BookService — convenience layer over ContentService for PAW books.
+
+A "book" is just a content asset of type ``book``/``dashboard``. This service
+filters the content store down to books and pairs each with an embed URL from
+:class:`UIService`, so the common "list the books in a folder and get an iframe
+URL" workflow is one call.
+"""
+
+from __future__ import annotations
+
+from typing import List
+
+from PAWpy.Objects.Asset import Asset
+from PAWpy.Services.ContentService import ContentService
+from PAWpy.Services.ObjectService import ObjectService
+from PAWpy.Services.RestService import RestService
+from PAWpy.Services.UIService import UIService
+
+
+class BookService(ObjectService):
+    def __init__(self, rest: RestService, content: ContentService, ui: UIService):
+        super().__init__(rest)
+        self._content = content
+        self._ui = ui
+
+    def get_all(self, folder_path: str) -> List[Asset]:
+        """List the books/dashboards directly under *folder_path*."""
+        children = self._content.list_children(folder_path)
+        return [a for a in children if a.is_book]
+
+    def get(self, path: str, expand_content: bool = False) -> Asset:
+        """Fetch a single book by content-store path."""
+        return self._content.get_by_path(path, expand_content=expand_content)
+
+    def get_embed_url(self, path: str, embed: bool = True) -> str:
+        """Build the ``/ui?type=book`` iframe URL for the book at *path*."""
+        return self._ui.book_url(path, embed=embed)
+
+    def exists(self, path: str) -> bool:
+        return self._content.exists(path)
+
+    def delete(self, path: str) -> None:
+        self._content.delete_by_path(path)

PAWpy/Services/ContentService.py

@@ -0,0 +1,142 @@
+"""ContentService — CRUD over the PAW Content Services API.
+
+Wraps the OData-style ``/pacontent/v1/Assets`` surface documented by IBM:
+
+    GET    /pacontent/v1/Assets('<id>')                  fetch by id
+    GET    /pacontent/v1/Assets(path='<path>')           fetch by path (encoded x2)
+    GET    /pacontent/v1/Assets(path='<folder>')/Assets  list children
+    POST   /pacontent/v1/Assets                          create folder / dashboard
+    PUT    /pacontent/v1/Assets(id='<id>', type='<t>')   update content / props
+    DELETE /pacontent/v1/Assets(id='<id>', type='<t>')   delete by id+type
+    DELETE /pacontent/v1/Assets(path='<path>')           delete by path
+
+Supports the OData query options ``$filter / $select / $expand / $orderby /
+$top / $skip`` via :func:`PAWpy.Utils.odata_query`.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from PAWpy.Objects.Asset import Asset
+from PAWpy.Services.ObjectService import ObjectService
+from PAWpy.Services.RestService import RestService
+from PAWpy.Utils.Utils import encode_path_twice, odata_query, odata_value_list
+
+# Default base path of the content services API. Override via the constructor
+# for deployments that expose content under a different prefix.
+DEFAULT_CONTENT_BASE = "/pacontent/v1"
+
+
+class ContentService(ObjectService):
+    def __init__(self, rest: RestService, content_base: str = DEFAULT_CONTENT_BASE):
+        super().__init__(rest)
+        self._base = "/" + content_base.strip("/")
+
+    # ------------------------------------------------------------------ #
+    # Read
+    # ------------------------------------------------------------------ #
+    def get(self, asset_id: str, expand_content: bool = False) -> Asset:
+        """Fetch a single asset by id."""
+        params = odata_query(expand="content") if expand_content else None
+        resp = self._rest.GET(f"{self._base}/Assets('{asset_id}')", params=params)
+        return Asset(resp.json())
+
+    def get_by_path(self, path: str, expand_content: bool = False) -> Asset:
+        """Fetch a single asset by its content-store path (e.g. ``/shared/FP&A``)."""
+        encoded = encode_path_twice(path)
+        params = odata_query(expand="content") if expand_content else None
+        resp = self._rest.GET(f"{self._base}/Assets(path='{encoded}')", params=params)
+        return Asset(resp.json())
+
+    def list_children(
+        self,
+        folder_path: str,
+        *,
+        filter: Optional[str] = None,
+        select: Optional[str] = None,
+        expand: Optional[str] = None,
+        orderby: Optional[str] = None,
+        top: Optional[int] = None,
+        skip: Optional[int] = None,
+    ) -> List[Asset]:
+        """List the child assets inside the folder at *folder_path*."""
+        encoded = encode_path_twice(folder_path)
+        params = odata_query(
+            filter=filter, select=select, expand=expand,
+            orderby=orderby, top=top, skip=skip,
+        )
+        resp = self._rest.GET(
+            f"{self._base}/Assets(path='{encoded}')/Assets",
+            params=params or None,
+        )
+        return [Asset(item) for item in odata_value_list(resp.json())]
+
+    # ------------------------------------------------------------------ #
+    # Create
+    # ------------------------------------------------------------------ #
+    def create(
+        self,
+        type: str,
+        name: str,
+        path: str,
+        content: Any = None,
+        custom_properties: Optional[Dict[str, Any]] = None,
+    ) -> Asset:
+        """Create a new asset (``type`` = ``folder`` or ``dashboard``)."""
+        body: Dict[str, Any] = {"type": type, "name": name, "path": path}
+        if content is not None:
+            body["content"] = content
+        if custom_properties is not None:
+            body["custom_properties"] = custom_properties
+        resp = self._rest.POST(f"{self._base}/Assets", json=body)
+        return Asset(resp.json())
+
+    def create_folder(self, name: str, path: str, **kwargs) -> Asset:
+        return self.create("folder", name, path, **kwargs)
+
+    # ------------------------------------------------------------------ #
+    # Update
+    # ------------------------------------------------------------------ #
+    def update(
+        self,
+        asset_id: str,
+        type: str,
+        content: Any = None,
+        custom_properties: Optional[Dict[str, Any]] = None,
+        expand_content: bool = True,
+    ) -> Asset:
+        """Update an asset's ``content`` and/or ``custom_properties``."""
+        body: Dict[str, Any] = {}
+        if content is not None:
+            body["content"] = content
+        if custom_properties is not None:
+            body["custom_properties"] = custom_properties
+        params = odata_query(expand="content") if expand_content else None
+        resp = self._rest.PUT(
+            f"{self._base}/Assets(id='{asset_id}', type='{type}')",
+            json=body,
+            params=params,
+        )
+        return Asset(resp.json())
+
+    # ------------------------------------------------------------------ #
+    # Delete
+    # ------------------------------------------------------------------ #
+    def delete(self, asset_id: str, type: str) -> None:
+        self._rest.DELETE(f"{self._base}/Assets(id='{asset_id}', type='{type}')")
+
+    def delete_by_path(self, path: str) -> None:
+        encoded = encode_path_twice(path)
+        self._rest.DELETE(f"{self._base}/Assets(path='{encoded}')")
+
+    # ------------------------------------------------------------------ #
+    # Convenience
+    # ------------------------------------------------------------------ #
+    def exists(self, path: str) -> bool:
+        from PAWpy.Exceptions.Exceptions import PAWNotFoundException
+        try:
+            self.get_by_path(path)
+            return True
+        except PAWNotFoundException:
+            return False

PAWpy/Services/ObjectService.py

@@ -0,0 +1,14 @@
+"""Base for every service — holds the shared RestService handle."""
+
+from __future__ import annotations
+
+from PAWpy.Services.RestService import RestService
+
+
+class ObjectService:
+    def __init__(self, rest: RestService):
+        self._rest = rest
+
+    @property
+    def rest(self) -> RestService:
+        return self._rest