pyPreservica 2.0.3__py3-none-any.whl → 3.3.3__py3-none-any.whl

pyPreservica/retentionAPI.py

@@ -9,9 +9,8 @@ licence:    Apache License 2.0
 
 """
 
-
 import xml.etree.ElementTree
-from typing import Set
+from typing import Set, Callable
 
 from pyPreservica.common import *
 
@@ -59,8 +58,10 @@ class RetentionPolicy:
 class RetentionAPI(AuthenticatedAPI):
 
     def __init__(self, username=None, password=None, tenant=None, server=None, use_shared_secret=False,
-                 two_fa_secret_key: str = None, protocol: str = "https"):
-        super().__init__(username, password, tenant, server, use_shared_secret, two_fa_secret_key, protocol)
+                 two_fa_secret_key: str = None, protocol: str = "https", request_hook: Callable = None, credentials_path: str = 'credentials.properties'):
+        super().__init__(username, password, tenant, server, use_shared_secret, two_fa_secret_key,
+                         protocol, request_hook, credentials_path)
+
         if self.major_version < 7 and self.minor_version < 2:
             raise RuntimeError("Retention API is only available when connected to a v6.2 System")
 
@@ -76,7 +77,8 @@ class RetentionAPI(AuthenticatedAPI):
 
          """
         headers = {HEADER_TOKEN: self.token, 'Content-Type': 'application/xml;charset=UTF-8'}
-        request = self.session.get(f'{self.protocol}://{self.server}/api/entity/retention-policies/{reference}', headers=headers)
+        request = self.session.get(f'{self.protocol}://{self.server}/api/entity/retention-policies/{reference}',
+                                   headers=headers)
         if request.status_code == requests.codes.ok:
             xml_response = str(request.content.decode('utf-8'))
             logger.debug(xml_response)
@@ -90,14 +92,22 @@ class RetentionAPI(AuthenticatedAPI):
             security_tag = entity_response.find(f'.//{{{self.rm_ns}}}RetentionPolicy/{{{self.rm_ns}}}SecurityTag').text
             rp.security_tag = security_tag
             start_date_field = entity_response.find(
-                f'.//{{{self.rm_ns}}}RetentionPolicy/{{{self.rm_ns}}}StartDateField').text
-            rp.start_date_field = start_date_field
-            period = entity_response.find(f'.//{{{self.rm_ns}}}RetentionPolicy/{{{self.rm_ns}}}Period').text
-            rp.period = period
-            period_unit = entity_response.find(f'.//{{{self.rm_ns}}}RetentionPolicy/{{{self.rm_ns}}}PeriodUnit').text
-            rp.period_unit = period_unit
-            expiry_action = entity_response.find(
-                f'.//{{{self.rm_ns}}}RetentionPolicy/{{{self.rm_ns}}}ExpiryAction')
+                f'.//{{{self.rm_ns}}}RetentionPolicy/{{{self.rm_ns}}}StartDateField')
+            if start_date_field is not None:
+                rp.start_date_field = start_date_field.text
+            else:
+                rp.start_date_field = None
+            period = entity_response.find(f'.//{{{self.rm_ns}}}RetentionPolicy/{{{self.rm_ns}}}Period')
+            if period is not None:
+                rp.period = period.text
+            else:
+                rp.period = None
+            period_unit = entity_response.find(f'.//{{{self.rm_ns}}}RetentionPolicy/{{{self.rm_ns}}}PeriodUnit')
+            if period_unit is not None:
+                rp.period_unit = period_unit.text
+            else:
+                rp.period_unit = None
+            expiry_action = entity_response.find(f'.//{{{self.rm_ns}}}RetentionPolicy/{{{self.rm_ns}}}ExpiryAction')
             if expiry_action is not None:
                 rp.expiry_action = expiry_action.text
             else:
