pixeltable 0.2.7__py3-none-any.whl → 0.2.9__py3-none-any.whl

pixeltable/io/globals.py

@@ -1,18 +1,21 @@
 from typing import Any, Optional, Literal
 
-import pixeltable as pxt
+import pixeltable.exceptions as excs
 from pixeltable import Table
+from pixeltable.io.external_store import SyncStatus
 
 
 def create_label_studio_project(
         t: Table,
         label_config: str,
-        col_mapping: Optional[dict[str, str]] = None,
+        name: Optional[str] = None,
         title: Optional[str] = None,
-        media_import_method: Literal['post', 'file'] = 'file',
+        media_import_method: Literal['post', 'file', 'url'] = 'post',
+        col_mapping: Optional[dict[str, str]] = None,
         sync_immediately: bool = True,
         **kwargs: Any
-) -> None:
+) -> SyncStatus:
+    # TODO(aaron-siegel): Add link in docstring to a Label Studio howto
     """
     Creates a new Label Studio project and links it to the specified `Table`.
 
@@ -27,33 +30,58 @@ def create_label_studio_project(
     will always have a JSON-typed column `annotations` representing the output.
 
     By default, Pixeltable will link each of these columns to a column of the specified `Table`
-    with the same name. If any of the data fields are missing, an exception will be thrown. If
+    with the same name. If any of the data fields are missing, an exception will be raised. If
     the `annotations` column is missing, it will be created. The default names can be overridden
     by specifying an optional `col_mapping`, with Pixeltable column names as keys and Label
-    Studio field names as values.
+    Studio field names as values. In all cases, the Pixeltable columns must have types that are
+    consistent with their corresponding Label Studio fields; otherwise, an exception will be raised.
+
+    The API key and URL for a valid Label Studio server must be specified in Pixeltable config. Either:
+
+    * Set the `LABEL_STUDIO_API_KEY` and `LABEL_STUDIO_URL` environment variables; or
+    * Specify `api_key` and `url` fields in the `label-studio` section of `$PIXELTABLE_HOME/config.yaml`.
 
     Args:
         t: The Table to link to.
         label_config: The Label Studio project configuration, in XML format.
-        col_mapping: An optional mapping of local column names to remote column names.
-        title: An optional title for the Label Studio project. If not specified, the
-            name of the `Table` will be used as a default.
+        name: An optional name for the new project in Pixeltable. If specified, must be a valid
+            Pixeltable identifier and must not be the name of any other external data store
+            linked to `t`. If not specified, a default name will be used of the form
+            `ls_project_0`, `ls_project_1`, etc.
+        title: An optional title for the Label Studio project. This is the title that annotators
+            will see inside Label Studio. Unlike `name`, it does not need to be an identifier and
+            does not need to be unique. If not specified, the table name `t.get_name()` will be used.
+        media_import_method: The method to use when transferring media files to Label Studio:
+            - `post`: Media will be sent to Label Studio via HTTP post. This should generally only be used for
+                prototyping; due to restrictions in Label Studio, it can only be used with projects that have
+                just one data field, and does not scale well.
+            - `file`: Media will be sent to Label Studio as a file on the local filesystem. This method can be
+                used if Pixeltable and Label Studio are running on the same host.
+            - `url`: Media will be sent to Label Studio as externally accessible URLs. This method cannot be
+                used with local media files or with media generated by computed columns.
+            The default is `post`.
+        col_mapping: An optional mapping of local column names to Label Studio fields.
         sync_immediately: If `True`, immediately perform an initial synchronization by
-            importing all rows of the `Table` as Label Studio tasks.
+            exporting all rows of the `Table` as Label Studio tasks.
+        kwargs: Additional keyword arguments are passed to the `start_project` method in the Label
+            Studio SDK, as described here:
+            https://labelstud.io/sdk/project.html#label_studio_sdk.project.Project.start_project
     """
-    from pixeltable.datatransfer.label_studio import LabelStudioProject, ANNOTATIONS_COLUMN
+    from pixeltable.io.label_studio import LabelStudioProject
 
-    ls_project = LabelStudioProject.create(title or t.get_name(), label_config, media_import_method, **kwargs)
-
-    # Create a column to hold the annotations, if one does not yet exist.
-    if col_mapping is not None and ANNOTATIONS_COLUMN in col_mapping.values():
-        local_annotations_column = next(k for k, v in col_mapping.items() if v == ANNOTATIONS_COLUMN)
-    else:
-        local_annotations_column = ANNOTATIONS_COLUMN
-    if local_annotations_column not in t.column_names():
-        t[local_annotations_column] = pxt.JsonType(nullable=True)
+    ls_project = LabelStudioProject.create(
+        t,
+        label_config,
+        name,
+        title,
+        media_import_method,
+        col_mapping,
+        **kwargs
+    )
 
     # Link the project to `t`, and sync if appropriate.
-    t._link(ls_project, col_mapping)
+    t._link_external_store(ls_project)
     if sync_immediately:
-        t.sync()
+        return t.sync()
+    else:
+        return SyncStatus.empty()