Merge branch 'develop' of https://github.com/Labelbox/labelbox-python into ms/validation-part2

Author: Matt Sokoloff

Dockerfile

@@ -1,6 +1,6 @@
 FROM python:3.7
 
-RUN pip install pytest
+RUN pip install pytest pytest-cases
 
 
 WORKDIR /usr/src/labelbox

labelbox/__init__.py

@@ -1,5 +1,5 @@
 name = "labelbox"
-__version__ = "2.4.10"
+__version__ = "2.4.11"
 
 from labelbox.client import Client
 from labelbox.schema.bulk_import_request import BulkImportRequest
@@ -15,4 +15,4 @@
 from labelbox.schema.asset_metadata import AssetMetadata
 from labelbox.schema.webhook import Webhook
 from labelbox.schema.prediction import Prediction, PredictionModel
-from labelbox.schema.ontology import Ontology
+from labelbox.schema.ontology import Ontology

labelbox/exceptions.py

@@ -106,6 +106,6 @@ class UuidError(LabelboxError):
     pass
 
 
-class NDJsonError(LabelboxError):
-    """Raised when an ndjson line is invalid."""
+class MALValidationError(LabelboxError):
+    """Raised when user input is invalid for MAL imports."""
     ...

labelbox/schema/bulk_import_request.py

@@ -1,23 +1,24 @@
 import json
-import logging
 import time
-from pathlib import Path
 from uuid import UUID, uuid4
-from pydantic import BaseModel, validator
+
+import logging
+from pathlib import Path
 import pydantic
 import backoff
 import ndjson
-import labelbox
 import requests
+from pydantic import BaseModel, validator
+from typing_extensions import Literal
+from typing import (Any, List, Optional, BinaryIO, Dict, Iterable, Tuple, Union,
+                    Type, Set)
+
+import labelbox
 from labelbox import utils
 from labelbox.orm import query
 from labelbox.orm.db_object import DbObject
-from labelbox.orm.model import Field
-from labelbox.orm.model import Relationship
+from labelbox.orm.model import Field, Relationship
 from labelbox.schema.enums import BulkImportRequestState
-from pydantic import ValidationError
-from typing import Any, List, Optional, BinaryIO, Dict, Iterable, Tuple, Union, Type, Set
-from typing_extensions import TypedDict, Literal
 
 NDJSON_MIME_TYPE = "application/x-ndjson"
 logger = logging.getLogger(__name__)
@@ -187,6 +188,8 @@ def create_from_url(cls,
             project_id (str): id of project for which predictions will be imported
             name (str): name of BulkImportRequest
             url (str): publicly accessible URL pointing to ndjson file containing predictions
+            validate (bool): a flag indicating if there should be a validation
+                if `url` is valid ndjson
         Returns:
             BulkImportRequest object
         """
@@ -219,7 +222,7 @@ def create_from_objects(cls,
                             client,
                             project_id: str,
                             name: str,
-                            predictions: Iterable[dict],
+                            predictions: Iterable[Dict],
                             validate=True) -> 'BulkImportRequest':
         """
         Creates a `BulkImportRequest` from an iterable of dictionaries.
@@ -239,11 +242,13 @@ def create_from_objects(cls,
             }
         }``
 
-        Args:x
+        Args:
             client (Client): a Labelbox client
             project_id (str): id of project for which predictions will be imported
             name (str): name of BulkImportRequest
             predictions (Iterable[dict]): iterable of dictionaries representing predictions
+            validate (bool): a flag indicating if there should be a validation
+                if `predictions` is valid ndjson
         Returns:
             BulkImportRequest object
         """
@@ -311,7 +316,8 @@ def create_from_local_file(cls,
         return cls(client, response_data["createBulkImportRequest"])
 
 
-def _validate_ndjson(lines: Iterable[Dict[str, Any]], project) -> None:
+def _validate_ndjson(lines: Iterable[Dict[str, Any]],
+                     project: "labelbox.Project") -> None:
     """   
     Client side validation of an ndjson object.
 
@@ -326,7 +332,7 @@ def _validate_ndjson(lines: Iterable[Dict[str, Any]], project) -> None:
         project (Project): id of project for which predictions will be imported
     
     Raises:
-        NDJsonError: Raise for invalid NDJson
+        MALValidationError: Raise for invalid NDJson
         UuidError: Duplicate UUID in upload
     """
     data_row_ids = {
@@ -345,8 +351,8 @@ def _validate_ndjson(lines: Iterable[Dict[str, Any]], project) -> None:
                     f'{uuid} already used in this import job, '
                     'must be unique for the project.')
             uids.add(uuid)
-        except (ValidationError, ValueError, TypeError, KeyError) as e:
-            raise labelbox.exceptions.NDJsonError(
+        except (pydantic.ValidationError, ValueError, TypeError, KeyError) as e:
+            raise labelbox.exceptions.MALValidationError(
                 f"Invalid NDJson on line {idx}") from e
 
 
@@ -404,19 +410,19 @@ def get_mal_schemas(ontology):
 LabelboxID: str = pydantic.Field(..., min_length=25, max_length=25)
 
 
-class Bbox(TypedDict):
+class Bbox(BaseModel):
     top: float
     left: float
     height: float
     width: float
 
 
-class Point(TypedDict):
+class Point(BaseModel):
     x: float
     y: float
 
 
-class FrameLocation(TypedDict):
+class FrameLocation(BaseModel):
     end: int
     start: int
 
@@ -426,7 +432,9 @@ class VideoSupported(BaseModel):
     frames: Optional[List[FrameLocation]]
 
 
-class UnionConstructor:
+#Base class for a special kind of union.
+# Compatible with pydantic. Improves error messages over a traditional union
+class SpecialUnion:
 
     def __new__(cls, **kwargs):
         return cls.build(kwargs)
@@ -437,8 +445,8 @@ def __get_validators__(cls):
 
     @classmethod
     def get_union_types(cls):
-        if not issubclass(cls, UnionConstructor):
-            raise TypeError("{} must be a subclass of UnionConstructor")
+        if not issubclass(cls, SpecialUnion):
+            raise TypeError("{} must be a subclass of SpecialUnion")
 
         union_types = [x for x in cls.__orig_bases__ if hasattr(x, "__args__")]
         if len(union_types) < 1:
@@ -451,7 +459,16 @@ def get_union_types(cls):
         return union_types[0].__args__[0].__args__
 
     @classmethod
-    def build(cls: Any, data) -> "NDBase":
+    def build(cls: Any, data: Union[dict, BaseModel]) -> "NDBase":
+        """
+            Checks through all objects in the union to see which matches the input data.
+            Args:
+                data  (Union[dict, BaseModel]) : The data for constructing one of the objects in the union
+            raises:
+                KeyError: data does not contain the determinant fields for any of the types supported by this SpecialUnion
+                ValidationError: Error while trying to construct a specific object in the union
+            
+        """
         if isinstance(data, BaseModel):
             data = data.dict()
 
@@ -504,7 +521,6 @@ class NDFeatureSchema(BaseModel):
 
 class NDBase(NDFeatureSchema):
     ontology_type: str
-    schemaId: str = LabelboxID
     uuid: UUID
     dataRow: DataRow
 
@@ -551,7 +567,7 @@ class NDText(NDBase):
     #No feature schema to check
 
 
-class NDCheckList(VideoSupported, NDBase):
+class NDChecklist(VideoSupported, NDBase):
     ontology_type: Literal["checklist"] = "checklist"
     answers: List[NDFeatureSchema] = pydantic.Field(determinant=True)
 
@@ -564,7 +580,7 @@ def validate_answers(cls, value, field):
 
     def validate_feature_schemas(self, valid_feature_schemas):
         #Test top level feature schema for this tool
-        super(NDCheckList, self).validate_feature_schemas(valid_feature_schemas)
+        super(NDChecklist, self).validate_feature_schemas(valid_feature_schemas)
         #Test the feature schemas provided to the answer field
         if len(set([answer.schemaId for answer in self.answers])) != len(
                 self.answers):
@@ -593,9 +609,9 @@ def validate_feature_schemas(self, valid_feature_schemas):
 
 #A union with custom construction logic to improve error messages
 class NDClassification(
-        UnionConstructor,
+        SpecialUnion,
         Type[Union[NDText, NDRadio,  # type: ignore
-                   NDCheckList]]):
+                   NDChecklist]]):
     ...
 
 
@@ -663,7 +679,7 @@ class NDPoint(NDBaseTool):
     #Could check if points are positive
 
 
-class EntityLocation(TypedDict):
+class EntityLocation(BaseModel):
     start: int
     end: int
 
@@ -674,6 +690,9 @@ class NDTextEntity(NDBaseTool):
 
     @validator('location')
     def is_valid_location(cls, v):
+        if isinstance(v, BaseModel):
+            v = v.dict()
+
         if len(v) < 2:
             raise ValueError(
                 f"A line must have at least 2 points to be valid. Found {v}")
@@ -685,7 +704,7 @@ def is_valid_location(cls, v):
         return v
 
 
-class MaskFeatures(TypedDict):
+class MaskFeatures(BaseModel):
     instanceURI: str
     colorRGB: Union[List[int], Tuple[int, int, int]]
 
@@ -696,6 +715,9 @@ class NDMask(NDBaseTool):
 
     @validator('mask')
     def is_valid_mask(cls, v):
+        if isinstance(v, BaseModel):
+            v = v.dict()
+
         colors = v['colorRGB']
         #Does the dtype matter? Can it be a float?
         if not isinstance(colors, (tuple, list)):
@@ -713,15 +735,17 @@ def is_valid_mask(cls, v):
 
 #A union with custom construction logic to improve error messages
 class NDTool(
-        UnionConstructor,
+        SpecialUnion,
         Type[Union[NDMask,  # type: ignore
                    NDTextEntity, NDPoint, NDRectangle, NDPolyline,
                    NDPolygon,]]):
     ...
 
 
-class NDAnnotation(UnionConstructor,
-                   Type[Union[NDTool, NDClassification]]):  # type: ignore
+class NDAnnotation(
+        SpecialUnion,
+        Type[Union[NDTool,  # type: ignore
+                   NDClassification]]):
 
     @classmethod
     def build(cls: Any, data) -> "NDBase":

labelbox/schema/project.py

@@ -5,7 +5,7 @@
 import logging
 from pathlib import Path
 import time
-from typing import Union, Iterable
+from typing import Dict, List, Union, Iterable
 from urllib.parse import urlparse
 
 from labelbox import utils
@@ -177,6 +177,69 @@ def export_labels(self, timeout_seconds=60):
                          self.uid)
             time.sleep(sleep_time)
 
+    def upsert_instructions(self, instructions_file: str):
+        """
+        * Uploads instructions to the UI. Running more than once will replace the instructions
+            
+        Args:
+            instructions_file (str): Path to a local file.
+                * Must be either a pdf, text, or html file.
+
+        Raises:
+            ValueError:
+                * project must be setup 
+                * instructions file must end with one of ".text", ".txt", ".pdf", ".html"
+        """
+
+        if self.setup_complete is None:
+            raise ValueError(
+                "Cannot attach instructions to a project that has not been set up."
+            )
+
+        frontend = self.labeling_frontend()
+        frontendId = frontend.uid
+
+        if frontend.name != "Editor":
+            logger.warn(
+                f"This function has only been tested to work with the Editor front end. Found %s",
+                frontend.name)
+
+        supported_instruction_formats = (".text", ".txt", ".pdf", ".html")
+        if not instructions_file.endswith(supported_instruction_formats):
+            raise ValueError(
+                f"instructions_file must end with one of {supported_instruction_formats}. Found {instructions_file}"
+            )
+
+        lfo = list(self.labeling_frontend_options())[-1]
+        instructions_url = self.client.upload_file(instructions_file)
+        customization_options = json.loads(lfo.customization_options)
+        customization_options['projectInstructions'] = instructions_url
+        option_id = lfo.uid
+
+        self.client.execute(
+            """mutation UpdateFrontendWithExistingOptionsPyApi (
+                    $frontendId: ID!, 
+                    $optionsId: ID!, 
+                    $name: String!, 
+                    $description: String!, 
+                    $customizationOptions: String!
+                ) {
+                    updateLabelingFrontend(
+                        where: {id: $frontendId}, 
+                        data: {name: $name, description: $description}
+                    ) {id}
+                    updateLabelingFrontendOptions(
+                        where: {id: $optionsId}, 
+                        data: {customizationOptions: $customizationOptions}
+                    ) {id}
+                }""", {
+                "frontendId": frontendId,
+                "optionsId": option_id,
+                "name": frontend.name,
+                "description": "Video, image, and text annotation",
+                "customizationOptions": json.dumps(customization_options)
+            })
+
     def labeler_performance(self):
         """ Returns the labeler performances for this Project.
 
@@ -486,8 +549,8 @@ def enable_model_assisted_labeling(self, toggle: bool = True) -> bool:
     def upload_annotations(
             self,
             name: str,
-            annotations: Union[str, Union[str, Path], Iterable[dict]],
-            validate=True) -> 'BulkImportRequest':  # type: ignore
+            annotations: Union[str, Path, Iterable[Dict]],
+            validate: bool = True) -> 'BulkImportRequest':  # type: ignore
         """ Uploads annotations to a new Editor project.
 
         Args:
@@ -497,7 +560,7 @@ def upload_annotations(
                 ndjson file
                 OR local path to an ndjson file
                 OR iterable of annotation rows
-            validate (str):
+            validate (bool):
                 Whether or not to validate the payload before uploading.
         Returns:
             BulkImportRequest

requirements.txt

@@ -2,3 +2,4 @@ requests==2.22.0
 ndjson==0.3.1
 backoff==1.10.0
 google-api-core>=1.22.1
+pydantic==1.8