feat: ability to add client_metadata directly in folder.create_data_group - BOT-516 (#1032)

Author: arthur-encord

encord/common/deprecated.py

@@ -1,19 +1,34 @@
 import functools
+import inspect
 import warnings
 
 
 def deprecated(version, alternative=None):
-    def decorator(func):
-        @functools.wraps(func)
-        def new_func(*args, **kwargs):
-            message = f"Function {func.__name__} is deprecated"
-            if version:
-                message += f" since version {version}"
-            if alternative:
-                message += f", use {alternative} instead"
-            warnings.warn(message, category=DeprecationWarning, stacklevel=2)
-            return func(*args, **kwargs)
+    def decorator(obj):
+        message = f"{obj.__name__} is deprecated"
+        if version:
+            message += f" since version {version}"
+        if alternative:
+            message += f", use {alternative} instead"
 
-        return new_func
+        if inspect.isclass(obj):
+            # Handle class
+            original_init = obj.__init__
+
+            @functools.wraps(original_init)
+            def new_init(self, *args, **kwargs):
+                warnings.warn(message, category=DeprecationWarning, stacklevel=2)
+                original_init(self, *args, **kwargs)
+
+            obj.__init__ = new_init
+            return obj
+        else:
+            # Handle function
+            @functools.wraps(obj)
+            def new_func(*args, **kwargs):
+                warnings.warn(message, category=DeprecationWarning, stacklevel=2)
+                return obj(*args, **kwargs)
+
+            return new_func
 
     return decorator

encord/orm/storage.py

@@ -3,9 +3,10 @@
 from dataclasses import dataclass
 from datetime import datetime
 from enum import auto
-from typing import Dict, List, Optional, Union
+from typing import Any, Dict, List, Optional, Union
 from uuid import UUID
 
+from encord.common.deprecated import deprecated
 from encord.orm.analytics import CamelStrEnum
 from encord.orm.base_dto import BaseDTO, Field
 from encord.orm.dataset import DataUnitError, LongPollingStatus
@@ -266,23 +267,10 @@ class CreateStorageFolderPayload(BaseDTO):
     cloud_synced_folder_params: Optional[CloudSyncedFolderParams] = None
 
 
-class LayoutPayload(BaseDTO):
-    """Layout configuration for a group or view.
-
-    Args:
-        layout: Layout specification. Can be a built-in layout identifier
-            (``"default-grid"`` or ``"default-list"``) or a custom
-            layout dictionary.
-    """
-
-    layout: Union[Literal["default-grid"], Literal["default-list"], Dict]
-
-
 class DataGroupGrid(BaseDTO):
     """Grid-based layout for a data group.
 
     Args:
-        layout_type: Fixed value ``"default-grid"`` identifying grid layout.
         layout_contents:  Ordered list of item UUIDs to display in the grid.
         name: Optional name of the data group.
     """
@@ -292,12 +280,11 @@ class DataGroupGrid(BaseDTO):
     name: Optional[str] = None
 
 
-class DataGroupList(BaseDTO):
+class DataGroupCarousel(BaseDTO):
     """Carousel layout for a data group.
 
     Args:
-        layout_type:   Fixed value ``"default-list"`` identifying list layout.
-        layout_contents:  Ordered list of item UUIDs to display in the list.
+        layout_contents:  Ordered list of item UUIDs to display in the carousel.
         name:  Optional name of the data group.
     """
 
@@ -306,11 +293,17 @@ class DataGroupList(BaseDTO):
     name: Optional[str] = None
 
 
+@deprecated(version=None, alternative="DataGroupCarousel")
+class DataGroupList(DataGroupCarousel):
+    """
+    Deprecated, will be removed in a future release. Use `DataGroupCarousel` instead.
+    """
+
+
 class DataGroupCustom(BaseDTO):
     """Custom layout for a data group.
 
     Args:
-        layout_type: Fixed value ``"custom"`` identifying custom layout.
         name: Optional name of the data group.
         layout_contents: Mapping from arbitrary keys to item UUIDs.
         layout: Arbitrary layout configuration structure.
@@ -324,7 +317,7 @@ class DataGroupCustom(BaseDTO):
     settings: Optional[Dict] = None
 
 
-DataGroupInput = Union[DataGroupGrid, DataGroupList, DataGroupCustom]
+DataGroupInput = Union[DataGroupGrid, DataGroupCarousel, DataGroupCustom]
 
 
 class CreateDataGroupPayload(BaseDTO):
@@ -333,10 +326,12 @@ class CreateDataGroupPayload(BaseDTO):
     Args:
         item_type: Item type of the group. Must be ``"GROUP"``.
         params: Layout and configuration for the data group.
+        client_metadata: Optional custom metadata to be associated with the data group.
     """
 
     item_type: Literal["GROUP"] = "GROUP"
     params: DataGroupInput
+    client_metadata: Optional[Dict[str, Any]] = None
 
 
 class UploadSignedUrlsPayload(BaseDTO):

encord/storage.py

@@ -1232,12 +1232,16 @@ def move_to_folder(self, target_folder: Optional[Union["StorageFolder", UUID]])
     def create_data_group(
         self,
         params: Union[DataGroupInput, List[UUID]],
+        *,
+        client_metadata: Optional[Dict[str, Any]] = None,
     ) -> UUID:
         """Creates a data group storage item in this folder.
 
         Args:
             params (Union[DataGroupInput, List[UUID]]): Parameters for the data group. When a list of UUIDs is provided,
                 the group will be created with a grid layout. For custom layouts, use DataGroupGrid, DataGroupList or DataGroupCustom.
+            client_metadata (Optional[Dict[str, Any]]): Optional custom metadata to be associated with the data group.
+                Should be a dictionary that is JSON-serializable.
 
         Returns:
             UUID: The UUID of the data group storage item.
@@ -1247,7 +1251,10 @@ def create_data_group(
         return self._api_client.post(
             f"storage/folders/{self.uuid}/create-group-item",
             params=None,
-            payload=orm_storage.CreateDataGroupPayload(params=params),
+            payload=orm_storage.CreateDataGroupPayload(
+                params=params,
+                client_metadata=client_metadata,
+            ),
             result_type=UUID,
         )
 

tests/common/test_deprecated.py

@@ -0,0 +1,30 @@
+import warnings
+
+from encord.common.deprecated import deprecated
+
+
+def test_deprecated() -> None:
+    class SampleClass:
+        @deprecated(version="1.0", alternative="new_method")
+        def method(self):
+            return "method called"
+
+    @deprecated(version="1.0")
+    class OldClass:
+        pass
+
+    with warnings.catch_warnings(record=True) as w:
+        obj = SampleClass()
+        result = obj.method()
+
+        assert result == "method called"
+        assert len(w) == 1
+        assert issubclass(w[0].category, DeprecationWarning)
+        assert "method is deprecated since version 1.0, use new_method instead" in str(w[0].message)
+
+    with warnings.catch_warnings(record=True) as w:
+        OldClass()
+
+        assert len(w) == 1
+        assert issubclass(w[0].category, DeprecationWarning)
+        assert "OldClass is deprecated since version 1.0" in str(w[0].message)

tests/docs/data-groups-caro.py

@@ -2,7 +2,7 @@
 
 from encord.constants.enums import DataType
 from encord.objects.metadata import DataGroupMetadata
-from encord.orm.storage import DataGroupList, StorageItemType
+from encord.orm.storage import DataGroupCarousel, StorageItemType
 from encord.user_client import EncordUserClient
 
 # --- Configuration ---
@@ -76,10 +76,10 @@
     # Add more groups as needed...
 ]
 
-# --- Create the data groups using default list layout ---
+# --- Create the data groups using default carousel layout ---
 for g in groups:
     group = folder.create_data_group(
-        DataGroupList(
+        DataGroupCarousel(
             name=g["name"],
             layout_contents=g["uuids"],
         )