[SYNPY-1671] Adding store & delete factory method, find_entity_id, is_synapse_id, onweb, md5_query (#1300)

* Adding delete factory method

* [SYNPY-1674] Creating functions for additional Synapse class methods, find_entity_id, is_synapse_id, onweb, md5_query (#1301)

Author: BryanFauble

docs/explanations/structuring_your_project.md

@@ -108,6 +108,6 @@ Manifests are crucial for the organization of your data in Synapse. In the **hie
 
 ### An example: ELITE portal
 
-Synapse Project: https://www.synapse.org/#!Synapse:syn27229419/wiki/623145
+Synapse Project: https://www.synapse.org/Synapse:syn27229419/wiki/623145
 
 This project powers the elite portal: https://eliteportal.synapse.org/. More information about the studies and the files can be found in this portal.

docs/reference/experimental/async/factory_operations.md

@@ -28,3 +28,49 @@ at your own risk.
 ::: synapseclient.operations.LinkOptions
     options:
       inherited_members: true
+
+[](){ #factory-delete-async }
+::: synapseclient.operations.delete_async
+
+[](){ #factory-store-async }
+::: synapseclient.operations.store_async
+
+[](){ #factory-store-file-options-async }
+::: synapseclient.operations.StoreFileOptions
+    options:
+      inherited_members: true
+
+[](){ #factory-store-container-options-async }
+::: synapseclient.operations.StoreContainerOptions
+    options:
+      inherited_members: true
+
+[](){ #factory-store-table-options-async }
+::: synapseclient.operations.StoreTableOptions
+    options:
+      inherited_members: true
+
+[](){ #factory-store-json-schema-options-async }
+::: synapseclient.operations.StoreJSONSchemaOptions
+    options:
+      inherited_members: true
+
+[](){ #factory-store-grid-options-async }
+::: synapseclient.operations.StoreGridOptions
+    options:
+      inherited_members: true
+
+[](){ #factory-find-entity-id-async }
+::: synapseclient.operations.find_entity_id_async
+
+[](){ #factory-is-synapse-id-async }
+::: synapseclient.operations.is_synapse_id_async
+
+[](){ #factory-onweb-async }
+::: synapseclient.operations.onweb_async
+
+[](){ #factory-md5-query-async }
+::: synapseclient.operations.md5_query_async
+
+[](){ #factory-print-entity-async }
+::: synapseclient.operations.print_entity_async

docs/reference/experimental/sync/factory_operations.md

@@ -28,3 +28,49 @@ at your own risk.
 ::: synapseclient.operations.LinkOptions
     options:
       inherited_members: true
+
+[](){ #factory-delete-sync }
+::: synapseclient.operations.delete
+
+[](){ #factory-store-sync }
+::: synapseclient.operations.store
+
+[](){ #factory-store-file-options-sync }
+::: synapseclient.operations.StoreFileOptions
+    options:
+      inherited_members: true
+
+[](){ #factory-store-container-options-sync }
+::: synapseclient.operations.StoreContainerOptions
+    options:
+      inherited_members: true
+
+[](){ #factory-store-table-options-sync }
+::: synapseclient.operations.StoreTableOptions
+    options:
+      inherited_members: true
+
+[](){ #factory-store-json-schema-options-sync }
+::: synapseclient.operations.StoreJSONSchemaOptions
+    options:
+      inherited_members: true
+
+[](){ #factory-store-grid-options-sync }
+::: synapseclient.operations.StoreGridOptions
+    options:
+      inherited_members: true
+
+[](){ #factory-find-entity-id-sync }
+::: synapseclient.operations.find_entity_id
+
+[](){ #factory-is-synapse-id-sync }
+::: synapseclient.operations.is_synapse_id
+
+[](){ #factory-onweb-sync }
+::: synapseclient.operations.onweb
+
+[](){ #factory-md5-query-sync }
+::: synapseclient.operations.md5_query
+
+[](){ #factory-print-entity-sync }
+::: synapseclient.operations.print_entity

docs/tutorials/home.md

@@ -7,7 +7,7 @@ organizing, and discussing your scientific research.
 
 ## What do you need to get started?
 First off, to browse Synapse and access its most basic level of functionality, you
-will need to [register for a Synapse account](https://www.synapse.org/#!RegisterAccount:0).
+will need to [register for a Synapse account](https://www.synapse.org/RegisterAccount:0).
 In doing so, you will be agreeing to the
 [Synapse Code of Conduct and Synapse Terms and Conditions of Use](https://help.synapse.org/docs/Synapse-Governance.2004255211.html).
 
@@ -38,7 +38,7 @@ conditions for use.
 
 To work with data of your own or your team’s, you must become a
 [certified user](https://help.synapse.org/docs/Synapse-User-Account-Types.2007072795.html#SynapseUserAccountTypes-CertifiedUser). To become certified, you must pass a
-[certification quiz](https://www.synapse.org/#!Quiz:Certification),
+[certification quiz](https://www.synapse.org/Quiz:Certification),
  which will ask you about information that can be found throughout this documentation site.
 
 

docs/tutorials/python/project.md

@@ -30,7 +30,7 @@ project = Project(name="My uniquely named project about Alzheimer's Disease")
 project.store()
 ```
 
-Now that you have created your project you are able to inspect the project in the [synapse web UI](https://www.synapse.org/#!Profile:v/projects/created_by_me).
+Now that you have created your project you are able to inspect the project in the [synapse web UI](https://www.synapse.org/Profile:v/projects/created_by_me).
 
 
 

synapseclient/api/__init__.py

@@ -55,6 +55,7 @@
     get_entity_type,
     get_upload_destination,
     get_upload_destination_location,
+    is_synapse_id,
     post_entity,
     post_entity_acl,
     put_entity,
@@ -162,6 +163,7 @@
     get_user_profile_by_username,
     is_user_certified,
 )
+from .web_services import open_entity_in_browser
 from .wiki_services import (
     delete_wiki_page,
     get_attachment_handles,
@@ -229,6 +231,9 @@
     "put_entity_acl",
     "set_entity_permissions",
     "update_entity_acl",
+    "is_synapse_id",
+    # web_services
+    "open_entity_in_browser",
     # configuration_services
     "get_config_file",
     "get_config_section_dict",

synapseclient/api/entity_services.py

@@ -1656,3 +1656,73 @@ async def main():
     else:
         # Entity inherits from a benefactor, use POST to create new ACL
         return await client.rest_post_async(uri=uri, body=json.dumps(acl))
+
+
+async def is_synapse_id(
+    syn_id: str,
+    *,
+    synapse_client: Optional["Synapse"] = None,
+) -> bool:
+    """
+    Check if given synID is valid (attached to actual entity).
+
+    Arguments:
+        syn_id: A Synapse ID to validate.
+        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:
+        True if the Synapse ID is valid and exists.
+
+    Example: Validating a Synapse ID
+        Check if a Synapse ID exists:
+
+        ```python
+        import asyncio
+        from synapseclient import Synapse
+        from synapseclient.api import is_synapse_id
+
+        syn = Synapse()
+        syn.login()
+
+        async def main():
+            if await is_synapse_id("syn123456"):
+                print("Valid Synapse ID")
+            else:
+                print("Invalid or non-existent Synapse ID")
+
+        asyncio.run(main())
+        ```
+    """
+    from synapseclient.core.exceptions import (
+        SynapseAuthenticationError,
+        SynapseFileNotFoundError,
+    )
+
+    if not isinstance(syn_id, str):
+        return False
+
+    try:
+        await get_entity(entity_id=syn_id, synapse_client=synapse_client)
+    except SynapseFileNotFoundError:
+        return False
+    except (SynapseHTTPError, SynapseAuthenticationError) as err:
+        # Extract status code
+        status = None
+        if hasattr(err, "__context__") and hasattr(err.__context__, "response"):
+            status = err.__context__.response.status_code
+        elif hasattr(err, "response"):
+            status = err.response.status_code
+
+        # If we can't determine the status, re-raise the exception
+        if status is None:
+            raise
+
+        if status in (400, 404):
+            return False
+        # Valid ID but user lacks permission or is not logged in
+        elif status == 403:
+            return True
+        raise
+    return True

synapseclient/api/web_services.py

@@ -0,0 +1,113 @@
+"""This module provides web browser-related services for Synapse entities."""
+
+import webbrowser
+from typing import TYPE_CHECKING, Optional, Union
+
+from synapseclient.core.utils import id_of
+
+if TYPE_CHECKING:
+    from synapseclient import Synapse
+    from synapseclient.models import (
+        Dataset,
+        DatasetCollection,
+        EntityView,
+        File,
+        Folder,
+        Link,
+        MaterializedView,
+        Project,
+        RecordSet,
+        SubmissionView,
+        Table,
+        VirtualTable,
+    )
+
+
+async def open_entity_in_browser(
+    entity: Union[
+        str,
+        "Dataset",
+        "DatasetCollection",
+        "EntityView",
+        "File",
+        "Folder",
+        "Link",
+        "MaterializedView",
+        "Project",
+        "RecordSet",
+        "SubmissionView",
+        "Table",
+        "VirtualTable",
+    ],
+    subpage_id: Optional[str] = None,
+    *,
+    synapse_client: Optional["Synapse"] = None,
+) -> str:
+    """
+    Open up a browser window to the entity page or wiki-subpage.
+
+    Arguments:
+        entity: Either an Entity object (Dataset, DatasetCollection, EntityView,
+            File, Folder, Link, MaterializedView, Project, RecordSet,
+            SubmissionView, Table, VirtualTable) or a Synapse ID string.
+        subpage_id: (Optional) ID of one of the wiki's sub-pages.
+        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 URL that was opened in the browser.
+
+    Example: Opening an entity in browser
+        Open an entity's page in the default web browser:
+
+        ```python
+        import asyncio
+        from synapseclient import Synapse
+        from synapseclient.api import open_entity_in_browser
+
+        syn = Synapse()
+        syn.login()
+
+        async def main():
+            url = await open_entity_in_browser("syn123456")
+            print(f"Opened: {url}")
+
+        asyncio.run(main())
+        ```
+
+    Example: Opening a wiki subpage
+        Open a specific wiki subpage:
+
+        ```python
+        import asyncio
+        from synapseclient import Synapse
+        from synapseclient.api import open_entity_in_browser
+
+        syn = Synapse()
+        syn.login()
+
+        async def main():
+            url = await open_entity_in_browser("syn123456", subpage_id="12345")
+            print(f"Opened wiki subpage: {url}")
+
+        asyncio.run(main())
+        ```
+    """
+    from synapseclient import Synapse
+
+    client = Synapse.get_client(synapse_client=synapse_client)
+
+    synapse_id = id_of(entity)
+
+    # Construct the URL
+    portal_endpoint = client.portalEndpoint
+    if subpage_id is None:
+        url = f"{portal_endpoint}/Synapse:{synapse_id}"
+    else:
+        url = f"{portal_endpoint}/Wiki:{synapse_id}/ENTITY/{subpage_id}"
+
+    # Open in browser
+    webbrowser.open(url)
+
+    return url