Skip to content

Commit 928e29e

Browse files
BryanFaubleBryanFauble
committed
Update synchronousProtocol and docs
1 parent 9074267 commit 928e29e

20 files changed

+313
-3
lines changed

‎docs/reference/experimental/async/dataset.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ at your own risk.
2828
- get_acl_async
2929
- set_permissions_async
3030
- delete_permissions_async
31+
- list_acl_async
3132
---
3233
[](){ #entity-ref-reference-async }
3334
::: synapseclient.models.EntityRef

‎docs/reference/experimental/async/dataset_collection.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ at your own risk.
2828
- get_acl_async
2929
- set_permissions_async
3030
- delete_permissions_async
31+
- list_acl_async
3132
---
3233
[](){ #entity-ref-dataset-collection-reference-async }
3334
::: synapseclient.models.EntityRef

‎docs/reference/experimental/async/entityview.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ at your own risk.
2525
- get_permissions_async
2626
- set_permissions_async
2727
- delete_permissions_async
28+
- list_acl_async
2829
---
2930

3031
[](){ #view-type-mask-reference }

‎docs/reference/experimental/async/file.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ at your own risk.
2222
- get_acl_async
2323
- set_permissions_async
2424
- delete_permissions_async
25+
- list_acl_async
2526
---
2627
[](){ #filehandle-reference-async }
2728
::: synapseclient.models.file.FileHandle

‎docs/reference/experimental/async/folder.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,3 +19,4 @@ at your own risk.
1919
- get_acl_async
2020
- set_permissions_async
2121
- delete_permissions_async
22+
- list_acl_async

‎docs/reference/experimental/async/materializedview.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,3 +19,4 @@ at your own risk.
1919
- get_acl_async
2020
- set_permissions_async
2121
- delete_permissions_async
22+
- list_acl_async

‎docs/reference/experimental/async/project.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,3 +18,4 @@ at your own risk.
1818
- get_acl_async
1919
- set_permissions_async
2020
- delete_permissions_async
21+
- list_acl_async

‎docs/reference/experimental/async/table.md

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ at your own risk.
2727
- get_acl_async
2828
- set_permissions_async
2929
- delete_permissions_async
30+
- list_acl_async
3031

3132
[](){ #column-reference-async }
3233
::: synapseclient.models.Column
@@ -64,3 +65,141 @@ at your own risk.
6465
::: synapseclient.models.CsvTableDescriptor
6566
[](){ #csv-to-pandas-df-reference-async }
6667
::: synapseclient.models.mixins.table_components.csv_to_pandas_df
68+
69+
## delete_permissions_async Flow Diagram
70+
71+
The following sequence diagram illustrates the complete flow and function calls of the `delete_permissions_async` method:
72+
73+
```mermaid
74+
sequenceDiagram
75+
participant User as User/Client
76+
participant Entity as Entity (File/Folder/Project)
77+
participant Tracker as BenefactorTracker
78+
participant SynClient as Synapse Client
79+
participant API as Synapse API
80+
participant Logger as Logger
81+
82+
User->>Entity: delete_permissions_async(params)
83+
84+
Note over Entity: Parameter Validation & Setup
85+
Entity->>Entity: Validate entity.id exists
86+
Entity->>SynClient: get_client()
87+
88+
alt Project Entity
89+
Entity->>Logger: warn("Project ACL cannot be deleted")
90+
Entity->>Entity: set include_self=False
91+
end
92+
93+
Entity->>Entity: _normalize_target_entity_types()
94+
Entity->>Tracker: create BenefactorTracker()
95+
96+
alt Recursive or Container Content Processing
97+
Entity->>Entity: _collect_entities()
98+
Note over Entity: Gather all entities to process
99+
100+
Entity->>Tracker: track_entity_benefactor(entity_ids)
101+
102+
loop For each entity_id
103+
Tracker->>API: get_entity_benefactor(entity_id)
104+
API-->>Tracker: benefactor_result
105+
end
106+
107+
Note over Tracker: Build benefactor relationships
108+
Tracker->>Tracker: Update entity_benefactors mapping
109+
Tracker->>Tracker: Update benefactor_children mapping
110+
end
111+
112+
alt Dry Run Mode
113+
Entity->>Entity: _build_and_log_dry_run_tree()
114+
Entity->>Logger: Log what would be deleted
115+
Entity-->>User: Return (no actual deletion)
116+
else Actual Deletion
117+
118+
alt Include Self
119+
Entity->>Entity: _delete_current_entity_acl()
120+
121+
Entity->>Tracker: track_entity_benefactor([self.id])
122+
Tracker->>API: get_entity_benefactor(self.id)
123+
API-->>Tracker: benefactor_result
124+
125+
Entity->>Tracker: will_acl_deletion_affect_others(self.id)
126+
Tracker-->>Entity: boolean result
127+
128+
alt Will Affect Others
129+
Entity->>Logger: info("Deleting ACL will affect X entities")
130+
end
131+
132+
Entity->>API: delete_entity_acl(self.id)
133+
134+
alt Success
135+
API-->>Entity: Success
136+
Entity->>Logger: debug("Deleted ACL for entity")
137+
Entity->>Tracker: mark_acl_deleted(self.id)
138+
Tracker->>Tracker: Update benefactor relationships
139+
Tracker-->>Entity: affected_entities list
140+
141+
alt Has Affected Entities
142+
Entity->>Logger: info("ACL deletion caused X entities to inherit from new benefactor")
143+
end
144+
else HTTP Error
145+
API-->>Entity: SynapseHTTPError
146+
alt Already Inherits (403)
147+
Entity->>Logger: debug("Entity already inherits permissions")
148+
else Other Error
149+
Entity->>Entity: raise exception
150+
end
151+
end
152+
end
153+
154+
alt Process Container Contents
155+
Entity->>Entity: _process_container_contents()
156+
157+
alt Process Files
158+
loop For each file
159+
Entity->>Entity: file.delete_permissions_async(recursive=False)
160+
Note right of Entity: Recursive call for each file
161+
end
162+
end
163+
164+
alt Process Folders
165+
Entity->>Entity: _process_folder_permission_deletion()
166+
167+
loop For each folder
168+
alt Recursive Mode
169+
Entity->>Entity: folder.delete_permissions_async(recursive=True)
170+
else Direct Mode
171+
Entity->>Entity: folder.delete_permissions_async(recursive=False)
172+
end
173+
Note right of Entity: Recursive calls for folders
174+
end
175+
end
176+
end
177+
end
178+
179+
Entity-->>User: Complete
180+
181+
Note over User,Logger: Key Features:
182+
Note over User,Logger: • Async operations with asyncio.gather()
183+
Note over User,Logger: • Benefactor relationship tracking
184+
Note over User,Logger: • Recursive processing capabilities
185+
Note over User,Logger: • Dry run mode for preview
186+
Note over User,Logger: • Error handling for inheritance conflicts
187+
Note over User,Logger: • Cascading permission updates
188+
```
189+
190+
### Key Components:
191+
192+
- **Entity**: The primary object (File, Folder, Project) whose permissions are being deleted
193+
- **BenefactorTracker**: Manages benefactor relationships and tracks cascading changes
194+
- **Synapse Client**: Handles API communication and logging
195+
- **Synapse API**: REST endpoints for ACL operations (`delete_entity_acl`, `get_entity_benefactor`)
196+
- **Logger**: Records operations, warnings, and debug information
197+
198+
### Flow Highlights:
199+
200+
1. **Validation Phase**: Parameter validation and client setup
201+
2. **Collection Phase**: Gathering entities for recursive operations
202+
3. **Tracking Phase**: Parallel benefactor relationship discovery
203+
4. **Preview Phase**: Dry run mode shows what would be deleted
204+
5. **Deletion Phase**: Actual ACL deletions with error handling
205+
6. **Cascading Phase**: Updates benefactor relationships for affected entities

‎docs/reference/experimental/async/virtualtable.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,3 +19,4 @@ at your own risk.
1919
- get_acl_async
2020
- set_permissions_async
2121
- delete_permissions_async
22+
- list_acl_async

‎docs/reference/experimental/sync/dataset.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ at your own risk.
2828
- get_acl
2929
- set_permissions
3030
- delete_permissions
31+
- list_acl
3132
---
3233
[](){ #entity-ref-reference-sync }
3334
::: synapseclient.models.EntityRef

0 commit comments

Comments
 (0)