From 40686a5ff1b7213e95f41053632c0d99274776a2 Mon Sep 17 00:00:00 2001 From: Alex Cota Date: Mon, 11 Jan 2021 20:51:34 -0800 Subject: [PATCH 01/12] Modify files for sphinx auto docs --- .gitignore | 3 ++ labelbox/client.py | 49 +++++++++++++------------- labelbox/schema/asset_metadata.py | 8 +++-- labelbox/schema/benchmark.py | 15 ++++++-- labelbox/schema/bulk_import_request.py | 19 ++++++++-- labelbox/schema/data_row.py | 17 +++++++-- labelbox/schema/dataset.py | 28 +++++++++------ labelbox/schema/enums.py | 2 ++ labelbox/schema/label.py | 13 +++++++ labelbox/schema/labeling_frontend.py | 22 ++++++++++-- labelbox/schema/ontology.py | 19 +++++++--- labelbox/schema/organization.py | 16 +++++++-- labelbox/schema/prediction.py | 15 ++++++-- labelbox/schema/project.py | 34 +++++++++++++++--- labelbox/schema/review.py | 18 +++++++++- labelbox/schema/task.py | 16 +++++++-- labelbox/schema/user.py | 16 +++++++++ labelbox/schema/webhook.py | 8 +++++ 18 files changed, 255 insertions(+), 63 deletions(-) diff --git a/.gitignore b/.gitignore index b15995323..b23aa97bc 100644 --- a/.gitignore +++ b/.gitignore @@ -131,3 +131,6 @@ dmypy.json # macos files .DS_STORE + +# Docs build +labelbox/build/ \ No newline at end of file diff --git a/labelbox/client.py b/labelbox/client.py index 96ba7ccf0..d26fb24a9 100644 --- a/labelbox/client.py +++ b/labelbox/client.py @@ -29,6 +29,7 @@ class Client: """ 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, @@ -36,18 +37,16 @@ def __init__(self, endpoint='https://api.labelbox.com/graphql'): """ Creates and initializes a Labelbox Client. - Logging is defaulted to level WARNING. To receive more verbose - output to console, update logging.level to the - appropriate level. + Logging is defaulted to level WARNING. To receive more verbose + output to console, update logging.level to the appropriate level. - >>> import logger - >>> logging.basicConfig(level = logging.INFO) - >>> client = Client("") + >>> import logger + >>> logging.basicConfig(level = logging.INFO) + >>> client = Client("") Args: - 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. + api_key (String): API key. If None, the key is obtained from the "LABELBOX_API_KEY" environment variable. + endpoint (String): 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 @@ -336,6 +335,7 @@ def get_dataset(self, dataset_id): def get_user(self): """ Gets the current User database object. + >>> user = client.get_user() """ @@ -377,6 +377,7 @@ def get_projects(self, where=None): for filtering. Returns: An iterable of Projects (typically a PaginatedCollection). + """ return self._get_all(Project, where) @@ -390,6 +391,7 @@ def get_datasets(self, where=None): for filtering. Returns: An iterable of Datasets (typically a PaginatedCollection). + """ return self._get_all(Dataset, where) @@ -403,6 +405,7 @@ def get_labeling_frontends(self, where=None): for filtering. Returns: An iterable of LabelingFrontends (typically a PaginatedCollection). + """ return self._get_all(LabelingFrontend, where) @@ -434,16 +437,15 @@ def _create(self, db_object_type, data): return db_object_type(self, res) def create_dataset(self, **kwargs): - """ Creates a Dataset object on the server. Attribute values are - passed as keyword arguments: + """ Creates a Dataset object on the server. + + Attribute values are passed as keyword arguments. - >>> project = client.get_project("") - >>> dataset = client.create_dataset(name="", projects=project) + >>> project = client.get_project("") + >>> dataset = client.create_dataset(name="", projects=project) - Kwargs: - Keyword arguments with new Dataset attribute values. - Keys are attribute names (in Python, snake-case convention) and - values are desired attribute values. + Args: + kwargs: Keyword arguments with Dataset attribute values. Returns: A new Dataset object. Raises: @@ -453,15 +455,14 @@ def create_dataset(self, **kwargs): return self._create(Dataset, kwargs) def create_project(self, **kwargs): - """ Creates a Project object on the server. Attribute values are - passed as keyword arguments: + """ Creates a Project object on the server. + + Attribute values are passed as keyword arguments. - >>> project = client.create_project(name="", description="") + >>> project = client.create_project(name="", description="") - Kwargs: - Keyword arguments with new Project attribute values. - Keys are attribute names (in Python, snake-case convention) and - values are desired attribute values. + Args: + kwargs: Keyword arguments with new Project attribute values. Returns: A new Project object. Raises: diff --git a/labelbox/schema/asset_metadata.py b/labelbox/schema/asset_metadata.py index f0990834f..0d88f3d73 100644 --- a/labelbox/schema/asset_metadata.py +++ b/labelbox/schema/asset_metadata.py @@ -3,8 +3,12 @@ class AssetMetadata(DbObject): - """ AssetMetadata is a datatype to provide extra context about an asset - while labeling. + """ Asset metadata (AKA Attachments) provides extra context about an asset while labeling. + + Attributes: + meta_type (String): "IMAGE", "VIDEO", "TEXT", or "IMAGE_OVERLAY" + meta_value (String): URL to an external file or a string of text + """ VIDEO = "VIDEO" IMAGE = "IMAGE" diff --git a/labelbox/schema/benchmark.py b/labelbox/schema/benchmark.py index fe5075fc7..7a6bb3ff8 100644 --- a/labelbox/schema/benchmark.py +++ b/labelbox/schema/benchmark.py @@ -3,12 +3,21 @@ class Benchmark(DbObject): - """ Benchmarks (also known as Golden Standard) is a quality assurance tool - for training data. Training data quality is the measure of accuracy and - consistency of the training data. Benchmarks works by interspersing data + """ Represents a benchmark label. + + The Benchmarks tool works by interspersing data to be labeled, for which there is a benchmark label, to each person labeling. These labeled data are compared against their respective benchmark and an accuracy score between 0 and 100 percent is calculated. + + Attributes: + created_at (DateTime) + last_activity (DateTime) + average_agreement (Float) + completed_count (Int) + + created_by (Relationship): `ToOne` relationship to User + reference_label (Relationship): `ToOne` relationship to Label """ created_at = Field.DateTime("created_at") created_by = Relationship.ToOne("User", False, "created_by") diff --git a/labelbox/schema/bulk_import_request.py b/labelbox/schema/bulk_import_request.py index b1ff198ce..bec49eb4e 100644 --- a/labelbox/schema/bulk_import_request.py +++ b/labelbox/schema/bulk_import_request.py @@ -92,6 +92,20 @@ def _send_create_file_command( class BulkImportRequest(DbObject): + """ Represents an import job. + + Attributes: + name (String) + state (Enum): FAILED, RUNNING, or FINISHED (Refers to the whole import job) + input_file_url (String): URL to your web-hosted NDJSON file + error_file_url (String): NDJSON that contains error messages for failed annotations + status_file_url (String): NDJSON that contains status for each annotation + created_at (DateTime): UTC timestamp for date BulkImportRequest was created + + project (Relationship): `ToOne` relationship to Project + created_by (Relationship): `ToOne` relationship to User + + """ name = Field.String("name") state = Field.Enum(BulkImportRequestState, "state") input_file_url = Field.String("input_file_url") @@ -196,8 +210,9 @@ def create_from_url(cls, client, project_id: str, name: str, def create_from_objects(cls, client, project_id: str, name: str, predictions: Iterable[dict]) -> 'BulkImportRequest': """ - Creates a BulkImportRequest from an iterable of dictionaries conforming to - JSON predictions format, e.g.: + Creates a `BulkImportRequest` from an iterable of dictionaries. + + Conforms to JSON predictions format, e.g.: ``{ "uuid": "9fd9a92e-2560-4e77-81d4-b2e955800092", "schemaId": "ckappz7d700gn0zbocmqkwd9i", diff --git a/labelbox/schema/data_row.py b/labelbox/schema/data_row.py index f8d12361c..5bf1c4460 100644 --- a/labelbox/schema/data_row.py +++ b/labelbox/schema/data_row.py @@ -5,8 +5,21 @@ class DataRow(DbObject, Updateable, BulkDeletable): - """ A DataRow represents a single piece of data. For example, if you have - a CSV with 100 rows, you will have 1 Dataset and 100 DataRows. + """ Internal Labelbox representation of a single piece of data (e.g. image, video, text). + + Attributes: + external_id (String): User-generated file name or identifier + row_data (String): Paths to local files are uploaded to Labelbox's server. Otherwise, it's treated as an external URL. + updated_at (DateTime) + created_at (DateTime) + + dataset (Relationship): `ToOne` relationship to Dataset + created_by (Relationship): `ToOne` relationship to User + organization (Relationship): `ToOne` relationship to Organization + labels (Relationship): `ToMany` relationship to Label + metadata (Relationship): `ToMany` relationship to AssetMetadata + predictions (Relationship): `ToMany` relationship to Prediction + """ external_id = Field.String("external_id") row_data = Field.String("row_data") diff --git a/labelbox/schema/dataset.py b/labelbox/schema/dataset.py index 750b2e013..361f07ba6 100644 --- a/labelbox/schema/dataset.py +++ b/labelbox/schema/dataset.py @@ -8,8 +8,19 @@ class Dataset(DbObject, Updateable, Deletable): - """ A dataset is a collection of DataRows. For example, if you have a CSV with - 100 rows, you will have 1 Dataset and 100 DataRows. + """ A Dataset is a collection of DataRows. + + Attributes: + name (String) + description (String) + updated_at (DateTime) + created_at (DateTime) + + projects (Relationship): `ToMany` relationship to Project + data_rows (Relationship): `ToMany` relationship to DataRow + created_by (Relationship): `ToOne` relationship to User + organization (Relationship): `ToOne` relationship to Organization + """ name = Field.String("name") description = Field.String("description") @@ -27,14 +38,11 @@ def create_data_row(self, **kwargs): >>> dataset.create_data_row(row_data="http://my_site.com/photos/img_01.jpg") - Kwargs: - Key-value arguments containing new `DataRow` data. - At a minimum `kwargs` must contain `row_data`. The value for - `row_data` is a string. If it is a path to an existing local - file then it is uploaded to Labelbox's server. Otherwise it is - treated as an external URL. + Args: + kwargs: Key-value arguments containing new `DataRow` data. At a minimum, must contain ``row_data``. + Raises: - InvalidQueryError: If `DataRow.row_data` field value is not provided + InvalidQueryError: If ``DataRow.row_data`` field value is not provided in `kwargs`. InvalidAttributeError: in case the DB object type does not contain any of the field names given in `kwargs`. @@ -62,7 +70,7 @@ def create_data_rows(self, items): is uploaded to Labelbox and a DataRow referencing it is created. If an item is a `dict`, then it should map `DataRow` fields (or their names) to values. At the minimum an `item` passed as a `dict` must - contain a `DataRow.row_data` key and value. + contain a ``DataRow.row_data`` key and value. >>> dataset.create_data_rows([ >>> {DataRow.row_data:"http://my_site.com/photos/img_01.jpg"}, diff --git a/labelbox/schema/enums.py b/labelbox/schema/enums.py index b6943cef9..438fc496a 100644 --- a/labelbox/schema/enums.py +++ b/labelbox/schema/enums.py @@ -2,6 +2,8 @@ class BulkImportRequestState(Enum): + """ State of the import job when importing annotations (RUNNING, FAILED, or FINISHED). + """ RUNNING = "RUNNING" FAILED = "FAILED" FINISHED = "FINISHED" diff --git a/labelbox/schema/label.py b/labelbox/schema/label.py index ef968b15e..3059aa01b 100644 --- a/labelbox/schema/label.py +++ b/labelbox/schema/label.py @@ -7,6 +7,19 @@ class Label(DbObject, Updateable, BulkDeletable): """ Label represents an assessment on a DataRow. For example one label could contain 100 bounding boxes (annotations). + + Attributes: + label (String) + seconds_to_label (Float) + agreement (Float) + benchmark_agreement (Float) + is_benchmark_reference (Boolean) + + project (Relationship): `ToOne` relationship to Project + data_row (Relationship): `ToOne` relationship to DataRow + reviews (Relationship): `ToMany` relationship to Review + created_by (Relationship): `ToOne` relationship to User + """ def __init__(self, *args, **kwargs): diff --git a/labelbox/schema/labeling_frontend.py b/labelbox/schema/labeling_frontend.py index 2dbbe813c..b2b1e9a81 100644 --- a/labelbox/schema/labeling_frontend.py +++ b/labelbox/schema/labeling_frontend.py @@ -3,9 +3,18 @@ class LabelingFrontend(DbObject): - """ Is a type representing an HTML / JavaScript UI that is used to generate - labels. “Image Labeling” is the default Labeling Frontend that comes in every + """ Label editor. + + Represents an HTML / JavaScript UI that is used to generate + labels. “Editor” is the default Labeling Frontend that comes in every organization. You can create new labeling frontends for an organization. + + Attributes: + name (String) + description (String) + iframe_url_path (String) + + projects (Relationship): `ToMany` relationship to Project """ name = Field.String("name") description = Field.String("description") @@ -16,6 +25,15 @@ class LabelingFrontend(DbObject): class LabelingFrontendOptions(DbObject): + """ Label interface options. + + Attributes: + customization_options (Field) + + project (Relationship): `ToOne` relationship to Project + labeling_frontend (Relationship): `ToOne` relationship to LabelingFrontend + organization (Relationship): `ToOne` relationship to Organization + """ customization_options = Field.String("customization_options") project = Relationship.ToOne("Project") diff --git a/labelbox/schema/ontology.py b/labelbox/schema/ontology.py index 301507884..33da2413b 100644 --- a/labelbox/schema/ontology.py +++ b/labelbox/schema/ontology.py @@ -1,4 +1,3 @@ -"""Client side object for interacting with the ontology.""" import abc from dataclasses import dataclass @@ -65,10 +64,20 @@ def from_json(cls, json_dict): class Ontology(DbObject): - """ A ontology specifies which tools and classifications are available - to a project. - - NOTE: This is read only for now. + """An ontology specifies which tools and classifications are available + to a project. This is read only for now. + + Attributes: + name (String) + description (String) + updated_at (DateTime) + created_at (DateTime) + normalized (Json) + object_schema_count (Int) + classification_schema_count (Int) + + projects (Relationship): `ToMany` relationship to Project + created_by (Relationship): `ToOne` relationship to User >>> project = client.get_project(name="") >>> ontology = project.ontology() diff --git a/labelbox/schema/organization.py b/labelbox/schema/organization.py index 5a4465189..381959304 100644 --- a/labelbox/schema/organization.py +++ b/labelbox/schema/organization.py @@ -3,9 +3,19 @@ class Organization(DbObject): - """ An Organization is a group of Users associated with data created by - Users within that Organization. Typically all Users within an Organization - have access to data created by any User in the same Organization. + """ An Organization is a group of Users. + It is associated with data created by Users within that Organization. + Typically all Users within an Organization have access to data created by any User in the same Organization. + + Attributes: + updated_at (DateTime) + created_at (DateTime) + name (String) + + users (Relationship): `ToMany` relationship to User + projects (Relationship): `ToMany` relationship to Project + webhooks (Relationship): `ToMany` relationship to Webhook + """ # RelationshipManagers in Organization use the type in Query (and diff --git a/labelbox/schema/prediction.py b/labelbox/schema/prediction.py index a59e0ca86..f17386c8e 100644 --- a/labelbox/schema/prediction.py +++ b/labelbox/schema/prediction.py @@ -3,15 +3,26 @@ class PredictionModel(DbObject): - """ A prediction model represents a specific version of a model. + """ A prediction created by a PredictionModel. NOTE: This is used for the legacy editor [1], if you wish to - import annotations, refer to [2] + import annotations, refer to [2]. [1] https://labelbox.com/docs/legacy/import-model-prediction [2] https://labelbox.com/docs/automation/model-assisted-labeling + Attributes: + updated_at (DateTime) + created_at (DateTime) + label (String) + agreement (Float) + + organization (Relationship): `ToOne` relationship to Organization + prediction_model (Relationship): `ToOne` relationship to PredictionModel + data_row (Relationship): `ToOne` relationship to PredictionModel + project (Relationship): `ToOne` relationship to Project + """ updated_at = Field.DateTime("updated_at") created_at = Field.DateTime("created_at") diff --git a/labelbox/schema/project.py b/labelbox/schema/project.py index e2a6927c3..1aad1431a 100644 --- a/labelbox/schema/project.py +++ b/labelbox/schema/project.py @@ -27,6 +27,31 @@ class Project(DbObject, Updateable, Deletable): """ A Project is a container that includes a labeling frontend, an ontology, datasets and labels. + + Attributes: + name (String) + description (String) + updated_at (DateTime) + created_at (DateTime) + setup_complete (DateTime) + last_activity_time (DateTime) + auto_audit_number_of_labels (Int) + auto_audit_percentage (Float) + + datasets (Relationship): `ToMany` relationship to Dataset + created_by (Relationship): `ToOne` relationship to User + organization (Relationship): `ToOne` relationship to Organization + reviews (Relationship): `ToMany` relationship to Review + labeling_frontend (Relationship): `ToOne` relationship to LabelingFrontend + labeling_frontend_options (Relationship): `ToMany` relationship to LabelingFrontendOptions + labeling_parameter_overrides (Relationship): `ToMany` relationship to LabelingParameterOverride + webhooks (Relationship): `ToMany` relationship to Webhook + benchmarks (Relationship): `ToMany` relationship to Benchmark + active_prediction_model (Relationship): `ToOne` relationship to PredictionModel + predictions (Relationship): `ToMany` relationship to Prediction + ontology (Relationship): `ToOne` relationship to Ontology + + """ name = Field.String("name") description = Field.String("description") @@ -58,8 +83,9 @@ def create_label(self, **kwargs): """ Creates a label on a Legacy Editor project. Not supported in the new Editor. - Kwargs: - Label attributes. At the minimum the label `DataRow`. + Args: + kwargs: Label attributes. At the minimum the label `DataRow`. + """ # Copy-paste of Client._create code so we can inject # a connection to Type. Type objects are on their way to being @@ -129,9 +155,7 @@ def export_labels(self, timeout_seconds=60): Args: timeout_seconds (float): Max waiting time, in seconds. 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. + URL of the data file with this Project's labels. If the server didn't generate during the `timeout_seconds` period, None is returned. """ sleep_time = 2 id_param = "projectId" diff --git a/labelbox/schema/review.py b/labelbox/schema/review.py index 8a4ee5275..a96ba90f8 100644 --- a/labelbox/schema/review.py +++ b/labelbox/schema/review.py @@ -6,10 +6,26 @@ class Review(DbObject, Deletable, Updateable): """ Reviewing labeled data is a collaborative quality assurance technique. + A Review object indicates the quality of the assigned Label. The aggregated - review numbers can be obtained on a Project object. """ + review numbers can be obtained on a Project object. + + Attributes: + created_at (DateTime) + updated_at (DateTime) + score (Float) + + created_by (Relationship): `ToOne` relationship to User + organization (Relationship): `ToOne` relationship to Organization + project (Relationship): `ToOne` relationship to Project + label (Relationship): `ToOne` relationship to Label + + """ class NetScore(Enum): + """ Negative, Zero, or Positive. + + """ Negative = auto() Zero = auto() Positive = auto() diff --git a/labelbox/schema/task.py b/labelbox/schema/task.py index 9af3e6f91..7553b5260 100644 --- a/labelbox/schema/task.py +++ b/labelbox/schema/task.py @@ -11,6 +11,17 @@ class Task(DbObject): """ Represents a server-side process that might take a longer time to process. Allows the Task state to be updated and checked on the client side. + + Attributes: + updated_at (DateTime) + created_at (DateTime) + name (String) + status (String) + completion_percentage (Float) + + created_by (Relationship): `ToOne` relationship to User + organization (Relationship): `ToOne` relationship to Organization + """ updated_at = Field.DateTime("updated_at") created_at = Field.DateTime("created_at") @@ -33,9 +44,10 @@ def refresh(self): def wait_till_done(self, timeout_seconds=60): """ Waits until the task is completed. Periodically queries the server to update the task attributes. + Args: - timeout_seconds (float): Maximum time this method can block, in - seconds. Defaults to one minute. + timeout_seconds (Float): Maximum time this method can block, in seconds. Defaults to one minute. + """ check_frequency = 2 # frequency of checking, in seconds while True: diff --git a/labelbox/schema/user.py b/labelbox/schema/user.py index 33b15df79..e5dc654cb 100644 --- a/labelbox/schema/user.py +++ b/labelbox/schema/user.py @@ -5,6 +5,22 @@ class User(DbObject): """ A User is a registered Labelbox user (for example you) associated with data they create or import and an Organization they belong to. + + Attributes: + updated_at (DateTime) + created_at (DateTime) + email (String) + name (String) + nickname (String) + intercom_hash (String) + picture (String) + is_viewer (Boolean) + is_external_viewer (Boolean) + + organization (Relationship): `ToOne` relationship to Organization + created_tasks (Relationship): `ToMany` relationship to Task + projects (Relationship): `ToMany` relationship to Project + """ updated_at = Field.DateTime("updated_at") created_at = Field.DateTime("created_at") diff --git a/labelbox/schema/webhook.py b/labelbox/schema/webhook.py index bb37481ae..6a10319b5 100644 --- a/labelbox/schema/webhook.py +++ b/labelbox/schema/webhook.py @@ -7,6 +7,14 @@ class Webhook(DbObject, Updateable): """ Represents a server-side rule for sending notifications to a web-server whenever one of several predefined actions happens within a context of a Project or an Organization. + + Attributes: + updated_at (DateTime) + created_at (DateTime) + url (String) + topics (String): LABEL_CREATED, LABEL_UPDATED, LABEL_DELETED + status (String): ACTIVE, INACTIVE, REVOKED + """ # Status From 3e382228f28aa4574e526a7fab500c376ad09179 Mon Sep 17 00:00:00 2001 From: Alex Cota Date: Tue, 12 Jan 2021 19:39:19 -0800 Subject: [PATCH 02/12] Fix Python class names and kwargs --- .gitignore | 2 +- labelbox/client.py | 29 ++++++------- labelbox/exceptions.py | 1 + labelbox/pagination.py | 5 ++- labelbox/schema/asset_metadata.py | 5 +-- labelbox/schema/benchmark.py | 14 +++--- labelbox/schema/bulk_import_request.py | 19 ++++----- labelbox/schema/data_row.py | 17 ++++---- labelbox/schema/dataset.py | 15 ++++--- labelbox/schema/label.py | 15 +++---- labelbox/schema/labeling_frontend.py | 8 ++-- labelbox/schema/ontology.py | 21 ++++----- labelbox/schema/organization.py | 8 ++-- labelbox/schema/prediction.py | 46 ++++++++++---------- labelbox/schema/project.py | 59 +++++++++++++------------- labelbox/schema/review.py | 10 ++--- labelbox/schema/task.py | 14 +++--- labelbox/schema/user.py | 19 ++++----- labelbox/schema/webhook.py | 10 ++--- 19 files changed, 153 insertions(+), 164 deletions(-) diff --git a/.gitignore b/.gitignore index b23aa97bc..bd46f49c6 100644 --- a/.gitignore +++ b/.gitignore @@ -133,4 +133,4 @@ dmypy.json .DS_STORE # Docs build -labelbox/build/ \ No newline at end of file +labelbox/build/ diff --git a/labelbox/client.py b/labelbox/client.py index d26fb24a9..204c763a5 100644 --- a/labelbox/client.py +++ b/labelbox/client.py @@ -26,10 +26,11 @@ class Client: - """ 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). + """ 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, @@ -38,20 +39,19 @@ def __init__(self, """ Creates and initializes a Labelbox Client. Logging is defaulted to level WARNING. To receive more verbose - output to console, update logging.level to the appropriate level. + output to console, update `logging.level` to the appropriate level. >>> import logger >>> logging.basicConfig(level = logging.INFO) >>> client = Client("") Args: - api_key (String): API key. If None, the key is obtained from the "LABELBOX_API_KEY" environment variable. - endpoint (String): URL of the Labelbox server to connect to. + 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: @@ -73,8 +73,10 @@ def __init__(self, labelbox.exceptions.InternalServerError)) def execute(self, query, params=None, timeout=10.0): """ Sends a request to the server for the execution of the - given query. Checks the response for errors and wraps errors - in appropriate labelbox.exceptions.LabelboxError subtypes. + given query. + + Checks the response for errors and wraps errors + in appropriate `labelbox.exceptions.LabelboxError` subtypes. Args: query (str): The query to execute. @@ -218,7 +220,6 @@ def upload_file(self, path: str) -> str: str, the URL of uploaded data. Raises: labelbox.exceptions.LabelboxError: If upload failed. - """ content_type, _ = mimetypes.guess_type(path) filename = os.path.basename(path) @@ -337,7 +338,6 @@ def get_user(self): """ Gets the current User database object. >>> user = client.get_user() - """ return self._get_single(User, None) @@ -377,7 +377,6 @@ def get_projects(self, where=None): for filtering. Returns: An iterable of Projects (typically a PaginatedCollection). - """ return self._get_all(Project, where) @@ -391,7 +390,6 @@ def get_datasets(self, where=None): for filtering. Returns: An iterable of Datasets (typically a PaginatedCollection). - """ return self._get_all(Dataset, where) @@ -405,7 +403,6 @@ def get_labeling_frontends(self, where=None): for filtering. Returns: An iterable of LabelingFrontends (typically a PaginatedCollection). - """ return self._get_all(LabelingFrontend, where) @@ -445,7 +442,7 @@ def create_dataset(self, **kwargs): >>> dataset = client.create_dataset(name="", projects=project) Args: - kwargs: Keyword arguments with Dataset attribute values. + **kwargs: Keyword arguments with Dataset attribute values. Returns: A new Dataset object. Raises: @@ -462,7 +459,7 @@ def create_project(self, **kwargs): >>> project = client.create_project(name="", description="") Args: - kwargs: Keyword arguments with new Project attribute values. + **kwargs: Keyword arguments with Project attribute values. Returns: A new Project object. Raises: diff --git a/labelbox/exceptions.py b/labelbox/exceptions.py index 9dc8a75cf..9a7292b33 100644 --- a/labelbox/exceptions.py +++ b/labelbox/exceptions.py @@ -31,6 +31,7 @@ class ResourceNotFoundError(LabelboxError): def __init__(self, db_object_type, params): """ Constructor. + Args: db_object_type (type): A labelbox.schema.DbObject subtype. params (dict): Dict of params identifying the sought resource. diff --git a/labelbox/pagination.py b/labelbox/pagination.py index 566edffa2..5b8b6719a 100644 --- a/labelbox/pagination.py +++ b/labelbox/pagination.py @@ -4,16 +4,17 @@ class PaginatedCollection: """ An iterable collection of database objects (Projects, Labels, etc...). + Implements automatic (transparent to the user) paginated fetching during iteration. Intended for use by library internals and not by the end user. - For a list of attributes see __init__(...) documentation. The params of __init__ map exactly to object attributes. """ def __init__(self, client, query, params, dereferencing, obj_class): """ Creates a PaginatedCollection. - Params: + + Args: client (labelbox.Client): the client used for fetching data from DB. query (str): Base query used for pagination. It must contain two '%d' placeholders, the first for pagination 'skip' clause and diff --git a/labelbox/schema/asset_metadata.py b/labelbox/schema/asset_metadata.py index 0d88f3d73..c5aa0ff9c 100644 --- a/labelbox/schema/asset_metadata.py +++ b/labelbox/schema/asset_metadata.py @@ -6,9 +6,8 @@ class AssetMetadata(DbObject): """ Asset metadata (AKA Attachments) provides extra context about an asset while labeling. Attributes: - meta_type (String): "IMAGE", "VIDEO", "TEXT", or "IMAGE_OVERLAY" - meta_value (String): URL to an external file or a string of text - + meta_type (str): IMAGE, VIDEO, TEXT, or IMAGE_OVERLAY + meta_value (str): URL to an external file or a string of text """ VIDEO = "VIDEO" IMAGE = "IMAGE" diff --git a/labelbox/schema/benchmark.py b/labelbox/schema/benchmark.py index 7a6bb3ff8..f703c2519 100644 --- a/labelbox/schema/benchmark.py +++ b/labelbox/schema/benchmark.py @@ -5,16 +5,16 @@ class Benchmark(DbObject): """ Represents a benchmark label. - The Benchmarks tool works by interspersing data - to be labeled, for which there is a benchmark label, to each person labeling. - These labeled data are compared against their respective benchmark and an + The Benchmarks tool works by interspersing data to be labeled, for + which there is a benchmark label, to each person labeling. These + labeled data are compared against their respective benchmark and an accuracy score between 0 and 100 percent is calculated. Attributes: - created_at (DateTime) - last_activity (DateTime) - average_agreement (Float) - completed_count (Int) + created_at (datetime) + last_activity (datetime) + average_agreement (float) + completed_count (int) created_by (Relationship): `ToOne` relationship to User reference_label (Relationship): `ToOne` relationship to Label diff --git a/labelbox/schema/bulk_import_request.py b/labelbox/schema/bulk_import_request.py index bec49eb4e..a8d54e40b 100644 --- a/labelbox/schema/bulk_import_request.py +++ b/labelbox/schema/bulk_import_request.py @@ -92,19 +92,18 @@ def _send_create_file_command( class BulkImportRequest(DbObject): - """ Represents an import job. + """Represents the import job when importing annotations. Attributes: - name (String) + name (str) state (Enum): FAILED, RUNNING, or FINISHED (Refers to the whole import job) - input_file_url (String): URL to your web-hosted NDJSON file - error_file_url (String): NDJSON that contains error messages for failed annotations - status_file_url (String): NDJSON that contains status for each annotation - created_at (DateTime): UTC timestamp for date BulkImportRequest was created + input_file_url (str): URL to your web-hosted NDJSON file + error_file_url (str): NDJSON that contains error messages for failed annotations + status_file_url (str): NDJSON that contains status for each annotation + created_at (datetime): UTC timestamp for date BulkImportRequest was created project (Relationship): `ToOne` relationship to Project created_by (Relationship): `ToOne` relationship to User - """ name = Field.String("name") state = Field.Enum(BulkImportRequestState, "state") @@ -117,8 +116,7 @@ class BulkImportRequest(DbObject): created_by = Relationship.ToOne("User", False, "created_by") def refresh(self) -> None: - """ - Synchronizes values of all fields with the database. + """Synchronizes values of all fields with the database. """ query_str, params = query.get_single(BulkImportRequest, self.uid) res = self.client.execute(query_str, params) @@ -126,7 +124,8 @@ def refresh(self) -> None: self._set_field_values(res) def wait_until_done(self, sleep_time_seconds: int = 30) -> None: - """ + """Blocks import job until certain conditions are met. + Blocks until the BulkImportRequest.state changes either to `BulkImportRequestState.FINISHED` or `BulkImportRequestState.FAILED`, periodically refreshing object's state. diff --git a/labelbox/schema/data_row.py b/labelbox/schema/data_row.py index 5bf1c4460..78c068298 100644 --- a/labelbox/schema/data_row.py +++ b/labelbox/schema/data_row.py @@ -8,18 +8,18 @@ class DataRow(DbObject, Updateable, BulkDeletable): """ Internal Labelbox representation of a single piece of data (e.g. image, video, text). Attributes: - external_id (String): User-generated file name or identifier - row_data (String): Paths to local files are uploaded to Labelbox's server. Otherwise, it's treated as an external URL. - updated_at (DateTime) - created_at (DateTime) + external_id (str): User-generated file name or identifier + row_data (str): Paths to local files are uploaded to Labelbox's server. + Otherwise, it's treated as an external URL. + updated_at (datetime) + created_at (datetime) dataset (Relationship): `ToOne` relationship to Dataset created_by (Relationship): `ToOne` relationship to User organization (Relationship): `ToOne` relationship to Organization labels (Relationship): `ToMany` relationship to Label metadata (Relationship): `ToMany` relationship to AssetMetadata - predictions (Relationship): `ToMany` relationship to Prediction - + predictions (Relationship): `ToMany` relationship to Prediction """ external_id = Field.String("external_id") row_data = Field.String("row_data") @@ -49,7 +49,8 @@ def __init__(self, *args, **kwargs): self.metadata.supports_sorting = False def create_metadata(self, meta_type, meta_value): - """ Creates an asset metadata for this DataRow. + """ Attaches asset metadata to a DataRow. + >>> datarow.create_metadata("TEXT", "This is a text message") Args: @@ -57,7 +58,7 @@ def create_metadata(self, meta_type, meta_value): VIDEO, IMAGE, TEXT. meta_value (str): Asset metadata value. Returns: - AssetMetadata DB object. + `AssetMetadata` DB object. """ meta_type_param = "metaType" meta_value_param = "metaValue" diff --git a/labelbox/schema/dataset.py b/labelbox/schema/dataset.py index 361f07ba6..7a7f0ecd4 100644 --- a/labelbox/schema/dataset.py +++ b/labelbox/schema/dataset.py @@ -11,10 +11,10 @@ class Dataset(DbObject, Updateable, Deletable): """ A Dataset is a collection of DataRows. Attributes: - name (String) - description (String) - updated_at (DateTime) - created_at (DateTime) + name (str) + description (str) + updated_at (datetime) + created_at (datetime) projects (Relationship): `ToMany` relationship to Project data_rows (Relationship): `ToMany` relationship to DataRow @@ -39,10 +39,11 @@ def create_data_row(self, **kwargs): >>> dataset.create_data_row(row_data="http://my_site.com/photos/img_01.jpg") Args: - kwargs: Key-value arguments containing new `DataRow` data. At a minimum, must contain ``row_data``. + **kwargs: Key-value arguments containing new `DataRow` data. At a minimum, + must contain `row_data`. Raises: - InvalidQueryError: If ``DataRow.row_data`` field value is not provided + InvalidQueryError: If `DataRow.row_data` field value is not provided in `kwargs`. InvalidAttributeError: in case the DB object type does not contain any of the field names given in `kwargs`. @@ -70,7 +71,7 @@ def create_data_rows(self, items): is uploaded to Labelbox and a DataRow referencing it is created. If an item is a `dict`, then it should map `DataRow` fields (or their names) to values. At the minimum an `item` passed as a `dict` must - contain a ``DataRow.row_data`` key and value. + contain a `DataRow.row_data` key and value. >>> dataset.create_data_rows([ >>> {DataRow.row_data:"http://my_site.com/photos/img_01.jpg"}, diff --git a/labelbox/schema/label.py b/labelbox/schema/label.py index 3059aa01b..f25ae6c76 100644 --- a/labelbox/schema/label.py +++ b/labelbox/schema/label.py @@ -9,11 +9,11 @@ class Label(DbObject, Updateable, BulkDeletable): contain 100 bounding boxes (annotations). Attributes: - label (String) - seconds_to_label (Float) - agreement (Float) - benchmark_agreement (Float) - is_benchmark_reference (Boolean) + label (str) + seconds_to_label (float) + agreement (float) + benchmark_agreement (float) + is_benchmark_reference (bool) project (Relationship): `ToOne` relationship to Project data_row (Relationship): `ToOne` relationship to DataRow @@ -49,9 +49,8 @@ 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. + Args: + **kwargs: Review attributes. At a minimum, a `Review.score` field value must be provided. """ kwargs[Entity.Review.label.name] = self kwargs[Entity.Review.project.name] = self.project() diff --git a/labelbox/schema/labeling_frontend.py b/labelbox/schema/labeling_frontend.py index b2b1e9a81..13fe76635 100644 --- a/labelbox/schema/labeling_frontend.py +++ b/labelbox/schema/labeling_frontend.py @@ -10,9 +10,9 @@ class LabelingFrontend(DbObject): organization. You can create new labeling frontends for an organization. Attributes: - name (String) - description (String) - iframe_url_path (String) + name (str) + description (str) + iframe_url_path (str) projects (Relationship): `ToMany` relationship to Project """ @@ -28,7 +28,7 @@ class LabelingFrontendOptions(DbObject): """ Label interface options. Attributes: - customization_options (Field) + customization_options (str) project (Relationship): `ToOne` relationship to Project labeling_frontend (Relationship): `ToOne` relationship to LabelingFrontend diff --git a/labelbox/schema/ontology.py b/labelbox/schema/ontology.py index 33da2413b..9b28f6d01 100644 --- a/labelbox/schema/ontology.py +++ b/labelbox/schema/ontology.py @@ -68,21 +68,16 @@ class Ontology(DbObject): to a project. This is read only for now. Attributes: - name (String) - description (String) - updated_at (DateTime) - created_at (DateTime) - normalized (Json) - object_schema_count (Int) - classification_schema_count (Int) + name (str) + description (str) + updated_at (datetime) + created_at (datetime) + normalized (json) + object_schema_count (int) + classification_schema_count (int) projects (Relationship): `ToMany` relationship to Project created_by (Relationship): `ToOne` relationship to User - - >>> project = client.get_project(name="") - >>> ontology = project.ontology() - >>> ontology.normalized - """ name = Field.String("name") @@ -102,6 +97,7 @@ def __init__(self, *args, **kwargs) -> None: self._classifications: Optional[List[Classification]] = None def tools(self) -> List[Tool]: + """Get list of tools (AKA objects) in an Ontology.""" if self._tools is None: self._tools = [ Tool.from_json(tool) for tool in self.normalized['tools'] @@ -109,6 +105,7 @@ def tools(self) -> List[Tool]: return self._tools # type: ignore def classifications(self) -> List[Classification]: + """Get list of classifications in an Ontology.""" if self._classifications is None: self._classifications = [ Classification.from_json(classification) diff --git a/labelbox/schema/organization.py b/labelbox/schema/organization.py index 381959304..c23d72133 100644 --- a/labelbox/schema/organization.py +++ b/labelbox/schema/organization.py @@ -4,18 +4,18 @@ class Organization(DbObject): """ An Organization is a group of Users. + It is associated with data created by Users within that Organization. Typically all Users within an Organization have access to data created by any User in the same Organization. Attributes: - updated_at (DateTime) - created_at (DateTime) - name (String) + updated_at (datetime) + created_at (datetime) + name (str) users (Relationship): `ToMany` relationship to User projects (Relationship): `ToMany` relationship to Project webhooks (Relationship): `ToMany` relationship to Webhook - """ # RelationshipManagers in Organization use the type in Query (and diff --git a/labelbox/schema/prediction.py b/labelbox/schema/prediction.py index f17386c8e..309f5928f 100644 --- a/labelbox/schema/prediction.py +++ b/labelbox/schema/prediction.py @@ -3,26 +3,19 @@ class PredictionModel(DbObject): - """ A prediction created by a PredictionModel. + """ A PredictionModel creates a Prediction. Legacy editor only. - NOTE: This is used for the legacy editor [1], if you wish to - import annotations, refer to [2]. - - - [1] https://labelbox.com/docs/legacy/import-model-prediction - [2] https://labelbox.com/docs/automation/model-assisted-labeling + Refer to BulkImportRequest if using the new Editor. Attributes: - updated_at (DateTime) - created_at (DateTime) - label (String) - agreement (Float) - - organization (Relationship): `ToOne` relationship to Organization - prediction_model (Relationship): `ToOne` relationship to PredictionModel - data_row (Relationship): `ToOne` relationship to PredictionModel - project (Relationship): `ToOne` relationship to Project - + updated_at (datetime) + created_at (datetime) + name (str) + slug (str) + version (int) + + created_by (Relationship): `ToOne` relationship to User + organization (Relationship): `ToOne` relationship to Organization """ updated_at = Field.DateTime("updated_at") created_at = Field.DateTime("created_at") @@ -38,15 +31,20 @@ class PredictionModel(DbObject): class Prediction(DbObject): - """ A prediction created by a PredictionModel. + """ A prediction created by a PredictionModel. Legacy editor only. - NOTE: This is used for the legacy editor [1], if you wish to - import annotations, refer to [2] - - - [1] https://labelbox.com/docs/legacy/import-model-prediction - [2] https://labelbox.com/docs/automation/model-assisted-labeling + Refer to BulkImportRequest if using the new Editor. + Attributes: + updated_at (datetime) + created_at (datetime) + label (str) + agreement (float) + + organization (Relationship): `ToOne` relationship to Organization + prediction_model (Relationship): `ToOne` relationship to PredictionModel + data_row (Relationship): `ToOne` relationship to DataRow + project (Relationship): `ToOne` relationship to Project """ updated_at = Field.DateTime("updated_at") created_at = Field.DateTime("created_at") diff --git a/labelbox/schema/project.py b/labelbox/schema/project.py index 1aad1431a..e673c6893 100644 --- a/labelbox/schema/project.py +++ b/labelbox/schema/project.py @@ -29,14 +29,14 @@ class Project(DbObject, Updateable, Deletable): datasets and labels. Attributes: - name (String) - description (String) - updated_at (DateTime) - created_at (DateTime) - setup_complete (DateTime) - last_activity_time (DateTime) - auto_audit_number_of_labels (Int) - auto_audit_percentage (Float) + name (str) + description (str) + updated_at (datetime) + created_at (datetime) + setup_complete (datetime) + last_activity_time (datetime) + auto_audit_number_of_labels (int) + auto_audit_percentage (float) datasets (Relationship): `ToMany` relationship to Dataset created_by (Relationship): `ToOne` relationship to User @@ -50,8 +50,6 @@ class Project(DbObject, Updateable, Deletable): active_prediction_model (Relationship): `ToOne` relationship to PredictionModel predictions (Relationship): `ToMany` relationship to Prediction ontology (Relationship): `ToOne` relationship to Ontology - - """ name = Field.String("name") description = Field.String("description") @@ -80,12 +78,10 @@ class Project(DbObject, Updateable, Deletable): ontology = Relationship.ToOne("Ontology", True) def create_label(self, **kwargs): - """ Creates a label on a Legacy Editor project. Not - supported in the new Editor. + """ Creates a label on a Legacy Editor project. Not supported in the new Editor. Args: - kwargs: Label attributes. At the minimum the label `DataRow`. - + **kwargs: Label attributes. At minimum, the label `DataRow`. """ # Copy-paste of Client._create code so we can inject # a connection to Type. Type objects are on their way to being @@ -112,8 +108,7 @@ def create_label(self, **kwargs): return Label(self.client, res["createLabel"]) def labels(self, datasets=None, order_by=None): - """ - Custom relationship expansion method to support limited filtering. + """ Custom relationship expansion method to support limited filtering. Args: datasets (iterable of Dataset): Optional collection of Datasets @@ -155,7 +150,8 @@ def export_labels(self, timeout_seconds=60): Args: timeout_seconds (float): Max waiting time, in seconds. 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. + URL of the data file with this Project's labels. If the server didn't + generate during the `timeout_seconds` period, None is returned. """ sleep_time = 2 id_param = "projectId" @@ -210,7 +206,7 @@ def review_metrics(self, net_score): Args: net_score (None or Review.NetScore): Indicates desired metric. Returns: - int, aggregation count of reviews for given net_score. + int, aggregation count of reviews for given `net_score`. """ if net_score not in (None,) + tuple(Entity.Review.NetScore): raise InvalidQueryError( @@ -254,8 +250,8 @@ def setup(self, labeling_frontend, labeling_frontend_options): self.update(setup_complete=timestamp) def set_labeling_parameter_overrides(self, data): - """ Adds labeling parameter overrides to this project. Example: - + """ Adds labeling parameter overrides to this project. + >>> project.set_labeling_parameter_overrides([ >>> (data_row_1, 2, 3), (data_row_2, 1, 4)]) @@ -331,12 +327,12 @@ def extend_reservations(self, queue_type): return res["extendReservations"] def create_prediction_model(self, name, version): - """ Creates a PredictionModel connected to a Legacy Editor - Project. + """ Creates a PredictionModel connected to a Legacy Editor Project. + Args: name (str): The new PredictionModel's name. version (int): The new PredictionModel's version. - Return: + Returns: A newly created PredictionModel. """ PM = Entity.PredictionModel @@ -348,7 +344,8 @@ def create_prediction_model(self, name, version): return model def create_prediction(self, label, data_row, prediction_model=None): - """ Creates a Prediction within a Legacy Editor Project. + """ Creates a Prediction within a Legacy Editor Project. Not supported + in the new Editor. Args: label (str): The `label` field of the new Prediction. @@ -395,11 +392,10 @@ def enable_model_assisted_labeling(self, toggle: bool=True) -> bool: """ Turns model assisted labeling either on or off based on input Args: - toggle (Boolean): True or False boolean + toggle (bool): True or False boolean Returns: True if toggled on or False if toggled off """ - project_param = "project_id" show_param = "show" @@ -427,15 +423,14 @@ def upload_annotations( """ Uploads annotations to a new Editor project. Args: - name: name of the BulkImportRequest job - annotations: + name (str): name of the BulkImportRequest job + annotations (str or dict): url that is publicly accessible by Labelbox containing an ndjson file OR local path to an ndjson file OR iterable of annotation rows Returns: BulkImportRequest - """ if isinstance(annotations, str) or isinstance(annotations, Path): @@ -485,6 +480,12 @@ def _is_url_valid(url: Union[str, Path]) -> bool: f'Invalid annotations given of type: {type(annotations)}') class LabelingParameterOverride(DbObject): + """ Customizes the order of assets in the label queue. + + Attributes: + priority (int): A prioritization score. + number_of_labels (int): Number of times an asset should be labeled. + """ priority = Field.Int("priority") number_of_labels = Field.Int("number_of_labels") diff --git a/labelbox/schema/review.py b/labelbox/schema/review.py index a96ba90f8..10ff904d2 100644 --- a/labelbox/schema/review.py +++ b/labelbox/schema/review.py @@ -11,20 +11,18 @@ class Review(DbObject, Deletable, Updateable): review numbers can be obtained on a Project object. Attributes: - created_at (DateTime) - updated_at (DateTime) - score (Float) + created_at (datetime) + updated_at (datetime) + score (float) created_by (Relationship): `ToOne` relationship to User organization (Relationship): `ToOne` relationship to Organization project (Relationship): `ToOne` relationship to Project label (Relationship): `ToOne` relationship to Label - """ class NetScore(Enum): - """ Negative, Zero, or Positive. - + """ Negative, Zero, or Positive. """ Negative = auto() Zero = auto() diff --git a/labelbox/schema/task.py b/labelbox/schema/task.py index 7553b5260..a6ec0f3b8 100644 --- a/labelbox/schema/task.py +++ b/labelbox/schema/task.py @@ -13,15 +13,14 @@ class Task(DbObject): Allows the Task state to be updated and checked on the client side. Attributes: - updated_at (DateTime) - created_at (DateTime) - name (String) - status (String) - completion_percentage (Float) + updated_at (datetime) + created_at (datetime) + name (str) + status (str) + completion_percentage (float) created_by (Relationship): `ToOne` relationship to User organization (Relationship): `ToOne` relationship to Organization - """ updated_at = Field.DateTime("updated_at") created_at = Field.DateTime("created_at") @@ -46,8 +45,7 @@ def wait_till_done(self, timeout_seconds=60): to update the task attributes. Args: - timeout_seconds (Float): Maximum time this method can block, in seconds. Defaults to one minute. - + timeout_seconds (float): Maximum time this method can block, in seconds. Defaults to one minute. """ check_frequency = 2 # frequency of checking, in seconds while True: diff --git a/labelbox/schema/user.py b/labelbox/schema/user.py index e5dc654cb..f8487fa52 100644 --- a/labelbox/schema/user.py +++ b/labelbox/schema/user.py @@ -7,20 +7,19 @@ class User(DbObject): data they create or import and an Organization they belong to. Attributes: - updated_at (DateTime) - created_at (DateTime) - email (String) - name (String) - nickname (String) - intercom_hash (String) - picture (String) - is_viewer (Boolean) - is_external_viewer (Boolean) + updated_at (datetime) + created_at (datetime) + email (str) + name (str) + nickname (str) + intercom_hash (str) + picture (str) + is_viewer (bool) + is_external_viewer (bool) organization (Relationship): `ToOne` relationship to Organization created_tasks (Relationship): `ToMany` relationship to Task projects (Relationship): `ToMany` relationship to Project - """ updated_at = Field.DateTime("updated_at") created_at = Field.DateTime("created_at") diff --git a/labelbox/schema/webhook.py b/labelbox/schema/webhook.py index 6a10319b5..a83b93fb1 100644 --- a/labelbox/schema/webhook.py +++ b/labelbox/schema/webhook.py @@ -9,11 +9,11 @@ class Webhook(DbObject, Updateable): a Project or an Organization. Attributes: - updated_at (DateTime) - created_at (DateTime) - url (String) - topics (String): LABEL_CREATED, LABEL_UPDATED, LABEL_DELETED - status (String): ACTIVE, INACTIVE, REVOKED + updated_at (datetime) + created_at (datetime) + url (str) + topics (str): LABEL_CREATED, LABEL_UPDATED, LABEL_DELETED + status (str): ACTIVE, INACTIVE, REVOKED """ From a7d348b10bf9f67610819e6f6d3c23046e6cbaee Mon Sep 17 00:00:00 2001 From: Alex Cota Date: Thu, 14 Jan 2021 09:09:49 -0800 Subject: [PATCH 03/12] Update upload_annotations docstrings in project.py --- labelbox/schema/project.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/labelbox/schema/project.py b/labelbox/schema/project.py index e673c6893..3ef233f7c 100644 --- a/labelbox/schema/project.py +++ b/labelbox/schema/project.py @@ -423,8 +423,8 @@ def upload_annotations( """ Uploads annotations to a new Editor project. Args: - name (str): name of the BulkImportRequest job - annotations (str or dict): + name (str or Path or Iterable): name of the BulkImportRequest job + annotations (str or Path or Iterable): url that is publicly accessible by Labelbox containing an ndjson file OR local path to an ndjson file From 41f017618a0698d9b146753d0e22e2cd7cea381d Mon Sep 17 00:00:00 2001 From: Florijan Stamenkovic Date: Fri, 15 Jan 2021 11:03:38 +0100 Subject: [PATCH 04/12] Fix project.upload_annotations docstring --- labelbox/schema/project.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/labelbox/schema/project.py b/labelbox/schema/project.py index 3ef233f7c..0411add1b 100644 --- a/labelbox/schema/project.py +++ b/labelbox/schema/project.py @@ -423,7 +423,7 @@ def upload_annotations( """ Uploads annotations to a new Editor project. Args: - name (str or Path or Iterable): name of the BulkImportRequest job + name (str): name of the BulkImportRequest job annotations (str or Path or Iterable): url that is publicly accessible by Labelbox containing an ndjson file From d15b9732b53796773159d35853f6d5f8e0feee47 Mon Sep 17 00:00:00 2001 From: Alex Cota Date: Fri, 15 Jan 2021 13:30:07 -0800 Subject: [PATCH 05/12] Add missing files and udpate .gitignore --- .gitignore | 4 + labelbox/Makefile | 20 +++++ labelbox/make.bat | 35 ++++++++ labelbox/source/conf.py | 58 +++++++++++++ labelbox/source/index.rst | 171 ++++++++++++++++++++++++++++++++++++++ 5 files changed, 288 insertions(+) create mode 100644 labelbox/Makefile create mode 100644 labelbox/make.bat create mode 100644 labelbox/source/conf.py create mode 100644 labelbox/source/index.rst diff --git a/.gitignore b/.gitignore index bd46f49c6..3cc432e3e 100644 --- a/.gitignore +++ b/.gitignore @@ -134,3 +134,7 @@ dmypy.json # Docs build labelbox/build/ + +# Docs source files +labelbox/source/_static +labelbox/source/_templates diff --git a/labelbox/Makefile b/labelbox/Makefile new file mode 100644 index 000000000..d0c3cbf10 --- /dev/null +++ b/labelbox/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/labelbox/make.bat b/labelbox/make.bat new file mode 100644 index 000000000..6247f7e23 --- /dev/null +++ b/labelbox/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/labelbox/source/conf.py b/labelbox/source/conf.py new file mode 100644 index 000000000..1e5688dd6 --- /dev/null +++ b/labelbox/source/conf.py @@ -0,0 +1,58 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys +# sys.path.insert(0, os.path.abspath('.')) +sys.path.insert(0, os.path.abspath('../../labelbox')) +sys.path.insert(0, os.path.abspath('../../')) + + +# -- Project information ----------------------------------------------------- + +project = 'Labelbox Python API reference' +copyright = '2021, Labelbox' +author = 'Alexandra Cota' + +release = '2.4' + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.viewcode', + 'sphinxcontrib.napoleon' +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'py3-sphinx'] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] \ No newline at end of file diff --git a/labelbox/source/index.rst b/labelbox/source/index.rst new file mode 100644 index 000000000..4bf477382 --- /dev/null +++ b/labelbox/source/index.rst @@ -0,0 +1,171 @@ +Labelbox Python API reference +=================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + +Client +---------------------- + +.. automodule:: labelbox.client + :members: + :special-members: __init__ + :exclude-members: upload_data, upload_file + :show-inheritance: + +AssetMetadata +-------------------------------------- + +.. automodule:: labelbox.schema.asset_metadata + :members: + :show-inheritance: + +Benchmark +-------------------------------- + +.. automodule:: labelbox.schema.benchmark + :members: + :show-inheritance: + +BulkImportRequest +-------------------------------------------- + +.. automodule:: labelbox.schema.bulk_import_request + :members: + :exclude-members: create_from_local_file, create_from_objects, create_from_url, from_name + :show-inheritance: + +DataRow +-------------------------------- + +.. automodule:: labelbox.schema.data_row + :members: + :show-inheritance: + +Dataset +------------------------------ + +.. automodule:: labelbox.schema.dataset + :members: + :show-inheritance: + +Label +---------------------------- + +.. automodule:: labelbox.schema.label + :members: + :show-inheritance: + +LabelingFrontend +----------------------------------------- + +.. automodule:: labelbox.schema.labeling_frontend + :members: LabelingFrontend + :exclude-members: LabelingFrontendOptions + :show-inheritance: + +LabelingFrontendOptions +----------------------------------------- +.. automodule:: labelbox.schema.labeling_frontend + :members: LabelingFrontendOptions + :exclude-members: LabelingFrontend + :show-inheritance: + :noindex: + +LabelingParameterOverride +----------------------------------------- +.. automodule:: labelbox.schema.project + :members: LabelingParameterOverride + :show-inheritance: + :noindex: + +Ontology +------------------------------- + +.. automodule:: labelbox.schema.ontology + :members: + :exclude-members: OntologyEntity, Classification, Tool, Option + :show-inheritance: + +Organization +----------------------------------- + +.. automodule:: labelbox.schema.organization + :members: + :show-inheritance: + +Prediction +--------------------------------- + +.. automodule:: labelbox.schema.prediction + :members: Prediction + :exclude-members: PredictionModel + :show-inheritance: + +PredictionModel +--------------------------------- +.. automodule:: labelbox.schema.prediction + :members: PredictionModel + :exclude-members: Prediction + :show-inheritance: + :noindex: + +Project +------------------------------ + +.. automodule:: labelbox.schema.project + :members: + :exclude-members: LabelerPerformance, LabelingParameterOverride + :show-inheritance: + +Review +----------------------------- + +.. automodule:: labelbox.schema.review + :members: + :show-inheritance: + +Task +--------------------------- + +.. automodule:: labelbox.schema.task + :members: + :show-inheritance: + +User +--------------------------- + +.. automodule:: labelbox.schema.user + :members: + :show-inheritance: + +Webhook +------------------------------ + +.. automodule:: labelbox.schema.webhook + :members: + :show-inheritance: + +Exceptions +-------------------------- + +.. automodule:: labelbox.exceptions + :members: + :show-inheritance: + +Pagination +-------------------------- + +.. automodule:: labelbox.pagination + :members: + :special-members: __init__ + :show-inheritance: + +Enums +---------------------------- + +.. automodule:: labelbox.schema.enums + :members: + :show-inheritance: + From a69a7c6c821797a18668690f2b3d22ba1496cfee Mon Sep 17 00:00:00 2001 From: Florijan Stamenkovic Date: Tue, 19 Jan 2021 12:33:04 +0100 Subject: [PATCH 06/12] Move Sphinx documentation files to 'docs' directory --- .gitignore | 11 +++++------ {labelbox => docs}/Makefile | 0 {labelbox => docs}/make.bat | 0 {labelbox => docs}/source/conf.py | 0 {labelbox => docs}/source/index.rst | 0 5 files changed, 5 insertions(+), 6 deletions(-) rename {labelbox => docs}/Makefile (100%) rename {labelbox => docs}/make.bat (100%) rename {labelbox => docs}/source/conf.py (100%) rename {labelbox => docs}/source/index.rst (100%) diff --git a/.gitignore b/.gitignore index 3cc432e3e..ca9669026 100644 --- a/.gitignore +++ b/.gitignore @@ -132,9 +132,8 @@ dmypy.json # macos files .DS_STORE -# Docs build -labelbox/build/ - -# Docs source files -labelbox/source/_static -labelbox/source/_templates +# Sphinx Docs build +docs/build/ +# and source files +docs/source/_static +docs/source/_templates diff --git a/labelbox/Makefile b/docs/Makefile similarity index 100% rename from labelbox/Makefile rename to docs/Makefile diff --git a/labelbox/make.bat b/docs/make.bat similarity index 100% rename from labelbox/make.bat rename to docs/make.bat diff --git a/labelbox/source/conf.py b/docs/source/conf.py similarity index 100% rename from labelbox/source/conf.py rename to docs/source/conf.py diff --git a/labelbox/source/index.rst b/docs/source/index.rst similarity index 100% rename from labelbox/source/index.rst rename to docs/source/index.rst From 64004038ebb01292b0cddd6c355fd5b9d2bcd907 Mon Sep 17 00:00:00 2001 From: Florijan Stamenkovic Date: Tue, 19 Jan 2021 12:33:14 +0100 Subject: [PATCH 07/12] Add Sphinx requirements --- docs/requirements.txt | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 docs/requirements.txt diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 000000000..342321b6e --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,2 @@ +Sphinx==3.4.3 +sphinxcontrib-napoleon==0.7 From a06b8046cf4e904e4f8b282f9e4e8482101730a1 Mon Sep 17 00:00:00 2001 From: Florijan Stamenkovic Date: Tue, 19 Jan 2021 12:40:12 +0100 Subject: [PATCH 08/12] Add docs/README.md --- docs/README.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 docs/README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..344baf218 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,39 @@ +# Labelbox Python SDK API Documentation + +The Labelbox Python API documentation is generated from source code comments +using Sphinx (https://www.sphinx-doc.org/). + +## Preparing Sphinx + +To generate the documentation install Sphinx and Sphinxcontrib-Napoleon. The +easiest way to do it is using a Python virtual env and pip: + +``` +# create a virtual environment +python3 -m venv labelbox_docs_venv + +# activate the venv +source ./labelbox_docs_venv/bin/activate + +# upgrade venv pip and setuptools +pip install --upgrade pip setuptools + +# install Sphinx and necessary contrib from requriements +pip install -r labelbox_root/docs/requirements.txt +``` + +For more detailed info and installation alternatives please visit: +https://www.sphinx-doc.org/en/master/usage/installation.html + +## Generating Labelbox SDK API documentation + +With the Sphinx environment prepared, enter the docs folder: + +``` +cd labelbox_root/docs/ +``` + +Run `make`, instructing it to build docs as HTML: +``` +make html +``` From 40626650664f0fcbeb3520d5d275618918d4c6a8 Mon Sep 17 00:00:00 2001 From: Florijan Stamenkovic Date: Tue, 19 Jan 2021 13:05:42 +0100 Subject: [PATCH 09/12] Add Sphinx theme to requirements --- docs/requirements.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/requirements.txt b/docs/requirements.txt index 342321b6e..ac42c4269 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,2 +1,3 @@ Sphinx==3.4.3 sphinxcontrib-napoleon==0.7 +sphinx-rtd-theme==0.5.1 From af5ca7687f226be2d32865377ec0d57b3551bcd7 Mon Sep 17 00:00:00 2001 From: Florijan Stamenkovic Date: Tue, 19 Jan 2021 13:06:48 +0100 Subject: [PATCH 10/12] Fix docs/source/conf.py --- docs/source/conf.py | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 1e5688dd6..131ae59bc 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -12,9 +12,7 @@ # import os import sys -# sys.path.insert(0, os.path.abspath('.')) -sys.path.insert(0, os.path.abspath('../../labelbox')) -sys.path.insert(0, os.path.abspath('../../')) +sys.path.insert(0, os.path.abspath('../..')) # -- Project information ----------------------------------------------------- @@ -42,7 +40,7 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'py3-sphinx'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] # -- Options for HTML output ------------------------------------------------- @@ -55,4 +53,4 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] \ No newline at end of file +html_static_path = ['_static'] From d939720e30c5353a87628d520660a9cfce937c36 Mon Sep 17 00:00:00 2001 From: Florijan Stamenkovic Date: Tue, 19 Jan 2021 13:07:18 +0100 Subject: [PATCH 11/12] Add google-api-core (for retry) to requirements.txt --- requirements.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/requirements.txt b/requirements.txt index 07429a0ca..d6e1b9c66 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,3 +1,4 @@ requests==2.22.0 ndjson==0.3.1 backoff==1.10.0 +google-api-core>=1.22.1 From 9b184403092ad276325b5057f9f0b139cd86dc83 Mon Sep 17 00:00:00 2001 From: Florijan Stamenkovic Date: Tue, 19 Jan 2021 13:10:16 +0100 Subject: [PATCH 12/12] Update README.md --- docs/README.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/README.md b/docs/README.md index 344baf218..57cbf138b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,7 +3,7 @@ The Labelbox Python API documentation is generated from source code comments using Sphinx (https://www.sphinx-doc.org/). -## Preparing Sphinx +## Preparing the Sphinx environment To generate the documentation install Sphinx and Sphinxcontrib-Napoleon. The easiest way to do it is using a Python virtual env and pip: @@ -20,10 +20,13 @@ pip install --upgrade pip setuptools # install Sphinx and necessary contrib from requriements pip install -r labelbox_root/docs/requirements.txt + +# install Labelbox dependencies +pip install -r labelbox_root/requirements.txt ``` -For more detailed info and installation alternatives please visit: -https://www.sphinx-doc.org/en/master/usage/installation.html +There are other ways to do prepare the environment, but we highly recommend +using a Python virtual environment. ## Generating Labelbox SDK API documentation @@ -33,7 +36,7 @@ With the Sphinx environment prepared, enter the docs folder: cd labelbox_root/docs/ ``` -Run `make`, instructing it to build docs as HTML: +Run the make build tool, instructing it to build docs as HTML: ``` make html ```