@@ -132,8 +142,9 @@ class RetentionAPI(AuthenticatedAPI):
         """
         headers = {HEADER_TOKEN: self.token, 'Content-Type': 'text/plain;charset=UTF-8'}
         data = str(status)
-        request = self.session.put(f'{self.protocol}://{self.server}/api/entity/retention-policies/{reference}/assignable',
-                                   headers=headers, data=data)
+        request = self.session.put(
+            f'{self.protocol}://{self.server}/api/entity/retention-policies/{reference}/assignable',
+            headers=headers, data=data)
         if request.status_code == requests.codes.ok:
             pass
         elif request.status_code == requests.codes.unauthorized:
@@ -228,7 +239,8 @@ class RetentionAPI(AuthenticatedAPI):
 
         xml_request = xml.etree.ElementTree.tostring(retention_policy, encoding='utf-8')
 
-        request = self.session.put(f'{self.protocol}://{self.server}/api/entity/retention-policies/{reference}', data=xml_request,
+        request = self.session.put(f'{self.protocol}://{self.server}/api/entity/retention-policies/{reference}',
+                                   data=xml_request,
                                    headers=headers)
         if request.status_code == requests.codes.ok:
             return self.policy(reference)
@@ -372,7 +384,8 @@ class RetentionAPI(AuthenticatedAPI):
          """
         headers = {HEADER_TOKEN: self.token, 'Content-Type': 'application/xml;charset=UTF-8'}
         data = {'start': str(0), 'max': "250"}
-        request = self.session.get(f'{self.protocol}://{self.server}/api/entity/retention-policies', data=data, headers=headers)
+        request = self.session.get(f'{self.protocol}://{self.server}/api/entity/retention-policies', data=data,
+                                   headers=headers)
         if request.status_code == requests.codes.ok:
             xml_response = str(request.content.decode('utf-8'))
             logger.debug(xml_response)
@@ -388,10 +401,10 @@ class RetentionAPI(AuthenticatedAPI):
         else:
             raise RuntimeError(request.status_code, "policies failed")
 
-    def policies(self) -> Set[RetentionPolicy]:
+    def policies(self, maximum: int = 250, next_page: str = None) -> PagedSet:
         """
         Return a list of all retention policies
-        Only returns the first 250 policies in the system
+        Returns a maximum of 250 policies by default
 
 
         :return: Set of retention policies
@@ -399,22 +412,33 @@ class RetentionAPI(AuthenticatedAPI):
 
         """
         headers = {HEADER_TOKEN: self.token, 'Content-Type': 'application/xml;charset=UTF-8'}
-        data = {'start': str(0), 'max': "250"}
-        request = self.session.get(f'{self.protocol}://{self.server}/api/entity/retention-policies', data=data, headers=headers)
+
+        if next_page is None:
+            params = {'start': '0', 'max': str(maximum)}
+            request = self.session.get(f'{self.protocol}://{self.server}/api/entity/retention-policies', params=params,
+                                       headers=headers)
+        else:
+            request = self.session.get(next_page, headers=headers)
+
         if request.status_code == requests.codes.ok:
             xml_response = str(request.content.decode('utf-8'))
             entity_response = xml.etree.ElementTree.fromstring(xml_response)
             logger.debug(xml_response)
             result = set()
+            next_url = entity_response.find(f'.//{{{self.entity_ns}}}Paging/{{{self.entity_ns}}}Next')
             total_results = int(entity_response.find(
                 f'.//{{{self.entity_ns}}}TotalResults').text)
-            if total_results > 250:
-                logger.error("Not all retention policies have been returned.")
             for assignment in entity_response.findall(f'.//{{{self.entity_ns}}}RetentionPolicy'):
                 ref = assignment.attrib['ref']
                 name = assignment.attrib['name']
                 result.add(self.policy(reference=ref))
