diff --git a/docs/css/custom.css b/docs/css/custom.css index a9ad98683..af1c6d107 100644 --- a/docs/css/custom.css +++ b/docs/css/custom.css @@ -1,31 +1,3 @@ -[data-md-color-scheme="default"] { - --doc-symbol-attribute-fg-color: #953800; - --doc-symbol-function-fg-color: #8250df; - --doc-symbol-method-fg-color: #8250df; - --doc-symbol-class-fg-color: #0550ae; - --doc-symbol-module-fg-color: #5cad0f; - - --doc-symbol-attribute-bg-color: #9538001a; - --doc-symbol-function-bg-color: #8250df1a; - --doc-symbol-method-bg-color: #8250df1a; - --doc-symbol-class-bg-color: #0550ae1a; - --doc-symbol-module-bg-color: #5cad0f1a; -} - -[data-md-color-scheme="slate"] { - --doc-symbol-attribute-fg-color: #953800; - --doc-symbol-function-fg-color: #8250df; - --doc-symbol-method-fg-color: #8250df; - --doc-symbol-class-fg-color: #0550ae; - --doc-symbol-module-fg-color: #5cad0f; - - --doc-symbol-attribute-bg-color: #9538001a; - --doc-symbol-function-bg-color: #8250df1a; - --doc-symbol-method-bg-color: #8250df1a; - --doc-symbol-class-bg-color: #0550ae1a; - --doc-symbol-module-bg-color: #5cad0f1a; -} - /* Indentation. */ div.doc-contents { padding-left: 25px; @@ -35,37 +7,3 @@ div.doc-contents { .md-typeset table tbody { font-size: .7rem } - -/* Adds icons in front of `class`, `attribute`, and `function` */ -div.doc-class .doc-heading:first-of-type::before { - color: var(--doc-symbol-class-fg-color); - background-color: var(--doc-symbol-class-bg-color); - border-radius: .1rem; - font-size: .85em; - padding: 0 .3em; - font-weight: bold; - content: "class"; - margin-right: 5px; -} - -div.doc-attribute .doc-heading:first-of-type::before { - color: var(--doc-symbol-attribute-fg-color); - background-color: var(--doc-symbol-attribute-bg-color); - border-radius: .1rem; - font-size: .85em; - padding: 0 .3em; - font-weight: bold; - content: "attr"; - margin-right: 5px; -} - -div.doc-function .doc-heading:first-of-type::before { - color: var(--doc-symbol-function-fg-color); - background-color: var(--doc-symbol-function-bg-color); - border-radius: .1rem; - font-size: .85em; - padding: 0 .3em; - font-weight: bold; - content: "func"; - margin-right: 5px; -} diff --git a/mkdocs.yml b/mkdocs.yml index 3dd6df1d4..768dcd0e3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -130,15 +130,24 @@ plugins: default_handler: python handlers: python: + import: + - https://docs.python.org/3/objects.inv + - https://python-markdown.github.io/objects.inv options: members_order: source show_if_no_docstring: False show_root_heading: True show_category_heading: True + show_symbol_type_heading: True + show_symbol_type_toc: True docstring_style: google docstring_section_style: spacy filters: - "!^_" + separate_signature: True + show_signature_annotations: True + signature_crossrefs: True + - autorefs - termynal: prompt_literal_start: diff --git a/setup.cfg b/setup.cfg index 8eca3513b..ec1e3655a 100644 --- a/setup.cfg +++ b/setup.cfg @@ -114,7 +114,7 @@ docs = mkdocs>=1.5.3 mkdocs-material>=9.4.14 mkdocstrings>=0.24.0 - mkdocstrings-python>=1.7.5 + mkdocstrings-python>=1.8.0 termynal>=0.11.1 mkdocs-open-in-new-tab~=1.0.3 markdown-include~=0.8.1 diff --git a/synapseclient/services/json_schema.py b/synapseclient/services/json_schema.py index a3f537b84..037f48db0 100644 --- a/synapseclient/services/json_schema.py +++ b/synapseclient/services/json_schema.py @@ -3,7 +3,7 @@ JSON Schema *********** -.. warning:: +!!! warning This is a beta implementation and is subject to change. Use at your own risk. """ @@ -11,7 +11,7 @@ import json from functools import wraps -from typing import Mapping, Sequence, Union +from typing import Mapping, Optional, Sequence, Union from synapseclient.client import Synapse from synapseclient.core.exceptions import SynapseAuthenticationError, SynapseHTTPError @@ -24,19 +24,17 @@ class JsonSchemaVersion: """Json schema version response object - :param organization: JSON schema organization. - :type organization: JsonSchemaOrganization - :param name: Name of the JSON schema. - :type name: str - :param semantic_version: Version of JSON schema. Defaults to None. - :type semantic_version: str, optional + Attributes: + organization: Json Schema Organization + name: Name of the JSON schema. + semantic_version: Version of JSON schema. Defaults to None. """ def __init__( self, organization: JsonSchemaOrganization, name: str, - semantic_version: str = None, + semantic_version: Optional[str] = None, ) -> None: self.organization = organization self.name = name @@ -105,11 +103,9 @@ def create( ): """Create JSON schema version - :param json_schema_body: JSON schema body - :type json_schema_body: dict - :param dry_run: Do not store to Synapse. Defaults to False. - :type dry_run: bool, optional - :returns: JSON Schema + Arguments: + json_schema_body: JSON schema body + dry_run: Do not store to Synapse. Defaults to False. """ uri = f"{self.organization.name}-{self.name}" if self.semantic_version: @@ -144,9 +140,10 @@ def expand(self): def bind_to_object(self, synapse_id: str): """Bind schema to an entity - :param synapse_id: Synapse Id to bind json schema to. - :type synapse_id: str + Arguments: + synapse_id: Synapse Id to bind json schema to. """ + self.must_get() response = self.service.bind_json_schema_to_entity(synapse_id, self.uri) return response @@ -155,10 +152,9 @@ def bind_to_object(self, synapse_id: str): class JsonSchema: """Json schema response object - :param organization: JSON schema organization. - :type organization: JsonSchemaOrganization - :param name: Name of the JSON schema. - :type name: str + Attributes: + organization: JSON schema organization. + name: Name of the JSON schema. """ def __init__(self, organization: JsonSchemaOrganization, name: str) -> None: @@ -255,12 +251,13 @@ def create( ): """Create JSON schema - :param json_schema_body: JSON schema body - :type json_schema_body: dict - :param semantic_version: Version of JSON schema. Defaults to None. - :type semantic_version: str, optional - :param dry_run: Do not store to Synapse. Defaults to False. - :type dry_run: bool, optional + Arguments: + json_schema_body: JSON schema body + semantic_version: Version of JSON schema. Defaults to None. + dry_run: Do not store to Synapse. Defaults to False. + + Returns: + JSON schema """ uri = f"{self.organization.name}-{self.name}" if semantic_version: @@ -278,8 +275,8 @@ def create( class JsonSchemaOrganization: """Json Schema Organization - :param name: Name of JSON schema organization - :type name: str + Attributes: + name: Name of JSON schema organization """ def __init__(self, name: str) -> None: @@ -381,12 +378,10 @@ def set_acl( ): """Set ACL of JSON schema organization - :param principal_ids: List of Synapse user or team ids. - :type principal_ids: list - :param access_type: Access control list. Defaults to ["CHANGE_PERMISSIONS", "DELETE", "READ", "CREATE", "UPDATE"]. - :type access_type: list, optional - :param etag: Etag. Defaults to None. - :type etag: str, optional + Arguments: + principal_ids: List of Synapse user or team ids. + access_type: Access control list. Defaults to ["CHANGE_PERMISSIONS", "DELETE", "READ", "CREATE", "UPDATE"]. Defaults to DEFAULT_ACCESS. + etag: Etag. Defaults to None. """ self.must_get() if etag is None: @@ -407,12 +402,10 @@ def update_acl( ): """Update ACL of JSON schema organization - :param principal_ids: List of Synapse user or team ids. - :type principal_ids: list - :param access_type: Access control list. Defaults to ["CHANGE_PERMISSIONS", "DELETE", "READ", "CREATE", "UPDATE"]. - :type access_type: list, optional - :param etag: Etag. Defaults to None. - :type etag: str, optional + Arguments: + principal_ids: List of Synapse user or team ids. + access_type: Access control list. Defaults to ["CHANGE_PERMISSIONS", "DELETE", "READ", "CREATE", "UPDATE"]. Defaults to DEFAULT_ACCESS. + etag: Etag. Defaults to None. """ self.must_get() principal_ids = set(principal_ids) @@ -446,10 +439,9 @@ def list_json_schemas(self): def get_json_schema(self, json_schema_name: str, raw: bool = False): """Get JSON schema - :param json_schema_name: Name of JSON schema. - :type json_schema_name: str - :param raw: Return raw JSON schema. Default is False. - :type raw: bool, optional + Arguments: + json_schema_name: Name of JSON schema. + raw: Return raw JSON schema. Defaults to False. """ self.must_get() if json_schema_name not in self._json_schemas: @@ -469,14 +461,11 @@ def create_json_schema( ): """Create JSON schema - :param json_schema_body: JSON schema dict - :type json_schema_body: dict - :param name: Name of JSON schema. Defaults to None. - :type name: str, optional - :param semantic_version: Version of JSON schema. Defaults to None. - :type semantic_version: str, optional - :param dry_run: Don't store to Synapse. Defaults to False. - :type dry_run: bool, optional + Arguments: + json_schema_body: JSON schema dict + name: Name of JSON schema. Defaults to None. + semantic_version: Version of JSON schema. Defaults to None. + dry_run: Don't store to Synapse. Defaults to False. """ if name: uri = f"{self.name}-{name}" @@ -498,8 +487,8 @@ def create_json_schema( class JsonSchemaService: """Json Schema Service - :param synapse: Synapse connection - :type synapse: Synapse + Attributes + synapse: Synapse connection """ def __init__(self, synapse: Synapse = None) -> None: @@ -550,8 +539,8 @@ def wrapper(self, *args, **kwargs): def create_organization(self, organization_name: str): """Create a new organization - :param organization_name: JSON schema organization name - :type organization_name: str + Arguments: + organization_name: JSON schema organization name """ request_body = {"organizationName": organization_name} response = self.synapse.restPOST( @@ -563,8 +552,8 @@ def create_organization(self, organization_name: str): def get_organization(self, organization_name: str): """Get a organization - :param organization_name: JSON schema organization name - :type organization_name: str + Arguments: + organization_name: JSON schema organization name """ response = self.synapse.restGET( f"/schema/organization?name={organization_name}" @@ -583,8 +572,8 @@ def list_organizations(self): def delete_organization(self, organization_id: str): """Delete organization - :param organization_id: JSON schema organization Id - :type organization_id: str + Arguments: + organization_id: JSON schema organization Id """ response = self.synapse.restDELETE(f"/schema/organization/{organization_id}") return response @@ -593,8 +582,8 @@ def delete_organization(self, organization_id: str): def get_organization_acl(self, organization_id: str): """Get ACL associated with Organization - :param organization_id: JSON schema organization Id - :type organization_id: str + Arguments: + organization_id: JSON schema organization Id """ response = self.synapse.restGET(f"/schema/organization/{organization_id}/acl") return response @@ -606,14 +595,12 @@ def update_organization_acl( resource_access: Sequence[Mapping[str, Sequence[str]]], etag: str, ): - """Get ACL associated with Organization + """Update ACL associated with Organization - :param organization_id: JSON schema organization Id - :type organization_id: str - :param resource_access: Resource access array - :type resource_access: list - :param etag: Etag - :type etag: str + Arguments: + organization_id: JSON schema organization Id + resource_access: Resource access array + etag: Etag """ request_body = {"resourceAccess": resource_access, "etag": etag} response = self.synapse.restPUT( @@ -624,8 +611,8 @@ def update_organization_acl( def list_json_schemas(self, organization_name: str): """List JSON schemas for an organization - :param organization_name: JSON schema organization name - :type organization_name: str + Arguments: + organization_name: JSON schema organization name """ request_body = {"organizationName": organization_name} response = self.synapse._POST_paginated("/schema/list", request_body) @@ -634,10 +621,9 @@ def list_json_schemas(self, organization_name: str): def list_json_schema_versions(self, organization_name: str, json_schema_name: str): """List version information for each JSON schema - :param organization_name: JSON schema organization name - :type organization_name: str - :param json_schema_name: JSON schema name - :type json_schema_name: str + Arguments: + organization_name: JSON schema organization name + json_schema_name: JSON schema name """ request_body = { "organizationName": organization_name, @@ -650,10 +636,9 @@ def list_json_schema_versions(self, organization_name: str, json_schema_name: st def create_json_schema(self, json_schema_body: dict, dry_run: bool = False): """Create a JSON schema - :param json_schema_body: JSON schema body - :type json_schema_body: dict - :param dry_run: Don't store to Synapse. Default to False. - :type dry_run: bool, optional + Arguments: + json_schema_body: JSON schema body + dry_run: Don't store to Synapse. Default to False. """ request_body = { "concreteType": "org.sagebionetworks.repo.model.schema.CreateSchemaRequest", @@ -666,8 +651,8 @@ def create_json_schema(self, json_schema_body: dict, dry_run: bool = False): def get_json_schema_body(self, json_schema_uri: str): """Get registered JSON schema with its $id - :param json_schema_uri: JSON schema URI - :type json_schema_uri: str + Arguments: + json_schema_uri: JSON schema URI """ response = self.synapse.restGET(f"/schema/type/registered/{json_schema_uri}") return response @@ -676,8 +661,8 @@ def get_json_schema_body(self, json_schema_uri: str): def delete_json_schema(self, json_schema_uri: str): """Delete the given schema using its $id - :param json_schema_uri: JSON schema URI - :type json_schema_uri: str + Arguments: + json_schema_uri: JSON schema URI """ response = self.synapse.restDELETE(f"/schema/type/registered/{json_schema_uri}") return response @@ -686,8 +671,8 @@ def delete_json_schema(self, json_schema_uri: str): def json_schema_validation(self, json_schema_uri: str): """Use a JSON schema for validation - :param json_schema_uri: JSON schema URI - :type json_schema_uri: str + Arguments: + json_schema_uri: JSON schema URI """ request_body = { "concreteType": ( @@ -704,10 +689,9 @@ def json_schema_validation(self, json_schema_uri: str): def bind_json_schema_to_entity(self, synapse_id: str, json_schema_uri: str): """Bind a JSON schema to an entity - :param synapse_id: Synapse Id - :type synapse_id: str - :param json_schema_uri: JSON schema URI - :type json_schema_uri: str + Arguments: + synapse_id: Synapse Id + json_schema_uri: JSON schema URI """ request_body = {"entityId": synapse_id, "schema$id": json_schema_uri} response = self.synapse.restPUT( @@ -719,8 +703,8 @@ def bind_json_schema_to_entity(self, synapse_id: str, json_schema_uri: str): def get_json_schema_from_entity(self, synapse_id: str): """Get bound schema from entity - :param synapse_id: Synapse Id - :type synapse_id: str + Arguments: + synapse_id: Synapse Id """ response = self.synapse.restGET(f"/entity/{synapse_id}/schema/binding") return response @@ -729,8 +713,8 @@ def get_json_schema_from_entity(self, synapse_id: str): def delete_json_schema_from_entity(self, synapse_id: str): """Delete bound schema from entity - :param synapse_id: Synapse Id - :type synapse_id: str + Arguments: + synapse_id: Synapse Id """ response = self.synapse.restDELETE(f"/entity/{synapse_id}/schema/binding") return response @@ -739,8 +723,8 @@ def delete_json_schema_from_entity(self, synapse_id: str): def validate_entity_with_json_schema(self, synapse_id: str): """Get validation results of an entity against bound JSON schema - :param synapse_id: Synapse Id - :type synapse_id: str + Arguments: + synapse_id: Synapse Id """ response = self.synapse.restGET(f"/entity/{synapse_id}/schema/validation") return response @@ -750,8 +734,8 @@ def get_json_schema_validation_statistics(self, synapse_id: str): """Get the summary statistic of json schema validation results for a container entity - :param synapse_id: Synapse Id - :type synapse_id: str + Arguments: + synapse_id: Synapse Id """ response = self.synapse.restGET( f"/entity/{synapse_id}/schema/validation/statistics" @@ -763,8 +747,8 @@ def get_invalid_json_schema_validation(self, synapse_id: str): """Get a single page of invalid JSON schema validation results for a container Entity (Project or Folder). - :param synapse_id: Synapse Id - :type synapse_id: str + Arguments: + synapse_id: Synapse Id """ request_body = {"containerId": synapse_id} response = self.synapse._POST_paginated( @@ -777,10 +761,9 @@ def get_invalid_json_schema_validation(self, synapse_id: str): def bind_json_schema(self, json_schema_uri: str, entity: Union[str, Entity]): """Bind a JSON schema to an entity - :param json_schema_uri: JSON schema URI - :type json_schema_uri: str - :param entity: Synapse Entity or Synapse Id - :type entity: str, Entity + Arguments: + json_schema_uri: JSON schema URI + entity: Synapse Entity or Synapse Id """ synapse_id = id_of(entity) response = self.bind_json_schema_to_entity(synapse_id, json_schema_uri) @@ -789,8 +772,8 @@ def bind_json_schema(self, json_schema_uri: str, entity: Union[str, Entity]): def get_json_schema(self, entity: Union[str, Entity]): """Get a JSON schema associated to an Entity - :param entity: Synapse Entity or Synapse Id - :type entity: str, Entity + Arguments: + entity: Synapse Entity or Synapse Id """ synapse_id = id_of(entity) response = self.get_json_schema_from_entity(synapse_id) @@ -799,8 +782,8 @@ def get_json_schema(self, entity: Union[str, Entity]): def unbind_json_schema(self, entity: Union[str, Entity]): """Unbind a JSON schema from an entity - :param entity: Synapse Entity or Synapse Id - :type entity: str, Entity + Arguments: + entity: Synapse Entity or Synapse Id """ synapse_id = id_of(entity) response = self.delete_json_schema_from_entity(synapse_id) @@ -809,8 +792,8 @@ def unbind_json_schema(self, entity: Union[str, Entity]): def validate(self, entity: Union[str, Entity]): """Validate an entity based on the bound JSON schema - :param entity: Synapse Entity or Synapse Id - :type entity: str, Entity + Arguments: + entity: Synapse Entity or Synapse Id """ synapse_id = id_of(entity) response = self.validate_entity_with_json_schema(synapse_id) @@ -819,8 +802,8 @@ def validate(self, entity: Union[str, Entity]): def validation_stats(self, entity: Union[str, Entity]): """Get validation statistics of an entity based on the bound JSON schema - :param entity: Synapse Entity or Synapse Id - :type entity: str, Entity + Arguments: + entity: Synapse Entity or Synapse Id """ synapse_id = id_of(entity) response = self.get_json_schema_validation_statistics(synapse_id) @@ -829,8 +812,8 @@ def validation_stats(self, entity: Union[str, Entity]): def validate_children(self, entity: Union[str, Entity]): """Validate an entity and it's children based on the bound JSON schema - :param entity: Synapse Entity or Synapse Id of a project or folder. - :type entity: str, Entity + Arguments: + entity: Synapse Entity or Synapse Id of a project or folder. """ synapse_id = id_of(entity) response = self.get_invalid_json_schema_validation(synapse_id) diff --git a/synapseutils/__init__.py b/synapseutils/__init__.py index 9ee43c498..1a6d4651d 100644 --- a/synapseutils/__init__.py +++ b/synapseutils/__init__.py @@ -1,6 +1,4 @@ """ -## Overview - The ``synapseutils`` package provides both higher level beta functions as well as utilities for interacting with [Synapse](http://www.synapse.org). The behavior of these functions are subject to change.