pyPreservica 2.7.2__py3-none-any.whl → 3.3.4__py3-none-any.whl

pyPreservica/__init__.py

@@ -6,23 +6,35 @@ author:     James Carr
 licence:    Apache License 2.0
 
 """
+
 from .common import *
-from .contentAPI import ContentAPI
+from .contentAPI import ContentAPI, Field, SortOrder
 from .entityAPI import EntityAPI
-from .uploadAPI import UploadAPI, simple_asset_package, complex_asset_package, cvs_to_xsd, cvs_to_xml, \
-                    cvs_to_cmis_xslt, csv_to_search_xml, generic_asset_package, upload_config, multi_asset_package
+from .uploadAPI import (
+    UploadAPI,
+    simple_asset_package,
+    complex_asset_package,
+    cvs_to_xsd,
+    cvs_to_xml,
+    cvs_to_cmis_xslt,
+    csv_to_search_xml,
+    generic_asset_package,
+    upload_config,
+    multi_asset_package,
+)
 from .workflowAPI import WorkflowAPI, WorkflowContext, WorkflowInstance
 from .retentionAPI import RetentionAPI, RetentionAssignment, RetentionPolicy
 from .parAPI import PreservationActionRegistry
 from .adminAPI import AdminAPI
 from .monitorAPI import MonitorAPI, MonitorCategory, MonitorStatus, MessageStatus
-from .webHooksAPI import WebHooksAPI, TriggerType, WebHookHandler
+from .webHooksAPI import WebHooksAPI, TriggerType, WebHookHandler, FlaskWebhookHandler
 from .authorityAPI import AuthorityAPI, Table
-from .mdformsAPI import MDFormsAPI
+from .mdformsAPI import MetadataGroupsAPI, Group, GroupField, GroupFieldType
+from .settingsAPI import SettingsAPI
 
 __author__ = "James Carr (drjamescarr@gmail.com)"
 
 # Version of the pyPreservica package
-__version__ = "2.7.2"
+__version__ = "3.3.4"
 
 __license__ = "Apache License Version 2.0"

pyPreservica/adminAPI.py

@@ -10,7 +10,7 @@ licence:    Apache License 2.0
 """
 import csv
 import xml.etree.ElementTree
-from typing import List, Any
+from typing import List, Any, Union
 
 from pyPreservica.common import *
 
@@ -36,7 +36,7 @@ class AdminAPI(AuthenticatedAPI):
         request = self.session.delete(f'{self.protocol}://{self.server}/api/admin/security/roles/{role_name}',
                                       headers=headers)
         if request.status_code == requests.codes.no_content:
-            return
+            return None
         elif request.status_code == requests.codes.unauthorized:
             self.token = self.__token__()
             return self.delete_system_role(role_name)
@@ -61,7 +61,7 @@ class AdminAPI(AuthenticatedAPI):
         request = self.session.delete(f'{self.protocol}://{self.server}/api/admin/security/tags/{tag_name}',
                                       headers=headers)
         if request.status_code == requests.codes.no_content:
-            return
+            return None
         elif request.status_code == requests.codes.unauthorized:
             self.token = self.__token__()
             return self.delete_security_tag(tag_name)
@@ -211,7 +211,7 @@ class AdminAPI(AuthenticatedAPI):
         headers = {HEADER_TOKEN: self.token, 'Content-Type': 'application/xml;charset=UTF-8'}
         request = self.session.delete(f'{self.protocol}://{self.server}/api/admin/users/{username}', headers=headers)
         if request.status_code == requests.codes.no_content:
-            return
+            return None
         elif request.status_code == requests.codes.unauthorized:
             self.token = self.__token__()
             return self.delete_user(username)
@@ -251,8 +251,9 @@ class AdminAPI(AuthenticatedAPI):
             xml.etree.ElementTree.SubElement(xml_roles, "Role").text = role
         xml_request = xml.etree.ElementTree.tostring(xml_object, encoding='utf-8')
         logger.debug(xml_request)
