[SYNPY-1244] Add delete permissions/acl functionality (#1200)

* Add delete_permissions functionality for both sync and async functions to all models which allow setting permissions via the mixin

Author: BryanFauble

docs/reference/experimental/async/dataset.md

@@ -24,9 +24,10 @@ at your own risk.
             - delete_column
             - reorder_column
             - rename_column
-            - get_permissions
-            - get_acl
-            - set_permissions
+            - get_permissions_async
+            - get_acl_async
+            - set_permissions_async
+            - delete_permissions_async
 ---
 [](){ #entity-ref-reference-async }
 ::: synapseclient.models.EntityRef

docs/reference/experimental/async/dataset_collection.md

@@ -24,9 +24,10 @@ at your own risk.
             - delete_column
             - reorder_column
             - rename_column
-            - get_permissions
-            - get_acl
-            - set_permissions
+            - get_permissions_async
+            - get_acl_async
+            - set_permissions_async
+            - delete_permissions_async
 ---
 [](){ #entity-ref-dataset-collection-reference-async }
 ::: synapseclient.models.EntityRef

docs/reference/experimental/async/entityview.md

@@ -24,6 +24,7 @@ at your own risk.
             - get_acl_async
             - get_permissions_async
             - set_permissions_async
+            - delete_permissions_async
 ---
 
 [](){ #view-type-mask-reference }

docs/reference/experimental/async/file.md

@@ -21,6 +21,7 @@ at your own risk.
         - get_permissions_async
         - get_acl_async
         - set_permissions_async
+        - delete_permissions_async
 ---
 [](){ #filehandle-reference-async }
 ::: synapseclient.models.file.FileHandle

docs/reference/experimental/async/folder.md

@@ -18,3 +18,4 @@ at your own risk.
         - get_permissions_async
         - get_acl_async
         - set_permissions_async
+        - delete_permissions_async

docs/reference/experimental/async/materializedview.md

@@ -15,6 +15,7 @@ at your own risk.
             - delete_async
             - query_async
             - query_part_mask_async
-            - get_permissions
-            - get_acl
-            - set_permissions
+            - get_permissions_async
+            - get_acl_async
+            - set_permissions_async
+            - delete_permissions_async

docs/reference/experimental/async/project.md

@@ -17,3 +17,4 @@ at your own risk.
         - get_permissions_async
         - get_acl_async
         - set_permissions_async
+        - delete_permissions_async

docs/reference/experimental/async/table.md

@@ -23,9 +23,10 @@ at your own risk.
         - delete_column
         - add_column
         - reorder_column
-        - get_permissions
-        - get_acl
-        - set_permissions
+        - get_permissions_async
+        - get_acl_async
+        - set_permissions_async
+        - delete_permissions_async
 
 [](){ #column-reference-async }
 ::: synapseclient.models.Column

docs/reference/experimental/async/virtualtable.md

@@ -15,6 +15,7 @@ at your own risk.
             - delete_async
             - query_async
             - query_part_mask_async
-            - get_permissions
-            - get_acl
-            - set_permissions
+            - get_permissions_async
+            - get_acl_async
+            - set_permissions_async
+            - delete_permissions_async

docs/reference/experimental/sync/dataset.md

@@ -27,6 +27,7 @@ at your own risk.
             - get_permissions
             - get_acl
             - set_permissions
+            - delete_permissions
 ---
 [](){ #entity-ref-reference-sync }
 ::: synapseclient.models.EntityRef

docs/reference/experimental/sync/dataset_collection.md

@@ -27,6 +27,7 @@ at your own risk.
             - get_permissions
             - get_acl
             - set_permissions
+            - delete_permissions
 ---
 [](){ #entity-ref-dataset-collection-reference-sync }
 ::: synapseclient.models.EntityRef

docs/reference/experimental/sync/entityview.md

@@ -24,6 +24,7 @@ at your own risk.
             - get_acl
             - get_permissions
             - set_permissions
+            - delete_permissions
 ---
 
 [](){ #view-type-mask-reference-sync }

docs/reference/experimental/sync/file.md

@@ -31,6 +31,7 @@ at your own risk.
         - get_permissions
         - get_acl
         - set_permissions
+        - delete_permissions
 ---
 [](){ #filehandle-reference-sync }
 ::: synapseclient.models.file.FileHandle

docs/reference/experimental/sync/folder.md

@@ -29,3 +29,4 @@ at your own risk.
         - get_permissions
         - get_acl
         - set_permissions
+        - delete_permissions

docs/reference/experimental/sync/materializedview.md

@@ -19,3 +19,4 @@ at your own risk.
             - get_permissions
             - get_acl
             - set_permissions
+            - delete_permissions

docs/reference/experimental/sync/project.md

@@ -28,3 +28,4 @@ at your own risk.
         - get_permissions
         - get_acl
         - set_permissions
+        - delete_permissions

docs/reference/experimental/sync/submissionview.md

@@ -23,3 +23,4 @@ at your own risk.
             - get_acl
             - get_permissions
             - set_permissions
+            - delete_permissions

docs/reference/experimental/sync/table.md

@@ -37,6 +37,7 @@ at your own risk.
         - get_permissions
         - get_acl
         - set_permissions
+        - delete_permissions
 
 [](){ #column-reference-sync }
 ::: synapseclient.models.Column

docs/reference/experimental/sync/virtualtable.md

@@ -18,3 +18,4 @@ at your own risk.
             - get_permissions
             - get_acl
             - set_permissions
+            - delete_permissions

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,49 @@ 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()
+            return self.restGET(uri)
         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 +2914,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 +2924,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 +2943,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]