feat: Add documents endpoint

Merge pull request #16 from DSD-DBS/add-documents

Author: ewuerger

.gitignore

@@ -39,6 +39,9 @@ MANIFEST
 pip-log.txt
 pip-delete-this-directory.txt
 
+# IDE
+.vscode
+
 # Unit test / coverage reports
 htmlcov/
 .tox/

polarion_rest_api_client/base_client.py

@@ -17,6 +17,7 @@ class DefaultFields:
     _workitems: str = "@basic"
     _linkedworkitems: str = "id,role,suspect"
     _workitem_attachments: str = "@basic"
+    _documents: str = "@basic"
 
     @property
     def workitems(self):
@@ -45,11 +46,23 @@ def workitem_attachments(self):
     def workitem_attachments(self, value):
         self._workitem_attachments = value
 
+    @property
+    def documents(self):
+        """Return the fields dict for document."""
+        return {"documents": self._documents}
+
+    @documents.setter
+    def documents(self, value):
+        self._documents = value
+
     @property
     def all_types(self):
         """Return all fields dicts merged together."""
         return (
-            self.workitem_attachments | self.workitems | self.linkedworkitems
+            self.workitem_attachments
+            | self.workitems
+            | self.linkedworkitems
+            | self.documents
         )
 
 

polarion_rest_api_client/client.py

@@ -10,13 +10,15 @@
 import random
 import time
 import typing as t
+import urllib.parse
 
 from polarion_rest_api_client import base_client
 from polarion_rest_api_client import data_models as dm
 from polarion_rest_api_client import errors
 from polarion_rest_api_client.open_api_client import client as oa_client
 from polarion_rest_api_client.open_api_client import models as api_models
 from polarion_rest_api_client.open_api_client import types as oa_types