+        params = {"source": "UX2"}
         request = self.session.post(f'{self.protocol}://{self.server}/api/admin/users', data=xml_request,
-                                    headers=headers)
+                                    headers=headers, params=params)
         if request.status_code == requests.codes.created:
             return self.user_details(username)
         elif request.status_code == requests.codes.unauthorized:
@@ -444,7 +445,7 @@ class AdminAPI(AuthenticatedAPI):
         :param xml_data: The xml schema as a UTF-8 string or a file like object
         :type xml_data: Any
 
-        :return: None
+        :return:
         :rtype: None
         """
 
@@ -463,7 +464,7 @@ class AdminAPI(AuthenticatedAPI):
                                     params=params,
                                     data=xml_data)
         if request.status_code == requests.codes.created:
-            return
+            return None
         elif request.status_code == requests.codes.unauthorized:
             self.token = self.__token__()
             return self.add_xml_schema(name, description, originalName, xml_data)
@@ -493,7 +494,7 @@ class AdminAPI(AuthenticatedAPI):
         :param document_type: The type of the XML document, defaults to descriptive metadata templates
         :type document_type: str
 
-        :return: None
+        :return:
         :rtype: None
 
         """
@@ -513,7 +514,7 @@ class AdminAPI(AuthenticatedAPI):
                                     params=params,
                                     data=xml_data)
         if request.status_code == requests.codes.created:
-            return
+            return None
         elif request.status_code == requests.codes.unauthorized:
             self.token = self.__token__()
             return self.add_xml_document(name, xml_data, document_type)
@@ -523,12 +524,12 @@ class AdminAPI(AuthenticatedAPI):
 
     def delete_xml_document(self, uri: str):
         """
-        Delete a XML document from Preservica
+        Delete an XML document from Preservica's XML document store
 
         :param uri: The URI of the xml document to delete
         :type uri: str
 
-        :return: None
+        :return:
         :rtype: None
 
         """
@@ -543,13 +544,14 @@ class AdminAPI(AuthenticatedAPI):
                     f"{self.protocol}://{self.server}/api/admin/documents/{document['ApiId']}",
                     headers=headers)
                 if request.status_code == requests.codes.no_content:
-                    return
+                    return None
                 elif request.status_code == requests.codes.unauthorized:
                     self.token = self.__token__()
                     return self.delete_xml_document(uri)
                 else:
                     logger.error(request.content.decode('utf-8'))
                     raise RuntimeError(request.status_code, "delete_xml_document failed")
+        return None
 
     def delete_xml_schema(self, uri: str):
         """
@@ -558,7 +560,7 @@ class AdminAPI(AuthenticatedAPI):
         :param uri: The URI of the xml schema to delete
         :type uri: str
 
-        :return: None
+        :return:
         :rtype: None
 
         """
@@ -572,17 +574,18 @@ class AdminAPI(AuthenticatedAPI):
                 request = self.session.delete(f"{self.protocol}://{self.server}/api/admin/schemas/{schema['ApiId']}",
                                               headers=headers)
                 if request.status_code == requests.codes.no_content:
-                    return
+                    return None
                 elif request.status_code == requests.codes.unauthorized:
                     self.token = self.__token__()
                     return self.delete_xml_schema(uri)
                 else:
                     logger.error(request.content.decode('utf-8'))
                     raise RuntimeError(request.status_code, "delete_xml_schema failed")
+        return None
 
-    def xml_schema(self, uri: str) -> str:
+    def xml_schema(self, uri: str) -> Union[str, None]:
         """
-         fetch the metadata schema XSD document as a string by its URI
+         Fetch the metadata schema XSD document as a string by its URI
 
         :param uri: The URI of the xml schema
         :type uri: str
@@ -607,8 +610,9 @@ class AdminAPI(AuthenticatedAPI):
                 else:
                     logger.error(request.content.decode('utf-8'))
                     raise RuntimeError(request.status_code, "xml_schema failed")
+        return None
 
-    def xml_document(self, uri: str) -> str:
+    def xml_document(self, uri: str) -> Union[str, None]:
         """
         fetch the metadata XML document as a string by its URI
 
