Merge pull request landlab#1999 from landlab/mcflugen/deprecate-old-a…

…dd-field

Upgrade old field method usage

news/1999.misc

@@ -0,0 +1,3 @@
+
+Deprecated passing the `at` keyword as the first argument to
+functions like, for example, :meth:`~.GraphFields.add_ones`.

src/landlab/field/graph_field.py

@@ -2,11 +2,14 @@
 :class:`~landlab.graph.graph.Graph`.
 """
 
+import inspect
+import warnings
+
 import numpy as np
 import xarray as xr
 
-from .errors import FieldError
-from .errors import GroupError
+from landlab.field.errors import FieldError
+from landlab.field.errors import GroupError
 
 
 def reshape_for_storage(array, field_size=None):
@@ -658,14 +661,9 @@ def has_field(self, *args, **kwds):
 
         :meta landlab: info-field
         """
-        if len(args) == 2:
-            group, field = args
-        elif len(args) == 1:
-            group, field = kwds.pop("at", self.default_group), args[0]
-        else:
-            raise ValueError("number of arguments must be 1 or 2")
-        if group is None:
-            raise ValueError("no group provided")
+        kwds.setdefault("at", self.default_group)
+        args, group = _parse_args_and_location(1, *args, **kwds)
+        field = args[0]
 
         try:
             return field in self[group]
@@ -784,14 +782,9 @@ def field_values(self, *args, **kwds):
 
         :meta landlab: field-io
         """
-        if len(args) == 2:
-            group, field = args
-        elif len(args) == 1:
-            group, field = kwds.pop("at", self.default_group), args[0]
-        else:
-            raise ValueError("number of arguments must be 1 or 2")
-        if group is None:
-            raise ValueError("no group provided")
+        kwds.setdefault("at", self.default_group)
+        args, group = _parse_args_and_location(1, *args, **kwds)
+        field = args[0]
 
         try:
             fields = self[group]
@@ -883,17 +876,12 @@ def return_array_or_field_values(self, *args, **kwds):
 
         :meta landlab: field-io
         """
-        if len(args) == 2:
-            group, field = args
-        elif len(args) == 1:
-            group, field = kwds.pop("at", self.default_group), args[0]
-        else:
-            raise ValueError("number of arguments must be 1 or 2")
-        if group is None:
-            raise ValueError("no group provided")
+        kwds.setdefault("at", self.default_group)
+        args, group = _parse_args_and_location(1, *args, **kwds)
+        field = args[0]
 
         if isinstance(field, str):
-            vals = self.field_values(group, field)
+            vals = self.field_values(field, at=group)
         else:
             vals = np.asarray(field)
             if vals.size != self[group].size:
@@ -932,14 +920,9 @@ def field_units(self, *args, **kwds):
 
         :meta landlab: info-field
         """
-        if len(args) == 2:
-            group, field = args
-        elif len(args) == 1:
-            group, field = kwds.pop("at", self.default_group), args[0]
-        else:
-            raise ValueError("number of arguments must be 1 or 2")
-        if group is None:
-            raise ValueError("no group provided")
+        kwds.setdefault("at", self.default_group)
+        args, group = _parse_args_and_location(1, *args, **kwds)
+        field = args[0]
 
         return self[group]._ds[field].attrs["units"]
 
@@ -977,10 +960,9 @@ def empty(self, *args, **kwds):
 
         :meta landlab: field-add
         """
-        if len(args) == 0:
-            group = kwds.pop("at", kwds.pop("centering", "node"))
-        else:
-            group = args[0]
+        kwds.setdefault("at", kwds.pop("centering", "node"))
+        args, group = _parse_args_and_location(0, *args, **kwds)
+        kwds.pop("at")
 
         if group == "grid":
             raise ValueError(
@@ -1148,12 +1130,10 @@ def add_field(self, *args, **kwds):
 
         :meta landlab: field-add
         """
-        if len(args) == 3:
-            at, name, value_array = args
-        elif len(args) == 2:
-            at, name, value_array = (kwds.pop("at", None), args[0], args[1])
-        else:
-            raise ValueError("number of arguments must be 2 or 3")
+        kwds.setdefault("at", "node")
+        args, at = _parse_args_and_location(2, *args, **kwds)
+        name, value_array = args
+        kwds.pop("at")
 
         units = kwds.get("units", "?")
         copy = kwds.get("copy", False)
@@ -1250,12 +1230,11 @@ def add_empty(self, *args, **kwds):
 
         :meta landlab: field-add
         """
-        if len(args) == 2:
-            loc, name = args
-        elif len(args) == 1:
-            loc, name = kwds.pop("at"), args[0]
-        else:
-            raise ValueError("number of arguments must be 1 or 2")
+        kwds.setdefault("at", "node")
+        args, loc = _parse_args_and_location(1, *args, **kwds)
+        name = args[0]
+        kwds.pop("at")
+
         units = kwds.pop("units", "?")
         copy = kwds.pop("copy", False)
         clobber = kwds.pop("clobber", False)
@@ -1397,14 +1376,65 @@ def add_full(self, *args, **kwds):
 
         :meta landlab: field-add
         """
-        if len(args) == 3:
-            at, name, fill_value = args
-        elif len(args) == 2:
-            at = kwds.pop("at", "node")
-            name, fill_value = args
-        else:
-            raise ValueError("number of arguments must be 2 or 3")
+        kwds.setdefault("at", "node")
+        args, at = _parse_args_and_location(2, *args, **kwds)
+        name, fill_value = args
+        kwds.pop("at")
 
         data = self.add_empty(name, at=at, **kwds)
         data.fill(fill_value)
         return data
+
+
+def _parse_args_and_location(n_args: int, *args, **kwds) -> tuple[str, str]:
+    """Parse arguments for backward compatibility.
+
+    Parameters
+    ----------
+    n_args : int
+        The new number of expected arguments.
+    *args : tuple
+        The passed arguments.
+    **kwds : dict
+        The passed keyword arguments.
+
+    Returns
+    -------
+    tuple of tuple, str
+        The arguments as expect with the new signature followed by
+        the location string.
+
+    Examples
+    --------
+    >>> from landlab.field.graph_field import _parse_args_and_location
+    >>> _parse_args_and_location(0, "node")
+    ((), 'node')
+    >>> _parse_args_and_location(1, "node", "z")
+    (('z',), 'node')
+    >>> _parse_args_and_location(2, "cell", "z", [1, 2, 3])
+    (('z', [1, 2, 3]), 'cell')
+    >>> _parse_args_and_location(2, "cell", "z", [1, 2, 3], at="node")
+    (('z', [1, 2, 3]), 'cell')
+    >>> _parse_args_and_location(2, "z", [1, 2, 3], at="node")
+    (('z', [1, 2, 3]), 'node')
+    """
+    if len(args) == n_args:
+        return args, kwds.get("at", None)
+    elif len(args) == n_args + 1:
+        caller_name = inspect.stack()[1].function
+        sig = f"at={args[0]!r}"
+        if n_args > 0:
+            sig = ", ".join([f"arg{n}" for n in range(n_args)] + [sig])
+
+        warnings.warn(
+            f"Calling `{caller_name}` with the field location as the first argument"
+            " is deprecated and will be removed in future versions. Instead, please use"
+            " the `at` keyword to specify the location:"
+            f" {caller_name}({sig}).",
+            FutureWarning,
+            stacklevel=3,
+        )
+
+        return args[1:], args[0]
+    else:
+        raise ValueError(f"number of arguments must be {n_args} or {n_args + 1}")