From 6854ac8e5ad4fab0468c68c9b1683b62ef5cd662 Mon Sep 17 00:00:00 2001 From: Alexandra Cota Date: Thu, 14 Nov 2019 15:42:10 -0800 Subject: [PATCH 1/6] edit docstrings in client.py and project.py --- labelbox/client.py | 56 ++++++++++++++++++++------------------ labelbox/schema/project.py | 29 +++++++++++++------- 2 files changed, 49 insertions(+), 36 deletions(-) diff --git a/labelbox/client.py b/labelbox/client.py index 520e84607..b91adbded 100644 --- a/labelbox/client.py +++ b/labelbox/client.py @@ -32,7 +32,7 @@ class Client: def __init__(self, api_key=None, endpoint='https://api.labelbox.com/graphql'): - """ Create and initialize a Labelbox Client. + """ Creates and initializes a Labelbox Client. Args: api_key (str): API key. If None, the key is obtained from @@ -63,19 +63,20 @@ def execute(self, query, params=None, timeout=10.0): in appropriate labelbox.exceptions.LabelboxError subtypes. Args: - query (str): the query to execute. - params (dict): query parameters referenced within the query. + query (str): The query to execute. + params (dict): Query parameters referenced within the query. timeout (float): Max allowed time for query execution, in seconds. - Return: + Returns: dict, parsed JSON response. Raises: labelbox.exceptions.AuthenticationError: If authentication failed. - labelbox.exceptions.InvalidQueryError: If `query` is not + labelbox.exceptions.InvalidQueryError: If `query` was not syntactically or semantically valid (checked server-side). labelbox.exceptions.ApiLimitError: If the server API limit was - exceeded. Check Labelbox documentation to see API limits. + exceeded. See "How to import data" documentation to see + API limits. labelbox.exceptions.TimeoutError: If response was not received in `timeout` seconds. labelbox.exceptions.NetworkError: If an unknown error occurred @@ -172,12 +173,13 @@ def check_errors(keywords, *path): def upload_data(self, data): """ Uploads the given data (bytes) to Labelbox. + Args: - data (bytes): the data to upload. - Return: + data (bytes): The data to upload. + Returns: str, the URL of uploaded data. Raises: - labelbox.exceptions.LabelboxError: if upload failes. + labelbox.exceptions.LabelboxError: If upload failed. """ request_data = { "operations": json.dumps({ @@ -213,7 +215,7 @@ def _get_single(self, db_object_type, uid): Args: db_object_type (type): DbObject subclass. uid (str): Unique ID of the row. - Return: + Returns: Object of `db_object_type`. Raises: labelbox.exceptions.ResourceNotFoundError: If there is no object @@ -230,9 +232,10 @@ def _get_single(self, db_object_type, uid): def get_project(self, project_id): """ Gets a single Project with the given ID. + Args: project_id (str): Unique ID of the Project. - Return: + Returns: The sought Project. Raises: labelbox.exceptions.ResourceNotFoundError: If there is no @@ -242,9 +245,10 @@ def get_project(self, project_id): def get_dataset(self, dataset_id): """ Gets a single Dataset with the given ID. + Args: dataset_id (str): Unique ID of the Dataset. - Return: + Returns: The sought Dataset. Raises: labelbox.exceptions.ResourceNotFoundError: If there is no @@ -267,7 +271,7 @@ def _get_all(self, db_object_type, where): db_object_type (type): DbObject subclass. where (Comparison, LogicalOperation or None): The `where` clause for filtering. - Return: + Returns: An iterable of `db_object_type` instances. """ not_deleted = db_object_type.deleted == False @@ -284,7 +288,7 @@ def get_projects(self, where=None): Args: where (Comparison, LogicalOperation or None): The `where` clause for filtering. - Return: + Returns: An iterable of Projects (typically a PaginatedCollection). """ return self._get_all(Project, where) @@ -295,7 +299,7 @@ def get_datasets(self, where=None): Args: where (Comparison, LogicalOperation or None): The `where` clause for filtering. - Return: + Returns: An iterable of Datasets (typically a PaginatedCollection). """ return self._get_all(Dataset, where) @@ -306,23 +310,23 @@ def get_labeling_frontends(self, where=None): Args: where (Comparison, LogicalOperation or None): The `where` clause for filtering. - Return: + Returns: An iterable of LabelingFrontends (typically a PaginatedCollection). """ return self._get_all(LabelingFrontend, where) def _create(self, db_object_type, data): - """ Creates a object on the server. Attribute values are + """ Creates an object on the server. Attribute values are passed as keyword arguments: Args: db_object_type (type): A DbObjectType subtype. data (dict): Keys are attributes or their names (in Python, snake-case convention) and values are desired attribute values. - Return: - a new object of the given DB object type. + Returns: + A new object of the given DB object type. Raises: - InvalidAttributeError: in case the DB object type does not contain + InvalidAttributeError: If the DB object type does not contain any of the attribute names given in `data`. """ # Convert string attribute names to Field or Relationship objects. @@ -347,10 +351,10 @@ def create_dataset(self, **kwargs): Keyword arguments with new Dataset attribute values. Keys are attribute names (in Python, snake-case convention) and values are desired attribute values. - Return: - a new Dataset object. + Returns: + A new Dataset object. Raises: - InvalidAttributeError: in case the Dataset type does not contain + InvalidAttributeError: If the Dataset type does not contain any of the attribute names given in kwargs. """ return self._create(Dataset, kwargs) @@ -364,10 +368,10 @@ def create_project(self, **kwargs): Keyword arguments with new Project attribute values. Keys are attribute names (in Python, snake-case convention) and values are desired attribute values. - Return: - a new Project object. + Returns: + A new Project object. Raises: - InvalidAttributeError: in case the Project type does not contain + InvalidAttributeError: If the Project type does not contain any of the attribute names given in kwargs. """ return self._create(Project, kwargs) diff --git a/labelbox/schema/project.py b/labelbox/schema/project.py index 0474253f1..8b9942683 100644 --- a/labelbox/schema/project.py +++ b/labelbox/schema/project.py @@ -43,6 +43,7 @@ class Project(DbObject, Updateable, Deletable): def create_label(self, **kwargs): """ Creates a label on this Project. + Kwargs: Label attributes. At the minimum the label `DataRow`. """ @@ -107,9 +108,10 @@ def labels(self, datasets=None, order_by=None): def export_labels(self, timeout_seconds=60): """ Calls the server-side Label exporting that generates a JSON payload, and returns the URL to that payload. + Args: timeout_seconds (float): Max waiting time, in seconds. - Return: + Returns: URL of the data file with this Project's labels. If the server didn't generate during the `timeout_seconds` period, None is returned. @@ -136,6 +138,7 @@ def export_labels(self, timeout_seconds=60): def labeler_performance(self): """ Returns the labeler performances for this Project. + Returns: A PaginatedCollection of LabelerPerformance objects. """ @@ -161,9 +164,10 @@ def create_labeler_performance(client, result): def review_metrics(self, net_score): """ Returns this Project's review metrics. + Args: net_score (None or Review.NetScore): Indicates desired metric. - Return: + Returns: int, aggregation count of reviews for given net_score. """ if net_score not in (None,) + tuple(Entity.Review.NetScore): @@ -180,8 +184,10 @@ def review_metrics(self, net_score): def setup(self, labeling_frontend, labeling_frontend_options): """ Finalizes the Project setup. + Args: - labeling_frontend (LabelingFrontend): The labeling frontend to use. + labeling_frontend (LabelingFrontend): Which UI to use to label the + data. labeling_frontend_options (dict or str): Labeling frontend options, a.k.a. project ontology. If given a `dict` it will be converted to `str` using `json.dumps`. @@ -210,8 +216,8 @@ def set_labeling_parameter_overrides(self, data): Args: data (iterable): An iterable of tuples. Each tuple must contain (DataRow, priority, numberOfLabels) for the new override. - Return: - bool indicating if the operation was a success. + Returns: + bool, indicates if the operation was a success. """ data_str = ",\n".join( "{dataRow: {id: \"%s\"}, priority: %d, numLabels: %d }" % ( @@ -226,10 +232,11 @@ def set_labeling_parameter_overrides(self, data): def unset_labeling_parameter_overrides(self, data_rows): """ Removes labeling parameter overrides to this project. + Args: data_rows (iterable): An iterable of DataRows. - Return: - bool indicating if the operation was a success. + Returns: + bool, indicates if the operation was a success. """ id_param = "projectId" query_str = """mutation UnsetLabelingParameterOverridesPyApi($%s: ID!){ @@ -241,7 +248,8 @@ def unset_labeling_parameter_overrides(self, data_rows): return res["project"]["unsetLabelingParameterOverrides"]["success"] def upsert_review_queue(self, quota_factor): - """ Reinitiate the review queue for this project. + """ Reinitiates the review queue for this project. + Args: quota_factor (float): Which part (percentage) of the queue to reinitiate. Between 0 and 1. @@ -257,11 +265,12 @@ def upsert_review_queue(self, quota_factor): def extend_reservations(self, queue_type): - """ Extend all the current reservations for the current user on the given + """ Extends all the current reservations for the current user on the given queue type. + Args: queue_type (str): Either "LabelingQueue" or "ReviewQueue" - Return: + Returns: int, the number of reservations that were extended. """ if queue_type not in ("LabelingQueue", "ReviewQueue"): From 85760b33c8fe6bba6e6ce52aa9d4c1cc3ae078a1 Mon Sep 17 00:00:00 2001 From: Alexandra Cota Date: Thu, 14 Nov 2019 15:45:55 -0800 Subject: [PATCH 2/6] edit docstrings in dataset.py --- labelbox/schema/dataset.py | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/labelbox/schema/dataset.py b/labelbox/schema/dataset.py index 4fe18455b..bba40abd0 100644 --- a/labelbox/schema/dataset.py +++ b/labelbox/schema/dataset.py @@ -24,6 +24,7 @@ class Dataset(DbObject, Updateable, Deletable): def create_data_row(self, **kwargs): """ Creates a single DataRow belonging to this dataset. + Kwargs: Key-value arguments containing new `DataRow` data. At a minimum they must contain `row_data`. The value for @@ -63,17 +64,17 @@ def create_data_rows(self, items): Args: items (iterable of (dict or str)): See above for details. - Return: + Returns: Task representing the data import on the server side. The Task can be used for inspecting task progress and waiting until it's done. - Raise: - InvalidQueryError: if the `items` parameter does not conform to + Raises: + InvalidQueryError: If the `items` parameter does not conform to the specification above or if the server did not accept the DataRow creation request (unknown reason). - ResourceNotFoundError: if unable to retrieve the Task for the + ResourceNotFoundError: If unable to retrieve the Task for the import process. This could imply that the import failed. - InvalidAttributeError: if there are fields in `items` not valid for + InvalidAttributeError: If there are fields in `items` not valid for a DataRow. """ file_upload_thread_count = 20 @@ -153,7 +154,7 @@ def data_row_for_external_id(self, external_id): A single `DataRow` with the given ID. Raises: - labelbox.exceptions.ResourceNotFoundError: if there is no `DataRow` + labelbox.exceptions.ResourceNotFoundError: If there is no `DataRow` in this `DataSet` with the given external ID, or if there are multiple `DataRows` for it. """ From ffb6429af64f638a16da9773ff14eaa9dc1e0f3c Mon Sep 17 00:00:00 2001 From: Alexandra Cota Date: Thu, 14 Nov 2019 15:47:50 -0800 Subject: [PATCH 3/6] edit docstrings in data_row.py --- labelbox/schema/data_row.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/labelbox/schema/data_row.py b/labelbox/schema/data_row.py index 3b2f96555..1f43e3c5a 100644 --- a/labelbox/schema/data_row.py +++ b/labelbox/schema/data_row.py @@ -23,6 +23,7 @@ class DataRow(DbObject, Updateable, BulkDeletable): @staticmethod def bulk_delete(data_rows): """ Deletes all the given DataRows. + Args: data_rows (list of DataRow): The DataRows to delete. """ @@ -35,11 +36,12 @@ def __init__(self, *args, **kwargs): def create_metadata(self, meta_type, meta_value): """ Creates an asset metadata for this DataRow. + Args: meta_type (str): Asset metadata type, must be one of: VIDEO, IMAGE, TEXT. meta_value (str): Asset metadata value. - Return: + Returns: AssetMetadata DB object. """ meta_type_param = "metaType" From c29a1ed20dfe8a26cb4e3237f57b256fe3e4bfc3 Mon Sep 17 00:00:00 2001 From: Alexandra Cota Date: Thu, 14 Nov 2019 15:50:45 -0800 Subject: [PATCH 4/6] edit docstrings in label.py --- labelbox/schema/label.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/labelbox/schema/label.py b/labelbox/schema/label.py index f5d894f8b..efe05b843 100644 --- a/labelbox/schema/label.py +++ b/labelbox/schema/label.py @@ -28,6 +28,7 @@ def __init__(self, *args, **kwargs): @staticmethod def bulk_delete(labels): """ Deletes all the given Labels. + Args: labels (list of Label): The Labels to delete. """ @@ -35,6 +36,7 @@ def bulk_delete(labels): def create_review(self, **kwargs): """ Creates a Review for this label. + Kwargs: Review attributes. At a minimum a `Review.score` field value must be provided. @@ -45,7 +47,8 @@ def create_review(self, **kwargs): def create_benchmark(self): """ Creates a Benchmark for this Label. - Return: + + Returns: The newly created Benchmark. """ label_id_param = "labelId" From c97e2467bd5236a36c4832a4f6ce0f614927919d Mon Sep 17 00:00:00 2001 From: Alexandra Cota Date: Thu, 14 Nov 2019 15:53:35 -0800 Subject: [PATCH 5/6] edit docstrings in webhook.py --- labelbox/schema/webhook.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/labelbox/schema/webhook.py b/labelbox/schema/webhook.py index d35a6b386..c62df75a9 100644 --- a/labelbox/schema/webhook.py +++ b/labelbox/schema/webhook.py @@ -28,6 +28,7 @@ class Webhook(DbObject, Updateable): @staticmethod def create(client, topics, url, secret, project): """ Creates a Webhook. + Args: client (Client): The Labelbox client used to connect to the server. @@ -39,7 +40,7 @@ def create(client, topics, url, secret, project): project (Project or None): The project for which notifications should be sent. If None notifications are sent for all events in your organization. - Return: + Returns: A newly created Webhook. """ project_str = "" if project is None \ @@ -58,6 +59,7 @@ def create(client, topics, url, secret, project): def update(self, topics=None, url=None, status=None): """ Updates this Webhook. + Args: topics (list of str): The new topics value, optional. url (str): The new URL value, optional. From a2075421f0270996524ee1787888da15edb04c68 Mon Sep 17 00:00:00 2001 From: Alexandra Cota Date: Fri, 15 Nov 2019 09:25:32 -0800 Subject: [PATCH 6/6] changes to docstrings in client.py after first PR. --- labelbox/client.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/labelbox/client.py b/labelbox/client.py index b91adbded..2d3c4ccd0 100644 --- a/labelbox/client.py +++ b/labelbox/client.py @@ -72,11 +72,11 @@ def execute(self, query, params=None, timeout=10.0): Raises: labelbox.exceptions.AuthenticationError: If authentication failed. - labelbox.exceptions.InvalidQueryError: If `query` was not + labelbox.exceptions.InvalidQueryError: If `query` is not syntactically or semantically valid (checked server-side). labelbox.exceptions.ApiLimitError: If the server API limit was - exceeded. See "How to import data" documentation to see - API limits. + exceeded. See "How to import data" in the online documentation + to see API limits. labelbox.exceptions.TimeoutError: If response was not received in `timeout` seconds. labelbox.exceptions.NetworkError: If an unknown error occurred