@@ -634,6 +638,7 @@ class AdminAPI(AuthenticatedAPI):
                 else:
                     logger.error(request.content.decode('utf-8'))
                     raise RuntimeError(request.status_code, "xml_document failed")
+        return None
 
     def xml_documents(self) -> List:
         """
@@ -754,7 +759,7 @@ class AdminAPI(AuthenticatedAPI):
             logger.error(request.content.decode('utf-8'))
             raise RuntimeError(request.status_code, "xml_transforms failed")
 
-    def xml_transform(self, input_uri: str, output_uri: str) -> str:
+    def xml_transform(self, input_uri: str, output_uri: str) -> Union[str, None]:
         """
         fetch the XML transform as a string by its URIs
 
@@ -782,6 +787,7 @@ class AdminAPI(AuthenticatedAPI):
                 else:
                     logger.error(request.content.decode('utf-8'))
                     raise RuntimeError(request.status_code, "xml_transform failed")
+        return None
 
     def delete_xml_transform(self, input_uri: str, output_uri: str):
         """
@@ -793,7 +799,7 @@ class AdminAPI(AuthenticatedAPI):
         :param output_uri: The URI of the output XML document
         :type output_uri: str
 
-        :return: None
+        :return:
         :rtype: None
 
         """
@@ -808,13 +814,14 @@ class AdminAPI(AuthenticatedAPI):
                     f"{self.protocol}://{self.server}/api/admin/transforms/{transform['ApiId']}",
                     headers=headers)
                 if request.status_code == requests.codes.no_content:
-                    return
+                    return None
                 elif request.status_code == requests.codes.unauthorized:
                     self.token = self.__token__()
                     return self.delete_xml_transform(input_uri, output_uri)
                 else:
                     logger.error(request.content.decode('utf-8'))
                     raise RuntimeError(request.status_code, "delete_xml_transform failed")
+        return None
 
     def add_xml_transform(self, name: str, input_uri: str, output_uri: str, purpose: str, originalName: str,
                           xml_data: Any):
@@ -839,7 +846,7 @@ class AdminAPI(AuthenticatedAPI):
         :param xml_data: The transform xml as a string or file like object
         :type xml_data: Any
 
-        :return: None
+        :return:
         :rtype: None
 
         """
@@ -860,7 +867,7 @@ class AdminAPI(AuthenticatedAPI):
                                     params=params,
                                     data=xml_data)
         if request.status_code == requests.codes.created:
-            return
+            return None
 
         if request.status_code == requests.codes.unauthorized:
             self.token = self.__token__()

pyPreservica/authorityAPI.py

@@ -8,9 +8,8 @@ author:     James Carr
 licence:    Apache License 2.0
 
 """
-import json
+
 import csv
-import requests
 from typing import List, Set
 
 from pyPreservica.common import *
@@ -55,7 +54,7 @@ class AuthorityAPI(AuthenticatedAPI):
             self.token = self.__token__()
             return self.delete_record(reference)
         if response.status_code == requests.codes.no_content:
-            return
+            return None
         else:
             exception = HTTPException("", response.status_code, response.url, "delete_record",
                                       response.content.decode('utf-8'))
@@ -92,7 +91,7 @@ class AuthorityAPI(AuthenticatedAPI):
          :param table:    The Table to add the record to
          :type: table:    Table
 
-         :param record:    The record
+         :param record:    The record as a dictionary
          :type: record:    dict
 
          :return: A single record
@@ -123,7 +122,7 @@ class AuthorityAPI(AuthenticatedAPI):
         """
          Return a record by its reference
 
-         :param reference:    The record reference
+         :param reference:    The reference of the record
          :type: reference:    str
 
          :return: A single record
@@ -149,7 +148,7 @@ class AuthorityAPI(AuthenticatedAPI):
         """
          Return all records from a table
 
