add --folder to upload (#1408)

* add --folder-name to upload

* changelog

* --folder

* pass folder id to reserve dataset upload api call

* docs

---------

Co-authored-by: Florian M <[email protected]>

Author: normanrz

docs/src/cli/upload.md

@@ -32,6 +32,10 @@ webknossos upload [OPTIONS] SOURCE
     Number of processes to spawn for parallel upload execution.  
     Default: 5.
 
+- `--folder`  
+    WEBKNOSSOS dataset folder in which the dataset should be placed. Specify the folder path as a string, separated by `/`. Note that this is about the folders listed in the dataset dashboard, and is independent of the underlying storage location. Example: `Datasets/mySubfolder`.  
+    If not provided, the root folder is used.
+
 ### Environment Variables for Remote Paths
 
 When using remote paths (e.g., HTTP or S3), configure the following environment variables:

webknossos/Changelog.md

@@ -15,6 +15,7 @@ For upgrade instructions, please check the respective _Breaking Changes_ section
 ### Breaking Changes
 
 ### Added
+- Added `--folder` option to `upload` CLI command. [#1408](https://github.com/scalableminds/webknossos-libs/pull/1408)
 
 ### Changed
 - Relaxed layer name validation to match WEBKNOSSOS behavior. [#1402](https://github.com/scalableminds/webknossos-libs/pull/1402)

webknossos/webknossos/cli/upload.py

@@ -7,7 +7,7 @@
 from ..client import webknossos_context
 from ..client._defaults import DEFAULT_WEBKNOSSOS_URL
 from ..client._upload_dataset import DEFAULT_SIMULTANEOUS_UPLOADS
-from ..dataset import Dataset
+from ..dataset import Dataset, RemoteFolder
 from ._utils import parse_path
 
 
@@ -42,7 +42,14 @@ def main(
         str | None,
         typer.Option(
             help="Alternative name to rename your dataset on upload to WEBKNOSSOS. "
-            "(if not provided, current name of dataset is used)",
+            "If not provided, current dataset name is used.",
+        ),
+    ] = None,
+    folder: Annotated[
+        str | None,
+        typer.Option(
+            help="WEBKNOSSOS dataset folder in which the dataset should be placed. Specify the folder path as a string, separated by `/`. Note that this is about the folders listed in the dataset dashboard, and is independent of the underlying storage location. Example: `Datasets/mySubfolder`. "
+            "If not provided, the root folder is used.",
         ),
     ] = None,
     jobs: Annotated[
@@ -56,6 +63,9 @@ def main(
     """Upload a dataset to a WEBKNOSSOS server."""
 
     with webknossos_context(url=webknossos_url, token=token):
+        folder_id: None | RemoteFolder = None
+        if folder is not None:
+            folder_id = RemoteFolder.get_by_path(folder)
         Dataset.open(dataset_path=source).upload(
-            new_dataset_name=dataset_name, jobs=jobs
+            new_dataset_name=dataset_name, jobs=jobs, folder_id=folder_id
         )

webknossos/webknossos/client/_upload_dataset.py

@@ -49,6 +49,7 @@ def upload_dataset(
     layers_to_link: list[LayerToLink] | None = None,
     jobs: int | None = None,
     datastore_url: str | None = None,
+    folder_id: str | None = None,
 ) -> str:
     if new_dataset_name is None:
         new_dataset_name = dataset.name
@@ -103,7 +104,7 @@ def upload_dataset(
             layers_to_link=[
                 layer._as_api_linked_layer_identifier() for layer in layers_to_link
             ],
-            folder_id=None,
+            folder_id=folder_id,
             initial_teams=[],
         ),
         retry_count=MAXIMUM_RETRY_COUNT,

webknossos/webknossos/dataset/dataset.py

@@ -707,7 +707,11 @@ def upload(
             from ..client._upload_dataset import upload_dataset
 
             new_dataset_id = upload_dataset(
-                self, new_dataset_name, converted_layers_to_link, jobs
+                self,
+                new_dataset_name,
+                converted_layers_to_link,
+                jobs,
+                folder_id=folder_id,
             )
 
         return RemoteDataset.open(dataset_id=new_dataset_id)