-            return result
+            has_more = True
+            url = None
+            if next_url is None:
+                has_more = False
+            else:
+                url = next_url.text
+            return PagedSet(result, has_more, total_results, url)
         elif request.status_code == requests.codes.unauthorized:
             self.token = self.__token__()
             return self.policies()
@@ -453,7 +477,11 @@ class RetentionAPI(AuthenticatedAPI):
             api_id = entity_response.find(f'.//{{{self.rm_ns}}}ApiId').text
             policy_ref = entity_response.find(f'.//{{{self.rm_ns}}}RetentionPolicy').text
             entity_ref = entity_response.find(f'.//{{{self.rm_ns}}}Entity').text
-            start_date = entity_response.find(f'.//{{{self.rm_ns}}}StartDate').text
+            start_date = entity_response.find(f'.//{{{self.rm_ns}}}StartDate')
+            if start_date is not None:
+                start_date = start_date.text
+            else:
+                start_date = None
             assert entity_ref == entity.reference
             assert policy_ref == policy.reference
             return RetentionAssignment(entity_ref, policy_ref, api_id, start_date)
@@ -514,7 +542,11 @@ class RetentionAPI(AuthenticatedAPI):
                 entity_ref = assignment.find(f'.//{{{self.rm_ns}}}Entity').text
                 assert entity_ref == entity.reference
                 policy = assignment.find(f'.//{{{self.rm_ns}}}RetentionPolicy').text
-                start_date = assignment.find(f'.//{{{self.rm_ns}}}StartDate').text
+                start_date = assignment.find(f'.//{{{self.rm_ns}}}StartDate')
+                if start_date is not None:
+                    start_date = start_date.text
+                else:
+                    start_date = None
                 expired = bool(assignment.find(f'.//{{{self.rm_ns}}}Expired').text == 'true')
                 api_id = assignment.find(f'.//{{{self.rm_ns}}}ApiId').text
                 ra = RetentionAssignment(entity_ref, policy, api_id, start_date, expired)

pyPreservica/settingsAPI.py

