[SYNPY-1590] Implement core functionality of Submission(+Status, +Bundle) OOP model

setup.cfg

@@ -126,7 +126,7 @@ docs =
     mkdocs>=1.5.3
     mkdocs-material>=9.4.14
     mkdocstrings>=0.24.0
-    mkdocstrings-python>=1.8.0
+    mkdocstrings-python>=2.0.0
     termynal>=0.11.1
     mkdocs-open-in-new-tab~=1.0.3
     markdown-include~=0.8.1

synapseclient/annotations.py

@@ -72,7 +72,8 @@
 
 import collections
 import datetime
-import typing
+from logging import Logger
+from typing import Any, Callable, Mapping, Optional, Union
 
 from deprecated import deprecated
 
@@ -95,8 +96,8 @@ def raise_anno_type_error(anno_type: str):
     raise ValueError(f"Unknown type in annotations response: {anno_type}")
 
 
-ANNO_TYPE_TO_FUNC: typing.Dict[
-    str, typing.Callable[[str], typing.Union[str, int, float, datetime.datetime]]
+ANNO_TYPE_TO_FUNC: dict[
+    str, Callable[[str], Union[str, int, float, datetime.datetime]]
 ] = collections.defaultdict(
     raise_anno_type_error,
     {
@@ -109,7 +110,7 @@ def raise_anno_type_error(anno_type: str):
 )
 
 
-def is_synapse_annotations(annotations: typing.Mapping) -> bool:
+def is_synapse_annotations(annotations: Mapping) -> bool:
     """Tests if the given object is a Synapse-style Annotations object.
 
     Arguments:
@@ -125,7 +126,7 @@ def is_synapse_annotations(annotations: typing.Mapping) -> bool:
     return annotations.keys() >= {"id", "etag", "annotations"}
 
 
-def _annotation_value_list_element_type(annotation_values: typing.List):
+def _annotation_value_list_element_type(annotation_values: list):
     if not annotation_values:
         raise ValueError("annotations value list can not be empty")
 
@@ -228,6 +229,127 @@ def to_submission_status_annotations(annotations, is_private=True):
     return synapseAnnos
 
 
+def to_submission_annotations(
+    id: Union[str, int],
+    etag: str,
+    annotations: dict[str, Any],
+    logger: Optional[Logger] = None,
+) -> dict[str, Any]:
+    """
+    Converts a normal dictionary to the format used for submission annotations, which is different from the format
+    used to annotate entities.
+
+    This function creates the proper nested structure that includes id, etag, and annotations in the format
+    expected by the submissionAnnotations field of a SubmissionStatus request body.
+
+    Arguments:
+        id: The unique ID of the submission being annotated.
+        etag: The etag of the submission status for optimistic concurrency control.
+        annotations: A normal Python dictionary comprised of the annotations to be added.
+        logger: An optional logger instance. If not provided, a default logger will be used.
+
+    Returns:
+        A dictionary in the format expected by submissionAnnotations with nested structure containing
+        id, etag, and annotations object with type/value format.
+
+    Example: Using this function
+        Converting annotations to submission format
+
+            from synapseclient.annotations import to_submission_annotations
+
+            # Input annotations
+            my_annotations = {
+                "score": 85,
+                "feedback": "Good work!"
+            }
+
+            # Convert to submission annotations format
+            submission_annos = to_submission_annotations(
+                id="9999999",
+                etag="abc123",
+                annotations=my_annotations,
+                is_private=True
+            )
+
+            # Result:
+            # {
+            #     "id": "9999999",
+            #     "etag": "abc123",
+            #     "annotations": {
+            #         "score": {"type": "INTEGER", "value": [85]},
+            #         "feedback": {"type": "STRING", "value": ["Good work!"]},
+            #     }
+            # }
+
+    Note:
+        This function is designed specifically for the submissionAnnotations field format,
+        which is part of the creation of a SubmissionStatus request body:
+
+        <https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/annotation/v2/Annotations.html>
+    """
+    # Create the base structure
+    submission_annos = {"id": str(id), "etag": str(etag), "annotations": {}}
+
+    # Convert each annotation to the proper nested format
+    for key, value in annotations.items():
+        # Ensure value is a list
+        if not isinstance(value, list):
+            value_list = [value]
+        else:
+            value_list = value
+
+        # Warn about empty annotation values and skip them
+        if not value_list:
+            if logger:
+                logger.warning(
+                    f"Annotation '{key}' has an empty value list and will be skipped"
+                )
+            else:
+                from synapseclient import Synapse
+
+                client = Synapse.get_client()
+                client.logger.warning(
+                    f"Annotation '{key}' has an empty value list and will be skipped"
+                )
+            continue
+
+        # Determine type based on the first element
+        first_element = value_list[0]
+
+        if isinstance(first_element, str):
+            submission_annos["annotations"][key] = {
+                "type": "STRING",
+                "value": value_list,
+            }
+        elif isinstance(first_element, bool):
+            # Convert booleans to lowercase strings
+            submission_annos["annotations"][key] = {
+                "type": "STRING",
+                "value": [str(v).lower() for v in value_list],
+            }
+        elif isinstance(first_element, int):
+            submission_annos["annotations"][key] = {"type": "LONG", "value": value_list}
+        elif isinstance(first_element, float):
+            submission_annos["annotations"][key] = {
+                "type": "DOUBLE",
+                "value": value_list,
+            }
+        elif is_date(first_element):
+            # Convert dates to unix timestamps
+            submission_annos["annotations"][key] = {
+                "type": "LONG",
+                "value": [to_unix_epoch_time(v) for v in value_list],
+            }
+        else:
+            # Default to string representation
+            submission_annos["annotations"][key] = {
+                "type": "STRING",
+                "value": [str(v) for v in value_list],
+            }
+
+    return submission_annos
+
+
 # TODO: this should accept a status object and return its annotations or an empty dict if there are none
 def from_submission_status_annotations(annotations) -> dict:
     """
@@ -347,9 +469,9 @@ class Annotations(dict):
 
     def __init__(
         self,
-        id: typing.Union[str, int, Entity],
+        id: Union[str, int, Entity],
         etag: str,
-        values: typing.Dict = None,
+        values: dict = None,
         **kwargs,
     ):
         """
@@ -404,7 +526,7 @@ def etag(self, value):
         self._etag = str(value)
 
 
-def to_synapse_annotations(annotations: Annotations) -> typing.Dict[str, typing.Any]:
+def to_synapse_annotations(annotations: Annotations) -> dict[str, Any]:
     """Transforms a simple flat dictionary to a Synapse-style Annotation object. See
     the [Synapse API](https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/annotation/v2/Annotations.html)
     documentation for more information on Synapse-style Annotation objects.
@@ -459,9 +581,7 @@ def _convert_to_annotations_list(annotations):
     return nested_annos
 
 
-def from_synapse_annotations(
-    raw_annotations: typing.Dict[str, typing.Any]
-) -> Annotations:
+def from_synapse_annotations(raw_annotations: dict[str, Any]) -> Annotations:
     """Transforms a Synapse-style Annotation object to a simple flat dictionary.
 
     Arguments:

synapseclient/api/__init__.py

@@ -64,15 +64,28 @@
     update_entity_acl,
 )
 from .evaluation_services import (
+    batch_update_submission_statuses,
+    cancel_submission,
     create_or_update_evaluation,
+    create_submission,
     delete_evaluation,
+    delete_submission,
     get_all_evaluations,
+    get_all_submission_statuses,
     get_available_evaluations,
     get_evaluation,
     get_evaluation_acl,
     get_evaluation_permissions,
+    get_evaluation_submission_bundles,
+    get_evaluation_submissions,
     get_evaluations_by_project,
+    get_submission,
+    get_submission_count,
+    get_submission_status,
+    get_user_submission_bundles,
+    get_user_submissions,
     update_evaluation_acl,
+    update_submission_status,
 )
 from .file_services import (
     AddPartResponse,
@@ -282,4 +295,18 @@
     "get_evaluation_acl",
     "update_evaluation_acl",
     "get_evaluation_permissions",
+    # submission-related evaluation services
+    "create_submission",
+    "get_submission",
+    "get_evaluation_submissions",
+    "get_user_submissions",
+    "get_submission_count",
+    "delete_submission",
+    "cancel_submission",
+    "get_submission_status",
+    "update_submission_status",
+    "get_all_submission_statuses",
+    "batch_update_submission_statuses",
+    "get_evaluation_submission_bundles",
+    "get_user_submission_bundles",
 ]