Fixes for pandas v3 compatibility

docs/src/whatsnew/latest.rst

@@ -75,6 +75,9 @@ This document explains the changes made to Iris for this release
    testing conveniences in favour of the conveniences found in :mod:`iris/tests/_shared_utils.py`.
    (:pull:`6950`)
 
+#. `@hsteptoe`_ has deprecated the use of the `copy` kwarg across :mod:`iris.pandas` to reflect changes
+   to the default behaviour of pandas v3 `New pandas v3 copy behaviour`_. (:pull:`6948`)
+
 
 🔗 Dependencies
 ===============
@@ -122,13 +125,21 @@ This document explains the changes made to Iris for this release
    from unittest to pytest. Iris is now also ruff-PT compliant, save for PT019.
    (:issue:`6212`, :pull:`6939`)
 
+#. `@hsteptoe`_ and `@ESadek-MO`_ (reviewer) updated chained assignment useage within the tests 
+   associated with :mod:`iris.pandas` to reflect changes in pandas v3 `New pandas v3 copy behaviour`_. 
+   (:pull:`6948`, :issue:`6761`)
+
+#. `@hsteptoe`_ and `@ESadek-MO`_ (reviewer) added static type hinting to :mod:`iris.pandas`. (:pull:`6948`)
+
 .. comment
     Whatsnew author names (@github name) in alphabetical order. Note that,
     core dev names are automatically included by the common_links.inc:
 
 .. _@hdyson: https://github.com/hdyson
-
-.. _SPEC0 Minimum Supported Dependencies: https://scientific-python.org/specs/spec-0000/
+.. _@hsteptoe: https://github.com/hsteptoe
 
 .. comment
     Whatsnew resources in alphabetical order:
+
+.. _New pandas v3 copy behaviour: https://pandas.pydata.org/docs/whatsnew/v3.0.0.html#consistent-copy-view-behaviour-with-copy-on-write
+.. _SPEC0 Minimum Supported Dependencies: https://scientific-python.org/specs/spec-0000/

lib/iris/_deprecation.py

@@ -4,8 +4,82 @@
 # See LICENSE in the root of the repository for full licensing details.
 """Utilities for producing runtime deprecation messages."""
 
+from functools import wraps
+import inspect
 import warnings
 
+from iris.warnings import IrisUserWarning
+
+
+def explicit_copy_checker(f):
+    """Check for explicitly set parameters in a function.
+
+    This is intended to be used as a decorator for functions that take a
+    variable number of parameters, to allow the function to determine which
+    parameters were explicitly set by the caller.
+
+    This can be helpful when wanting raise DeprecationWarning of function
+    parameters, but only when they are explicitly set by the caller, and not
+    when they are left at their default value.
+
+    Parameters
+    ----------
+    f : function
+        The function to be decorated. The function must have a signature that
+        allows for variable parameters (e.g. ``*args`` and/or ``**kwargs``), and
+        the parameters to be checked must be explicitly listed in the function
+        signature (i.e. not just passed via ``**kwargs``).
+
+    Returns
+    -------
+    function
+        The decorated function, which will have an additional keyword argument
+        ``explicit_params`` added to its signature. This argument will be a set
+        of the names of the parameters that were explicitly set by the caller when
+        calling the function.
+
+    Examples
+    --------
+    The following example shows how to use the ``explicit_copy_checker`` decorator to
+    check for explicitly set parameters in a function, and raise a DeprecationWarning
+    if a deprecated parameter is explicitly set by the caller.
+
+    >>> from iris._deprecation import explicit_copy_checker, IrisDeprecation
+    >>> @explicit_copy_checker
+    ... def my_function(a, b=1):
+    ...     print(f"a={a}, b={b}")
+    ...     if "b" in kwargs["explicit_params"]:
+    ...         warnings.warn("Parameter 'b' is deprecated.", IrisDeprecation)
+    >>> my_function(1)  # No warning, 'b' is not explicitly set
+    >>> my_function(1, b=3)  # Warning, 'b' is explicitly set
+
+    """
+    varnames = inspect.getfullargspec(f)[0]
+
+    @wraps(f)
+    def wrapper(*a, **kw):
+        explicit_params = set(list(varnames[: len(a)]) + list(kw.keys()))
+        if "copy" in explicit_params:
+            if kw["copy"] is False:
+                msg = (
+                    "Pandas v3 behaviour defaults to copy=True. The `copy`"
+                    f" parameter in `{f.__name__}` is deprecated and"
+                    "will be removed in a future release."
+                )
+                warnings.warn(msg, category=IrisUserWarning)
+            else:
+                msg = (
+                    f"The `copy` parameter in `{f.__name__}` is deprecated and"
+                    " will be removed in a future release. The function will"
+                    " always make a copy of the data array, to ensure that the"
+                    " returned Cubes are independent of the input pandas data."
+                )
+                warn_deprecated(msg)
+        else:
+            return f(*a, **kw)
+
+    return wrapper
+
 
 class IrisDeprecation(UserWarning):
     """An Iris deprecation warning.