-         :param table:    The authority table
+         :param table:    The authority table to return the records from
          :type: table:    Table
 
          :return: List of records
@@ -178,7 +177,7 @@ class AuthorityAPI(AuthenticatedAPI):
         :param reference:    The reference for the authority table
         :type: reference:    str
 
-        :return: An authority table
+        :return: An authority table of interest
         :rtype: Table
 
         """

pyPreservica/common.py

@@ -23,10 +23,13 @@ import xml.etree.ElementTree
 from enum import Enum
 from pathlib import Path
 import pyotp
-from requests import Response, Session
+from requests import Session
 from urllib3.util import Retry
 import requests
 from requests.adapters import HTTPAdapter
+from typing import TypeVar
+from datetime import datetime
+import dateutil
 
 import pyPreservica
 
@@ -79,9 +82,9 @@ class FileHash:
 
 def identifiersToDict(identifiers: set) -> dict:
     """
-    Convert a set of tuples to a dict
-    :param identifiers:
-    :return:
+        Convert a set of tuples to a dict
+        :param identifiers:
+        :return:
     """
     result = {}
     for identifier_tuple in identifiers:
@@ -405,6 +408,9 @@ class Bitstream:
         self.length = int(length)
         self.fixity = fixity
         self.content_url = content_url
+        self.bs_index = None
+        self.gen_index = None
+        self.co_ref = None
 
     def __str__(self):
         return f"""
@@ -417,6 +423,26 @@ class Bitstream:
         return self.__str__()
 
 
+class ExternIdentifier:
+    """
+        Class to represent the External Identifier Object in the Preservica data model
+    """
+
+    def __init__(self, identifier_type: str, identifier_value: str):
+        self.type = identifier_type
+        self.value = identifier_value
+        self.id = None
+
+    def __str__(self):
+        return f"""
+           Identifier:          {self.id}
+           Identifier Type:     {self.type}
+           Identifier Value:    {self.value}
+        """
+
+    def __repr__(self):
+        return self.__str__()
+
 class Generation:
     """
          Class to represent the Generation Object in the Preservica data model
@@ -477,10 +503,10 @@ class Entity:
     def __repr__(self):
         return self.__str__()
 
-    def has_metadata(self):
+    def has_metadata(self) -> bool:
         return bool(self.metadata)
 
-    def metadata_namespaces(self):
+    def metadata_namespaces(self) -> list:
         return list(self.metadata.values())
 
 
@@ -525,6 +551,9 @@ class ContentObject(Entity):
         self.tag = "ContentObject"
 
 
+EntityT = TypeVar("EntityT", Folder, Asset, ContentObject, None)
+
+
 class Representation:
     """
         Class to represent the Representation Object in the Preservica data model
@@ -565,12 +594,28 @@ class Thumbnail(Enum):
     LARGE = "large"
 
 
+class AsyncProgress(Enum):
+    """
+    Enumeration of the possible status of an asynchronous process
+    """
+    ABORTED = "ABORTED"
+    ACTIVE = "ACTIVE"
+    COMPLETED = "COMPLETED"
+    PENDING = "PENDING"
+    SUSPENDING = "SUSPENDING"
+    SUSPENDED = "SUSPENDED"
+    UNKNOWN = "UNKNOWN"
+    FAILED = "FAILED"
+    FINISHED_MIXED_OUTCOME = "FINISHED_MIXED_OUTCOME"
+    CANCELLED = "CANCELLED"
+
+
 def sanitize(filename) -> str:
     """
     Return a fairly safe version of the filename.
 
     We don't limit ourselves to ascii, because we want to keep municipality
-    names, etc, but we do want to get rid of anything potentially harmful,
+    names, etc., but we do want to get rid of anything potentially harmful,
     and make sure we do not exceed Windows filename length limits.
     Hence, a less safe blacklist, rather than a whitelist.
     """
