deprecations and changelog

Author: normanrz

webknossos/Changelog.md

@@ -17,6 +17,7 @@ For upgrade instructions, please check the respective _Breaking Changes_ section
 ### Added
 
 ### Changed
+- `Layer.add_mag_as_copy` now automatically uses file-based copy, if possible. Therefore, `Dataset.fs_copy_dataset`, `Dataset.add_fs_copy_layer` and `Layer.add_fs_copy_mag` are deprecated. [#1362](https://github.com/scalableminds/webknossos-libs/pull/1362)
 
 ### Fixed
 

webknossos/webknossos/dataset/dataset.py

@@ -2524,13 +2524,15 @@ def add_fs_copy_layer(
         foreign_layer: str | Path | Layer,
         new_layer_name: str | None = None,
     ) -> Layer:
-        """
+        """Deprecated. File-based copy is automatically used in `Dataset.add_layer_as_copy`.
+
         Copies the files at `foreign_layer` which belongs to another dataset
         to the current dataset via the filesystem. Additionally, the relevant
         information from the `datasource-properties.json` of the other dataset
         are copied too. If new_layer_name is None, the name of the foreign
         layer is used.
         """
+        warn_deprecated("add_fs_copy_layer", "add_layer_as_copy")
         self._ensure_writable()
         foreign_layer = Layer._ensure_layer(foreign_layer)
 
@@ -2705,7 +2707,8 @@ def fs_copy_dataset(
         exists_ok: bool = False,
         layers_to_ignore: Iterable[str] | None = None,
     ) -> "Dataset":
-        """
+        """Deprecated. File-based copy is automatically used by `Dataset.copy_dataset`.
+
         Creates an independent copy of the dataset with all layers at a new location.
 
         This method copies the files of the dataset as is and, therefore, might be faster than Dataset.copy_dataset, which decodes and encodes all the data.
@@ -2731,6 +2734,7 @@ def fs_copy_dataset(
         Note:
             WKW layers can only be copied to datasets on local file systems.
         """
+        warn_deprecated("fs_copy_dataset", "copy_dataset")
 
         new_dataset_path = UPath(new_dataset_path)
 

webknossos/webknossos/dataset/layer.py

@@ -2,6 +2,7 @@
 import operator
 import re
 import warnings
+from inspect import getframeinfo, stack
 from os import PathLike
 from os.path import relpath
 from pathlib import Path
@@ -1076,17 +1077,13 @@ def add_mag_as_ref(
 
         return self.get_mag(foreign_mag_view.mag)
 
-    def add_fs_copy_mag(
+    def _add_fs_copy_mag(
         self,
         foreign_mag_view_or_path: PathLike | str | MagView,
         *,
         extend_layer_bounding_box: bool = True,
         exists_ok: bool = False,
     ) -> MagView:
-        """
-        Copies the data at `foreign_mag_view_or_path` which belongs to another dataset to the current dataset via the filesystem.
-        Additionally, the relevant information from the `datasource-properties.json` of the other dataset are copied, too.
-        """
         self._ensure_writable()
         foreign_mag_view = MagView._ensure_mag_view(foreign_mag_view_or_path)
         self._assert_mag_does_not_exist_yet(foreign_mag_view.mag)
@@ -1113,6 +1110,30 @@ def add_fs_copy_mag(
 
         return mag
 
+    def add_fs_copy_mag(
+        self,
+        foreign_mag_view_or_path: PathLike | str | MagView,
+        *,
+        extend_layer_bounding_box: bool = True,
+        exists_ok: bool = False,
+    ) -> MagView:
+        """Deprecated. File-copy is automatically selected when using `Layer.add_mag_as_copy`.
+
+        Copies the data at `foreign_mag_view_or_path` which belongs to another dataset to the current dataset via the filesystem.
+        Additionally, the relevant information from the `datasource-properties.json` of the other dataset are copied, too.
+        """
+        caller = getframeinfo(stack()[2][0])
+        warnings.warn(
+            f"[DEPRECATION] Direct use of `Layer.add_fs_copy_mag` is deprecated, please use `Layer.add_mag_as_copy` instead (see {caller.filename}:{caller.lineno}), which automatically uses file-based copy if available.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self._add_fs_copy_mag(
+            foreign_mag_view_or_path,
+            extend_layer_bounding_box=extend_layer_bounding_box,
+            exists_ok=exists_ok,
+        )
+
     def add_mag_from_zarrarray(
         self,
         mag: MagLike,