Added deprecation framework

- Added deprecation decorators
- Added deprecation store
- Added deprecation to auto documentation
- Added deprecation to be shown in `WebvizPluginPlaceholder` component

Author: rubenthoms

CONTRIBUTING.md

@@ -636,3 +636,53 @@ $$\alpha = \frac{\beta}{\gamma}$$
 
 Example of auto-built documentation for `webviz-config` can be seen
 [here on github](https://equinor.github.io/webviz-config/).
+
+
+## Deprecate plugins or arguments
+
+Plugins can be marked as deprecated by using the `@deprecated_plugin(short_message, long_message)` decorator.
+
+```python
+from webviz_config.webviz_deprecated import deprecated_plugin
+
+
+@deprecated_plugin("This message is shown to the end user in the app.", "This message is shown in the documentation of the plugin.")
+class MyPlugin(WebvizPluginABC):
+    ...
+```
+
+Plugin arguments can be marked as deprecated by using the `@deprecated_plugin_arguments(check={})` decorator in front of the `__init__` function.
+Arguments can either be marked as deprecated in any case (see `MyPluginExample1`) or their values can be checked within a function (see `MyPluginExample2`) which returns a tuple containing a short string shown to the end user in the app and a long string shown in the plugin's documentation.
+
+```python
+from typing import Optional, Tuple
+from webviz_config.webviz_deprecated import deprecated_plugin_arguments
+
+
+class MyPluginExample1(WebvizPluginABC):
+    ...
+    @deprecated_plugin_arguments(
+        {
+            "arg3": (
+                "Short message shown to the end user both in the app and documentation.", 
+                (
+                    "This can be a long message, which is shown only in the documentation, explaining "
+                    "e.g. why it is deprecated and which plugin should be used instead."
+                )
+            )
+        }
+    )
+    def __init__(self, arg1: str, arg2: int, arg3: Optional[int] = None):
+        ...
+
+class MyPluginExample2(WebvizPluginABC):
+    ...
+    @deprecated_plugin_arguments(check_deprecation)
+    def __init__(self, arg1: str, arg2: int, arg3: Optional[int] = None):
+        ...
+
+def check_deprecation(arg1: int, arg3: int) -> Optional[Tuple[str, str]]:
+    if arg3 == arg1:
+        return ("This message is shown to the end user in the app.", "This message is shown in the documentation of the plugin.")
+    return None
+```

setup.py

@@ -24,7 +24,7 @@ def get_long_description() -> str:
 
 TESTS_REQUIRES = [
     "bandit",
-    "black",
+    "black>=20.8b1",
     "jsonschema",
     "mock",
     "mypy",
@@ -72,6 +72,7 @@ def get_long_description() -> str:
         ],
     },
     install_requires=[
+        "astunparse>=1.6.3",
         "bleach>=3.1",
         "cryptography>=2.4",
         "dash>=1.16",
@@ -85,6 +86,7 @@ def get_long_description() -> str:
         "pyarrow>=0.16",
         "pyyaml>=5.1",
         "tqdm>=4.8",
+        "dataclasses>=0.8; python_version<'3.7'",
         "importlib-metadata>=1.7; python_version<'3.8'",
         "typing-extensions>=3.7; python_version<'3.8'",
         "webviz-core-components>=0.1.0",

tests/test_plugin_metadata.py

@@ -1,9 +1,9 @@
 import webviz_config
-from webviz_config.plugins import metadata
+from webviz_config.plugins import METADATA
 
 
 def test_webviz_config_metadata():
-    meta = metadata["BannerImage"]
+    meta = METADATA["BannerImage"]
 
     assert meta["dist_name"] == "webviz-config"
     assert meta["dist_version"] == webviz_config.__version__

webviz_config/_config_parser.py

@@ -3,12 +3,18 @@
 import pathlib
 import inspect
 import typing
+import warnings
 
 import yaml
 
 from . import plugins as standard_plugins
 from .utils import terminal_colors
 from .utils._get_webviz_plugins import _get_webviz_plugins
+from ._deprecation_store import (
+    DEPRECATION_STORE,
+    DeprecatedArgument,
+    DeprecatedArgumentCheck,
+)
 
 SPECIAL_ARGS = ["self", "app", "webviz_settings", "_call_signature"]
 
@@ -19,7 +25,7 @@ def _call_signature(
     config_folder: pathlib.Path,
     contact_person: typing.Optional[dict] = None,
 ) -> tuple:
-    # pylint: disable=too-many-branches,too-many-statements
+    # pylint: disable=too-many-branches,too-many-statements,too-many-locals
     """Takes as input the name of a plugin together with user given arguments
     (originating from the configuration file). Returns the equivalent Python code wrt.
     initiating an instance of that plugin (with the given arguments).
@@ -110,6 +116,76 @@ def _call_signature(
             except TypeError:
                 pass
 
+    kwargs_including_defaults = kwargs
+    deprecation_warnings = []
+
+    deprecated_plugin = DEPRECATION_STORE.get_stored_plugin_deprecation(
+        getattr(standard_plugins, plugin_name)
+    )
+    if deprecated_plugin:
+        deprecation_warnings.append(deprecated_plugin.short_message)
+
+    deprecations = DEPRECATION_STORE.get_stored_plugin_argument_deprecations(
+        getattr(standard_plugins, plugin_name).__init__
+    )
+
+    signature = inspect.signature(getattr(standard_plugins, plugin_name).__init__)
+    for key, value in signature.parameters.items():
+        if value.default is not inspect.Parameter.empty and key not in kwargs.keys():
+            kwargs_including_defaults[key] = value.default
+
+    for deprecation in deprecations:
+        if isinstance(deprecation, DeprecatedArgument):
+            if deprecation.argument_name in kwargs_including_defaults.keys():
+                deprecation_warnings.append(deprecation.short_message)
+                warnings.warn(
+                    """Deprecated Argument: {} with value '{}' in method {} in module {}
+------------------------
+{}
+===
+{}
+""".format(
+                        deprecation.argument_name,
+                        kwargs_including_defaults[deprecation.argument_name],
+                        deprecation.method_name,
+                        getattr(deprecation.method_reference, "__module__"),
+                        deprecation.short_message,
+                        deprecation.long_message,
+                    ),
+                    FutureWarning,
+                )
+        elif isinstance(deprecation, DeprecatedArgumentCheck):
+            mapped_args: typing.Dict[str, typing.Any] = {}
+            for arg in deprecation.argument_names:
+                for name, value in kwargs_including_defaults.items():
+                    if arg == name:
+                        mapped_args[arg] = value
+                        break
+
+            result = deprecation.callback(**mapped_args)  # type: ignore
+            if result:
+                deprecation_warnings.append(result[0])
+                warnings.warn(
+                    """Deprecated Argument(s): {} with value '{}' in method {} in module {}
+------------------------
+{}
+===
+{}
+""".format(
+                        deprecation.argument_names,
+                        [
+                            value
+                            for key, value in kwargs_including_defaults.items()
+                            if key in deprecation.argument_names
+                        ],
+                        deprecation.method_name,
+                        getattr(deprecation.method_reference, "__module__"),
+                        result[0],
+                        result[1],
+                    ),
+                    FutureWarning,
+                )
+
     special_args = ""
     if "app" in argspec.args:
         special_args += "app=app, "
@@ -118,7 +194,10 @@ def _call_signature(
 
     return (
         f"{plugin_name}({special_args}**{kwargs})",
-        f"plugin_layout(contact_person={contact_person})",
+        (
+            f"plugin_layout(contact_person={contact_person}"
+            f", deprecation_warnings={deprecation_warnings})"
+        ),
     )
 
 
@@ -278,9 +357,7 @@ def clean_configuration(self) -> None:
                     )
 
                 plugin["_call_signature"] = _call_signature(
-                    plugin_name,
-                    kwargs,
-                    self._config_folder,
+                    plugin_name, kwargs, self._config_folder,
                 )
 
                 self.assets.update(getattr(standard_plugins, plugin_name).ASSETS)

webviz_config/_deprecation_store.py

@@ -0,0 +1,68 @@
+from typing import Any, List, Optional, Dict, Callable, Union
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class DeprecatedPlugin:
+    class_reference: Any
+    short_message: str
+    long_message: str
+
+
+@dataclass(frozen=True)
+class DeprecatedArgument:
+    method_reference: Any
+    method_name: str
+    argument_name: str
+    argument_value: str
+    short_message: str
+    long_message: str
+
+
+@dataclass(frozen=True)
+class DeprecatedArgumentCheck:
+    method_reference: Any
+    method_name: str
+    argument_names: List[str]
+    callback: Callable
+    callback_code: str
+
+
+class DeprecationStore:
+    def __init__(self) -> None:
+        self.stored_plugin_deprecations: Dict[Any, DeprecatedPlugin] = {}
+        self.stored_plugin_argument_deprecations: List[
+            Union[DeprecatedArgument, DeprecatedArgumentCheck]
+        ] = []
+
+    def register_deprecated_plugin(self, deprecated_plugin: DeprecatedPlugin) -> None:
+        """This function is automatically called by the decorator
+        @deprecated_plugin, registering the plugin it decorates.
+        """
+        self.stored_plugin_deprecations[
+            deprecated_plugin.class_reference
+        ] = deprecated_plugin
+
+    def register_deprecated_plugin_argument(
+        self,
+        deprecated_plugin_argument: Union[DeprecatedArgument, DeprecatedArgumentCheck],
+    ) -> None:
+        """This function is automatically called by the decorator
+        @deprecated_plugin_arguments, registering the __init__ function it decorates.
+        """
+        self.stored_plugin_argument_deprecations.append(deprecated_plugin_argument)
+
+    def get_stored_plugin_deprecation(self, plugin: Any) -> Optional[DeprecatedPlugin]:
+        return self.stored_plugin_deprecations.get(plugin)
+
+    def get_stored_plugin_argument_deprecations(
+        self, method: Callable
+    ) -> List[Union[DeprecatedArgument, DeprecatedArgumentCheck]]:
+        return [
+            stored
+            for stored in self.stored_plugin_argument_deprecations
+            if stored.method_reference == method
+        ]
+
+
+DEPRECATION_STORE = DeprecationStore()