added doc strings and cleanup

Author: Matt Sokoloff

examples/basics/ontologies.ipynb

@@ -68,8 +68,7 @@
     "root_schema_node_cat_normalized_json = {\n",
     "     'tool': 'polygon', \n",
     "     'name': 'cat', \n",
-    "     'color': 'black', \n",
-    "     'classifications': [], \n",
+    "     'color': 'black'\n",
     "}\n",
     "\n",
     "ontology_normalized_json = {\"tools\" : [root_schema_node_cat_normalized_json], \"classifications\" : []}\n",

labelbox/client.py

@@ -24,7 +24,6 @@
 from labelbox.schema import role
 from labelbox.schema.ontology import Tool, Classification
 
-
 logger = logging.getLogger(__name__)
 
 _LABELBOX_API_KEY = "LABELBOX_API_KEY"
@@ -563,7 +562,8 @@ def create_dataset(self, iam_integration=IAMIntegration._DEFAULT, **kwargs):
                 )
 
             if not iam_integration.valid:
-                raise ValueError("Integration is not valid. Please select another.")
+                raise ValueError(
+                    "Integration is not valid. Please select another.")
 
             self.execute(
                 """mutation setSignerForDatasetPyApi($signerId: ID!, $datasetId: ID!) {
@@ -709,46 +709,86 @@ def get_data_row_ids_for_external_ids(
         return result
 
     def get_ontology(self, ontology_id):
+        """
+        Fetches an Ontology by id.
+
+        Args:
+            ontology_id (str): The id of the ontology to query for
+        Returns:
+            Ontology
+        """
         return self._get_single(Entity.Ontology, ontology_id)
 
-    def get_ontologies(self, name_contains: str):
+    def get_ontologies(self, name_contains):
+        """
+        Fetches all ontologies with names that match the name_contains string.
+
+        Args:
+            name_contains (str): the string to search ontology names by
+        Returns:
+            PaginatedCollection of Ontologies with names that match `name_contains`
+        """
         query_str = """query getOntologiesPyApi($search: String, $filter: OntologyFilter, $from : String, $first: PageSize){
             ontologies(where: {filter: $filter, search: $search}, after: $from, first: $first){
                 nodes {%s}
                 nextCursor
             }
         }
         """ % query.results_query_part(Entity.Ontology)
-        res = PaginatedCollection(
-            self, query_str, {'search' : name_contains, 'filter' :{'status' : 'ALL'}}, ['ontologies', 'nodes'],
-            Entity.Ontology, ['ontologies', 'nextCursor'])
+        params = {'search': name_contains, 'filter': {'status': 'ALL'}}
+        res = PaginatedCollection(self, query_str, params,
+                                  ['ontologies', 'nodes'], Entity.Ontology,
+                                  ['ontologies', 'nextCursor'])
         return res
 
     def get_root_schema_node(self, root_schema_id):
-        return self._get_single(Entity.RootSchemaNode, root_schema_id)
+        """
+        Fetches a root schema nodes by id
 
+        Args:
+            root_schema_id (str): The id of the root schema node to query for
+        Returns:
+            RootSchemaNode
+        """
+        return self._get_single(Entity.RootSchemaNode, root_schema_id)
 
     def get_root_schema_nodes(self, name_contains):
+        """
+        Fetches root schema nodes with names that match the name_contains string
+
+        Args:
+            name_contains (str): the string to search root schema node names by
+        Returns:
+            PaginatedCollection of RootSchemaNodes with names that match `name_contains`
+        """
         query_str = """query getRootSchemaNodePyApi($search: String, $filter: RootSchemaNodeFilter, $from : String, $first: PageSize){
             rootSchemaNodes(where: {filter: $filter, search: $search}, after: $from, first: $first){
                 nodes {%s}
                 nextCursor
             }
         }
         """ % query.results_query_part(Entity.RootSchemaNode)
-        return PaginatedCollection(
-            self, query_str, {'search' : name_contains, 'filter' :{'status' : 'ALL'}}, ['rootSchemaNodes', 'nodes'],
-            Entity.RootSchemaNode, ['rootSchemaNodes', 'nextCursor'])
+        params = {'search': name_contains, 'filter': {'status': 'ALL'}}
+        return PaginatedCollection(self, query_str, params,
+                                   ['rootSchemaNodes', 'nodes'],
+                                   Entity.RootSchemaNode,
+                                   ['rootSchemaNodes', 'nextCursor'])
 
-
-    def create_ontology_from_root_schema_nodes(self, name, schema_node_ids):
+    def create_ontology_from_root_schema_nodes(self, name,
+                                               root_schema_node_ids):
         """
-        Convenient way to create feature schema nodes.
-        If you want to mix new and old, you have to create w/ ontology builder and use create ontology..
+        Creates an ontology from a list of root schema node ids
+        This will reuse the schema nodes instead of making a copy
+
+        Args:
+            name (str): Name of the ontology
+            root_schema_node_ids (List[str]): List of root schema node ids include in the ontology
+        Returns:
+            The created Ontology
         """
         tools, classifications = [], []
-        for schema_node_id in schema_node_ids:
-            schema_node = self.get_root_schema_node(schema_node_id)
+        for schema_node_id in root_schema_node_ids:
+            schema_node = self.get_root_schema_node(root_schema_node_ids)
             tool = schema_node.normalized['tool']
             try:
                 Tool.Type(tool)
@@ -758,46 +798,67 @@ def create_ontology_from_root_schema_nodes(self, name, schema_node_ids):
                     Classification.Type(tool)
                     classifications.append(schema_node.normalized)
                 except ValueError:
-                    raise ValueError(f"Tool `{tool}` not in list of supported tools or classifications.")
-        return self.create_ontology(name, {'tools' : tools, 'classifications' : classifications})
-
+                    raise ValueError(
+                        f"Tool `{tool}` not in list of supported tools or classifications."
+                    )
+        normalized = {'tools': tools, 'classifications': classifications}
+        return self.create_ontology(name, normalized)
 
-    def create_ontology(self, name , normalized_json):
+    def create_ontology(self, name, normalized):
         """
-        Creates an ontology from normalized json.
-
-        Use the OntologyBuilder to easily build normalized json
+        Creates an ontology from normalized data
+            >>> normalized = {"tools" : [{'tool': 'polygon',  'name': 'cat', 'color': 'black'}], "classifications" : []}
+            >>> ontology = client.create_ontology("ontology-name", normalized)
 
-        >>> Ontology
-
-
-        You can also add reuse existing feature schema nodes
+        Or use the ontology builder. It is especially useful for complex ontologies
+            >>> normalized = OntologyBuilder(tools=[Tool(tool=Tool.Type.BBOX, name="cat", color = 'black')]).asdict()
+            >>> ontology = client.create_ontology("ontology-name", normalized)
 
+        To reuse existing root schema nodes, use `create_ontology_from_root_schema_nodes()`
+        More details can be found here:
+            https://github.com/Labelbox/labelbox-python/blob/develop/examples/basics/ontologies.ipynb
 
+        Args:
+            name (str): Name of the ontology
+            normalized (dict): A normalized ontology payload. See above for details.
+        Returns:
+            The created Ontology
         """
         query_str = """mutation upsertRootSchemaNodePyApi($data:  UpsertOntologyInput!){
-            upsertOntology(data: $data){
-             %s
-            }
+                           upsertOntology(data: $data){ %s }
         } """ % query.results_query_part(Entity.Ontology)
-        if normalized_json is None:
-            if root_schema_ids is None:
-                raise ValueError("Must provide either a normalized ontology or a list of root_schema_ids")
-            return root_schema_ids
-
-        res = self.execute(query_str, {'data' : {'name' : name ,'normalized' : json.dumps(normalized_json)}})
+        params = {'data': {'name': name, 'normalized': json.dumps(normalized)}}
+        res = self.execute(query_str, params)
         return Entity.Ontology(self, res['upsertOntology'])
 
+    def create_root_schema_node(self, normalized):
+        """
+        Creates a root schema node from normalized data.
+            >>> normalized = {'tool': 'polygon',  'name': 'cat', 'color': 'black'}
+            >>> root_schema_node = client.create_root_schema_node(normalized)
+
+        Or use the Tool or Classification objects. It is especially useful for complex tools.
+            >>> normalized = Tool(tool=Tool.Type.BBOX, name="cat", color = 'black').asdict()
+            >>> root_schema_node = client.create_root_schema_node(normalized)
 
-    def create_root_schema_node(self, normalized_json):
+        More details can be found here:
+            https://github.com/Labelbox/labelbox-python/blob/develop/examples/basics/ontologies.ipynb
+
+        Args:
+            normalized (dict): A normalized tool or classification payload. See above for details
+        Returns:
+            The created RootSchemaNode.
+        """
         query_str = """mutation upsertRootSchemaNodePyApi($data:  UpsertRootSchemaNodeInput!){
-            upsertRootSchemaNode(data: $data){
-             %s
-            }
+                        upsertRootSchemaNode(data: $data){ %s }
         } """ % query.results_query_part(Entity.RootSchemaNode)
-        # TODO: Is this necessary?
-        normalized_json = {k:v for k,v in normalized_json.items() if v}
-        # Check color. Quick gotcha..
+        normalized = {k: v for k, v in normalized.items() if v}
+
+        # The OntologyBuilder automatically assigns colors when calling asdict() but Tools and Classifications do not.
+        # So we check here to prevent getting 500 erros
+
         if 'color' not in normalized_json:
             raise KeyError("Must provide color.")
-        return Entity.RootSchemaNode(self, self.execute(query_str, {'data' : {'normalized' : json.dumps(normalized_json)}})['upsertRootSchemaNode'])
+        params = {'data': {'normalized': json.dumps(normalized_json)}}
+        res = self.execute(query_str, params)
+        return Entity.RootSchemaNode(self, res['upsertRootSchemaNode'])

labelbox/schema/ontology.py

@@ -16,7 +16,6 @@
 SchemaId: Type[str] = constr(min_length=25, max_length=25)
 
 
-
 class RootSchemaNode(DbObject):
     name = Field.String("name")
     color = Field.String("name")
@@ -360,7 +359,6 @@ def from_project(cls, project: "project.Project"):
     def from_ontology(cls, ontology: Ontology):
         return cls.from_dict(ontology.normalized)
 
-
     def add_tool(self, tool: Tool):
         if tool.name in (t.name for t in self.tools):
             raise InconsistentOntologyException(
@@ -374,6 +372,3 @@ def add_classification(self, classification: Classification):
                 f"Duplicate classification instructions '{classification.instructions}'. "
             )
         self.classifications.append(classification)
-
-
-

labelbox/schema/project.py

@@ -1,6 +1,5 @@
 import enum
 import json
-from labelbox.schema.labeling_frontend import LabelingFrontend
 import logging
 import time
 import warnings
@@ -423,16 +422,26 @@ def review_metrics(self, net_score):
         res = self.client.execute(query_str, {id_param: self.uid})
         return res["project"]["reviewMetrics"]["labelAggregate"]["count"]
 
-
     def setup_editor(self, ontology):
-        fe  = next(self.client.get_labeling_frontends(where = LabelingFrontend.name == "Editor"))
-        self.labeling_frontend.connect(fe)
-        query_str = """mutation ConnectOntology($projectId: ID!, $ontologyId: ID!) {project(where: {id: $projectId}) {connectOntology(ontologyId: $ontologyId) {id}}}"""
-        self.client.execute(query_str, {'ontologyId' : ontology.uid, 'projectId' :  self.uid})
+        """
+        Sets up the project using the Pictor editor.
+
+        Args:
+            ontology (Ontology): The ontology to attach to the project
+        """
+        labeling_front_end = next(
+            self.client.get_labeling_frontends(
+                where=Entity.LabelingFrontend.name == "Editor"))
+        self.labeling_frontend.connect(labeling_front_end)
+        query_str = """mutation ConnectOntologyPyApi($projectId: ID!, $ontologyId: ID!){
+            project(where: {id: $projectId}) {connectOntology(ontologyId: $ontologyId) {id}}}"""
+        self.client.execute(query_str, {
+            'ontologyId': ontology.uid,
+            'projectId': self.uid
+        })
         timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
         self.update(setup_complete=timestamp)
 
-
     def setup(self, labeling_frontend, labeling_frontend_options):
         """ Finalizes the Project setup.
 

tests/integration/annotation_import/test_model.py

@@ -29,6 +29,3 @@ def test_model_delete(client, model):
     after = list(client.get_models())
 
     assert len(before) == len(after) + 1
-
-
-

tests/integration/conftest.py

@@ -333,4 +333,3 @@ def configured_project_with_label(client, rand_gen, image_url):
     yield [project, label]
     dataset.delete()
     project.delete()
-

tests/integration/test_ontology.py

@@ -2,6 +2,9 @@
 
 from labelbox.exceptions import InconsistentOntologyException
 from labelbox import Tool, Classification, Option, OntologyBuilder
+from labelbox.orm.model import Entity
+import json
+import time
 
 _SAMPLE_ONTOLOGY = {
     "tools": [{
@@ -242,10 +245,74 @@ def test_from_project_ontology(client, project) -> None:
     assert o.asdict() == project.ontology().normalized
 
 
-
-def test_create_ontology(client, rand_gen):
-    name = f"test-ontology-{rand_gen(str)}"
-    normalized = {}
-    ontology = client.create_ontology(name = name)
-    assert
-
+def _get_attr_stringify_json(obj, attr):
+    value = getattr(obj, attr.name)
+    if attr.field_type.name.lower() == "json":
+        return json.dumps(value, sort_keys=True)
+    return value
+
+
+def test_root_schema_node_create_read(client, rand_gen):
+    name = f"test-root-schema-{rand_gen(str)}"
+    root_schema_node_cat_normalized_json = {
+        'tool': 'polygon',
+        'name': name,
+        'color': 'black',
+        'classifications': [],
+    }
+    created_root_schema_node = client.create_root_schema_node(
+        root_schema_node_cat_normalized_json)
+    queried_root_sceham_node = client.get_root_schema_node(
+        created_root_schema_node.uid)
+    for attr in Entity.RootSchemaNode.fields():
+        assert _get_attr_stringify_json(created_root_schema_node,
+                                        attr) == _get_attr_stringify_json(
+                                            queried_root_sceham_node, attr)
+
+    time.sleep(3)  # Slight delay for searching
+    queried_root_sceham_nodes = client.get_root_schema_nodes(name)
+    assert [
+        root_schema_node.name for root_schema_node in queried_root_sceham_nodes
+    ] == [name]
+    queried_root_sceham_nodes = queried_root_sceham_nodes[0]
+
+    for attr in Entity.RootSchemaNode.fields():
+        assert _get_attr_stringify_json(created_root_schema_node,
+                                        attr) == _get_attr_stringify_json(
+                                            queried_root_sceham_node, attr)
+
+
+def test_ontology_create_read(client, rand_gen):
+    ontology_name = f"test-ontology-{rand_gen(str)}"
+    tool_name = f"test-ontology-tool-{rand_gen(str)}"
+    root_schema_node_cat_normalized_json = {
+        'tool': 'polygon',
+        'name': tool_name,
+        'color': 'black',
+        'classifications': [],
+    }
+    root_schema_node = client.create_root_schema_node(
+        root_schema_node_cat_normalized_json)
+    created_ontology = client.create_ontology_from_root_schema_nodes(
+        name=ontology_name, root_schema_node_ids=[root_schema_node.uid])
+    tool_normalized = created_ontology.normalized['tools'][0]
+    for k, v in root_schema_node_cat_normalized_json.items():
+        assert tool_normalized[k] == v
+    assert tool_normalized['schemaNodeId'] == root_schema_node.uid
+    assert tool_normalized['featureSchemaId'] is not None
+
+    queried_ontology = client.get_ontology(created_ontology.uid)
+
+    for attr in Entity.Ontology.fields():
+        assert _get_attr_stringify_json(created_ontology,
+                                        attr) == _get_attr_stringify_json(
+                                            queried_ontology, attr)
+
+    time.sleep(3)  # Slight delay for searching
+    queried_ontologies = client.get_ontologies(ontology_name)
+    assert [ontology.name for ontology in queried_ontologies] == [ontology_name]
+    queried_ontology = queried_ontologies[0]
+    for attr in Entity.Ontology.fields():
+        assert _get_attr_stringify_json(created_ontology,
+                                        attr) == _get_attr_stringify_json(
+                                            queried_ontology, attr)