RF: Update Gifti/Cifti2MetaData checks to _sanitize, add doctests

Author: effigies

nibabel/cifti2/cifti2.py

@@ -122,23 +122,51 @@ class Cifti2MetaData(CaretMetaData):
     ----------
     data : list of (name, value) tuples
     """
-    def __init__(self, *args, **kwargs):
+    @staticmethod
+    def _sanitize(args, kwargs):
+        """ Sanitize and warn on deprecated arguments
+
+        Accept metadata positional/keyword argument that can take
+        ``None`` to indicate no initialization.
+
+        >>> import pytest
+        >>> Cifti2MetaData()
+        <Cifti2MetaData {}>
+        >>> Cifti2MetaData([("key", "val")])
+        <Cifti2MetaData {'key': 'val'}>
+        >>> Cifti2MetaData(key="val")
+        <Cifti2MetaData {'key': 'val'}>
+        >>> with pytest.warns(FutureWarning):
+        ...     Cifti2MetaData(None)
+        <Cifti2MetaData {}>
+        >>> with pytest.warns(FutureWarning):
+        ...     Cifti2MetaData(metadata=None)
+        <Cifti2MetaData {}>
+        >>> with pytest.warns(FutureWarning):
+        ...     Cifti2MetaData(metadata={'key': 'val'})
+        <Cifti2MetaData {'key': 'val'}>
+
+        Note that "metadata" could be a valid key:
+
+        >>> Cifti2MetaData(metadata='val')
+        <Cifti2MetaData {'metadata': 'val'}>
+        """
         if not args and list(kwargs) == ["metadata"]:
-            md = kwargs.pop("metadata")
-            if not isinstance(md, str):
-                warn("CaretMetaData now has a dict-like interface and will "
+            if not isinstance(kwargs["metadata"], str):
+                warn("Cifti2MetaData now has a dict-like interface and will "
                      "no longer accept the ``metadata`` keyword argument in "
                      "NiBabel 6.0. See ``pydoc dict`` for initialization options.",
-                     FutureWarning, stacklevel=2)
+                     FutureWarning, stacklevel=3)
+                md = kwargs.pop("metadata")
                 if md is not None:
                     args = (md,)
         if args == (None,):
-            warn("CaretMetaData now has a dict-like interface and will no longer "
+            warn("Cifti2MetaData now has a dict-like interface and will no longer "
                  "accept the positional argument ``None`` in NiBabel 6.0. "
                  "See ``pydoc dict`` for initialization options.",
-                 FutureWarning, stacklevel=2)
+                 FutureWarning, stacklevel=3)
             args = ()
-        super().__init__(*args, **kwargs)
+        return args, kwargs
 
     @property
     def data(self):

nibabel/gifti/gifti.py

@@ -30,24 +30,46 @@ class GiftiMetaData(CaretMetaData):
     """ A sequence of GiftiNVPairs containing metadata for a gifti data array
     """
 
-    def __init__(self, *args, **kwargs):
+    @staticmethod
+    def _sanitize(args, kwargs):
+        """ Sanitize and warn on deprecated arguments
+
+        Accept nvpair positional/keyword argument that is a single
+        ``GiftiNVPairs`` object.
+
+        >>> import pytest
+        >>> GiftiMetaData()
+        <GiftiMetaData {}>
+        >>> GiftiMetaData([("key", "val")])
+        <GiftiMetaData {'key': 'val'}>
+        >>> GiftiMetaData(key="val")
+        <GiftiMetaData {'key': 'val'}>
+        >>> GiftiMetaData({"key": "val"})
+        <GiftiMetaData {'key': 'val'}>
+        >>> nvpairs = GiftiNVPairs(name='key', value='val')
+        >>> with pytest.warns(FutureWarning):
+        ...     GiftiMetaData(nvpairs)
+        <GiftiMetaData {'key': 'val'}>
+        >>> with pytest.warns(FutureWarning):
+        ...     GiftiMetaData(nvpair=nvpairs)
+        <GiftiMetaData {'key': 'val'}>
+        """
         dep_init = False
         # Positional arg
         dep_init |= not kwargs and len(args) == 1 and isinstance(args[0], GiftiNVPairs)
         # Keyword arg
         dep_init |= not args and list(kwargs) == ["nvpair"]
-        if dep_init:
-            warnings.warn(
-                "GiftiMetaData now has a dict-like interface. "
-                "See ``pydoc dict`` for initialization options. "
-                "Passing ``GiftiNVPairs()`` or using the ``nvpair`` "
-                "keyword will fail or behave unexpectedly in NiBabel 6.0.",
-                FutureWarning, stacklevel=2)
-            super().__init__()
-            pair = args[0] if args else kwargs.get("nvpair")
-            self[pair.name] = pair.value
-        else:
-            super().__init__(*args, **kwargs)
+        if not dep_init:
+            return args, kwargs
+
+        warnings.warn(
+            "GiftiMetaData now has a dict-like interface. "
+            "See ``pydoc dict`` for initialization options. "
+            "Passing ``GiftiNVPairs()`` or using the ``nvpair`` "
+            "keyword will fail or behave unexpectedly in NiBabel 6.0.",
+            FutureWarning, stacklevel=3)
+        pair = args[0] if args else kwargs.get("nvpair")
+        return (), {pair.name: pair.value}
 
     @property
     def data(self):