Merge pull request #388 from euroargodev/deprec-before-major

Introduces deprecation warnings before major v1.0.0 release

argopy/errors.py

@@ -1,4 +1,9 @@
 """A bunch of custom errors used in argopy."""
+from typing import List
+import warnings
+import logging
+
+log = logging.getLogger("argopy.errors")
 
 
 class DataNotFound(ValueError):
@@ -144,3 +149,49 @@ class ErddapHTTPNotFound(APIServerError):
     """Raise when erddap resource is not found"""
 
     pass
+
+
+class OptionDeprecatedWarning(DeprecationWarning):
+    """When an option being deprecated is used
+
+    This is a class to emit a warning when an option being deprecated is used.
+
+    Parameters
+    ----------
+    reason: str, optional, default=None
+        Text message to send with deprecation warning
+    version: str, optional, default=None
+    ignore_caller: List, optional, default=[]
+    """
+    def __init__(self, reason: str = None, version: str = None, ignore_caller: List = []):
+        import inspect
+        ignore_caller = [ignore_caller]
+
+        if isinstance(reason, str):
+
+            fmt = "\nCall to deprecated option: {reason}"
+            if version is not None:
+                fmt = "%s -- Deprecated since version {version}" % fmt
+
+            issue_deprec = True
+            stack = inspect.stack()
+            for s in stack:
+                if "<module>" in s.function:
+                    break
+                elif s.function in ignore_caller:
+                    issue_deprec = False
+
+            if issue_deprec:
+                warnings.simplefilter("always", DeprecationWarning)
+                warnings.warn(
+                    fmt.format(reason=reason, version=version),
+                    category=DeprecationWarning,
+                    stacklevel=2,
+                )
+                warnings.simplefilter("default", DeprecationWarning)
+            else:
+                log.warning(fmt.format(reason=reason, version=version))
+
+        else:
+            raise TypeError(repr(type(reason)))
+

argopy/fetchers.py

@@ -16,7 +16,7 @@
 import logging
 
 from .options import OPTIONS, _VALIDATORS
-from .errors import InvalidFetcherAccessPoint, InvalidFetcher, OptionValueError
+from .errors import InvalidFetcherAccessPoint, InvalidFetcher, OptionValueError, OptionDeprecatedWarning
 from .related import (
     get_coriolis_profile_id,
 )
@@ -168,6 +168,10 @@ def __init__(self, mode: str = "", src: str = "", ds: str = "", **fetcher_kwargs
         ):
             raise OptionValueError("The 'argovis' data source fetching is only available in 'standard' user mode")
 
