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

pyPreservica/entityAPI.py

@@ -8,14 +8,15 @@ author:     James Carr
 licence:    Apache License 2.0
 
 """
-import hashlib
+
 import os.path
 import uuid
 import xml.etree.ElementTree
 from datetime import datetime, timedelta, timezone
 from io import BytesIO
 from time import sleep
-from typing import Any, Generator, Tuple, Iterable, Union
+from typing import Any, Generator, Tuple, Iterable, Union, Callable
+
 
 from pyPreservica.common import *
 
@@ -34,8 +35,12 @@ class EntityAPI(AuthenticatedAPI):
     """
 
     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"):
-        super().__init__(username, password, tenant, server, use_shared_secret, two_fa_secret_key, protocol)
+                 use_shared_secret: bool = 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)
+
         xml.etree.ElementTree.register_namespace("oai_dc", "http://www.openarchives.org/OAI/2.0/oai_dc/")
         xml.etree.ElementTree.register_namespace("ead", "urn:isbn:1-931666-22-9")
 
@@ -54,11 +59,15 @@ class EntityAPI(AuthenticatedAPI):
 
     def bitstream_chunks(self, bitstream: Bitstream, chunk_size: int = CHUNK_SIZE) -> Generator:
         """
-        Generator function to return bitstream chunks
+        Generator function to return bitstream chunks, allows the clients to
+        process chunks as they are downloaded.
 
-        :param bitstream:   The bitstream
-        :param chunk_size:  The chunk size to return
-        :return:            A chunk of the requested bitstream content
+        :param  bitstream: A bitstream object
+        :type  url: Bitstream
+        :param  chunk_size: Optional size of the chunks to be downloaded
+        :type  chunk_size: int
+        :return: Iterator
+        :rtype: Generator
         """
         if not isinstance(bitstream, Bitstream):
             logger.error("bitstream_content argument is not a Bitstream object")
@@ -66,40 +75,40 @@ class EntityAPI(AuthenticatedAPI):
         with self.session.get(bitstream.content_url, headers={HEADER_TOKEN: self.token}, stream=True) as request:
             if request.status_code == requests.codes.unauthorized:
                 self.token = self.__token__()
-                return self.bitstream_chunks(bitstream)
+                yield from self.bitstream_chunks(bitstream)
             elif request.status_code == requests.codes.ok:
                 for chunk in request.iter_content(chunk_size=chunk_size):
                     yield chunk
             else:
-                exception = HTTPException(bitstream.filename, request.status_code, request.url, "bitstream_content",
+                exception = HTTPException(bitstream.filename, request.status_code, request.url, "bitstream_chunks",
                                           request.content.decode('utf-8'))
                 logger.error(exception)
                 raise exception
 
     def bitstream_bytes(self, bitstream: Bitstream, chunk_size: int = CHUNK_SIZE) -> Union[BytesIO, None]:
         """
-                Download a file represented as a Bitstream to a byteIO array
+        Download a file represented as a Bitstream to a byteIO array
 
-                Returns the byteIO
-                Returns None if the file does not contain the correct number of bytes (default 2k)
+        Returns the byteIO
+        Returns None if the file does not contain the correct number of bytes (default 2k)
 
-                :param chunk_size: The buffer copy chunk size in bytes default
-                :param bitstream: A Bitstream object
-                :type bitstream: Bitstream
+        :param chunk_size: The buffer copy chunk size in bytes default
+        :param bitstream: A Bitstream object
+        :type bitstream: Bitstream
 
-                :return: The file in bytes
-                :rtype: byteIO
+        :return: The file in bytes
+        :rtype: byteIO
         """
         if not isinstance(bitstream, Bitstream):
             logger.error("bitstream_content argument is not a Bitstream object")
             raise RuntimeError("bitstream_bytes argument is not a Bitstream object")
-        with self.session.get(bitstream.content_url, headers={HEADER_TOKEN: self.token}, stream=True) as request:
-            if request.status_code == requests.codes.unauthorized:
+        with self.session.get(bitstream.content_url, headers={HEADER_TOKEN: self.token}, stream=True) as response:
+            if response.status_code == requests.codes.unauthorized:
                 self.token = self.__token__()
                 return self.bitstream_bytes(bitstream)
-            elif request.status_code == requests.codes.ok:
+            elif response.status_code == requests.codes.ok:
                 file_bytes = BytesIO()
-                for chunk in request.iter_content(chunk_size=chunk_size):
+                for chunk in response.iter_content(chunk_size=chunk_size):
                     file_bytes.write(chunk)
                 file_bytes.seek(0)
                 if file_bytes.getbuffer().nbytes == bitstream.length:
@@ -109,11 +118,49 @@ class EntityAPI(AuthenticatedAPI):
                     logger.error("Downloaded file size did not match the Preservica held value")
                     return None
             else:
-                exception = HTTPException(bitstream.filename, request.status_code, request.url, "bitstream_content",
+                exception = HTTPException(bitstream.filename, response.status_code, response.url, "bitstream_bytes",
+                                          response.content.decode('utf-8'))
+                logger.error(exception)
+                raise exception
+
+    def bitstream_location(self, bitstream: Bitstream) -> list:
+        """"
+        Retrieves information about a bitstreams storage locations
+
+        :param Bitstream bitstream: The bitstream object
+        :return: A list of strings containing all the storage locations of this bitstream
+        :rtype: list
+
+        """
+        if not isinstance(bitstream, Bitstream):
+            logger.error("bitstream argument is not a Bitstream object")
+            raise RuntimeError("bitstream argument is not a Bitstream object")
+
+        storage_locations = []
+
+        url: str = f'{self.protocol}://{self.server}/api/entity/content-objects/{bitstream.co_ref}/generations/{bitstream.gen_index}/bitstreams/{bitstream.bs_index}/storage-locations'
+
+        with self.session.get(url, headers={HEADER_TOKEN: self.token}, stream=True) as request:
+            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)
+                locations = entity_response.find(f'.//{{{self.entity_ns}}}StorageLocation')
+                for adapter in locations:
+                    storage_locations.append(adapter.attrib['name'])
+                return storage_locations
+
+            if request.status_code == requests.codes.unauthorized:
+                self.token = self.__token__()
+                return self.bitstream_location(bitstream)
+            else:
+                exception = HTTPException(bitstream.filename, request.status_code, request.url, "bitstream_location",
                                           request.content.decode('utf-8'))
                 logger.error(exception)
                 raise exception
 
+
+
     def bitstream_content(self, bitstream: Bitstream, filename: str, chunk_size: int = CHUNK_SIZE) -> Union[int, None]:
         """
         Download a file represented as a Bitstream to a local filename
@@ -303,6 +350,15 @@ class EntityAPI(AuthenticatedAPI):
             IncludedGenerations
             IncludeParentHierarchy
 
+
+        :param Entity entity: The entity to export Asset or Folder
+        :param str IncludeContent: "Content", "NoContent"
+        :param str IncludeMetadata: "Metadata", "NoMetadata", "MetadataWithEvents"
+        :param str IncludedGenerations: "LatestActive", "AllActive", "All"
+        :param str IncludeParentHierarchy: "true", "false"
+        :return: The path to the opex ZIP file
+        :rtype: str
+
         """
         status = "ACTIVE"
         pid = self.__export_opex_start__(entity, **kwargs)
@@ -317,12 +373,12 @@ class EntityAPI(AuthenticatedAPI):
 
     def download(self, entity: Entity, filename: str) -> str:
         """
-           Download a file from an asset
-
-           Returns the filename of the new file
+         Download the first generation of the access representation of an asset
 
-           :param entity: The entity containing the file
-           :param filename: The filename to write the bytes to
+        :param Entity entity: The entity
+        :param str filename: The file the image is written to
+        :return: The filename
+        :rtype: str
         """
         headers = {HEADER_TOKEN: self.token, 'Content-Type': 'application/octet-stream'}
         params = {'id': f'sdb:{entity.entity_type.value}|{entity.reference}'}
@@ -369,13 +425,13 @@ class EntityAPI(AuthenticatedAPI):
 
     def thumbnail(self, entity: Entity, filename: str, size=Thumbnail.LARGE):
         """
-            Download the thumbnail of an asset or folder
-
-            Returns the filename of the new thumbnail file or None if the entity has no thumbnail
+            Get the thumbnail image for an asset or folder
 
-            :param entity: The entity containing the file
-            :param filename: The filename to write the bytes to
-            :param size: The size of the thumbnail
+        :param Entity entity: The entity
+        :param str filename: The file the image is written to
+        :param Thumbnail size: The size of the thumbnail image
+        :return: The filename
+        :rtype: str
          """
         headers = {HEADER_TOKEN: self.token, 'Content-Type': 'application/octet-stream'}
         params = {'id': f'sdb:{entity.entity_type.value}|{entity.reference}', 'size': f'{size.value}'}
@@ -400,14 +456,14 @@ class EntityAPI(AuthenticatedAPI):
 
     def delete_identifiers(self, entity: Entity, identifier_type: str = None, identifier_value: str = None):
         """
-             Delete external identifiers from an entity
-
-             Returns the entity
+         Delete identifiers on an Entity object
 
-             :param entity: The entity to delete identifiers from
-             :param identifier_type: The type of the identifier to delete.
-             :param identifier_value: The value of the identifier to delete.
-          """
+        :param Entity entity: The entity the identifiers are deleted from
+        :param str identifier_type: The identifier type
+        :param str identifier_value: The identifier value
+        :return: entity
+        :rtype: Entity
+        """
 
         if (self.major_version < 7) and (self.minor_version < 1):
             raise RuntimeError("delete_identifiers API call is not available when connected to a v6.0 System")
@@ -450,14 +506,61 @@ class EntityAPI(AuthenticatedAPI):
             logger.error(request)
             raise RuntimeError(request.status_code, "delete_identifier failed")
 
-    def identifiers_for_entity(self, entity: Entity) -> set[Tuple]:
+    def entity_identifiers(self, entity: Entity,  external_identifier_type = None) -> set[ExternIdentifier]:
         """
-             Get all external identifiers on an entity
+         Get all external identifiers on an entity
 
-             Returns the set of external identifiers on the entity
+         Returns the set of external identifiers on the entity
 
-             :param entity: The Entity (Asset or Folder)
-             :type  entity: Entity
+         :param entity: The Entity (Asset or Folder)
+         :param external_identifier_type: Optional identifier type to filter the results
+         :type  entity: Entity
+        """
+        headers = {HEADER_TOKEN: self.token}
+        request = self.session.get(
+            f'{self.protocol}://{self.server}/api/entity/{entity.path}/{entity.reference}/identifiers',
+            headers=headers)
+        if request.status_code == requests.codes.ok:
+            xml_response = str(request.content.decode('utf-8'))
+            logger.debug(xml_response)
+            entity_response = xml.etree.ElementTree.fromstring(xml_response)
+            identifier_list = entity_response.findall(f'.//{{{self.xip_ns}}}Identifier')
+            result = set()
+            for identifier in identifier_list:
+                identifier_value = identifier_type = identifier_id = ""
+                for child in identifier:
+                    if child.tag.endswith("Type"):
+                        identifier_type = child.text
+                    if child.tag.endswith("Value"):
+                        identifier_value = child.text
+                    if child.tag.endswith("ApiId"):
+                        identifier_id = child.text
+                if external_identifier_type is None:
+                    external_id: ExternIdentifier = ExternIdentifier(identifier_type, identifier_value)
+                    external_id.identifier_id = identifier_id
+                    result.add(external_id)
+                else:
+                    if identifier_type == external_identifier_type:
+                        external_id: ExternIdentifier = ExternIdentifier(identifier_type, identifier_value)
+                        external_id.identifier_id = identifier_id
+                        result.add(external_id)
+            return result
+        elif request.status_code == requests.codes.unauthorized:
+            self.token = self.__token__()
+            return self.entity_identifiers(entity)
+        else:
+            exception = HTTPException(entity.reference, request.status_code, request.url, "identifiers_for_entity",
+                                      request.content.decode('utf-8'))
+            logger.error(exception)
+            raise exception
+
+    def identifiers_for_entity(self, entity: Entity) -> set[Tuple]:
+        """
+             Return a set of identifiers which belong to the entity
+
+            :param Entity entity: The entity
+            :return: Set of identifiers as tuples
+            :rtype: set(Tuple)
           """
         headers = {HEADER_TOKEN: self.token}
         request = self.session.get(
@@ -487,14 +590,14 @@ class EntityAPI(AuthenticatedAPI):
             logger.error(exception)
             raise exception
 
-    def identifier(self, identifier_type: str, identifier_value: str) -> set[Entity]:
+    def identifier(self, identifier_type: str, identifier_value: str) -> set[EntityT]:
         """
-             Get all entities which have the external identifier
-
-             Returns the set of entities which have the external identifier
+         Return a set of entities with external identifiers which match the type and value
 
-             :param identifier_type: The identifier type
-             :param identifier_value: The identifier value
+        :param str identifier_type: The identifier type
+        :param str identifier_value: The identifier value
+        :return: Set of entity objects which have a reference and title attribute
+        :rtype: set(Entity)
           """
         headers = {HEADER_TOKEN: self.token}
         payload = {'type': identifier_type, 'value': identifier_value}
@@ -528,14 +631,14 @@ class EntityAPI(AuthenticatedAPI):
 
     def add_identifier(self, entity: Entity, identifier_type: str, identifier_value: str):
         """
-             Add a new identifier to an entity
+         Add a new external identifier to an Entity object
 
-             Returns the internal identifier DB key
-
-            :param entity: The Entity
-            :param identifier_type: The identifier type
-            :param identifier_value: The identifier value
-          """
+        :param Entity entity: The entity the identifier is added to
+        :param str identifier_type: The identifier type
+        :param str identifier_value: The identifier value
+        :return: An internal id for this external identifier
+        :rtype: str
+        """
 
         if self.major_version < 7 and self.minor_version < 1:
             raise RuntimeError("add_identifier API call is not available when connected to a v6.0 System")
@@ -568,6 +671,76 @@ class EntityAPI(AuthenticatedAPI):
             logger.error(exception)
             raise exception
 
+    def update_identifiers(self, entity: Entity, identifier_type: str = None, identifier_value: str = None):
+        """
+             Update external identifiers based on Entity and Type
+
+             Returns the internal identifier DB Key
+
+             :param entity: The entity to delete identifiers from
+             :param identifier_type: The type of the identifier to delete.
+             :param identifier_value: The value of the identifier to delete.
+          """
+
+        if (self.major_version < 7) and (self.minor_version < 1):
+            raise RuntimeError("update_identifiers API call is not available when connected to a v6.0 System")
+
+        headers = {HEADER_TOKEN: self.token}
+        response = self.session.get(
+            f'{self.protocol}://{self.server}/api/entity/{entity.path}/{entity.reference}/identifiers',
+            headers=headers)
+
+        if response.status_code == requests.codes.ok:
+            xml_response = str(response.content.decode('utf-8'))
+            entity_response = xml.etree.ElementTree.fromstring(xml_response)
+            identifier_list = entity_response.findall(f'.//{{{self.xip_ns}}}Identifier')
+            for identifier_element in identifier_list:
+                _ref = _type = _value = _aipid = None
+                for identifier in identifier_element:
+                    if identifier.tag.endswith("Entity"):
+                        _ref = identifier.text
+                    if identifier.tag.endswith("Type") and identifier_type is not None:
+                        _type = identifier.text
+                    if identifier.tag.endswith("Value") and identifier_value is not None:
+                        _value = identifier.text
+                    if identifier.tag.endswith("ApiId"):
+                        _aipid = identifier.text
+                if _ref == entity.reference and _type == identifier_type:
+
+                    headers = {HEADER_TOKEN: self.token, 'Content-Type': 'application/xml;charset=UTF-8'}
+
+                    xml_object = xml.etree.ElementTree.Element('Identifier', {"xmlns": self.xip_ns})
+                    xml.etree.ElementTree.SubElement(xml_object, "Type").text = identifier_type
+                    xml.etree.ElementTree.SubElement(xml_object, "Value").text = identifier_value
+                    xml.etree.ElementTree.SubElement(xml_object, "Entity").text = entity.reference
+                    xml_request = xml.etree.ElementTree.tostring(xml_object, encoding='utf-8')
+
+                    put_response = self.session.put(
+                        f'{self.protocol}://{self.server}/api/entity/{entity.path}/{entity.reference}/identifiers/{_aipid}',
+                        headers=headers, data=xml_request)
+                    if put_response.status_code == requests.codes.ok:
+                        xml_string = str(put_response.content.decode("utf-8"))
+                        identifier_response = xml.etree.ElementTree.fromstring(xml_string)
+                        aip_id = identifier_response.find(f'.//{{{self.xip_ns}}}ApiId')
+                        if hasattr(aip_id, 'text'):
+                            return aip_id.text
+                        else:
+                            return None
+                    if put_response.status_code == requests.codes.unauthorized:
+                        self.token = self.__token__()
+                        return self.update_identifiers(entity, identifier_type, identifier_value)
+                    if put_response.status_code == requests.codes.no_content:
+                        pass
+                    else:
+                        return None
+            return entity
+        elif response.status_code == requests.codes.unauthorized:
+            self.token = self.__token__()
+            return self.update_identifiers(entity, identifier_type, identifier_value)
+        else:
+            logger.error(response)
+            raise RuntimeError(response.status_code, "update_identifiers failed")
+
     def delete_relationships(self, entity: Entity, relationship_type: str = None):
         """
         Delete a relationship between two entities by its internal id
@@ -607,7 +780,7 @@ class EntityAPI(AuthenticatedAPI):
         end_point = f"{entity.path}/{entity.reference}/links/{relationship.api_id}"
         request = self.session.delete(f'{self.protocol}://{self.server}/api/entity/{end_point}', headers=headers)
         if request.status_code == requests.codes.no_content:
-            print(relationship)
+            return None
         elif request.status_code == requests.codes.unauthorized:
             self.token = self.__token__()
             return self.__delete_relationship(relationship)
@@ -626,7 +799,7 @@ class EntityAPI(AuthenticatedAPI):
             :type: page_size: int
 
             :param entity: The Source Entity
-            :type: entity: Entity
+            :type: entity: An Entity type such as Asset, Folder etc
 
             :return: Generator
             :rtype:  Relationship
@@ -694,7 +867,7 @@ class EntityAPI(AuthenticatedAPI):
 
             return PagedSet(results, has_more, int(total_hits.text), url)
         elif request.status_code == requests.codes.unauthorized:
-            self.__relationships__(entity=entity, maximum=maximum, next_page=next_page)
+            return self.__relationships__(entity=entity, maximum=maximum, next_page=next_page)
         else:
             exception = HTTPException(entity.reference, request.status_code, request.url, "relationships",
                                       request.content.decode('utf-8'))
@@ -705,10 +878,10 @@ class EntityAPI(AuthenticatedAPI):
         """
             Add a new relationship link between two Assets or Folders
 
-            :param from_entity: The Source Entity
+            :param from_entity: The Source entity to link from
             :type from_entity: Entity
 
-            :param to_entity: The Target Entity
+            :param to_entity: The Target entity
             :type to_entity: Entity
 
             :param  relationship_type: The Relationship type
@@ -752,15 +925,17 @@ class EntityAPI(AuthenticatedAPI):
             logger.error(exception)
             raise exception
 
-    def delete_metadata(self, entity: Entity, schema: str) -> Entity:
+    def delete_metadata(self, entity: EntityT, schema: str) -> EntityT:
         """
-        Deletes all the metadata fragments on an entity which match the schema URI
-
-        Returns The updated Entity
+        Delete an existing descriptive XML document on an entity by its schema
+        This call will delete all fragments with the same schema
 
-        :param entity: The Entity to delete metadata from
-        :param schema: The schema URI to match against
+        :param Entity entity: The entity to add the metadata to
+        :param str schema: The metadata schema URI
+        :return: The updated Entity
+        :rtype: Entity
         """
+
         headers = {HEADER_TOKEN: self.token}
         for url in entity.metadata:
             if schema == entity.metadata[url]:
@@ -778,15 +953,45 @@ class EntityAPI(AuthenticatedAPI):
 
         return self.entity(entity.entity_type, entity.reference)
 
-    def update_metadata(self, entity: Entity, schema: str, data: Any) -> Entity:
+
+    def add_group_metadata(self, csv_file: str) -> str:
         """
-        Update all existing metadata fragments which match the schema
+           Perform bulk additions of metadata with a CSV file.
+           This is designed for metadata which populates a New Gen Metadata Group
+           Returns The process ID which will track the updates
+           Requires DataManagement permission
+
+           :param str csv_file:   The path of the CSV metadata file
+           :return: The process ID
+           :rtype: str
+           """
+        headers = {HEADER_TOKEN: self.token, 'Content-Type': 'text/csv;charset=UTF-8'}
+
+        url = f'{self.protocol}://{self.server}/api/entity/actions/metadata-csv-edits'
+
+        with open(csv_file, 'rb') as fd:
+            with self.session.post(url, headers=headers, data=fd) as request:
+                if request.status_code == requests.codes.unauthorized:
+                    self.token = self.__token__()
+                    return self.add_group_metadata(csv_file)
+                elif request.status_code == requests.codes.accepted:
+                    return str(request.content.decode('utf-8'))
+                else:
+                    exception = HTTPException(None, request.status_code, request.url, "add_group_metadata",
+                                              request.content.decode('utf-8'))
+                    logger.error(exception)
+                    raise exception
 
-        Returns The updated Entity
 
-        :param data:   The updated XML as a string or as IO bytes
-        :param entity: The Entity to update
-        :param schema: The schema URI to match against
+    def update_metadata(self, entity: EntityT, schema: str, data: Any) -> EntityT:
+        """
+        Update an existing descriptive XML document on an entity
+
+        :param Entity entity: The entity to add the metadata to
+        :param str schema: The metadata schema URI
+        :param data data: The XML document as a string or as a file bytes
+        :return: The updated Entity
+        :rtype: Entity
         """
         headers = {HEADER_TOKEN: self.token, 'Content-Type': 'application/xml;charset=UTF-8'}
 
@@ -809,7 +1014,7 @@ class EntityAPI(AuthenticatedAPI):
                     content.append(tree.getroot())
                 else:
                     raise RuntimeError("Unknown data type")
-                xml_request = xml.etree.ElementTree.tostring(xml_object, encoding='utf-8')
+                xml_request = xml.etree.ElementTree.tostring(xml_object, encoding='utf-8').decode("utf-8")
                 logger.debug(xml_request)
                 request = self.session.put(url, data=xml_request, headers=headers)
                 if request.status_code == requests.codes.ok:
@@ -824,15 +1029,51 @@ class EntityAPI(AuthenticatedAPI):
                     raise exception
         return self.entity(entity.entity_type, entity.reference)
 
-    def add_metadata(self, entity: Entity, schema: str, data) -> Entity:
+    def add_metadata_as_fragment(self, entity: EntityT, schema: str, xml_fragment: str) -> EntityT:
         """
-        Add a metadata fragment with a given namespace URI
+        Add a metadata fragment with a given namespace URI to an Entity
+        Don't parse the xml fragment which may add extra namespaces etc
 
         Returns The updated Entity
 
-        :param data:   The new XML as a string or as IO bytes
-        :param entity: The Entity to update
-        :param schema: The schema URI of the XML document
+        :param str xml_fragment:  The new XML as a string
+        :param Entity entity: The entity to update
+        :param str schema: The schema URI of the XML document
+        :rtype: Entity
+        """
+        headers = {HEADER_TOKEN: self.token, 'Content-Type': 'application/xml;charset=UTF-8'}
+
+        xml_doc = f"""<xip:MetadataContainer xmlns="{schema}" schemaUri="{schema}" xmlns:xip="{self.xip_ns}">
+            <xip:Entity>{entity.reference}</xip:Entity>
+                <xip:Content>
+                   {xml_fragment}
+                </xip:Content>
+            </xip:MetadataContainer>"""
+
+        end_point = f"/{entity.path}/{entity.reference}/metadata"
+        logger.debug(xml_doc)
+        request = self.session.post(f'{self.protocol}://{self.server}/api/entity{end_point}', data=xml_doc,
+                                    headers=headers)
+        if request.status_code == requests.codes.ok:
+            return self.entity(entity_type=entity.entity_type, reference=entity.reference)
+        elif request.status_code == requests.codes.unauthorized:
+            self.token = self.__token__()
+            return self.add_metadata(entity, schema, xml_fragment)
+        else:
+            exception = HTTPException(entity.reference, request.status_code, request.url, "add_metadata",
+                                      request.content.decode('utf-8'))
+            logger.error(exception)
+            raise exception
+
+    def add_metadata(self, entity: EntityT, schema: str, data) -> EntityT:
+        """
+        Add a new descriptive XML document to an existing entity
+
+        :param Entity entity: The entity to add the metadata to
+        :param str schema: The metadata schema URI
+        :param data data: The XML document as a string or as file bytes
+        :return: The updated entity with the new metadata
+        :rtype: Entity
         """
         headers = {HEADER_TOKEN: self.token, 'Content-Type': 'application/xml;charset=UTF-8'}
 
@@ -864,13 +1105,15 @@ class EntityAPI(AuthenticatedAPI):
             logger.error(exception)
             raise exception
 
-    def save(self, entity: Entity) -> Entity:
+    def save(self, entity: EntityT) -> EntityT:
         """
-        Save the title and description of an entity
+        Updates the title and description of an entity
+        The security tag and parent are not saved via this method call
 
-        Returns The updated Entity
-
-        :param entity: The Entity to update
+        :param entity: The entity (asset, folder, content_object) to be updated
+        :type  entity: Entity
+        :return: The updated entity
+        :rtype: Entity
         """
 
         headers = {HEADER_TOKEN: self.token, 'Content-Type': 'application/xml;charset=UTF-8'}
@@ -916,6 +1159,7 @@ class EntityAPI(AuthenticatedAPI):
                 if 'CustomType' in response:
                     content_object.custom_type = response['CustomType']
                 return content_object
+            return None
         elif request.status_code == requests.codes.unauthorized:
             self.token = self.__token__()
             return self.save(entity)
@@ -935,8 +1179,10 @@ class EntityAPI(AuthenticatedAPI):
 
         Returns The updated Entity
 
-        :param entity:      The Entity to update
-        :param dest_folder: The Folder which will become the new parent of this entity
+        :param Entity entity: The entity to move either asset or folder
+        :param Entity dest_folder: The new destination folder. This can be None to move a folder to the root of the repository
+        :return: Progress ID token
+        :rtype: str
         """
         headers = {HEADER_TOKEN: self.token, 'Content-Type': 'text/plain'}
         if isinstance(entity, Asset) and dest_folder is None:
@@ -959,7 +1205,18 @@ class EntityAPI(AuthenticatedAPI):
             logger.error(exception)
             raise exception
 
+    def get_progress(self, pid: str) -> AsyncProgress:
+        return AsyncProgress[self.get_async_progress(pid)]
+
     def get_async_progress(self, pid: str) -> str:
+        """
+        Return the status of a running process
+
+
+        :param pid: The progress ID
+        :return:  Workflow status
+        :rtype: str
+        """
         headers = {HEADER_TOKEN: self.token, 'Content-Type': 'text/plain'}
         request = self.session.get(f"{self.protocol}://{self.server}/api/entity/progress/{pid}", headers=headers)
         if request.status_code == requests.codes.ok:
@@ -978,16 +1235,15 @@ class EntityAPI(AuthenticatedAPI):
             logger.error(exception)
             raise exception
 
-    def move_sync(self, entity: Entity, dest_folder: Folder) -> Entity:
+    def move_sync(self, entity: EntityT, dest_folder: Folder) -> EntityT:
         """
-        Move an Entity (Asset or Folder) to a new Folder
-        If dest_folder is None then the entity must be a Folder and will be moved to the root of the repository
-
-        Returns The updated Entity.
-        Blocks until the move is complete.
+        Move an entity (asset or folder) to a new folder
+        This call blocks until the move is complete
 
-        :param entity:      The Entity to update
-        :param dest_folder: The Folder which will become the new parent of this entity
+        :param Entity entity: The entity to move either asset or folder
+        :param Entity dest_folder: The new destination folder. This can be None to move a folder to the root of the repository
+        :return: The updated entity
+        :rtype: Entity
         """
         headers = {HEADER_TOKEN: self.token, 'Content-Type': 'text/plain'}
         if isinstance(entity, Asset) and dest_folder is None:
@@ -1018,15 +1274,15 @@ class EntityAPI(AuthenticatedAPI):
             logger.error(exception)
             raise exception
 
-    def move(self, entity: Entity, dest_folder: Folder) -> Entity:
+    def move(self, entity: EntityT, dest_folder: Folder) -> EntityT:
         """
-        Move an Entity (Asset or Folder) to a new Folder
-        If dest_folder is None then the entity must be a Folder and will be moved to the root of the repository
-
-        Returns The updated Entity
+        Move an entity (asset or folder) to a new folder
+        This call is an alias for the move_sync (blocking) method.
 
-        :param entity:      The Entity to update
-        :param dest_folder: The Folder which will become the new parent of this entity
+        :param Entity entity: The entity to move either asset or folder
+        :param Entity dest_folder: The new destination folder. This can be None to move a folder to the root of the repository
+        :return: The updated entity
+        :rtype: Entity
         """
         return self.move_sync(entity, dest_folder)
 
@@ -1072,13 +1328,15 @@ class EntityAPI(AuthenticatedAPI):
             logger.error(exception)
             raise exception
 
-    def all_metadata(self, entity: Entity) -> Tuple:
+    def all_metadata(self, entity: Entity) -> Generator[Tuple[str, str], None, None]:
         """
         Retrieve all metadata fragments on an entity
 
         Returns XML documents in a tuple
 
-        :param entity:       The entity with the metadata
+        :param Entity entity:       The entity with the metadata
+        :return: A list of Tuples, the first value is the schmea and the second is the metadata
+        :rtype: Generator[Tuple[str, str]]
         """
 
         for uri, schema in entity.metadata.items():
@@ -1086,12 +1344,12 @@ class EntityAPI(AuthenticatedAPI):
 
     def metadata_for_entity(self, entity: Entity, schema: str) -> Union[str, None]:
         """
-        Retrieve the first metadata fragment on an entity with a matching schema URI
-
-        Returns XML document as a string
+       Fetch the first metadata document which matches the schema URI from an entity
 
-        :param entity:       The entity with the metadata
-        :param schema:       The schema URI
+        :param Entity entity: The entity containing the metadata
+        :param str schema: The metadata schema URI
+        :return: The first XML document on the entity matching the schema URI
+        :rtype: str
         """
 
         # if the entity is a lightweight enum version request the full object
@@ -1101,9 +1359,9 @@ class EntityAPI(AuthenticatedAPI):
         for uri, schema_name in entity.metadata.items():
             if schema == schema_name:
                 return self.metadata(uri)
-        return
+        return None
 
-    def metadata_tag_for_entity(self, entity: Entity, schema: str, tag: str, isXpath: bool = False) -> str:
+    def metadata_tag_for_entity(self, entity: Entity, schema: str, tag: str, isXpath: bool = False) -> Union[str, None]:
         """
         Retrieve the first value of the tag from a metadata template given by schema
 
@@ -1118,19 +1376,23 @@ class EntityAPI(AuthenticatedAPI):
         xml_doc = self.metadata_for_entity(entity, schema)
         if xml_doc:
             xml_object = xml.etree.ElementTree.fromstring(xml_doc)
-            if isXpath is False:
+            if not isXpath:
                 return xml_object.find(f'.//{{*}}{tag}').text
             else:
                 return xml_object.find(tag).text
+        return None
 
-    def security_tag_sync(self, entity: Entity, new_tag: str):
+    def security_tag_sync(self, entity: EntityT, new_tag: str) -> EntityT:
         """
-         Change the security tag for a folder or asset
-
-         Returns the updated entity after the security tag has been updated.
+        Change the security tag of an asset or folder
+        This is a blocking call which returns after all entities have been updated.
 
-         :param entity:       The entity to change
-         :param new_tag:      The new security tag
+        :param entity: The entity (asset, folder) to be updated
+        :type  entity: Entity
+        :param new_tag: The new security tag to be set on the entity
+        :type  new_tag: str
+        :return: The updated entity
+        :rtype: Entity
          """
         self.token = self.__token__()
         headers = {HEADER_TOKEN: self.token, 'Content-Type': 'text/plain'}
@@ -1157,12 +1419,15 @@ class EntityAPI(AuthenticatedAPI):
 
     def security_tag_async(self, entity: Entity, new_tag: str):
         """
-          Change the security tag for a folder or asset
+        Change the security tag of an asset or folder
+        This is a non blocking call which returns immediately.
 
-          Returns a process ID asynchronous (without blocking)
-
-          :param entity:       The entity to change
-          :param new_tag:      The new security tag
+        :param entity: The entity (asset, folder) to be updated
+        :type  entity: Entity
+        :param  new_tag: The new security tag to be set on the entity
+        :type  new_tag: str
+        :return: A progress id which can be used to monitor the workflow
+        :rtype: str
           """
         headers = {HEADER_TOKEN: self.token, 'Content-Type': 'text/plain'}
         end_point = f"/{entity.path}/{entity.reference}/security-descriptor"
@@ -1181,11 +1446,11 @@ class EntityAPI(AuthenticatedAPI):
 
     def metadata(self, uri: str) -> str:
         """
-        Retrieve the metadata fragment which is referenced by the URI
-
-        Returns XML document as a string
+        Fetch the metadata document by its identifier, this is the key from the entity metadata map
 
-        :param uri:          The endpoint of the metadata fragment
+        :param str uri: The metadata identifier
+        :return: An XML document as a string
+        :rtype: str
         """
         request = self.session.get(uri, headers={HEADER_TOKEN: self.token})
         if request.status_code == requests.codes.ok:
@@ -1203,14 +1468,17 @@ class EntityAPI(AuthenticatedAPI):
             logger.error(exception)
             raise exception
 
-    def entity(self, entity_type: EntityType, reference: str) -> Entity:
+    def entity(self, entity_type: EntityType, reference: str) -> EntityT:
         """
-        Retrieve an entity by its type and reference
-
-        Returns Entity (Asset, Folder, ContentObject)
+        Returns a generic entity based on its reference identifier
 
-        :param entity_type:          The type of entity to fetch
-        :param reference:            The unique identifier of the entity
+        :param  entity_type: The type of entity
+        :type  entity_type: EntityType
+        :param reference: The unique identifier for the entity
+        :type  reference: str
+        :return: The entity either Asset, Folder or ContentObject
+        :rtype: Entity
+        :raises RuntimeError: if the identifier is incorrect
         """
         if entity_type is EntityType.CONTENT_OBJECT:
             return self.content_object(reference)
@@ -1218,6 +1486,7 @@ class EntityAPI(AuthenticatedAPI):
             return self.folder(reference)
         if entity_type is EntityType.ASSET:
             return self.asset(reference)
+        return None
 
     def add_physical_asset(self, title: str, description: str, parent: Folder, security_tag: str = "open") -> Asset:
         """
@@ -1225,10 +1494,12 @@ class EntityAPI(AuthenticatedAPI):
 
         Returns Asset
 
-        :param title:           The title of the new Asset
-        :param description:     The description of the new Asset
-        :param parent:          The parent folder
-        :param security_tag:    The security setting
+        :param str title:           The title of the new Asset
+        :param str description:     The description of the new Asset
+        :param Folder parent:          The parent folder
+        :param str security_tag:    The security tag, defaults to open
+        :return:                The new physical object
+        :rtype:                 Asset
         """
 
         if (self.major_version < 7) and (self.minor_version < 4):
@@ -1265,15 +1536,134 @@ class EntityAPI(AuthenticatedAPI):
             logger.error(exception)
             raise exception
 
-    def asset(self, reference: str) -> Asset:
+    def merge_assets(self, assets: list[Asset], title: str, description: str) -> str:
+        """
+            Create a new Asset with the content from each Asset in supplied list
+            This call will create a new multipart Asset which contains all the content from list of Assets.
+
+            The return value is the progress status of the merge operation.
+        """
+
+        headers = {
+            HEADER_TOKEN: self.token,
+            "Content-Type": "application/xml;charset=UTF-8",
+            "accept": "text/plain;charset=UTF-8",
+        }
+
+        merge_object = xml.etree.ElementTree.Element("MergeAction", {"xmlns": self.entity_ns, "xmlns:xip": self.xip_ns})
+        xml.etree.ElementTree.SubElement(merge_object, "Title").text = str(title)
+        xml.etree.ElementTree.SubElement(merge_object, "Description").text = str(description)
+        for a in assets:
+            xml.etree.ElementTree.SubElement(merge_object, "Entity", {
+                "excludeIdentifiers": "true",
+                "excludeLinks": "true",
+                "excludeMetadata": "true",
+                "ref": a.reference,
+                "type": EntityType.ASSET.value}
+            )
+  #      order_object = xml.etree.ElementTree.SubElement(merge_object, "Order")
+  #      for a in assets:
+  #          xml.etree.ElementTree.SubElement(order_object, "Entity", {
+  #              "ref": a.reference,
+  #              "type": EntityType.CONTENT_OBJECT.value}
+  #          )
+        xml_request = xml.etree.ElementTree.tostring(merge_object, encoding="utf-8")
+        print(xml_request)
+        request = self.session.post(
+            f"{self.protocol}://{self.server}/api/entity/actions/merges", data=xml_request, headers=headers)
+        if request.status_code == requests.codes.accepted:
+            return request.content.decode('utf-8')
+        elif request.status_code == requests.codes.unauthorized:
+            self.token = self.__token__()
+            return self.merge_assets(assets, title, description)
+        else:
+            exception = HTTPException(
+                "",
+                request.status_code,
+                request.url,
+                "merge_assets",
+                request.content.decode("utf-8"),
+            )
+            logger.error(exception)
+            raise exception
+
+    def merge_folder(self, folder: Folder) -> str:
+        """
+            Create a new Asset with the content from each Asset in the Folder
+
+            This call will create a new multipart Asset which contains all the content from the Folder.
+
+            The new Asset which is created will have the same title, description and parent as the Folder.
+
+            The return value is the progress status of the merge operation.
+        """
+        headers = {HEADER_TOKEN: self.token, 'Content-Type': 'application/xml;charset=UTF-8', 'accept': 'text/plain;charset=UTF-8'}
+        payload = f"""<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+            <MergeAction xmlns="{self.entity_ns}" xmlns:xip="{self.xip_ns}">
+                <Title>{folder.title}</Title>
+                <Description>{folder.description}</Description>
+                <Entity excludeIdentifiers="true" excludeLinks="true" excludeMetadata="true" ref="{folder.reference}" type="SO"/>
+            </MergeAction>"""
+        request = self.session.post(
+            f"{self.protocol}://{self.server}/api/entity/actions/merges", data=payload, headers=headers)
+        if request.status_code == requests.codes.accepted:
+            return request.content.decode('utf-8')
+        elif request.status_code == requests.codes.unauthorized:
+            self.token = self.__token__()
+            return self.merge_folder(folder)
+        else:
+            exception = HTTPException(
+                folder.reference,
+                request.status_code,
+                request.url,
+                "merge_folder",
+                request.content.decode("utf-8"),
+            )
+            logger.error(exception)
+            raise exception
+
+
+    def xml_asset(self, reference: str) -> str:
         """
          Retrieve an Asset by its reference
 
-         Returns Asset
+         Returns an XML document of the full Asset
 
          :param reference:            The unique identifier of the entity
          """
         headers = {HEADER_TOKEN: self.token}
+        params = {"expand": "structure"}
+        request = self.session.get(f'{self.protocol}://{self.server}/api/entity/{IO_PATH}/{reference}', params=params, headers=headers)
+        if request.status_code == requests.codes.ok:
+            xml_response = str(request.content.decode('utf-8'))
+            return xml_response
+        elif request.status_code == requests.codes.unauthorized:
+            self.token = self.__token__()
+            return self.xml_asset(reference)
+        elif request.status_code == requests.codes.not_found:
+            exception = ReferenceNotFoundException(reference, request.status_code, request.url, "xml_asset")
+            logger.error(exception)
+            raise exception
+        else:
+            exception = HTTPException(reference, request.status_code, request.url, "xml_asset",
+                                      request.content.decode('utf-8'))
+            logger.error(exception)
+            raise exception
+
+
+    def asset(self, reference: str) -> Asset:
+
+        """
+         Returns an asset object back by its internal reference identifier
+
+        :param reference: The unique identifier for the asset usually its uuid
+        :type  reference: str
+        :return: The Asset object
+        :rtype: Asset
+        :raises RuntimeError: if the identifier is incorrect
+
+         """
+        headers = {HEADER_TOKEN: self.token}
         request = self.session.get(f'{self.protocol}://{self.server}/api/entity/{IO_PATH}/{reference}', headers=headers)
         if request.status_code == requests.codes.ok:
             xml_response = str(request.content.decode('utf-8'))
@@ -1299,11 +1689,13 @@ class EntityAPI(AuthenticatedAPI):
 
     def folder(self, reference: str) -> Folder:
         """
-         Retrieve a Folder by its reference
-
-         Returns Folder
+         Returns a folder object back by its internal reference identifier
 
-         :param reference:            The unique identifier of the entity
+        :param reference: The unique identifier for the folder usually its uuid
+        :type  reference: str
+        :return: The Folder object
+        :rtype: Folder
+        :raises RuntimeError: if the identifier is incorrect
          """
         headers = {HEADER_TOKEN: self.token}
         request = self.session.get(f'{self.protocol}://{self.server}/api/entity/{SO_PATH}/{reference}', headers=headers)
@@ -1331,11 +1723,13 @@ class EntityAPI(AuthenticatedAPI):
 
     def content_object(self, reference: str) -> ContentObject:
         """
-         Retrieve an ContentObject by its reference
-
-         Returns ContentObject
+         Returns a content object back by its internal reference identifier
 
-         :param reference:            The unique identifier of the entity
+        :param  reference: The unique identifier for the content object usually its uuid
+        :type  reference: str
+        :return: The content object
+        :rtype: ContentObject
+        :raises RuntimeError: if the identifier is incorrect
          """
         headers = {HEADER_TOKEN: self.token}
         request = self.session.get(f'{self.protocol}://{self.server}/api/entity/{CO_PATH}/{reference}', headers=headers)
@@ -1363,11 +1757,12 @@ class EntityAPI(AuthenticatedAPI):
 
     def content_objects(self, representation: Representation) -> list[ContentObject]:
         """
-         Retrieve a list of content objects within a representation
-
-         :param representation:
+         Return a list of content objects for a representation
 
-         :returns list[ContentObject]
+        :param  representation: The representation
+        :type  representation: Representation
+        :return: List of content objects
+        :rtype: list(ContentObject)
 
          """
         headers = {HEADER_TOKEN: self.token}
@@ -1397,13 +1792,17 @@ class EntityAPI(AuthenticatedAPI):
             logger.error(exception)
             raise exception
 
-    def generation(self, url: str) -> Generation:
+    def generation(self, url: str, content_ref: str = None) -> Generation:
+        """
+        Retrieve a list of generation objects
+
+        :param url:
+        :param content_ref:
+
+        :return: Generation
+        :rtype:  Generation
         """
-         Retrieve a list of generation objects
 
-         :param url:
-         :returns Generation
-         """
         headers = {HEADER_TOKEN: self.token}
         request = self.session.get(url, headers=headers)
         if request.status_code == requests.codes.ok:
@@ -1447,7 +1846,11 @@ class EntityAPI(AuthenticatedAPI):
             bitstreams = entity_response.findall(f'./{{{self.entity_ns}}}Bitstreams/{{{self.entity_ns}}}Bitstream')
             bitstream_list = []
             for bit in bitstreams:
-                bitstream_list.append(self.bitstream(bit.text))
+                bs: Bitstream = self.bitstream(bit.text)
+                bs.gen_index = index
+                if content_ref is not None:
+                    bs.co_ref = content_ref
+                bitstream_list.append(bs)
             generation = Generation(strtobool(ge.attrib['original']), strtobool(ge.attrib['active']),
                                     format_group.text if hasattr(format_group, 'text') else None,
                                     effective_date.text if hasattr(effective_date, 'text') else None,
@@ -1532,11 +1935,12 @@ class EntityAPI(AuthenticatedAPI):
 
     def bitstream(self, url: str) -> Bitstream:
         """
-         Retrieve a bitstream by its url
-
-         Returns Bitstream
+         Fetch a bitstream object from the server using its URL
 
-         :param url:
+        :param  url: The URL to the bitstream
+        :type  url: str
+        :return: a bitstream object
+        :rtype: Bitstream
          """
         headers = {HEADER_TOKEN: self.token}
         request = self.session.get(url, headers=headers)
@@ -1572,9 +1976,16 @@ class EntityAPI(AuthenticatedAPI):
     def replace_generation_sync(self, content_object: ContentObject, file_name, fixity_algorithm=None,
                                 fixity_value=None) -> str:
         """
-            Replace the last active generation of a content object with a new digital file.
+        Replace the last active generation of a content object with a new digital file.
 
-            Starts the workflow and blocks until the workflow completes.
+        Starts the workflow and blocks until the workflow completes.
+
+        :param ContentObject content_object: The content object to replace
+        :param str file_name: The path to the new content object
+        :param str fixity_algorithm: Optional fixity algorithm
+        :param str fixity_value: Optional fixity value
+        :return: Completed workflow status
+        :rtype: str
 
         """
 
@@ -1593,7 +2004,14 @@ class EntityAPI(AuthenticatedAPI):
         """
         Replace the last active generation of a content object with a new digital file.
 
-        Starts the workflow and returns
+        Starts the workflow and returns a process ID
+
+        :param ContentObject content_object: The content object to replace
+        :param str file_name: The path to the new content object
+        :param str fixity_algorithm: Optional fixity algorithm
+        :param str fixity_value: Optional fixity value
+        :return:  Process ID
+        :rtype: str
 
         """
         if (self.major_version < 7) and (self.minor_version < 2) and (self.patch_version < 1):
@@ -1647,11 +2065,12 @@ class EntityAPI(AuthenticatedAPI):
 
     def generations(self, content_object: ContentObject) -> list[Generation]:
         """
-        Retrieve list of generations on a content object
+        Return a list of Generation objects for a content object
 
-        Returns list
-
-        :param content_object:
+        :param  content_object: The content object
+        :type  content_object: ContentObject
+        :return: list of generations
+        :rtype: list(Generation)
         """
         headers = {HEADER_TOKEN: self.token}
         request = self.session.get(
@@ -1664,7 +2083,7 @@ class EntityAPI(AuthenticatedAPI):
             result = []
             for g in generations:
                 if hasattr(g, 'text'):
-                    generation = self.generation(g.text)
+                    generation = self.generation(g.text, content_object.reference)
                     generation.asset = content_object.asset
                     generation.content_object = content_object
                     generation.representation_type = content_object.representation_type
@@ -1681,13 +2100,11 @@ class EntityAPI(AuthenticatedAPI):
 
     def bitstreams_for_asset(self, asset: Union[Asset, Entity]) -> Iterable[Bitstream]:
         """
-
-        Return all the bitstreams within an asset.
+        Return all the active bitstreams within an asset.
         This includes all the representations and content objects
 
-
         :param asset:               The asset
-        :return:
+        :return: Iterable
         """
 
         for representation in self.representations(asset):
@@ -1702,10 +2119,14 @@ class EntityAPI(AuthenticatedAPI):
 
     def representations(self, asset: Asset) -> set[Representation]:
         """
-        Retrieve set of representations on an Asset
+        Return a set of representations for the asset
+
+        Representations are used to define how the information object are composed in terms of technology and structure.
 
-        :param asset:   The asset
-        :returns set[Representation]
+        :param asset: The asset containing the required representations
+        :type  asset: Asset
+        :return: Set of Representation objects
+        :rtype: set(Representation)
         """
         headers = {HEADER_TOKEN: self.token}
         if not isinstance(asset, Asset):
@@ -1733,11 +2154,11 @@ class EntityAPI(AuthenticatedAPI):
 
     def remove_thumbnail(self, entity: Entity):
         """
-          remove a thumbnail icon to a folder or asset
+        Remove the thumbnail for the entity to the uploaded image
 
-
-          :param entity:   The Entity
-          """
+        :param entity: The entity with the thumbnail
+        :type  entity: Entity
+        """
         if self.major_version < 7 and self.minor_version < 2:
             raise RuntimeError("Thumbnail API is only available when connected to a v6.2 System")
 
@@ -1760,13 +2181,14 @@ class EntityAPI(AuthenticatedAPI):
             logger.error(exception)
             raise exception
 
+
     def add_access_representation(self, entity: Entity, access_file: str, name: str = "Access"):
         """
-        Add a new representation to an existing asset.
+        Add a new Access representation to an existing asset.
 
-        :param entity:          The existing asset which will receive the new representation
-        :param access_file:     The new digital file
-        :param name:            The name of the new access representation defaults to "Access"
+        :param Entity entity:       The existing asset which will receive the new representation
+        :param str access_file:     The new digital file
+        :param str name:            The name of the new access representation defaults to "Access"
         :return:
         """
 
@@ -1799,12 +2221,14 @@ class EntityAPI(AuthenticatedAPI):
 
     def add_thumbnail(self, entity: Entity, image_file: str):
         """
-         add a thumbnail icon to a folder or asset
+        Set the thumbnail for the entity to the uploaded image
 
+        Supported image formats are png, jpeg, tiff, gif and bmp. The image must be 10MB or less in size.
+
+        :param Entity entity: The entity
+        :param str image_file: The path to the image
+        """
 
-         :param entity:       The Entity
-         :param image_file:   Path to image file
-         """
         if self.major_version < 7 and self.minor_version < 2:
             raise RuntimeError("Thumbnail API is only available when connected to a v6.2 System")
 
@@ -1845,7 +2269,7 @@ class EntityAPI(AuthenticatedAPI):
             params=params, headers=headers)
 
         if request.status_code == requests.codes.ok:
-            pass
+            return None
         elif request.status_code == requests.codes.unauthorized:
             self.token = self.__token__()
             return self._event_actions(entity, maximum=maximum)
@@ -1857,11 +2281,14 @@ class EntityAPI(AuthenticatedAPI):
 
     def all_descendants(self, folder: Union[Folder, Entity] = None) -> Generator[Entity, None, None]:
         """
-         Retrieve list of entities below a folder in the repository
+        Return all child entities recursively of a folder or repository down to the assets using a lazy iterator.
+        The paging is done internally using a default page
+        size of 100 elements. Callers can iterate over the result to get all children with a single call.
 
-         Returns list
+        :param str folder: The parent folder reference, None for the children of root folders
+        :return: A set of entity objects (Folders and Assets)
+        :rtype: set(Entity)
 
-         :param folder: The folder to find children of
          """
         for entity in self.descendants(folder=folder):
             yield entity
@@ -1869,6 +2296,17 @@ class EntityAPI(AuthenticatedAPI):
                 yield from self.all_descendants(folder=entity)
 
     def descendants(self, folder: Union[str, Folder] = None) -> Generator[Entity, None, None]:
+
+        """
+        Return the immediate child entities of a folder using a lazy iterator. The paging is done internally using a default page
+        size of 100 elements. Callers can iterate over the result to get all children with a single call.
+
+        :param str folder: The parent folder reference, None for the children of root folders
+        :return: A set of entity objects (Folders and Assets)
+        :rtype: set(Entity)
+
+        """
+
         maximum = 100
         paged_set = self.children(folder, maximum=maximum, next_page=None)
         for entity in paged_set.results:
@@ -1878,7 +2316,23 @@ class EntityAPI(AuthenticatedAPI):
             for entity in paged_set.results:
                 yield entity
 
+
+
     def children(self, folder: Union[str, Folder] = None, maximum: int = 100, next_page: str = None) -> PagedSet:
+
+        """
+        Return the child entities of a folder one page at a time. The caller is responsible for
+        requesting the next page of results.
+
+        This function is deprecated, use descendants instead as the paging is automatic
+
+        :param str folder: The parent folder reference, None for the children of root folders
+        :param int maximum: The maximum size of the result set in each page
+        :param str next_page: A URL for the next page of results
+        :return: A set of entity objects
+        :rtype: set(Entity)
+        """
+
         headers = {HEADER_TOKEN: self.token}
         data = {'start': str(0), 'max': str(maximum)}
 
@@ -1925,12 +2379,22 @@ class EntityAPI(AuthenticatedAPI):
             self.token = self.__token__()
             return self.children(folder_reference, maximum=maximum, next_page=next_page)
         else:
-            exception = HTTPException(folder.reference, request.status_code, request.url,
+            exception = HTTPException(folder_reference, request.status_code, request.url,
                                       "children", request.content.decode('utf-8'))
             logger.error(exception)
             raise exception
 
     def all_ingest_events(self, previous_days: int = 1) -> Generator:
+        """
+        Returns a list of ingest only events for the user's tenancy
+
+        This method uses a generator function to make repeated calls to the server for every page of results.
+
+        :param int previous_days: The number of days to look back for events
+        :return: A generator of events
+        :rtype: Generator
+        """
+
         self.token = self.__token__()
         previous = datetime.utcnow() - timedelta(days=previous_days)
         from_date = previous.replace(tzinfo=timezone.utc).isoformat()
@@ -1946,6 +2410,14 @@ class EntityAPI(AuthenticatedAPI):
                 yield entity
 
     def all_events(self) -> Generator:
+        """
+        Returns a list of events for the user's tenancy
+
+        This method uses a generator function to make repeated calls to the server for every page of results.
+
+        :return: A generator of events
+        :rtype: Generator
+        """
         self.token = self.__token__()
         paged_set = self._all_events_page()
         for entity in paged_set.results:
@@ -1971,9 +2443,15 @@ class EntityAPI(AuthenticatedAPI):
             actions = entity_response.findall(f'.//{{{self.xip_ns}}}EventAction')
             result_list = []
             for action in actions:
-                entity_ref = action.findall(f'.//{{{self.xip_ns}}}Entity')
-                for refs in entity_ref:
-                    result_list.append(refs.text)
+                item: dict = {}
+                event = action.find(f'.//{{{self.xip_ns}}}Event')
+                event_type = event.attrib["type"]
+                item['EventType'] = event_type
+                entity_date = action.find(f'.//{{{self.xip_ns}}}Date')
+                item['Date'] = entity_date.text
+                entity_ref = action.find(f'.//{{{self.xip_ns}}}Entity')
+                item['Entity'] = entity_ref.text
+                result_list.append(item)
             next_url = entity_response.find(f'.//{{{self.entity_ns}}}Next')
             total_hits = entity_response.find(f'.//{{{self.entity_ns}}}TotalResults')
             has_more = True
@@ -1983,8 +2461,17 @@ class EntityAPI(AuthenticatedAPI):
             else:
                 url = next_url.text
             return PagedSet(result_list, has_more, int(total_hits.text), url)
+        return None
+
+
+
 
     def entity_from_event(self, event_id: str) -> Generator:
+        """
+        Returns an entity from the user's tenancy
+        :rtype: Generator
+        
+        """
         self.token = self.__token__()
         paged_set = self._entity_from_event_page(event_id, 25, None)
         for entity in paged_set.results:
@@ -2007,6 +2494,8 @@ class EntityAPI(AuthenticatedAPI):
             params["from"] = kwargs.get("from_date")
         if "to_date" in kwargs:
             params["to"] = kwargs.get("to_date")
+        if "username" in kwargs:
+            params["username"] = kwargs.get("username")
 
         if next_page is None:
             request = self.session.get(f'{self.protocol}://{self.server}/api/entity/events', params=params,
@@ -2137,6 +2626,16 @@ class EntityAPI(AuthenticatedAPI):
             raise exception
 
     def entity_events(self, entity: Entity) -> Generator:
+        """
+        Returns a list of event actions performed against this entity
+
+        This method uses a generator function to make repeated calls to the server for every page of results.
+
+        :param Entity entity: The entity
+        :return: A list of events
+        :rtype: list
+
+        """
         self.token = self.__token__()
         paged_set = self._entity_events_page(entity)
         for entity in paged_set.results:
@@ -2147,6 +2646,17 @@ class EntityAPI(AuthenticatedAPI):
                 yield entity
 
     def updated_entities(self, previous_days: int = 1) -> Generator:
+        """
+        Fetch a list of entities which have changed (been updated) over the previous n days.
+
+        This method uses a generator function to make repeated calls to the server for every page of results.
+
+        :param int previous_days: The number of days to check for changes.
+        :return: A list of entities
+        :rtype: list
+
+        """
+
         self.token = self.__token__()
         maximum = 25
         paged_set = self._updated_entities_page(previous_days=previous_days, maximum=maximum, next_page=None)
@@ -2204,34 +2714,37 @@ class EntityAPI(AuthenticatedAPI):
             logger.error(exception)
             raise exception
 
-    def delete_asset(self, asset: Asset, operator_comment: str, supervisor_comment: str):
+    def delete_asset(self, asset: Asset, operator_comment: str, supervisor_comment: str, credentials_path: str = "credentials.properties"):
         """
-        Delete an asset from the repository
+        Initiate and approve the deletion of an asset.
 
-        :param asset:               The Asset
-        :param operator_comment:    The operator comment on the deletion
-        :param supervisor_comment:  The supervisor comment on the deletion
+        :param Asset asset: The asset to delete
+        :param str operator_comment: The comments from the operator which are added to the logs
+        :param str supervisor_comment: The comments from the supervisor which are added to the logs
+        :return: The asset reference
+        :rtype: str
         """
         if isinstance(asset, Asset):
-            return self._delete_entity(asset, operator_comment, supervisor_comment)
+            return self._delete_entity(asset, operator_comment, supervisor_comment, credentials_path)
         else:
             raise RuntimeError("delete_asset only deletes assets")
 
-    def delete_folder(self, folder: Folder, operator_comment: str, supervisor_comment: str):
+    def delete_folder(self, folder: Folder, operator_comment: str, supervisor_comment: str, credentials_path: str = "credentials.properties"):
         """
-         Delete an asset from the repository
-
+         Initiate and approve the deletion of a folder.
 
-         :param folder:             The Folder
-         :param operator_comment:   The operator comment on the deletion
-         :param supervisor_comment:  The supervisor comment on the deletion
+        :param Folder folder: The folder to delete
+        :param str operator_comment: The comments from the operator which are added to the logs
+        :param str supervisor_comment: The comments from the supervisor which are added to the logs
+        :return: The folder reference
+        :rtype: str
          """
         if isinstance(folder, Folder):
-            return self._delete_entity(folder, operator_comment, supervisor_comment)
+            return self._delete_entity(folder, operator_comment, supervisor_comment, credentials_path)
         else:
             raise RuntimeError("delete_folder only deletes folders")
 
-    def _delete_entity(self, entity: Entity, operator_comment: str, supervisor_comment: str):
+    def _delete_entity(self, entity: Entity, operator_comment: str, supervisor_comment: str, credentials_path: str = "credentials.properties"):
         """
         Delete an asset from the repository
 
@@ -2242,7 +2755,7 @@ class EntityAPI(AuthenticatedAPI):
 
         # check manager password is available:
         config = configparser.ConfigParser()
-        config.read('credentials.properties', encoding='utf-8')
+        config.read(credentials_path, encoding='utf-8')
         try:
             manager_username = config['credentials']['manager.username']
             manager_password = config['credentials']['manager.password']
@@ -2271,6 +2784,8 @@ class EntityAPI(AuthenticatedAPI):
                     entity_response = xml.etree.ElementTree.fromstring(req.content.decode("utf-8"))
                     status = entity_response.find(".//{http://status.preservica.com}Status")
                     if hasattr(status, 'text'):
+                        if status.text == "COMPLETED":
+                            return entity.reference
                         if status.text == "PENDING":
                             headers = {HEADER_TOKEN: self.manager_token(manager_username, manager_password),
                                        'Content-Type': 'application/xml;charset=UTF-8'}
@@ -2294,7 +2809,7 @@ class EntityAPI(AuthenticatedAPI):
                                        headers=headers)
         elif request.status_code == requests.codes.unauthorized:
             self.token = self.__token__()
-            return self._delete_entity(entity, operator_comment, supervisor_comment)
+            return self._delete_entity(entity, operator_comment, supervisor_comment, credentials_path)
         if request.status_code == requests.codes.unprocessable:
             logger.error(request.content.decode('utf-8'))
             raise RuntimeError(request.status_code, "no active workflow context for full deletion exists in the system")
@@ -2307,3 +2822,4 @@ class EntityAPI(AuthenticatedAPI):
                                   "_delete_entity", request.content.decode('utf-8'))
         logger.error(exception)
         raise exception
+