@@ -0,0 +1,295 @@
+"""
+pyPreservica Settings API  module definition
+
+API for retrieving information about configuration settings.
+
+author:     James Carr
+licence:    Apache License 2.0
+
+"""
+
+from typing import Callable
+
+from pyPreservica.common import *
+
+logger = logging.getLogger(__name__)
+
+
+class SettingsAPI(AuthenticatedAPI):
+    """
+    API for retrieving information about configuration settings.
+
+    Includes  methods for:
+
+    *  metadata-enrichment
+
+    """
+
+    def __init__(
+        self,
+        username=None,
+        password=None,
+        tenant=None,
+        server=None,
+        use_shared_secret=False,
+        two_fa_secret_key: str = None,
+        protocol: str = "https",
+        request_hook: Callable = None,
+        credentials_path: str = "credentials.properties",
+    ):
+        super().__init__(
+            username,
+            password,
+            tenant,
+            server,
+            use_shared_secret,
+            two_fa_secret_key,
+            protocol,
+            request_hook,
+            credentials_path,
+        )
+
+        if self.major_version < 7 and self.minor_version < 7:
+            raise RuntimeError(
+                "Settings API is only available when connected to a v7.7 System or higher"
+            )
+
+        self.base_url = "api/settings"
+
+    def metadata_enrichment_rules(self, profile_id: str = None) -> dict:
+        """
+        Returns a list of metadata enrichment rules.
+        An empty selection implies that the rule is applied to all content.
+        Rules define where particular behaviours, defined by profiles, will be applied.
+        Rules are evaluated in order, with the first matching rule being applied.
+
+        :param profile_id: The rules for a specific profile id, Set to None for all rules
+        :type profile_id: str
+
+        """
+        headers = {
+            HEADER_TOKEN: self.token,
+            "Accept": "application/json",
+            "Content-Type": "application/json;charset=UTF-8",
+        }
+
+        endpoint: str = "/metadata-enrichment/config/rules"
+
+        request = self.session.get(
+            f"{self.protocol}://{self.server}/{self.base_url}{endpoint}",
+            headers=headers)
+
+        if request.status_code == requests.codes.ok:
+            rules: dict = json.loads(request.content.decode("utf-8"))
+            if profile_id is None:
+                return rules
+            else:
+                profile_rules = []
+                for rule in rules["rules"]:
+                    if rule["profileId"] == profile_id:
+                        profile_rules.append(rule)
+                return {"rules": profile_rules}
+        else:
+            logger.debug(request.content.decode("utf-8"))
+            raise RuntimeError(request.status_code, f"metadata_enrichment_rules failed")
+
+    def metadata_enrichment_delete_rule(self, rule_id: str):
+        """
+        Deletes a metadata enrichment rule.
+
+        :param rule_id: The rule id
+        :type rule_id: str
+
+        :return: No return value
+        :rtype: None
+
+        """
+        headers = {
+            HEADER_TOKEN: self.token,
+            "Accept": "application/json",
+            "Content-Type": "application/json;charset=UTF-8",
+        }
+
+        endpoint: str = f"/metadata-enrichment/config/rules/{rule_id}"
+
+        request = self.session.delete(
+            f"{self.protocol}://{self.server}/{self.base_url}{endpoint}", headers=headers)
+
+        if request.status_code == requests.codes.no_content:
+            return
+        else:
+            logger.debug(request.content.decode("utf-8"))
+            raise RuntimeError(request.status_code, f"metadata_enrichment_delete_rule failed")
+
+    def metadata_enrichment_add_rule(self, profile_id: str, priority: int = 1):
+        """
+        Create a metadata enrichment rule to control when metadata enrichment profiles are applied and return it.
+        Rules define where particular behaviours, defined by profiles, will be applied.
+        Rules are evaluated in order, with the first matching rule being applied.
+        Note that not specifying, or specifying an empty selection implies that the rule will be applied to all content.
+        Currently only securityDescriptorSelector, representationSelector and hierarchySelector are supported selectors.
+        If a rule already exists for the requested priority, existing rules will be shifted down priority to accommodate the new entry.
+
+        :param profile_id: The profile id
+        :type profile_id: str
+
+        :param priority: The rule priority
+        :type priority: int
+
+        :return: The metadata enrichment rule
+        :rtype: dict
+        """
+
+        headers = {
+            HEADER_TOKEN: self.token,
+            "Accept": "application/json",
+            "Content-Type": "application/json;charset=UTF-8",
+        }
+
+        endpoint: str = "/metadata-enrichment/config/rules"
+
+        rule: dict = {
+            "profileId": profile_id,
+            "priority": str(priority),
+            "selectorSettings": {},
+        }
+
+        request = self.session.post(
+            f"{self.protocol}://{self.server}/{self.base_url}/{endpoint}",
+            headers=headers,
+            json=rule,
+        )
+        if request.status_code == requests.codes.created:
+            return json.loads(request.content.decode("utf-8"))
+        else:
+            logger.debug(request.content.decode("utf-8"))
+            raise RuntimeError(
+                request.status_code, f"metadata_enrichment_add_rule failed"
+            )
+
+    def metadata_enrichment_add_profile(self, name: str, active: bool = True):
+        """
+        Create a metadata enrichment profile to control automatic metadata enrichment of content and return it.
+        Profiles define a set of behaviours that will be applied when the profile is selected by a rule.
+        A profile has no effect if it is not used by a rule. Includes settings for PII identification.
+        PII detection tools may be run against the full text extracted from content.
+
+
+        :param name: The profile name
+        :type name: str
+
+        :param active: The profile active status
+        :type active: bool
+
+        :return: The metadata enrichment profile
+        :rtype: dict
+
+        """
+
+        headers = {
+            HEADER_TOKEN: self.token,
+            "Accept": "application/json",
+            "Content-Type": "application/json;charset=UTF-8",
+        }
+
+        endpoint: str = "/metadata-enrichment/config/profiles"
+
+        profile: dict = {"name": name, "piiSettings": {"active": str(active).lower()}}
+
+        request = self.session.post(
+            f"{self.protocol}://{self.server}/{self.base_url}{endpoint}",
+            headers=headers, json=profile)
+
+        if request.status_code == requests.codes.created:
+            return json.loads(request.content.decode("utf-8"))
+        else:
+            logger.debug(request.content.decode("utf-8"))
+            raise RuntimeError(request.status_code, f"metadata_enrichment_add_profile failed")
+
+    def metadata_enrichment_profile(self, profile_id: str) -> dict:
+        """
+        Returns a single profile by its ID
+        Profiles define a set of behaviours that will be applied when the profile is selected by a rule.
+        A profile has no effect if it is not used by a rule. Includes settings for PII identification.
+        PII detection tools may be run against the full text extracted from content.
+
+        :param profile_id: The profile name
+        :type profile_id: str
+
+        :return: The metadata enrichment profile
+        :rtype: dict
+
+        """
+        headers = {
+            HEADER_TOKEN: self.token,
+            "Accept": "application/json",
+            "Content-Type": "application/json;charset=UTF-8",
+        }
+
+        endpoint: str = f"/metadata-enrichment/config/profiles/{profile_id}"
+
+        request = self.session.get(
+            f"{self.protocol}://{self.server}/{self.base_url}{endpoint}", headers=headers)
+
+        if request.status_code == requests.codes.ok:
+            return json.loads(request.content.decode("utf-8"))
+        else:
+            logger.debug(request.content.decode("utf-8"))
+            raise RuntimeError(request.status_code, f"metadata_enrichment_profile failed")
+
+    def metadata_enrichment_delete_profile(self, profile_id: str) -> None:
+        """
+        Deletes a metadata enrichment profile
+
+        :param profile_id: The profile name
+        :type profile_id: str
+
+        :return: No return value
+        :rtype: None
+
+        """
+        headers = {
+            HEADER_TOKEN: self.token,
+            "Accept": "application/json",
+            "Content-Type": "application/json;charset=UTF-8",
+        }
+
+        endpoint: str = f"/metadata-enrichment/config/profiles/{profile_id}"
+
+        request = self.session.delete(
+            f"{self.protocol}://{self.server}/{self.base_url}{endpoint}", headers=headers)
+
+        if request.status_code == requests.codes.forbidden:
+            logger.debug(request.content.decode("utf-8"))
+            raise RuntimeError(request.status_code, f"Can't delete a profile with rules assigned")
+
+        if request.status_code == requests.codes.no_content:
+            return
+        else:
+            logger.debug(request.content.decode("utf-8"))
+            raise RuntimeError(request.status_code, f"metadata_enrichment_delete_profile failed")
+
+    def metadata_enrichment_profiles(self) -> dict:
+        """
+        Returns the list of all metadata enrichment profiles.
+        Profiles define a set of behaviours that will be applied when the profile is selected by a rule.
+        A profile has no effect if it is not used by a rule. Includes settings for PII identification.
+        PII detection tools may be run against the full text extracted from content.
+        """
+
+        headers = {
+            HEADER_TOKEN: self.token,
+            "Accept": "application/json",
+            "Content-Type": "application/json;charset=UTF-8",
+        }
+
+        endpoint: str = "/metadata-enrichment/config/profiles"
+
+        request = self.session.get(
+            f"{self.protocol}://{self.server}/{self.base_url}{endpoint}", headers=headers)
+
+        if request.status_code == requests.codes.ok:
+            return json.loads(request.content.decode("utf-8"))
+        else:
+            logger.debug(request.content.decode("utf-8"))
+            raise RuntimeError(request.status_code, f"metadata_enrichment_profiles failed")