+        if self._src == "gdac" and "ftp" in self.fetcher_kwargs:
+            OptionDeprecatedWarning(reason="The GDAC 'ftp' argument is deprecated, it will be replaced by 'gdac' in versions >= 0.1.18",
+                                   version="v0.0.17")
+
 
     def __repr__(self):
         para = (

argopy/options.py

@@ -11,8 +11,7 @@
 from fsspec.core import split_protocol
 from socket import gaierror
 from urllib.parse import urlparse
-from .errors import OptionValueError, FtpPathError, ErddapPathError
-
+from .errors import OptionValueError, FtpPathError, ErddapPathError, OptionDeprecatedWarning
 
 # Define a logger
 log = logging.getLogger("argopy.options")
@@ -97,37 +96,65 @@ def validate_http(this_path):
 class set_options:
     """Set options for argopy
 
-    List of options:
-
-    - ``dataset``: Define the Dataset to work with.
-        Default: ``phy``.
-        Possible values: ``phy``, ``bgc`` or ``ref``.
-    - ``src``: Source of fetched data.
-        Default: ``erddap``.
-        Possible values: ``erddap``, ``gdac``, ``argovis``
-    - ``mode``: User mode.
-        Default: ``standard``.
-        Possible values: ``standard``, ``expert`` or ``research``.
-    - ``ftp``: Default path to be used by the GDAC fetchers and Argo index stores
-        Default: https://data-argo.ifremer.fr
-    - ``erddap``: Default server address to be used by the data and index erddap fetchers
-        Default: https://erddap.ifremer.fr/erddap
-    - ``cachedir``: Absolute path to a local cache directory.
-        Default: ``~/.cache/argopy``
-    - ``cache_expiration``: Expiration delay of cache files in seconds.
-        Default: 86400
-    - ``api_timeout``: Define the time out of internet requests to web API, in seconds.
-        Default: 60
-    - ``trust_env``: Allow for local environment variables to be used to connect to the internet.
-        Default: False.
-        Argopy will get proxies information from HTTP_PROXY / HTTPS_PROXY environment variables if this option is True and it can also get proxy credentials from ~/.netrc file if this file exists.
-    - ``user``/``password``: Username and password to use when a simple authentication is required.
-        Default: None, None
-    - ``server``: Other than expected/default server to be uses by a function/method. This is mostly intended to be used for unit testing
-        Default: None
-    - ``argovis_api_key``: The API key to use when fetching data from the `argovis` data source. You can get a free key at https://argovis-keygen.colorado.edu
-        Default: `guest`
+    Parameters
+    ----------
+    dataset: str, default: 'phy'
+        Define the Dataset to work with: ``phy``, ``bgc`` or ``ref``
+
+        .. deprecated:: 0.1.17
+
+            - Replaced by ``ds`` in versions >= v0.1.18
+
+    src: str, default: 'erddap'
+        Source of fetched data: ``erddap``, ``gdac``, ``argovis``
+
+    mode: str, default: 'standard'
+        User mode: ``standard``, ``expert`` or ``research``
+
+    ftp: str, default: 'https://data-argo.ifremer.fr'
+        Default path to be used by the GDAC fetchers and Argo index stores
+
+        .. deprecated:: 0.1.17
+
+            - Replaced by ``gdac`` in versions >= v0.1.18
+
+    erddap: str, default: 'https://erddap.ifremer.fr/erddap'
+        Default server address to be used by the data and index erddap fetchers
+
+    cachedir: str, default: '~/.cache/argopy'
+        Absolute path to a local cache directory
+
+    cache_expiration: int, default: 86400
+        Expiration delay of cache files in seconds
+
+    api_timeout: int, default: 60
+        Time out for internet requests to web API, in seconds
+
+    trust_env: bool, default: False
+        Allow for local environment variables to be used to connect to the internet.
 
+        Argopy will get proxies information from HTTP_PROXY / HTTPS_PROXY environment variables if this option is True and it can also get proxy credentials from ~/.netrc file if this file exists
+
+    user: str, default: None
+        Username to use when a simple authentication is required
+
+    password: str, default: None
+        Password to use when a simple authentication is required
+
+    argovis_api_key: str, default:'guest'
+        The API key to use when fetching data from the `argovis` data source
+
+        You can get a free key at https://argovis-keygen.colorado.edu
+
+    Other Parameters
+    ----------------
+    server: : str, default: None
+        Other than expected/default server to be uses by a function/method
+
+        This is mostly intended to be used for unit testing
+
+    Examples
+    --------
 
     You can use ``set_options`` either as a context manager for temporary setting:
 
@@ -139,7 +166,12 @@ class set_options:
 
     >>> argopy.set_options(src='gdac')
 
+    Warns
+    -----
+    A DeprecationWarning can be raised when a deprecated option is set
+
     """
+
     def __init__(self, **kwargs):
         self.old = {}
         for k, v in kwargs.items():
@@ -153,6 +185,18 @@ def __init__(self, **kwargs):
             if k in _VALIDATORS and not _VALIDATORS[k](v):
                 raise OptionValueError(f"option {k!r} given an invalid value: {v!r}")
             self.old[k] = OPTIONS[k]
+
+            if k == 'dataset':
+                OptionDeprecatedWarning(reason="The 'dataset' option is deprecated, it will be replaced by 'ds' in "
+                                            "versions >= 0.1.18",
+                                     version="v0.0.17",
+                                     ignore_caller='test_opt_dataset')
+
+            if k == 'ftp':
+                OptionDeprecatedWarning(reason="The 'ftp' option is deprecated, it will be replaced by 'gdac' in "
+                                            "versions >= 0.1.18",
+                                     version="v0.0.17")
+
         self._apply_update(kwargs)
 
     def _apply_update(self, options_dict):

argopy/tests/test_deprecated.py

@@ -0,0 +1,33 @@
+import logging
+import pytest
+from mocked_http import mocked_server_address
+from mocked_http import mocked_httpserver as mocked_erddapserver
+
+import argopy
+from utils import (
+    requires_erddap,
+)
+
+
+log = logging.getLogger("argopy.tests.deprecated")
+
+
+def test_deprecated_option_dataset():
+    with pytest.deprecated_call():
+        argopy.set_options(dataset='phy')
+
+
+def test_deprecated_option_ftp():
+    with pytest.deprecated_call():
+        argopy.set_options(ftp='https://data-argo.ifremer.fr')
+
+
+def test_deprecated_fetcher_argument_ftp():
+    with pytest.deprecated_call():
+        argopy.DataFetcher(src='gdac', ftp='https://data-argo.ifremer.fr')
+
+@requires_erddap
+def test_deprecated_accessor_filter_data_mode(mocked_erddapserver):
+    with pytest.deprecated_call():
+        ds = argopy.DataFetcher(src='erddap', mode='expert', server=mocked_server_address).profile(6902746, 34).to_xarray()
+        ds.argo.filter_data_mode()

argopy/xarray.py

@@ -24,6 +24,7 @@
     groupby_remap,
 )
 from .utils.geo import toYearFraction
