Improve API documentation

Author: florijanstamenkovic

labelbox/client.py

@@ -21,9 +21,9 @@
 
 
 class Client:
-    """ A Labelbox client. Containes info necessary for connecting to
-    the server (URL, authentication key). Provides functions for querying
-    and creating top-level data objects (Projects, Datasets).
+    """ A Labelbox client. Contains info necessary for connecting to
+    a Labelbox server (URL, authentication key). Provides functions for
+    querying and creating top-level data objects (Projects, Datasets).
     """
 
     def __init__(self, api_key=None,
@@ -34,6 +34,10 @@ def __init__(self, api_key=None,
             api_key (str): API key. If None, the key is obtained from
                 the "LABELBOX_API_KEY" environment variable.
             endpoint (str): URL of the Labelbox server to connect to.
+        Raises:
+            labelbox.exceptions.AuthenticationError: If no `api_key`
+                is provided as an argument or via the environment
+                variable.
         """
         if api_key is None:
             if _LABELBOX_API_KEY not in os.environ:
@@ -198,7 +202,7 @@ def upload_data(self, data):
 
         return file_data["uploadFile"]["url"]
 
-    def get_single(self, db_object_type, uid):
+    def _get_single(self, db_object_type, uid):
         """ Fetches a single object of the given type, for the given ID.
 
         Args:
@@ -222,22 +226,38 @@ def get_single(self, db_object_type, uid):
             return db_object_type(self, res)
 
     def get_project(self, project_id):
-        """ Convenience for `client.get_single(Project, project_id)`. """
-        return self.get_single(Project, project_id)
+        """ Gets a single Project with the given ID.
+        Args:
+            project_id (str): Unique ID of the Project.
+        Return:
+            The sought Project.
+        Raises:
+            labelbox.exceptions.ResourceNotFoundError: If there is no
+                Project with the given ID.
+        """
+        return self._get_single(Project, project_id)
 
     def get_dataset(self, dataset_id):
-        """ Convenience for `client.get_single(Dataset, dataset_id)`. """
-        return self.get_single(Dataset, dataset_id)
+        """ Gets a single Dataset with the given ID.
+        Args:
+            dataset_id (str): Unique ID of the Dataset.
+        Return:
+            The sought Dataset.
+        Raises:
+            labelbox.exceptions.ResourceNotFoundError: If there is no
+                Dataset with the given ID.
+        """
+        return self._get_single(Dataset, dataset_id)
 
     def get_user(self):
-        """ Gets the current user database object. """
-        return self.get_single(User, None)
+        """ Gets the current User database object. """
+        return self._get_single(User, None)
 
     def get_organization(self):
-        """ Gets the organization DB object of the current user. """
-        return self.get_single(Organization, None)
+        """ Gets the Organization DB object of the current user. """
+        return self._get_single(Organization, None)
 
-    def get_all(self, db_object_type, where):
+    def _get_all(self, db_object_type, where):
         """ Fetches all the objects of the given type the user has access to.
 
         Args:
@@ -270,7 +290,7 @@ def get_projects(self, where=None):
             labelbox.exceptions.LabelboxError: Any error raised by
                 `Client.execute` can also be raised by this function.
         """
-        return self.get_all(Project, where)
+        return self._get_all(Project, where)
 
     def get_datasets(self, where=None):
         """ Fetches all the datasets the user has access to.
@@ -284,7 +304,7 @@ def get_datasets(self, where=None):
             labelbox.exceptions.LabelboxError: Any error raised by
                 `Client.execute` can also be raised by this function.
         """
-        return self.get_all(Dataset, where)
+        return self._get_all(Dataset, where)
 
     def get_labeling_frontends(self, where=None):
         """ Fetches all the labeling frontends.
@@ -298,7 +318,7 @@ def get_labeling_frontends(self, where=None):
             labelbox.exceptions.LabelboxError: Any error raised by
                 `Client.execute` can also be raised by this function.
         """
-        return self.get_all(LabelingFrontend, where)
+        return self._get_all(LabelingFrontend, where)
 
     def _create(self, db_object_type, data):
         """ Creates a object on the server. Attribute values are
@@ -328,7 +348,9 @@ def _create(self, db_object_type, data):
     def create_dataset(self, **kwargs):
         """ Creates a Dataset object on the server. Attribute values are
             passed as keyword arguments:
-                >>> dataset = client.create_dataset(name="MyDataset")
+                >>> project = client.get_project("uid_of_my_project")
+                >>> dataset = client.create_dataset(name="MyDataset",
+                >>>                                 projects=project)
 
         Kwargs:
             Keyword arguments with new Dataset attribute values.
@@ -338,7 +360,7 @@ def create_dataset(self, **kwargs):
             a new Dataset object.
         Raises:
             InvalidAttributeError: in case the Dataset type does not contain
-                any of the field names given in kwargs.
+                any of the attribute names given in kwargs.
         """
         return self._create(Dataset, kwargs)
 
