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

[jaymedina]

Problem:

This work is part of the ongoing effort to refactor the Synapse Python Client using object-oriented principles, following the pattern established in https://sagebionetworks.jira.com/browse/SYNPY-1418.

We currently to not have an OOP model for communications to the Evaluation API services provided by the Synapse platform.

Solution:

The work has been separated into 3 feature branches, with the *main branch being intended for merge into develop and the other 2 branches merging into *main when ready.

The acceptance criteria has been split up into these 3 branches in the following way.

---

Branch: synpy-1589-evaluation-model-main

• async integration tests are introduced

---

Branch: synpy-1590-submission-model-functionality

Evaluation API Design Summary

The data model of the Evaluation API is built around around two primary objects:

• Evaluation: The primary object representing a Synapse Evaluation. Access to Evaluations is governed by an Access Control List (ACL).
• Submission: A user in a Synapse Evaluation can submit a Synapse Entity as Submission to that Evaluation. Submission data is owned by the parent Evaluation, and is immutable.

The data model includes additional objects to support scoring of Submissions and convenient data access:

• SubmissionStatus: An object used to track scoring information for a single Submission. This object is intended to be modified by the users (or test harnesses) managing the Evaluation.
• SubmissionBundle: A convenience object to transport a Submission and its accompanying SubmissionStatus in a single web service call.
• SubmissionView (already implemented): A submission view can be created using the Entity Services providing as scope a list of evaluation ids, in order to query the set of submissions through the Table Query Services. Annotations set in the submissionAnnotations property of a SubmissionStatus can be exposed in the view.

Source: https://rest-docs.synapse.org/rest/#org.sagebionetworks.repo.web.controller.EvaluationController

The design for the python client tools for communicating with this API will take into consideration the Evaluation API design summary above. This implementation will look like so:

• The required API services that interact with the Submission(/Status/Bundle) object will be exposed under evaluation_services.py

Submission operations:
Create submission: https://rest-docs.synapse.org/rest/POST/evaluation/submission.html
Get submission: https://rest-docs.synapse.org/rest/GET/evaluation/submission/subId.html
Get submissions for evaluation: https://rest-docs.synapse.org/rest/GET/evaluation/evalId/submission/all.html
Get user submissions: https://rest-docs.synapse.org/rest/GET/evaluation/evalId/submission.html
Get submission count: https://rest-docs.synapse.org/rest/GET/evaluation/evalId/submission/count.html
Delete submission: https://rest-docs.synapse.org/rest/DELETE/evaluation/submission/subId.html
Cancel submission: https://rest-docs.synapse.org/rest/PUT/evaluation/submission/subId/cancellation.html

SubmissionStatus operations:
Get submission status: https://rest-docs.synapse.org/rest/GET/evaluation/submission/subId/status.html
Update submission status: https://rest-docs.synapse.org/rest/PUT/evaluation/submission/subId/status.html
Get all submission statuses: https://rest-docs.synapse.org/rest/GET/evaluation/evalId/submission/status/all.html
Batch update statuses: https://rest-docs.synapse.org/rest/PUT/evaluation/evalId/statusBatch.html

Bundle operations:
Get submission bundles: https://rest-docs.synapse.org/rest/GET/evaluation/evalId/submission/bundle/all.html
Get user submission bundles: https://rest-docs.synapse.org/rest/GET/evaluation/evalId/submission/bundle.html

• The following dataclasses are created in their own *.py files for discoverability:

Submission
SubmissionStatus
SubmissionBundle

• Submission will inherit SubmissionStatus
• SubmissionBundle will inherit Submission and SubmissionStatus
• async/sync methods are introduced to the DataClass that wrap around the new services
• async/sync methods' docstrings are updated with example use-cases
• async/sync Integration tests are patched/introduced

---

Branch: synpy-1590-submission-model-docs

• The old models are deprecated
• Our Synapse Python Client documentation (using mkdocs) is updated for these models
• A tutorial is made for popular use-cases of these models

Testing:

• Passing unit tests
• Passing integration tests
• Passing documentation build
• Running through the tutorial presents no issues

[thomasyu888]

Great work starting this, let's get the evaluation work across the finish line first so we don't spread ourselves too thin.