[SYNPY-1623] Factory function for get and creation of link entity (#1243)

* Create factory operations for get, as well as creating the Link Entity class

Author: BryanFauble

.github/workflows/build.yml

@@ -49,6 +49,7 @@ jobs:
     needs: [pre-commit]
 
     strategy:
+      fail-fast: false
       matrix:
         os: [ubuntu-22.04, macos-13, windows-2022]
 

.gitignore

@@ -33,3 +33,4 @@ coverage.xml
 .ipynb_checkpoints
 *.ipynb
 .env
+test.synapseConfig

docs/reference/experimental/async/factory_operations.md

@@ -0,0 +1,30 @@
+# Synapse Factory Operations
+
+Contained within this file are experimental interfaces for working with the Synapse Python
+Client. Unless otherwise noted these interfaces are subject to change at any time. Use
+at your own risk.
+
+## API Reference
+
+[](){ #factory-get-async }
+::: synapseclient.operations.get_async
+
+[](){ #factory-file-options-async }
+::: synapseclient.operations.FileOptions
+    options:
+      inherited_members: true
+
+[](){ #factory-activity-options-async }
+::: synapseclient.operations.ActivityOptions
+    options:
+      inherited_members: true
+
+[](){ #factory-table-options-async }
+::: synapseclient.operations.TableOptions
+    options:
+      inherited_members: true
+
+[](){ #factory-link-options-async }
+::: synapseclient.operations.LinkOptions
+    options:
+      inherited_members: true

docs/reference/experimental/async/link_entity.md

@@ -0,0 +1,16 @@
+[](){ #link-async }
+# Link
+
+Contained within this file are experimental interfaces for working with the Synapse Python
+Client. Unless otherwise noted these interfaces are subject to change at any time. Use
+at your own risk.
+
+## API Reference
+
+::: synapseclient.models.Link
+    options:
+      inherited_members: true
+      members:
+        - get_async
+        - store_async
+---

docs/reference/experimental/sync/factory_operations.md

@@ -0,0 +1,30 @@
+# Synapse Factory Operations
+
+Contained within this file are experimental interfaces for working with the Synapse Python
+Client. Unless otherwise noted these interfaces are subject to change at any time. Use
+at your own risk.
+
+## API Reference
+
+[](){ #factory-get-sync }
+::: synapseclient.operations.get
+
+[](){ #factory-file-options-sync }
+::: synapseclient.operations.FileOptions
+    options:
+      inherited_members: true
+
+[](){ #factory-activity-options-sync }
+::: synapseclient.operations.ActivityOptions
+    options:
+      inherited_members: true
+
+[](){ #factory-table-options-sync }
+::: synapseclient.operations.TableOptions
+    options:
+      inherited_members: true
+
+[](){ #factory-link-options-sync }
+::: synapseclient.operations.LinkOptions
+    options:
+      inherited_members: true

docs/reference/experimental/sync/link_entity.md

@@ -0,0 +1,16 @@
+[](){ #link-sync }
+# Link
+
+Contained within this file are experimental interfaces for working with the Synapse Python
+Client. Unless otherwise noted these interfaces are subject to change at any time. Use
+at your own risk.
+
+## API Reference
+
+::: synapseclient.models.Link
+    options:
+      inherited_members: true
+      members:
+        - get
+        - store
+---

mkdocs.yml

@@ -80,6 +80,7 @@ nav:
       - Core: reference/core.md
       - REST Apis: reference/rest_apis.md
       - Experimental:
+          - Factory Operations: reference/experimental/sync/factory_operations.md
           - Agent: reference/experimental/sync/agent.md
           - Project: reference/experimental/sync/project.md
           - Folder: reference/experimental/sync/folder.md
@@ -94,8 +95,10 @@ nav:
           - Activity: reference/experimental/sync/activity.md
           - Team: reference/experimental/sync/team.md
           - UserProfile: reference/experimental/sync/user_profile.md
+          - Link: reference/experimental/sync/link_entity.md
           - Functional Interfaces: reference/experimental/functional_interfaces.md
           - Asynchronous:
+              - Factory Operations: reference/experimental/async/factory_operations.md
               - Agent: reference/experimental/async/agent.md
               - Project: reference/experimental/async/project.md
               - Folder: reference/experimental/async/folder.md
@@ -110,6 +113,7 @@ nav:
               - Activity: reference/experimental/async/activity.md
               - Team: reference/experimental/async/team.md
               - UserProfile: reference/experimental/async/user_profile.md
+              - Link: reference/experimental/async/link_entity.md
           - Mixins:
               - AccessControllable: reference/experimental/mixins/access_controllable.md
               - StorableContainer: reference/experimental/mixins/storable_container.md

synapseclient/api/__init__.py

@@ -31,6 +31,7 @@
     delete_entity_generated_by,
     delete_entity_provenance,
     get_activity,
+    get_child,
     get_children,
     get_entities_by_md5,
     get_entity,
@@ -167,6 +168,7 @@
     "get_activity",
     "create_activity",
     "update_activity",
+    "get_child",
     "get_children",
     "post_entity_acl",
     "put_entity_acl",

synapseclient/api/entity_factory.py

@@ -340,6 +340,7 @@ class type. This will also download the file if `download_file` is set to True.
         EntityView,
         File,
         Folder,
+        Link,
         MaterializedView,
         Project,
         SubmissionView,
@@ -377,6 +378,7 @@ class type. This will also download the file if `download_file` is set to True.
         concrete_types.MATERIALIZED_VIEW: MaterializedView,
         concrete_types.SUBMISSION_VIEW: SubmissionView,
         concrete_types.VIRTUAL_TABLE: VirtualTable,
+        concrete_types.LINK_ENTITY: Link,
     }
 
     entity_class = ENTITY_TYPE_MAP.get(entity["concreteType"], None)

synapseclient/api/entity_services.py

@@ -1264,6 +1264,99 @@ async def main():
         yield child
 
 
+async def get_child(
+    entity_name: str,
+    parent_id: Optional[str] = None,
+    *,
+    synapse_client: Optional["Synapse"] = None,
+) -> Optional[str]:
+    """
+    Retrieve an entityId for a given parent ID and entity name.
+
+    This service can also be used to lookup projectId by setting the parentId to None.
+
+    This calls to the REST API found here: <https://rest-docs.synapse.org/rest/POST/entity/child.html>
+
+    Arguments:
+        entity_name: The name of the entity to find
+        parent_id: The parent ID. Set to None when looking up a project by name.
+        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.
+
+    Returns:
+        The entity ID if found, None if not found.
+
+    Raises:
+        SynapseHTTPError: If there's an error other than "not found" (404).
+
+    Example: Getting a child entity ID
+        Find a file by name within a folder:
+
+        ```python
+        import asyncio
+        from synapseclient import Synapse
+        from synapseclient.api import get_child
+
+        syn = Synapse()
+        syn.login()
+
+        async def main():
+            entity_id = await get_child(
+                entity_name="my_file.txt",
+                parent_id="syn123456"
+            )
+            if entity_id:
+                print(f"Found entity: {entity_id}")
+            else:
+                print("Entity not found")
+
+        asyncio.run(main())
+        ```
+
+    Example: Getting a project by name
+        Find a project by name:
+
+        ```python
+        import asyncio
+        from synapseclient import Synapse
+        from synapseclient.api import get_child
+
+        syn = Synapse()
+        syn.login()
+
+        async def main():
+            project_id = await get_child(
+                entity_name="My Project",
+                parent_id=None  # None for projects
+            )
+            if project_id:
+                print(f"Found project: {project_id}")
+
+        asyncio.run(main())
+        ```
+    """
+    from synapseclient import Synapse
+
+    client = Synapse.get_client(synapse_client=synapse_client)
+
+    entity_lookup_request = {
+        "parentId": parent_id,
+        "entityName": entity_name,
+    }
+
+    try:
+        response = await client.rest_post_async(
+            uri="/entity/child", body=json.dumps(entity_lookup_request)
+        )
+        return response.get("id")
+    except SynapseHTTPError as e:
+        if e.response.status_code == 404:
+            # Entity not found
+            return None
+        raise
+
+
 async def set_entity_permissions(
     entity_id: str,
     principal_id: Optional[str] = None,