update docstring to ensure return type gets shown up correctly; fix problem in tutorial; add more dataclasses

Author: linglp

docs/reference/experimental/mixins/base_json_schema.md

@@ -5,3 +5,5 @@
 ::: synapseclient.models.mixins.JSONSchemaValidation
 ::: synapseclient.models.mixins.InvalidJSONSchemaValidation
 ::: synapseclient.models.mixins.JSONSchemaDerivedKeys
+::: synapseclient.models.mixins.ValidationException
+::: synapseclient.models.mixins.CausingException

docs/tutorials/python/json_schema.md

@@ -15,7 +15,7 @@ By the end of this tutorial, you will:
 6. View schema validation statistics and results
 
 ## Prerequisites
-* You have a working [installation](../installation.md)of the Synapse Python Client.
+* You have a working [installation](../installation.md) of the Synapse Python Client.
 * Make sure that you have completed the [Project](./project.md) tutorial, which covers creating and managing projects in Synapse. This is a prerequisite because you need a project to organize and store the folder used in this tutorial.
 * You are familiar with Synapse concepts: [Project](./project.md), [Folder](./folder.md), [File](./file.md).
 * You are familiar with [adding annotations](./annotation.md) to synapse entity.
@@ -42,13 +42,13 @@ Next, try creating a test organization and register a schema if they do not alre
 {!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=51-65}
 ```
 
-Note: If you make an update to your schema, you can re-register your schema with the organization and give it a new version number:
+Note: If you update your schema, you can re-register it with the organization and assign a new version number to reflect the changes:
 ```python
 {!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=67-90}
 ```
 
 ## 4. Bind the JSON Schema to the Folder
-After creating the organization, you can now bind your json schema to a test folder. When you bind a JSON Schema to a project or folder, then all items inside of the project or folder will inherit the schema binding, unless the item has a schema bound to itself.
+After creating the organization, you can now bind your json schema to a test folder. When you bind a JSON Schema to a container entity such as a project or folder, then all items inside of the project or folder will inherit the schema binding, unless the item has a schema bound to itself.
 
 When you bind the schema, you may also include the boolean property `enable_derived_annos` to have Synapse automatically calculate derived annotations based on the schema:
 
@@ -144,7 +144,7 @@ In the synapse web UI, you could also see your invalid annotations being marked
 
 This step is only relevant for container entities, such as a folder or a project.
 
-Try creating a test file locally and store the file in the folder that we created earlier. Then, try adding invalid annotations to a file. This step demonstrates how the files inside a folder also inherit the schema from the parent entity.
+Try creating a test file locally and store the file in the folder that we created earlier. Then, try adding invalid annotations to that file. This step demonstrates how the files inside a folder also inherit the schema from the parent entity.
 ```python
 {!docs/tutorials/python/tutorial_scripts/json_schema.py!lines=121-146}
 ```

docs/tutorials/python/tutorial_scripts/json_schema.py

@@ -12,7 +12,7 @@
 
 # Retrieve test project
 PROJECT_ID = syn.findEntityId(
-    name="My uniquely named project about Alzheimer's Disease 2"
+    name="My uniquely named project about Alzheimer's Disease"
 )
 
 # Create a test folder for JSON schema experiments

synapseclient/models/mixins/__init__.py

@@ -4,12 +4,14 @@
 from synapseclient.models.mixins.asynchronous_job import AsynchronousCommunicator
 from synapseclient.models.mixins.json_schema import (
     BaseJSONSchema,
+    CausingException,
     ContainerEntityJSONSchema,
     InvalidJSONSchemaValidation,
     JSONSchemaBinding,
     JSONSchemaDerivedKeys,
     JSONSchemaValidation,
     JSONSchemaValidationStatistics,
+    ValidationException,
 )
 from synapseclient.models.mixins.storable_container import StorableContainer
 
@@ -24,4 +26,6 @@
     "InvalidJSONSchemaValidation",
     "JSONSchemaDerivedKeys",
     "JSONSchemaValidationStatistics",
+    "ValidationException",
+    "CausingException",
 ]

synapseclient/models/mixins/json_schema.py

@@ -203,11 +203,14 @@ async def bind_schema_async(
         Bind a JSON schema to the entity.
 
         Arguments:
-            json_schema_uri (str): The URI of the JSON schema to bind to the entity.
-            enable_derived_annos (bool, optional): If true, enable derived annotations. Defaults to False.
-            synapse_client (Optional[Synapse], optional): The Synapse client instance. If not provided,
+            json_schema_uri: The URI of the JSON schema to bind to the entity.
+            enable_derived_annos: If true, enable derived annotations. Defaults to False.
+            synapse_client: The Synapse client instance. If not provided,
                 the last created instance from the Synapse class constructor will be used.
 
+        Returns:
+            An object containing details about the JSON schema binding.
+
         Example: Using this function
             Binding JSON schema to a folder or a file
 
@@ -280,8 +283,6 @@ async def bind_schema_to_file():
                     return bound_schema_file
                 asyncio.run(bind_schema_to_file())
             ```
-        Returns:
-            JSONSchemaBinding: An object containing details about the JSON schema binding.
         """
         response = await bind_json_schema_to_entity(
             synapse_id=self.id,
@@ -315,10 +316,14 @@ async def get_schema_async(
     ) -> JSONSchemaBinding:
         """
         Get the JSON schema bound to the entity.
+
         Arguments:
