[SYNPY-1795] JSONSchema now saves version info when storing

[andrewelamb]

Problem:

• JSONSchema.store() returns self, but it does not give the version data that Synapse makes during the store (semantic_version, version_id, created_on, created_by). Users cannot get this data from the returned object.(https://sagebionetworks.jira.com/wiki/spaces/DPE/pages/4576444437/Improving+JSONSchema.store+method+output).
• Related problems in the same code:
  • When dry_run=True, Synapse makes the version, puts it in the response, and then deletes it. store_async() still set organization_id, created_by and created_on from this deleted version.
  • store_async() set created_on and created_by from the new version. On JSONSchema, these fields describe the schema, not the version.
  • store_async() set only organization_id. It did not set id or uri. If a user calls get(), changes organization_name, and then calls store(), the object has organization_id from the new schema, but id and uri from the old schema.
  • JSONSchemaVersionInfo.json_schema_uri returned "<org>-<name>-None" when the version has no semantic version.

Solution:

• synapseclient/models/organization.py:
  • New field JSONSchema.last_stored_version_info: Optional[JSONSchemaVersionInfo] = field(default=None, init=False, compare=False). Only store_async() sets it. It holds the version from the most recent store on this instance. It is not guaranteed to be the latest version in Synapse, and get() does not set or clear it.
  • store_async() returns before any instance change when dry_run=True.
  • After a store that is not a dry run, store_async() sets organization_id, id, uri and last_stored_version_info. It does not set created_on or created_by.
  • Docstrings updated: class Attributes:, store_async() (with a new example), and the sync store() on JSONSchemaProtocol.
  • JSONSchema.organization_id annotation changed from Optional[int] to Optional[str], as in the REST spec. The runtime behavior does not change.
• synapseclient/models/mixins/json_schema.py:
  • Class docstring on JSONSchemaVersionInfo. semantic_version changed to Optional[str].
  • json_schema_uri does not add the -None suffix when semantic_version is None.
• synapseclient/models/mixins/__init__.py: export JSONSchemaVersionInfo.
• docs/reference/experimental/mixins/base_json_schema.md: add JSONSchemaVersionInfo.
• synapseclient/extensions/curator/schema_management.py: both examples now print json_schema.last_stored_version_info.semantic_version.

Example:

js = JSONSchema(organization_name="my.org", name="my.schema").store(schema_body=body, version="0.0.1")
print(js.last_stored_version_info.version_id)
print(js.last_stored_version_info.semantic_version)

Testing:

• Unit tests (tests/unit/synapseclient/models/async/unit_test_organization_async.py): 59 pass.

  • Changed: test_store_async_with_schema_body, test_store_async_with_version, test_get_async (asserts that get_async() does not change last_stored_version_info).
  • Changed and parametrized: test_store_async_dry_run (new schema, and schema filled from get with a prior last_stored_version_info). It compares dataclasses.asdict(schema) before and after the dry run.
  • New: test_last_stored_version_info_field_definition (default is None, init=False, compare=False), test_store_async_after_get_updates_identity_keeps_created_values, test_store_async_second_store_replaces_version_info, TestJSONSchemaVersionInfo.test_json_schema_uri.
  • Mock data uses string organization ids, as the real API does.

• Integration tests (tests/integration/synapseclient/models/async/test_organization_async.py): all pass.

  • Changed: test_store_and_get (now stores with version="0.0.1"), test_delete_version (checks semantic_version is "0.0.1" and then "0.0.2").
  • New: test_store_dry_run (the instance does not change, and get_versions_async() finds no versions).

• Integration tests (tests/integration/synapseclient/operations/async/test_factory_operations_store_async.py):

  • Changed: test_store_async_json_schema_basic. It asserted that created_on is set after a store, and store_async() does not set it now. It now checks id, last_stored_version_info, and that semantic_version is "1.0.0".