RF: Drop support for pyzstd - depend on compression.zstd, falling back to

optional backports.zstd. Accept level_or_option parameter, but emit a
deprecation warning

Author: pauldmccarthy

nibabel/_compression.py

@@ -15,19 +15,22 @@
 import io
 import typing as ty
 
+try:
+    from compression import zstd
+    HAVE_ZSTD = True
+except ImportError:  # PY313
+    HAVE_ZSTD = False
+
+from .deprecated import alert_future_error
 from .optpkg import optional_package
 
 if ty.TYPE_CHECKING:
-    import io
 
     import indexed_gzip  # type: ignore[import]
 
-    # >= py314
-    try:
-        from compression import zstd  # type: ignore[import]
-    # < py314
-    except ImportError:
+    if not HAVE_ZSTD:  # PY313
         from backports import zstd  # type: ignore[import]
+        HAVE_ZSTD = True
 
     HAVE_INDEXED_GZIP = True
     HAVE_ZSTD = True
@@ -42,8 +45,8 @@
 
 else:
     indexed_gzip, HAVE_INDEXED_GZIP, _ = optional_package('indexed_gzip')
-    zstd, HAVE_ZSTD, _ = optional_package(('compression.zstd',
-                                           'backports.zstd', 'pyzstd'))
+    if not HAVE_ZSTD:  # PY313
+        zstd, HAVE_ZSTD, _ = optional_package('backports.zstd')
 
 # Collections of types for isinstance or exception matching
 COMPRESSED_FILE_LIKES: tuple[type[io.IOBase], ...] = (
@@ -151,19 +154,15 @@ def zstd_open(
     filename: str,
     mode: Mode = 'r',
     *,
-    level_or_option: int | dict | None = None,
-    zstd_dict: zstd.ZstdDict | None = None,
     level : int = None,
     options : dict = None,
+    zstd_dict: zstd.ZstdDict | None = None,
+    level_or_option: int | dict | None = None
 ) -> zstd.ZstdFile:
     """Open a zstd file for reading or writing.
 
-    The specific object type returned depends on which module out of
-    ``compression.zstd``, ``backports.zstd``, or ``pyzstd`` is available.
-
-    At most one of the ``level_or_options``, ``level``, or
-    ``options`` parameters may be provided - a ``ValueError`` will be raised
-    if more than one is specified.
+    The specific object returned will be a ``compression.zstd.ZstdFile`` or
+    a ``backports.zstd.ZstdFile``.
 
     Parameters
     ----------
@@ -172,34 +171,34 @@ def zstd_open(
         Path of file to open.
     mode : str
         Opening mode.
-    level_or_option: int or dict
-        Compression level or dictionary containing options (see also the
-        level and options parameters).
     zstd_dict : ZstdDict
         Dictionary used for compression/decompression.
     level : int
         Compression level when writing.
     options : dict
         Dictionary of compression/decompression options.
     """
-    level_or_option_provided = sum((level_or_option is not None,
-                                 level is not None,
-                                 options is not None))
-    if level_or_option_provided > 1:
-        raise ValueError(
-            'Only one of level_or_option, level, or options may be specified')
-    # pyzstd accepts level_or_option, but compression.zstd/backports.zstd
-    # expects level or options
-    level_or_option_kwarg = {}
-    if level_or_option_provided == 1:
-        level_or_option_value = [v for v in [level_or_option, level, options]
-                                  if v is not None][0]
-        if zstd.__name__ == 'pyzstd':
-            level_or_option_kwarg['level_or_option'] = level_or_option_value
-        else:
-            if isinstance(level_or_option_value, int):
-                level_or_option_kwarg['level'] = level_or_option_value
+    if level_or_option is not None:
+        alert_future_error(
+            'The level_or_option parameter will be removed in a future '
+            'version of nibabel',
+            '7.0',
+            warning_rec='This warning can be silenced by using the separate '
+            'level/option parameters',
+            error_rec='Future errors can be avoided by using the separate '
+            'level/option parameters',
+            error_class=TypeError)
+        level_or_option_provided = sum((level_or_option is not None,
+                                        level is not None,
+                                        options is not None))
+        if level_or_option_provided > 1:
+            raise ValueError(
+                'Only one of level_or_option, level or options may be '
+                'specified')
+        if level_or_option is not None:
+            if isinstance(level_or_option, int):
+                level = level_or_option
             else:
-                level_or_option_kwarg['options'] = level_or_option_value
+                options = level_or_option
     return zstd.ZstdFile(
-        filename, mode, zstd_dict=zstd_dict, **level_or_option_kwarg)
+        filename, mode, level=level, options=options, zstd_dict=zstd_dict)

nibabel/openers.py

@@ -62,8 +62,7 @@ class Opener:
 
     gz_def = (gzip_open, ('mode', 'compresslevel', 'mtime', 'keep_open'))
     bz2_def = (BZ2File, ('mode', 'buffering', 'compresslevel'))
-    zstd_def = (zstd_open, ('mode', 'level_or_option', 'zstd_dict', 'level',
-                            'option'))
+    zstd_def = (zstd_open, ('mode', 'level', 'option', 'zstd_dict'))
     compress_ext_map: dict[str | None, OpenerDef] = {
         '.gz': gz_def,
         '.bz2': bz2_def,
@@ -72,13 +71,12 @@ class Opener:
     }
     #: default compression level when writing gz and bz2 files
     default_compresslevel = 1
-    #: default option for zst files
-    default_zst_compresslevel = 3
-    default_level_or_option = {
+    #: default compression level for zst files
+    default_zst_level = {
         'rb': None,
         'r': None,
-        'wb': default_zst_compresslevel,
-        'w': default_zst_compresslevel,
+        'wb': 3,
+        'w': 3,
     }
     #: whether to ignore case looking for compression extensions
     compress_ext_icase: bool = True
@@ -92,19 +90,21 @@ def __init__(self, fileish: str | io.IOBase, *args, **kwargs):
             self._name = getattr(fileish, 'name', None)
             return
         opener, arg_names = self._get_opener_argnames(fileish)
-        # Get full arguments to check for mode and compresslevel
+        # Get full arguments to check for optional parameters
         full_kwargs = {**kwargs, **dict(zip(arg_names, args))}
         # Set default mode
         if 'mode' not in full_kwargs:
             mode = 'rb'
             kwargs['mode'] = mode
         else:
             mode = full_kwargs['mode']
-        # Default compression level
+        # Default gz/bz2 compression level
         if 'compresslevel' in arg_names and 'compresslevel' not in kwargs:
             kwargs['compresslevel'] = self.default_compresslevel
-        if 'level_or_option' in arg_names and 'level_or_option' not in kwargs:
-            kwargs['level_or_option'] = self.default_level_or_option[mode]
+        # Default zstd compression level
+        if ('level' in arg_names and 'level' not in kwargs and
+            'option' not in kwargs):
+            kwargs['level'] = self.default_zst_level[mode]
         # Default keep_open hint
         if 'keep_open' in arg_names:
             kwargs.setdefault('keep_open', False)