Add delete_permissions functionality

- Refactor existing integration tests in `test_permissions.py` to improve clarity and structure.
- Introduce a new class `TestDeletePermissions` to cover various scenarios for deleting permissions across entities.
- Implement unit tests for asynchronous permission deletion in `unit_test_permissions_async.py`, ensuring proper handling of errors and entity types.
- Create a new unit test file `unit_test_permissions.py` to test synchronous permission deletion methods.
- Ensure comprehensive coverage for edge cases, including invalid entity types and recursive deletion behavior.

Author: BryanFauble

synapseclient/api/__init__.py

@@ -25,6 +25,7 @@
 from .entity_services import (
     create_access_requirements_if_none,
     delete_entity,
+    delete_entity_acl,
     delete_entity_generated_by,
     get_entities_by_md5,
     get_entity,
@@ -81,6 +82,7 @@
     "put_entity",
     "post_entity",
     "delete_entity",
+    "delete_entity_acl",
     "get_upload_destination",
     "get_upload_destination_location",
     "create_access_requirements_if_none",

synapseclient/api/entity_services.py

@@ -291,6 +291,60 @@ async def main():
         )
 
 
+async def delete_entity_acl(
+    entity_id: str,
+    *,
+    synapse_client: Optional["Synapse"] = None,
+) -> None:
+    """
+    Delete the Access Control List (ACL) for a given Entity.
+
+    By default, Entities such as FileEntity and Folder inherit their permission from
+    their containing Project. For such Entities the Project is the Entity's 'benefactor'.
+    This permission inheritance can be overridden by creating an ACL for the Entity.
+    When this occurs the Entity becomes its own benefactor and all permission are
+    determined by its own ACL.
+
+    If the ACL of an Entity is deleted, then its benefactor will automatically be set
+    to its parent's benefactor. The ACL for a Project cannot be deleted.
+
+    Note: The caller must be granted ACCESS_TYPE.CHANGE_PERMISSIONS on the Entity to
+    call this method.
+
+    Arguments:
+        entity_id: The ID of the entity that should have its ACL deleted.
+        synapse_client: If not passed in and caching was not disabled by
+                `Synapse.allow_client_caching(False)` this will use the last created
+                instance from the Synapse class constructor.
+
+    Example: Delete the ACL for entity `syn123`:
+        This will delete the ACL for the entity, making it inherit permissions from
+        its parent.
+
+        ```python
+        import asyncio
+        from synapseclient import Synapse
+        from synapseclient.api import delete_entity_acl
+
+        syn = Synapse()
+        syn.login()
+
+        async def main():
+            await delete_entity_acl(entity_id="syn123")
+
+        asyncio.run(main())
+        ```
+
+    Returns: None
+    """
+    from synapseclient import Synapse
+
+    client = Synapse.get_client(synapse_client=synapse_client)
+    return await client.rest_delete_async(
+        uri=f"/entity/{entity_id}/acl",
+    )
+
+
 async def get_entity_path(
     entity_id: str,
     *,

synapseclient/client.py

@@ -2725,7 +2725,7 @@ def getChildren(
 
         Arguments:
             parent: An id or an object of a Synapse container or None to retrieve all projects
-            includeTypes: Must be a list of entity types (ie. ["folder","file"]) which can be found [here](http://docs.synapse.org/rest/org/sagebionetworks/repo/model/EntityType.html)
+            includeTypes: Must be a list of entity types (ie. ["folder","file"]) which can be found [here](https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/EntityType.html)
             sortBy: How results should be sorted. Can be NAME, or CREATED_ON
             sortDirection: The direction of the result sort. Can be ASC, or DESC
 
@@ -2795,24 +2795,48 @@ def _getBenefactor(
 
         return entity
 
-    def _getACL(self, entity: Union[Entity, str]) -> Dict[str, Union[str, list]]:
+    def _getACL(
+        self, entity: Union[Entity, str], check_benefactor: bool = True
+    ) -> Dict[str, Union[str, list]]:
         """
         Get the effective Access Control Lists (ACL) for a Synapse Entity.
 
         Arguments:
             entity: A Synapse Entity or Synapse ID
+            check_benefactor: If True (default), check the benefactor for the entity
+                to get the ACL. If False, only check the entity itself.
+                This is useful for checking the ACL of an entity that has local sharing
+                settings, but you want to check the ACL of the entity itself and not
+                the benefactor it may inherit from.
 
         Returns:
             A dictionary of the Entity's ACL
         """
         if hasattr(entity, "getACLURI"):
             uri = entity.getACLURI()
         else:
-            # Get the ACL from the benefactor (which may be the entity itself)
-            benefactor = self._getBenefactor(entity)
-            trace.get_current_span().set_attributes({"synapse.id": benefactor["id"]})
-            uri = "/entity/%s/acl" % (benefactor["id"])
-        return self.restGET(uri)
+            if check_benefactor:
+                # Get the ACL from the benefactor (which may be the entity itself)
+                benefactor = self._getBenefactor(entity)
+                trace.get_current_span().set_attributes(
+                    {"synapse.id": benefactor["id"]}
+                )
+                uri = "/entity/%s/acl" % (benefactor["id"])
+                return self.restGET(uri)
+            else:
+                synid, _ = utils.get_synid_and_version(entity)
+                trace.get_current_span().set_attributes({"synapse.id": synid})
+                uri = "/entity/%s/acl" % (synid)
+                try:
+                    return self.restGET(uri)
+                except SynapseHTTPError as e:
+                    if (
+                        "The requested ACL does not exist. This entity inherits its permissions from:"
+                        in str(e)
+                    ):
+                        # If the entity does not have an ACL, return an empty ACL
+                        return {"resourceAccess": []}
+                    raise e
 
     def _storeACL(
         self, entity: Union[Entity, str], acl: Dict[str, Union[str, list]]
@@ -2889,6 +2913,7 @@ def get_acl(
         self,
         entity: Union[Entity, Evaluation, str, collections.abc.Mapping],
         principal_id: str = None,
+        check_benefactor: bool = True,
     ) -> typing.List[str]:
         """
         Get the [ACL](https://rest-docs.synapse.org/rest/org/
@@ -2898,6 +2923,11 @@ def get_acl(
         Arguments:
             entity:      An Entity or Synapse ID to lookup
             principal_id: Identifier of a user or group (defaults to PUBLIC users)
+            check_benefactor: If True (default), check the benefactor for the entity
+                to get the ACL. If False, only check the entity itself.
+                This is useful for checking the ACL of an entity that has local sharing
+                settings, but you want to check the ACL of the entity itself and not
+                the benefactor it may inherit from.
 
         Returns:
             An array containing some combination of
@@ -2912,7 +2942,7 @@ def get_acl(
             {"synapse.id": id_of(entity), "synapse.principal_id": principal_id}
         )
 
-        acl = self._getACL(entity)
+        acl = self._getACL(entity=entity, check_benefactor=check_benefactor)
 
         team_list = self._find_teams_for_principal(principal_id)
         team_ids = [int(team.id) for team in team_list]