@@ -355,6 +377,6 @@ def create_project(self, **kwargs):
             a new Project object.
         Raises:
             InvalidAttributeError: in case the Project type does not contain
-                any of the field names given in kwargs.
+                any of the attribute names given in kwargs.
         """
         return self._create(Project, kwargs)

labelbox/orm/db_object.py

@@ -68,7 +68,7 @@ def _set_field_values(self, field_values):
 
     def __repr__(self):
         type_name = self.type_name()
-        if "uid" in dir(self):
+        if "uid" in self.__dict__:
             return "<%s ID: %s>" % (type_name, self.uid)
         else:
             return "<%s>" % type_name
@@ -217,7 +217,7 @@ class BulkDeletable:
     type.
     """
     @staticmethod
-    def bulk_delete(objects, use_where_clause):
+    def _bulk_delete(objects, use_where_clause):
         """
         Args:
             objects (list): Objects to delete. All objects must be of the same

labelbox/orm/model.py

@@ -196,6 +196,12 @@ def __init__(self, relationship_type, destination_type_name,
     def destination_type(self):
         return Entity.named(self.destination_type_name)
 
+    def __str__(self):
+        return self.name
+
+    def __repr__(self):
+        return "<Relationship: %r>" % self.name
+
 
 class Entity:
     """ An entity that contains fields and relationships. """

labelbox/schema.py

@@ -346,8 +346,12 @@ class DataRow(DbObject, Updateable, BulkDeletable):
     metadata = Relationship.ToMany("AssetMetadata", False, "metadata")
 
     @staticmethod
-    def bulk_delete(objects):
-        BulkDeletable.bulk_delete(objects, True)
+    def bulk_delete(data_rows):
+        """ Deletes all the given DataRows.
+        Args:
+            data_rows (list of DataRow): The DataRows to delete.
+        """
+        BulkDeletable._bulk_delete(data_rows, True)
 
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
@@ -387,8 +391,12 @@ def __init__(self, *args, **kwargs):
     reviews = Relationship.ToMany("Review", False)
 
     @staticmethod
-    def bulk_delete(objects):
-        BulkDeletable.bulk_delete(objects, False)
+    def bulk_delete(labels):
+        """ Deletes all the given Labels.
+        Args:
+            labels (list of Label): The Labels to delete.
+        """
+        BulkDeletable._bulk_delete(labels, False)
 
     def create_review(self, **kwargs):
         """ Creates a Review for this label.
@@ -570,6 +578,21 @@ class Webhook(DbObject):
 
     @staticmethod
     def create(client, topics, url, secret, project):
+        """ Creates a Webhook.
+        Args:
+            client (Client): The Labelbox client used to connect
+                to the server.
+            topics (list of str): A list of topics this Webhook should
+                get notifications for.
+            url (str): The URL to which notifications should be sent
+                by the Labelbox server.
+            secret (str): A secret key used for signing notifications.
+            project (Project or None): The project for which notifications
+                should be sent. If None notifications are sent for all
+                events in your organization.
+        Return:
+            A newly created Webhook.
+        """
         query_str, params = query.create_webhook(topics, url, secret, project)
         res = client.execute(query_str, params)
         return Webhook(client, res["data"]["createWebhook"])

tools/db_object_doc_gen.py

@@ -85,7 +85,7 @@ def header(level, text):
 
 
 def paragraph(text):
-    return tag(text, "p")
+    return tag(inject_class_links(text), "p")
 
 
 def strong(text):
@@ -121,15 +121,15 @@ def header_link(text, header_id):
     return tag(text, "a", {"href":"#" + header_id})
 
 
-def class_link(cls):
+def class_link(cls, text):
     """ Generates an intra-document link for the given class. Example:
         >>> from labelbox import Project
-        >>> class_link(Project)
-        >>> <a href="#class_labelbox_schema_project">Project</a>
+        >>> class_link(Project, "blah")
+        >>> <a href="#class_labelbox_schema_project">blah</a>
     """
     header_id = "class_" + labelbox.utils.snake_case(qual_class_name(cls).
                                                      replace(".", "_"))
-    return header_link(cls.__name__, header_id)
+    return header_link(text, header_id)
 
 
 def inject_class_links(text):
@@ -141,15 +141,15 @@ def inject_class_links(text):
         matches = list(re.finditer(pattern, text))
         for match in reversed(matches):
             start, end = match.span()
-            text = text[:start] + class_link(cls) + text[end:]
+            text = text[:start] + class_link(cls, match.group()) + text[end:]
     return text
 
 
 def is_method(attribute):
     """ Determines if the given attribute is most likely a method. It's
     approximative since from Python 3 there are no more unbound methods. """
     return inspect.isfunction(attribute) and "." in attribute.__qualname__ \
-        and inspect.getfullargspec(attribute).args[0] == 'self'
+        and inspect.getfullargspec(attribute).args[:1] == ['self']
 
 
 def preprocess_docstring(docstring):