+from .utils.decorators import deprecated
 from .errors import InvalidDatasetStructure, DataNotFound, OptionValueError
 
 
@@ -576,6 +577,11 @@ def profile2point(self):
         ds.argo._type = "point"
         return ds
 
+    @deprecated(
+        "This method is deprecated and will break your code for versions >= 0.1.18. ",
+        ignore_caller="postprocessing",
+        version="0.1.17",
+    )
     def filter_data_mode(  # noqa: C901
         self, keep_error: bool = True, errors: str = "raise"
     ):
@@ -602,6 +608,16 @@ def filter_data_mode(  # noqa: C901
         Returns
         -------
         :class:`xarray.Dataset`
+
+
+        .. deprecated:: 0.1.7
+
+            This method action and signature are deprecated and will break your code for versions >= 0.1.18.
+
+            In versions >= 0.1.18, this method behavior will be transferred to the new `transform_data_mode` method
+            while this method `filter_data_mode` will change its signature and behavior to really filter measurements
+            according to DATA_MODE or <PARAM>_DATA_MODE values.
+
         """
         if self._type != "point":
             raise InvalidDatasetStructure(

docs/whats-new.rst

@@ -11,6 +11,20 @@ What's New
 Coming up next
 --------------
 
+Features and front-end API
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. important:: Introduces deprecation warnings before the upcoming major release v1.0.0. (:pr:`389`) by `G. Maze <http://www.github.com/gmaze>`_.
+
+    .. currentmodule:: xarray
+
+    - Change of signature and action with xarray Argo accessor :meth:`Dataset.argo.filter_data_mode`
+
+    .. currentmodule:: argopy
+
+    - Refactor option "dataset" into "ds", see :class:`argopy.set_options`
+    - Refactor option "ftp" into "gdac", see :class:`argopy.set_options`
+
 Internals
 ^^^^^^^^^
 
@@ -19,7 +33,6 @@ Internals
 - Improve error and warning messages from mocked http server to address :issue:`381` (:pr:`382`) by `G. Maze <http://www.github.com/gmaze>`_
 
 
-
 v0.1.16 (27 Aug. 2024)
 ----------------------
 
@@ -71,6 +84,7 @@ Breaking changes
 
 - Drop support for erddapy < v0.8.0 (:pr:`344`) by `G. Maze <http://www.github.com/gmaze>`_.
 
+
 v0.1.15 (12 Dec. 2023)
 ----------------------
 
@@ -79,6 +93,7 @@ Internals
 
 - Fix bug whereby user name could not be retrieved using :func:`getpass.getuser`. This closes :issue:`310` and allows argopy to be integrated into the EU Galaxy tools for `ecology <https://github.com/galaxyecology/tools-ecology/pull/81>`_. (:pr:`311`) by `G. Maze <http://www.github.com/gmaze>`_.
 
+
 v0.1.14 (29 Sep. 2023)
 ----------------------
 
@@ -336,6 +351,7 @@ Breaking changes
 
 - Some documentation pages may have moved to new urls.
 
+
 v0.1.14rc1 (31 May 2023)
 ------------------------
 
@@ -622,6 +638,7 @@ Internals
 
 - Update and clean up requirements. Remove upper bound on all dependencies (:pr:`182`) by `R. Abernathey <http://www.github.com/rabernat>`_.
 
+
 v0.1.9 (19 Jan. 2022)
 ---------------------
 
@@ -791,6 +808,7 @@ Internals
         handlers=[logging.FileHandler("argopy.log", mode='w')]
     )
 
+
 v0.1.7 (4 Jan. 2021)
 -----------------------
 
@@ -927,6 +945,7 @@ Internals
 
 - Erddap fetcher now uses netcdf format to retrieve data (:pr:`19`).
 
+
 v0.1.3 (15 May 2020)
 --------------------
 
@@ -976,11 +995,13 @@ Internals
 
 - Improved unit testing (:commit:`e9555d1e6e90d3d1e75183cec0c4e14f7f19c17c`, :commit:`4b60ede844e37df86b32e4e2a2008335472a8cc1`, :commit:`34abf4913cb8bec027f88301c5504ebe594b3eae`)
 
+
 v0.1.2 (15 May 2020)
 --------------------
 
 We didn't like this one this morning, so we move one to the next one !
 
+
 v0.1.1 (3 Apr. 2020)
 ---------------------