@@ -630,19 +675,24 @@ class AuthenticatedAPI:
             logger.error(f"The AdminAPI requires the user to have ROLE_SDB_MANAGER_USER")
             raise RuntimeError(f"The API requires the user to have at least the ROLE_SDB_MANAGER_USER")
 
-    def _find_user_roles_(self) -> list:
+    def _find_user_roles_(self) -> list[str]:
         """
             Get a list of roles for the user
             :return list of roles:
         """
-        headers = {HEADER_TOKEN: self.token, 'Content-Type': 'application/xml;charset=UTF-8'}
+        headers = {HEADER_TOKEN: self.token, 'Content-Type': 'application/json'}
         request = self.session.get(f"{self.protocol}://{self.server}/api/user/details", headers=headers)
+        logger.debug(request.headers)
         if request.status_code == requests.codes.ok:
-            roles = json.loads(str(request.content.decode('utf-8')))['roles']
+            json_document = str(request.content.decode('utf-8'))
+            logger.debug(json_document)
+            roles: list[str] = json.loads(json_document)['roles']
             return roles
         elif request.status_code == requests.codes.unauthorized:
             self.token = self.__token__()
             return self._find_user_roles_()
+        return []
+
 
     def security_tags_base(self, with_permissions: bool = False) -> dict:
         """
@@ -714,11 +764,33 @@ class AuthenticatedAPI:
 
         return entity_dict
 
+    def edition(self) -> str:
+        """
+        Return the edition of this tenancy
+        """
+        if self.major_version < 8 and self.minor_version < 3:
+            raise RuntimeError("Entitlement API is only available when connected to a v7.3 System")
+
+        headers = {HEADER_TOKEN: self.token, 'Content-Type': 'application/json'}
+
+        response = self.session.get(f'{self.protocol}://{self.server}/api/entitlement/edition', headers=headers)
+
+        if response.status_code == requests.codes.ok:
+            return response.json()['edition']
+        elif response.status_code == requests.codes.unauthorized:
+            self.token = self.__token__()
+            return self.edition()
+        else:
+            exception = HTTPException("", response.status_code, response.url,
+                                      "edition", response.content.decode('utf-8'))
+            logger.error(exception)
+            raise exception
+
     def __version_namespace__(self):
         """
         Generate version specific namespaces from the server version
         """
-        if self.major_version == 7:
+        if self.major_version > 6:
             self.xip_ns = f"{NS_XIP_ROOT}v{self.major_version}.{self.minor_version}"
             self.entity_ns = f"{NS_ENTITY_ROOT}v{self.major_version}.{self.minor_version}"
             self.rm_ns = f"{NS_RM_ROOT}v{6}.{2}"
@@ -736,6 +808,8 @@ class AuthenticatedAPI:
                 self.sec_ns = f"{NS_SEC_ROOT}/v{self.major_version}.{self.minor_version}"
                 self.admin_ns = f"{NS_ADMIN}/v{self.major_version}.{self.minor_version}"
 
+        xml.etree.ElementTree.register_namespace("xip", f"{self.xip_ns}")
+
     def __version_number__(self):
         """
         Determine the version number of the server
@@ -750,6 +824,7 @@ class AuthenticatedAPI:
             self.major_version = int(version_numbers[0])
             self.minor_version = int(version_numbers[1])
             self.patch_version = int(version_numbers[2])
+
             return version
         elif request.status_code == requests.codes.unauthorized:
             self.token = self.__token__()
@@ -758,9 +833,12 @@ class AuthenticatedAPI:
             logger.error(f"version number failed with http response {request.status_code}")
             logger.error(str(request.content))
             RuntimeError(request.status_code, "version number failed")
+            return None
+
+
 
     def __str__(self):
-        return f"pyPreservica version: {pyPreservica.__version__}  (Preservica 7.0 Compatible) " \
+        return f"pyPreservica version: {pyPreservica.__version__}  (Preservica 8.0 Compatible) " \
                f"Connected to: {self.server} Preservica version: {self.version} as {self.username} " \
                f"in tenancy {self.tenant}"
 
