Merge pull request #1262 from Sage-Bionetworks/SYNPY-1673

[SYNPY-1673] Add JSONSchema documentation, deprecate old classes

Author: andrewelamb

docs/reference/experimental/async/json_schema.md

@@ -0,0 +1,18 @@
+# JSONSchema
+
+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.JSONSchema
+    options:
+        inherited_members: true
+        members:
+        - get_async
+        - store_async
+        - delete_async
+        - get_versions_async
+        - get_body_async
+        - from_uri

docs/reference/experimental/async/schema_organization.md

@@ -0,0 +1,18 @@
+# SchemaOrganization
+
+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.SchemaOrganization
+    options:
+        inherited_members: true
+        members:
+        - get_async
+        - store_async
+        - delete_async
+        - get_json_schemas_async
+        - get_acl_async
+        - update_acl_async

docs/reference/experimental/sync/json_schema.md

@@ -0,0 +1,18 @@
+# JSONSchema
+
+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.JSONSchema
+    options:
+        inherited_members: true
+        members:
+        - get
+        - store
+        - delete
+        - get_versions
+        - get_body
+        - from_uri

docs/reference/experimental/sync/schema_organization.md

@@ -0,0 +1,18 @@
+# SchemaOrganization
+
+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.SchemaOrganization
+    options:
+        inherited_members: true
+        members:
+        - get
+        - store
+        - delete
+        - get_json_schemas
+        - get_acl
+        - update_acl

docs/tutorials/python/json_schema.md

@@ -21,16 +21,17 @@ By the end of this tutorial, you will:
 * You are familiar with [adding annotations](./annotation.md) to synapse entity.
 
 