@@ -230,26 +230,51 @@ def process(collection, f):
 
         return "".join(result)
 
+    def parse_maybe_block(text):
+        """ Adapts to text. Calls `parse_block` if there is a codeblock
+        indented, otherwise just joins lines into a single line and
+        reduces whitespace.
+        """
+        if text is None:
+            return ""
+        if re.findall(r"\n\s+>>>", text):
+            return parse_block()
+        return re.sub(r"\s+", " ", text).strip()
+
     parts = (("Args: ", parse_list(args)),
-             ("Kwargs: ", parse_block(kwargs)),
-             ("Returns: ", parse_block(returns)),
+             ("Kwargs: ", parse_maybe_block(kwargs)),
+             ("Returns: ", parse_maybe_block(returns)),
              ("Raises: ", parse_list(raises)))
 
     return parse_block(docstring) + unordered_list([
         strong(name) + item for name, item in parts if bool(item)])
 
 
-def generate_methods(cls):
-    """ Generates HelpDocs style documentation for all the methods
-    of the given class.
+def generate_functions(cls, predicate):
+    """ Generates HelpDocs style documentation for the functions
+    of the given class that satisfy the given predicate. The functions
+    also must not being with "_", with the exception of Client.__init__.
+
+    Args:
+        cls (type): The class being generated.
+        predicate (callable): A callable accepting a single argument
+            (class attribute) and returning a bool indicating if
+            that attribute should be included in documentation
+            generation.
+    Return:
+        Textual documentation of functions belonging to the given
+        class that satisfy the given predicate.
     """
     text = []
-    for attr_name in dir(cls):
-        attr = getattr(cls, attr_name)
-        if ((is_method(attr) and not attr_name.startswith("_")) or
-            (cls == labelbox.Client and attr_name == "__init__")):
-            text.append(paragraph(generate_signature(attr)))
-            text.append(preprocess_docstring(attr.__doc__))
+    for name, attr in cls.__dict__.items():
+        if predicate(attr):
+            # static and class methods gave the __func__ attribute
+            # with the original definition that we need.
+            attr = getattr(attr, "__func__", attr)
+            if not name.startswith("_") or (cls == labelbox.Client and
+                                            name == "__init__"):
+                text.append(paragraph(generate_signature(attr)))
+                text.append(preprocess_docstring(attr.__doc__))
 
     return "".join(text)
 
@@ -319,29 +344,35 @@ def generate_class(cls, schema_class):
         text.append(generate_fields(cls))
         text.append(header(3, "Relationships"))
         text.append(generate_relationships(cls))
-    methods = generate_methods(cls).strip()
-    if len(methods):
-        text.append(header(3, "Methods"))
-        text.append(methods)
+
+    for name, predicate in (
+        ("Static Methods", lambda attr: type(attr) == staticmethod),
+        ("Class Methods", lambda attr: type(attr) == classmethod),
+        ("Object Methods", is_method)):
+        functions = generate_functions(cls, predicate).strip()
+        if len(functions):
+            text.append(header(3, name))
+            text.append(functions)
+
     return "\n".join(text)
 
 
-def generate_all(general_classes, schema_classes, error_classes):
+def generate_all():
     """ Generates the full HelpDocs API documentation article body. """
     text = []
     text.append(header(3, "General Classes"))
-    text.append(unordered_list([qual_class_name(cls) for cls in general_classes]))
+    text.append(unordered_list([qual_class_name(cls) for cls in GENERAL_CLASSES]))
     text.append(header(3, "Data Classes"))
-    text.append(unordered_list([qual_class_name(cls) for cls in schema_classes]))
+    text.append(unordered_list([qual_class_name(cls) for cls in SCHEMA_CLASSES]))
     text.append(header(3, "Error Classes"))
-    text.append(unordered_list([qual_class_name(cls) for cls in error_classes]))
+    text.append(unordered_list([qual_class_name(cls) for cls in ERROR_CLASSES]))
 
     text.append(header(1, "General classes"))
-    text.extend(generate_class(cls, False) for cls in general_classes)
+    text.extend(generate_class(cls, False) for cls in GENERAL_CLASSES)
     text.append(header(1, "Data Classes"))
-    text.extend(generate_class(cls, True) for cls in schema_classes)
+    text.extend(generate_class(cls, True) for cls in SCHEMA_CLASSES)
     text.append(header(1, "Error Classes"))
-    text.extend(generate_class(cls, False) for cls in error_classes)
+    text.extend(generate_class(cls, False) for cls in ERROR_CLASSES)
     return "\n".join(text)
 
 
@@ -353,7 +384,7 @@ def main():
 
     args = argp.parse_args()
 
-    body  = generate_all(GENERAL_CLASSES, SCHEMA_CLASSES, ERROR_CLASSES)
+    body  = generate_all()
 
     if args.helpdocs_api_key is not None:
         url = "https://api.helpdocs.io/v1/article/zg9hp7yx3u?key=" + \