-            synapse_client (Optional[Synapse], optional): The Synapse client instance. If not provided,
+            synapse_client: The Synapse client instance. If not provided,
                 the last created instance from the Synapse class constructor will be used.
 
+        Returns:
+            An object containing details about the bound JSON schema.
+
         Example: Using this function
             Retrieving the bound JSON schema from a folder or file
 
@@ -332,7 +337,8 @@ async def get_schema_async(
 
                 # Define Project and JSON schema info
                 PROJECT_ID = syn.findEntityId(name="test_json_schema_project") #replace with your project name
-                ORG_NAME = "UniqueOrg" # replace with your organization name                SCHEMA_NAME = "myTestSchema" # replace with your schema name
+                ORG_NAME = "UniqueOrg" # replace with your organization name
+                SCHEMA_NAME = "myTestSchema" # replace with your schema name
                 VERSION = "0.0.1"
                 SCHEMA_URI = f"{ORG_NAME}-{SCHEMA_NAME}-{VERSION}"
 
@@ -404,8 +410,6 @@ async def get_bound_schema_from_file():
                 bound_schema_file = asyncio.run(get_bound_schema_from_file())
                 print("Bound schema from file retrieved:", bound_schema_file)
             ```
-        Returns:
-            JSONSchemaBinding: An object containing details about the bound JSON schema.
         """
         response = await get_json_schema_from_entity(
             synapse_id=self.id, synapse_client=synapse_client
@@ -440,7 +444,7 @@ async def unbind_schema_async(
         Unbind the JSON schema bound to the entity.
 
         Arguments:
-            synapse_client (Optional[Synapse], optional): The Synapse client instance. If not provided,
+            synapse_client: The Synapse client instance. If not provided,
                 the last created instance from the Synapse class constructor will be used.
 
         Example: Using this function
@@ -542,6 +546,9 @@ async def validate_schema_async(
             synapse_client (Optional[Synapse], optional): The Synapse client instance. If not provided,
                 the last created instance from the Synapse class constructor will be used.
 
+        Returns:
+            The validation results.
+
         Example: Using this function
             Validating a folder or file against the bound JSON schema
 
@@ -635,8 +642,6 @@ async def validate_file_with_json_schema():
                 validation_response_file = asyncio.run(validate_file_with_json_schema())
                 print('validation response:', validation_response_file)
             ```
-        Returns:
-            Union[JSONSchemaValidation, InvalidJSONSchemaValidation]: The validation results.
         """
         response = await validate_entity_with_json_schema(
             synapse_id=self.id, synapse_client=synapse_client
@@ -706,6 +711,9 @@ async def get_schema_derived_keys_async(
             synapse_client (Optional[Synapse], optional): The Synapse client instance. If not provided,
                 the last created instance from the Synapse class constructor will be used.
 
+        Returns:
+            An object containing the derived keys for the entity.
+
         Example: Using this function
             Retrieving derived keys from a folder or file
 
@@ -797,8 +805,6 @@ async def get_schema_derived_keys_from_file():
                     return derived_keys_file
                 print('Derived keys from file:', asyncio.run(get_schema_derived_keys_from_file()))
             ```
-        Returns:
-            JSONSchemaDerivedKeys: An object containing the derived keys for the entity.
         """
         response = await get_json_schema_derived_keys(
             synapse_id=self.id, synapse_client=synapse_client
@@ -824,6 +830,9 @@ async def get_schema_validation_statistics_async(
             synapse_client (Optional[Synapse], optional): The Synapse client instance. If not provided,
                 the last created instance from the Synapse class constructor will be used.
 
+        Returns:
+            The validation statistics.
+
         Example: Using this function
             Retrieving validation statistics for a folder
 
@@ -894,8 +903,6 @@ async def get_validation_statistics():
                 stats = asyncio.run(get_validation_statistics())
                 print('Validation statistics:', stats)
             ```
-        Returns:
-            JSONSchemaValidationStatistics: The validation statistics.
         """
         response = await get_json_schema_validation_statistics(
             synapse_id=self.id, synapse_client=synapse_client
@@ -919,6 +926,10 @@ async def get_invalid_validation_async(
             synapse_client (Optional[Synapse], optional): The Synapse client instance. If not provided,
                 the last created instance from the Synapse class constructor will be used.
 
+        Yields:
+            An object containing the validation response, all validation messages,
+                                         and the validation exception details.
+
         Example: Using this function
             Retrieving invalid validation results for a folder
 
@@ -987,10 +998,6 @@ async def get_invalid_validation_async():
                     async for child in gen:
                         print(child)
             ```
-
-        Yields:
-            InvalidJSONSchemaValidation: An object containing the validation response, all validation messages,
-                                         and the validation exception details.
         """
         gen = get_invalid_json_schema_validation(
             synapse_client=synapse_client, synapse_id=self.id
@@ -1050,6 +1057,10 @@ def get_invalid_validation(
             synapse_client (Optional[Synapse], optional): The Synapse client instance. If not provided,
                 the last created instance from the Synapse class constructor will be used.
 
+        Yields:
+            An object containing the validation response, all validation messages,
+                                         and the validation exception details.
+
         Example: Using this function
             Retrieving invalid validation results for a folder
 
@@ -1117,10 +1128,6 @@ async def bind_json_schema():
                 for child in invalid_results:
                     print(child)
             ```
-
-        Yields:
-            InvalidJSONSchemaValidation: An object containing the validation response, all validation messages,
-                                         and the validation exception details.
         """
         gen = get_invalid_json_schema_validation_sync(
             synapse_client=synapse_client, synapse_id=self.id