-## 1. Set Up Synapse Python Client and Retrieve Project
+
+## 1. Set Up Synapse Python Client
 
 ```python
-{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=1-19}
+{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=1-10}
 ```
 
 ## 2. Take a Look at the Constants and Structure of the JSON Schema
 
 ```python
-{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=21-49}
+{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=13-43}
 ```
 
 Derived annotations allow you to define default values for annotations based on schema rules, ensuring consistency and reducing manual input errors. As you can see here, you could use derived annotations to prescribe default annotation values. Please read more about derived annotations [here](https://help.synapse.org/docs/JSON-Schemas.3107291536.html#JSONSchemas-DerivedAnnotations).
@@ -39,12 +40,12 @@ Derived annotations allow you to define default values for annotations based on
 ## 3. Try Create Test Organization and JSON Schema if They Do Not Exist
 Next, try creating a test organization and register a schema if they do not already exist:
 ```python
-{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=51-65}
+{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=46-62}
 ```
 
 Note: If you update your schema, you can re-register it with the organization by assigning a new version number to reflect the changes. Synapse does not allow re-creating a schema with the same version number, so please ensure that each schema version within an organization is unique:
 ```python
-{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=67-99}
+{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=64-97}
 ```
 
 ## 4. Bind the JSON Schema to the Folder
@@ -53,7 +54,7 @@ After creating the organization, you can now bind your json schema to a test fol
 When you bind the schema, you may also include the boolean property `enable_derived_annotations` to have Synapse automatically calculate derived annotations based on the schema:
 
 ```python
-{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=101-108}
+{!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=100-108}
 ```
 
 <details class="example">

docs/tutorials/python/tutorial_scripts/json_schema.py

@@ -3,29 +3,24 @@
 
 import synapseclient
 from synapseclient.core.utils import make_bogus_data_file
-from synapseclient.models import File, Folder
+from synapseclient.models import File, Folder, JSONSchema, Project, SchemaOrganization
 
-# 1. Set up Synapse Python client and retrieve project
+# 1. Set up Synapse Python client
 syn = synapseclient.Synapse()
 syn.login()
 
-# Retrieve test project
-PROJECT_ID = syn.findEntityId(
-    name="My uniquely named project about Alzheimer's Disease"
-)
-
-# Create a test folder for JSON schema experiments
-test_folder = Folder(name="clinical_data_folder", parent_id=PROJECT_ID).store()
-
 # 2. Take a look at the constants and structure of the JSON schema
+# Replace your own project name here
+PROJECT_ENT = Project(name="My uniquely named project about Alzheimer's Disease").get()
+# Replace your own json schema organization name here
 ORG_NAME = "myUniqueAlzheimersResearchOrgTutorial"
 VERSION = "0.0.1"
 NEW_VERSION = "0.0.2"
 
 SCHEMA_NAME = "clinicalObservations"
 
 title = "Alzheimer's Clinical Observation Schema"
-schema = {
+schema_body = {
     "$schema": "http://json-schema.org/draft-07/schema#",
     "$id": "https://example.com/schema/alzheimers_observation.json",
     "title": title,
@@ -48,20 +43,23 @@
 }
 
 # 3. Try create test organization and json schema if they do not exist
-js = syn.service("json_schema")
-all_orgs = js.list_organizations()
-for org in all_orgs:
-    if org["name"] == ORG_NAME:
-        syn.logger.info(f"Organization {ORG_NAME} already exists.")
-        break
-else:
-    syn.logger.info(f"Creating organization {ORG_NAME}.")
-    js.create_organization(ORG_NAME)
-
-my_test_org = js.JsonSchemaOrganization(ORG_NAME)
-test_schema = my_test_org.get_json_schema(SCHEMA_NAME)
-if not test_schema:
-    test_schema = my_test_org.create_json_schema(schema, SCHEMA_NAME, VERSION)
+organization = SchemaOrganization(name=ORG_NAME)
+try:
+    organization.store()
+except Exception as e:
+    organization.get()
+
+schemas = list(organization.get_json_schemas())
+for schema in schemas:
+    print(schema)
+
+schema = JSONSchema(name=SCHEMA_NAME, organization_name=ORG_NAME)
+try:
+    schema.get()
+except Exception as e:
+    schema.store(schema_body=schema_body, version=VERSION)
+
+schema.get_body()
 
 # If you want to make an update, you can re-register your schema with the organization:
 updated_schema = {
@@ -86,9 +84,7 @@
 }
 
 try:
-    new_test_schema = my_test_org.create_json_schema(
-        updated_schema, SCHEMA_NAME, VERSION
-    )
+    schema.store(schema_body=updated_schema, version=VERSION)
 except synapseclient.core.exceptions.SynapseHTTPError as e:
     if e.response.status_code == 400 and "already exists" in e.response.text:
         syn.logger.warning(
@@ -97,10 +93,15 @@
     else:
         raise e
 
+schema.store(schema_body=updated_schema, version=NEW_VERSION)
+schema.get_body(version=VERSION)
 # 4. Bind the JSON schema to the folder
-schema_uri = ORG_NAME + "-" + SCHEMA_NAME + "-" + VERSION
+
+# Create a test folder for JSON schema experiments
+test_folder = Folder(name="test_folder", parent_id=PROJECT_ENT.id).store()
+
 bound_schema = test_folder.bind_schema(
-    json_schema_uri=schema_uri, enable_derived_annotations=True
+    json_schema_uri=schema.uri, enable_derived_annotations=True
 )
 json_schema_version_info = bound_schema.json_schema_version_info
 syn.logger.info("JSON schema was bound successfully. Please see details below:")

mkdocs.yml

@@ -102,6 +102,8 @@ nav:
           - Curator: reference/experimental/sync/curator.md
           - Link: reference/experimental/sync/link_entity.md
           - Functional Interfaces: reference/experimental/functional_interfaces.md
+          - SchemaOrganization: reference/experimental/sync/schema_organization.md
+          - JSONSchema: reference/experimental/sync/json_schema.md
           - Extensions:
               - Curator: reference/extensions/curator.md
           - Asynchronous:
@@ -123,6 +125,8 @@ nav:
               - UserProfile: reference/experimental/async/user_profile.md
               - Curator: reference/experimental/async/curator.md
               - Link: reference/experimental/async/link_entity.md
+              - SchemaOrganization: reference/experimental/async/schema_organization.md
+              - JSONSchema: reference/experimental/async/json_schema.md
           - Mixins:
               - AccessControllable: reference/experimental/mixins/access_controllable.md
               - StorableContainer: reference/experimental/mixins/storable_container.md

synapseclient/client.py

@@ -1627,7 +1627,10 @@ def _print_transfer_progress(self, *args, **kwargs) -> None:
         "json_schema": "JsonSchemaService",
     }
 
-    # TODO: Deprecate method in https://sagebionetworks.jira.com/browse/SYNPY-1583
+    @deprecated(
+        version="4.11.0",
+        reason="To be removed in 5.0.0.",
+    )
     def get_available_services(self) -> typing.List[str]:
         """Get available Synapse services
         This is a beta feature and is subject to change
@@ -1638,7 +1641,10 @@ def get_available_services(self) -> typing.List[str]:
         services = self._services.keys()
         return list(services)
 
-    # TODO: Deprecate method in https://sagebionetworks.jira.com/browse/SYNPY-1583
+    @deprecated(
+        version="4.11.0",
+        reason="To be removed in 5.0.0.",
+    )
     def service(self, service_name: str):
         """Get available Synapse services
         This is a beta feature and is subject to change

synapseclient/models/schema_organization.py

@@ -229,6 +229,12 @@ def update_acl(
 class SchemaOrganization(SchemaOrganizationProtocol):
     """
     Represents an [Organization](https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/schema/Organization.html).
+
+    Attributes:
+        name: The name of the organization
+        id: The ID of the organization
+        created_on: The date this organization was created
+        created_by: The ID of the user that created this organization
     """
 
     name: Optional[str] = None
@@ -347,9 +353,8 @@ async def delete_async(self, synapse_client: Optional["Synapse"] = None) -> None
                 `Synapse.allow_client_caching(False)` this will use the last created
                 instance from the Synapse class constructor
 
-        Example: Delete a SchemaOrganization
-
-            Delete using a name
+        Example: Delete a SchemaOrganization using a name
+             
 
             ```python
             from synapseclient.models import SchemaOrganization
@@ -367,7 +372,8 @@ async def delete_org():
             asyncio.run(delete_org())
             ```
 
-            Delete using an id
+        Example: Delete a SchemaOrganization using an id
+             
 
             ```python
             from synapseclient.models import SchemaOrganization
@@ -383,6 +389,7 @@ async def delete_org():
                 await org.delete_async()
 
             asyncio.run(delete_org())
+            ```
         """
         if not self.id:
             await self.get_async(synapse_client=synapse_client)
@@ -771,8 +778,7 @@ def get_body(
 @async_to_sync
 class JSONSchema(JSONSchemaProtocol):
     """
-    Represents a:
-      [JSON Schema](https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/schema/JsonSchemaInfo.html)
+    Represents a [JSON Schema](https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/schema/JsonSchemaInfo.html)
 
     Attributes:
         name: The name of the schema
@@ -949,7 +955,6 @@ async def store_schema():
         )
         new_version_info = completed_request.new_version_info
         self.organization_id = new_version_info.organization_id
-        self.id = new_version_info.id
         self.created_by = new_version_info.created_by
         self.created_on = new_version_info.created_on
         return self

synapseclient/services/json_schema.py

@@ -4,7 +4,8 @@
 ***********
 
 !!! warning
-    This is a beta implementation and is subject to change.  Use at your own risk.
+    Everything in this module has been deprecated.
+    Use synapseclient.models.SchemaOrganization and synapseclient.models.JSONSchema instead.
 """
 
 from __future__ import annotations
@@ -13,6 +14,8 @@
 from functools import wraps
 from typing import Mapping, Optional, Sequence, Union
 
+from deprecated import deprecated
+
 from synapseclient.client import Synapse
 from synapseclient.core.exceptions import SynapseAuthenticationError, SynapseHTTPError
 from synapseclient.core.utils import id_of
@@ -21,6 +24,10 @@
 DEFAULT_ACCESS = ("CHANGE_PERMISSIONS", "DELETE", "READ", "CREATE", "UPDATE")
 
 
+@deprecated(
+    version="4.11.0",
+    reason="To be removed in 5.0.0. Use synapseclient.models.JSONSchema instead.",
+)
 class JsonSchemaVersion:
     """Json schema version response object
 
@@ -149,6 +156,10 @@ def bind_to_object(self, synapse_id: str):
         return response
 
 
+@deprecated(
+    version="4.11.0",
+    reason="To be removed in 5.0.0. Use synapseclient.models.JSONSchema instead.",
+)
 class JsonSchema:
     """Json schema response object
 
@@ -272,6 +283,10 @@ def create(
         return version
 
 
+@deprecated(
+    version="4.11.0",
+    reason="To be removed in 5.0.0. Use synapseclient.models.SchemaOrganization instead.",
+)
 class JsonSchemaOrganization:
     """Json Schema Organization
 
@@ -484,6 +499,10 @@ def create_json_schema(
         return json_schema
 
 
+@deprecated(
+    version="4.11.0",
+    reason="To be removed in 5.0.0.",
+)
 class JsonSchemaService:
     """Json Schema Service