+from polarion_rest_api_client.open_api_client.api.documents import get_document
 from polarion_rest_api_client.open_api_client.api.linked_work_items import (
     delete_linked_work_items,
     get_linked_work_items,
@@ -611,16 +613,20 @@ def get_work_items(
                         self._work_item(
                             work_item_id,
                             unset_str_builder(work_item.attributes.title),
-                            unset_str_builder(
-                                work_item.attributes.description.type
-                            )
-                            if work_item.attributes.description
-                            else None,
-                            unset_str_builder(
-                                work_item.attributes.description.value
-                            )
-                            if work_item.attributes.description
-                            else None,
+                            (
+                                unset_str_builder(
+                                    work_item.attributes.description.type
+                                )
+                                if work_item.attributes.description
+                                else None
+                            ),
+                            (
+                                unset_str_builder(
+                                    work_item.attributes.description.value
+                                )
+                                if work_item.attributes.description
+                                else None
+                            ),
                             unset_str_builder(work_item.attributes.type),
                             unset_str_builder(work_item.attributes.status),
                             work_item.attributes.additional_properties,
@@ -635,6 +641,89 @@ def get_work_items(
 
         return work_items, next_page
 
+    def get_document(
+        self,
+        space_id: str,
+        document_name: str,
+        fields: dict[str, str] | None = None,
+        include: str | None = None,
+        revision: str | None = None,
+        retry: bool = True,
+    ) -> dm.Document:
+        """Return the document with the given document_name and space_id."""
+
+        if " " in space_id or " " in document_name:
+            space_id = urllib.parse.quote(
+                space_id, safe="/", encoding=None, errors=None
+            )
+            document_name = urllib.parse.quote(
+                document_name, safe="/", encoding=None, errors=None
+            )
+        if fields is None:
+            fields = self.default_fields.documents
+
+        sparse_fields = _build_sparse_fields(fields)
+        response = get_document.sync_detailed(
+            self.project_id,
+            space_id,
+            document_name,
+            client=self.client,
+            fields=sparse_fields,
+            include=include,
+            revision=revision,
+        )
+
+        if not self._check_response(response, not retry) and retry:
+            sleep_random_time()
+            return self.get_document(
+                space_id, document_name, fields, include, revision, False
+            )
+
+        document_response = response.parsed
+
+        if isinstance(
+            document_response, api_models.DocumentsSingleGetResponse
+        ) and (data := document_response.data):
+            if not getattr(data.meta, "errors", []):
+                assert (attributes := data.attributes)
+                assert isinstance(data.id, str)
+                home_page_content = self._handle_home_page_content(
+                    attributes.home_page_content
+                )
+
+                document: dm.Document = dm.Document(
+                    id=data.id,
+                    module_folder=unset_str_builder(attributes.module_folder),
+                    module_name=unset_str_builder(attributes.module_name),
+                    type=unset_str_builder(attributes.type),
+                    status=unset_str_builder(attributes.status),
+                    home_page_content=home_page_content,
+                )
+        return document
+
+    def _handle_home_page_content(
+        self,
+        home_page_content: api_models.DocumentsSingleGetResponseDataAttributesHomePageContent
+        | oa_types.Unset,
+    ) -> dm.TextContent | None:
+        if isinstance(home_page_content, oa_types.Unset):
+            return None
+
+        home_page_content_type = None
+        home_page_content_value = None
+
+        if isinstance(
+            home_page_content.type,
+            api_models.DocumentsSingleGetResponseDataAttributesHomePageContentType,
+        ):
+            home_page_content_type = str(home_page_content.type)
+        if isinstance(home_page_content.value, str):
+            home_page_content_value = home_page_content.value
+        return dm.TextContent(
+            type=home_page_content_type,
+            value=home_page_content_value,
+        )
+
     def create_work_items(self, work_items: list[base_client.WorkItemType]):
         """Create the given list of work items."""
         current_batch = api_models.WorkitemsListPostRequest([])

polarion_rest_api_client/data_models.py

@@ -10,19 +10,68 @@
 import typing as t
 
 
-class WorkItem:
-    """A data class containing all relevant data of a Polarion WorkItem."""
+@dataclasses.dataclass
+class BaseItem:
+    """A parent data class for WorkItem and Document."""
 
     id: str | None = None
+    type: str | None = None
+    status: str | None = None
+    _checksum: str | None = dataclasses.field(init=False, default=None)
+
+    def __post_init__(self):
+        """Set initial checksum value."""
+        self._checksum = self.calculate_checksum()
+
+    def __eq__(self, other: object) -> bool:
+        """Compare only BaseItem attributes."""
+        if not isinstance(other, BaseItem):
+            return NotImplemented
+        if self.get_current_checksum() is None:
+            self.calculate_checksum()
+        if other.get_current_checksum() is None:
+            other.calculate_checksum()
+
+        return self.get_current_checksum() == other.get_current_checksum()
+
+    def to_dict(self) -> dict[str, t.Any]:
+        """Return the content of the BaseItem as dictionary."""
+        return {
+            "id": self.id,
+            "type": self.type,
+            "status": self.status,
+            "checksum": self._checksum,
+        }
+
+    def calculate_checksum(self) -> str:
+        """Calculate and return a checksum for this BaseItem.
+
+        In addition, the checksum will be written to self._checksum.
+        """
+        data = self.to_dict()
+        del data["checksum"]
+        del data["id"]
+
+        data = dict(sorted(data.items()))
+
+        converted = json.dumps(data).encode("utf8")
+        self._checksum = hashlib.sha256(converted).hexdigest()
+        return self._checksum
+
+    def get_current_checksum(self) -> str | None:
+        """Return the checksum currently set without calculation."""
+        return self._checksum
+
+
+class WorkItem(BaseItem):
+    """A data class containing all relevant data of a Polarion WorkItem."""
+
     title: str | None = None
     description_type: str | None = None
     description: str | None = None
-    type: str | None = None
-    status: str | None = None
     additional_attributes: dict[str, t.Any] = {}
     linked_work_items: list[WorkItemLink] = []
     attachments: list[WorkItemAttachment] = []
-    _checksum: str | None = None
 
     def __init__(
         self,
@@ -37,14 +86,11 @@ def __init__(
         attachments: list[WorkItemAttachment] | None = None,
         **kwargs,
     ):
-        self.id = id
+        super().__init__(id, type, status)
         self.title = title
         self.description_type = description_type
         self.description = description
-        self.type = type
-        self.status = status
         self.additional_attributes = (additional_attributes or {}) | kwargs
-        self._checksum = self.additional_attributes.pop("checksum", None)
         self.linked_work_items = linked_work_items or []
         self.attachments = attachments or []
 
@@ -125,10 +171,6 @@ def calculate_checksum(self) -> str:
         self._checksum = hashlib.sha256(converted).hexdigest()
         return self._checksum
 
-    def get_current_checksum(self) -> str | None:
-        """Return the checksum currently set without calculation."""
-        return self._checksum
-
 
 @dataclasses.dataclass
 class WorkItemLink:
@@ -157,3 +199,33 @@ class WorkItemAttachment:
     content_bytes: bytes | None = None
     mime_type: str | None = None
     file_name: str | None = None
+
+
+class Document(BaseItem):
+    """A data class containing all relevant data of a Polarion Document."""
+
+    module_folder: str | None = None
+    module_name: str | None = None
+    home_page_content: TextContent | None = None
+
+    def __init__(
+        self,
+        id: str | None = None,
+        module_folder: str | None = None,
+        module_name: str | None = None,
+        type: str | None = None,
+        status: str | None = None,
+        home_page_content: TextContent | None = None,
+    ):
+        super().__init__(id, type, status)
+        self.module_folder = module_folder
+        self.module_name = module_name
+        self.home_page_content = home_page_content
+
+
+@dataclasses.dataclass
+class TextContent:
+    """A data class for home_page_content of a Polarion Document."""
+
+    type: str | None = None
+    value: str | None = None

tests/__init__.py

@@ -59,7 +59,7 @@
     TEST_RESPONSES / "workitems_next_page_error.json"
 )
 TEST_WI_NEXT_PAGE_RESPONSE = TEST_RESPONSES / "workitems_next_page.json"
-
+TEST_DOCUMENT_RESPONSE = TEST_RESPONSES / "get_document.json"
 TEST_ERROR_RESPONSE = TEST_RESPONSES / "error.json"
 TEST_PROJECT_RESPONSE_JSON = TEST_RESPONSES / "project.json"
 

tests/data/mock_api_responses/get_document.json

@@ -0,0 +1,36 @@
+{
+    "data": {
+        "attributes": {
+            "autoSuspect": {},
+            "branchedWithQuery": {},
+            "derivedFromLinkRole": {},
+            "created": "1970-01-01T00:00:00Z",
+            "homePageContent": {
+                "type": "text/html",
+                "value": "<h1>My text value</h1>"
+            },
+            "moduleFolder": "MySpaceId",
+            "moduleName": "MyDocumentName",
+            "outlineNumbering": {},
+            "renderingLayouts": [],
+            "status": "open",
+            "structureLinkRole": "parent",
+            "title": "MyDocumentName",
+            "type": "standardSpecification",
+            "updated": "1970-01-01T00:00:00Z",
+            "usesOutlineNumbering": true
+        },
+        "id": "MyProjectId/MySpaceId/MyDocumentName",
+        "links": {
+            "self": "server-host-name/application-path/projects/MyProjectId/spaces/MySpaceId/documents/MyDocumentName"
+        },
+        "meta": {},
+        "relationships": {},
+        "revision": {},
+        "type": "documents"
+    },
+    "included": [],
+    "links": {
+        "self": "server-host-name/application-path/projects/MyProjectId/spaces/MySpaceId/documents/MyDocumentName"
+    }
+}

tests/data/mock_api_responses/get_document.json.license

@@ -0,0 +1,2 @@
+Copyright DB Netz AG and contributors
+SPDX-License-Identifier: Apache-2.0