@@ -777,7 +855,7 @@ class AuthenticatedAPI:
         with open('credentials.properties', 'wt', encoding="utf-8") as configfile:
             config.write(configfile)
 
-    def manager_token(self, username: str, password: str):
+    def manager_token(self, username: str, password: str) -> str:
         data = {'username': username, 'password': password, 'tenant': self.tenant}
         response = self.session.post(f'{self.protocol}://{self.server}/api/accesstoken/login', data=data)
         if response.status_code == requests.codes.ok:
@@ -789,7 +867,7 @@ class AuthenticatedAPI:
             logger.error(str(response.content))
             RuntimeError(response.status_code, "Could not generate valid manager approval token")
 
-    def __token__(self):
+    def __token__(self) -> str:
         """
             Generate am API token to use to authenticate calls
             :return: API Token
@@ -812,20 +890,23 @@ class AuthenticatedAPI:
                         if self.tenant is None:
                             self.tenant = response.json()['tenant']
                         if self.two_fa_secret_key:
+                            logger.debug("Found Two Factor Token")
                             totp = pyotp.TOTP(self.two_fa_secret_key)
                             data = {'username': self.username,
                                     'continuationToken': response.json()['continuationToken'],
                                     'tenant': self.tenant, 'twoFactorToken': totp.now()}
+
+                            header = {'Content-Type': 'application/x-www-form-urlencoded'}
                             response_2fa = self.session.post(
                                 f'{self.protocol}://{self.server}/api/accesstoken/complete-2fa',
-                                data=data)
+                                data=data, headers=header)
                             if response_2fa.status_code == requests.codes.ok:
                                 return response_2fa.json()['token']
                             else:
                                 msg = "Failed to create a 2FA authentication token. Check your credentials are correct"
                                 logger.error(msg)
-                                logger.error(str(response.content))
-                                raise RuntimeError(response.status_code, msg)
+                                logger.error(str(response_2fa.content))
+                                raise RuntimeError(response_2fa.status_code, msg)
                         else:
                             msg = "2FA twoFactorToken required to authenticate against this account using 2FA"
                             logger.error(msg)
@@ -857,12 +938,16 @@ class AuthenticatedAPI:
                 raise RuntimeError(response.status_code, msg)
 
     def __init__(self, username: str = None, password: str = None, tenant: str = None, server: str = None,
-                 use_shared_secret: bool = False, two_fa_secret_key: str = None, protocol: str = "https"):
+                 use_shared_secret: bool = False, two_fa_secret_key: str = None,
+                 protocol: str = "https", request_hook=None, credentials_path: str = 'credentials.properties'):
 
         config = configparser.ConfigParser(interpolation=configparser.Interpolation())
-        config.read('credentials.properties', encoding='utf-8')
+        config.read(os.path.relpath(credentials_path), encoding='utf-8')
         self.session: Session = requests.Session()
 
+        if request_hook is not None:
+            self.session.hooks['response'].append(request_hook)
+
         retries = Retry(
             total=3,
             backoff_factor=0.1,
@@ -950,3 +1035,15 @@ class AuthenticatedAPI:
 
         logger.debug(self.xip_ns)
         logger.debug(self.entity_ns)
+
+def parse_date_to_iso(date):
+    try:
+        date = datetime.datetime.fromisoformat(date.replace('Z','+0000'))
+        if date.tzinfo is None or date.tzinfo.utcoffset(date) is None:
+            date = date.replace(tzinfo=datetime.timezone.utc)
+        date = date.strftime('%Y-%m-%dT%H:%M:%S.%f%z')
+    except ValueError:
+        date = dateutil.parser.parse(date)
+        if date.tzinfo is None or date.tzinfo.utcoffset(date) is None:
+            date = date.replace(tzinfo=datetime.timezone.utc)
+        date = date.strftime('%Y-%m-%dT%H:%M:%S.%f%z')