Adjusted according to review comments

Author: rubenthoms

.pylintrc

@@ -14,6 +14,3 @@ min-public-methods = 1
 good-names = i,
              df,
              _
-             
-[TYPECHECK]
-signature-mutators=deprecated_plugin_arguments

CONTRIBUTING.md

@@ -12,7 +12,6 @@
   - [OAuth 2.0 Authorization Code flow](#oauth-2.0-authorization-code-flow)
 - [Run tests](#run-tests)
 - [Build documentation](#build-documentation)
-- [Deprecate plugins or arguments](#deprecate-plugins-or-arguments)
 
 ## Creating a new plugin
 
@@ -644,7 +643,7 @@ Example of auto-built documentation for `webviz-config` can be seen
 Plugins can be marked as deprecated by using the `@deprecated_plugin(short_message, long_message)` decorator.
 
 ```python
-from ..webviz_deprecated import deprecated_plugin
+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.")
@@ -653,27 +652,37 @@ 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 (MyPluginExample1) or their values can be checked within a function (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.
+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_deprecated import deprecated_plugin_arguments
+from webviz_config.webviz_deprecated import deprecated_plugin_arguments
 
 
 class MyPluginExample1(WebvizPluginABC):
     ...
-    @deprecated_plugin_arguments(check={"arg3": ("This message is shown to the end user in the app.", "This message is shown in the documentation of the plugin.")})
+    @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=check_deprecation)
+    @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
 ```

examples/basic_example.yaml

@@ -21,7 +21,7 @@ pages:
  - title: Table example
    content:
     - DataTable:
-        csv_file: /home/ruben/repos/webviz-config/examples/example_data.csv
+        csv_file: ./example_data.csv
 
  - title: PDF example
    content:

setup.py

@@ -77,7 +77,6 @@ def get_long_description() -> str:
         "cryptography>=2.4",
         "dash>=1.16",
         "dash-pivottable>=0.0.2",
-        "decorator>=5.0.6",
         "flask-caching>=1.4",
         "flask-talisman>=0.6",
         "jinja2>=2.10",
@@ -87,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

@@ -11,9 +11,9 @@
 from .utils import terminal_colors
 from .utils._get_webviz_plugins import _get_webviz_plugins
 from ._deprecation_store import (
-    deprecation_store,
+    DEPRECATION_STORE,
     DeprecatedArgument,
-    DeprecatedArgumentCheck
+    DeprecatedArgumentCheck,
 )
 
 SPECIAL_ARGS = ["self", "app", "webviz_settings", "_call_signature"]
@@ -25,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).
@@ -119,13 +119,13 @@ def _call_signature(
     kwargs_including_defaults = kwargs
     deprecation_warnings = []
 
-    deprecated_plugin = deprecation_store().get_stored_plugin_deprecation(
+    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(
+    deprecations = DEPRECATION_STORE.get_stored_plugin_argument_deprecations(
         getattr(standard_plugins, plugin_name).__init__
     )
 
@@ -139,21 +139,21 @@ def _call_signature(
             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 {}
+                    """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,
-                ),
-                DeprecationWarning,
-            )
+                        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:
@@ -166,23 +166,24 @@ def _call_signature(
             if result:
                 deprecation_warnings.append(result[0])
                 warnings.warn(
-                """Deprecated Argument(s): {} with value '{}' in method {} in module {}
+                    """Deprecated Argument(s): {} with value '{}' in method {} in module {}
 ------------------------
 {}
 ===
 {}
 """.format(
                         deprecation.argument_names,
                         [
-                            value for key, value in kwargs_including_defaults.items()
+                            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],
                     ),
-                    DeprecationWarning,
+                    FutureWarning,
                 )
 
     special_args = ""
@@ -356,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

@@ -2,13 +2,14 @@
 from dataclasses import dataclass
 
 
-@dataclass(eq=True, frozen=True)
+@dataclass(frozen=True)
 class DeprecatedPlugin:
     class_reference: Any
     short_message: str
     long_message: str
 
-@dataclass(eq=True, frozen=True)
+
+@dataclass(frozen=True)
 class DeprecatedArgument:
     method_reference: Any
     method_name: str
@@ -17,7 +18,8 @@ class DeprecatedArgument:
     short_message: str
     long_message: str
 
-@dataclass(eq=True, frozen=True)
+
+@dataclass(frozen=True)
 class DeprecatedArgumentCheck:
     method_reference: Any
     method_name: str
@@ -42,29 +44,25 @@ def register_deprecated_plugin(self, deprecated_plugin: DeprecatedPlugin) -> Non
         ] = deprecated_plugin
 
     def register_deprecated_plugin_argument(
-        self, deprecated_plugin_argument: Union[DeprecatedArgument, DeprecatedArgumentCheck]
+        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]:
-        if plugin in self.stored_plugin_deprecations:
-            return self.stored_plugin_deprecations[plugin]
-        return None
+        return self.stored_plugin_deprecations.get(plugin)
 
     def get_stored_plugin_argument_deprecations(
         self, method: Callable
     ) -> List[Union[DeprecatedArgument, DeprecatedArgumentCheck]]:
-        deprecations: List[Union[DeprecatedArgument, DeprecatedArgumentCheck]] = []
-        for stored in self.stored_plugin_argument_deprecations:
-            if stored.method_reference == method:
-                deprecations.append(stored)
-
-        return deprecations
+        return [
+            stored
+            for stored in self.stored_plugin_argument_deprecations
+            if stored.method_reference == method
+        ]
 
-def deprecation_store() -> DeprecationStore:
-    return DEPRECATION_STORE
 
 DEPRECATION_STORE = DeprecationStore()

webviz_config/_docs/_build_docs.py

@@ -33,7 +33,11 @@
 import webviz_config.plugins
 from .._config_parser import SPECIAL_ARGS
 from ..utils._get_webviz_plugins import _get_webviz_plugins
-from .._deprecation_store import DEPRECATION_STORE, DeprecatedArgument, DeprecatedArgumentCheck
+from .._deprecation_store import (
+    DEPRECATION_STORE,
+    DeprecatedArgument,
+    DeprecatedArgumentCheck,
+)
 
 
 class ArgInfo(TypedDict, total=False):
@@ -77,7 +81,10 @@ def _find_plugin_deprecated_arguments(plugin: Any) -> Dict[str, Tuple[str, str]]
     # Completely deprecated arguments have priority over deprecation check functions
     for deprecated_argument in deprecated_arguments:
         if isinstance(deprecated_argument, DeprecatedArgument):
-            result[deprecated_argument.argument_name] = (deprecated_argument.long_message, "")
+            result[deprecated_argument.argument_name] = (
+                deprecated_argument.long_message,
+                "",
+            )
     return result
 
 
@@ -122,10 +129,7 @@ def _extract_init_arguments_and_check_for_deprecation(
             result[arg]["typehint_string"] = _annotation_to_string(annotation)
 
     for arg, arg_info in result.items():
-        if arg in documented_args:
-            arg_info["description"] = " ".join(documented_args[arg].split())
-        else:
-            arg_info["description"] = ""
+        arg_info["description"] = " ".join(documented_args.get(arg, "").split())
 
         if arg in deprecated_arguments:
             arg_info["deprecated"] = True
@@ -152,7 +156,7 @@ def _document_plugin(plugin: Tuple[str, Any]) -> PluginInfo:
     (
         has_deprecated_arguments,
         arguments,
-        deprecation_check_code
+        deprecation_check_code,
     ) = _extract_init_arguments_and_check_for_deprecation(
         docstring_parts[1] if len(docstring_parts) > 1 else None, reference
     )
@@ -167,13 +171,13 @@ def _document_plugin(plugin: Tuple[str, Any]) -> PluginInfo:
         "description": docstring_parts[0] if docstring != "" else None,
         "name": name,
         "package_doc": import_module(subpackage).__doc__,  # type: ignore
-        "dist_name": webviz_config.plugins.metadata[name]["dist_name"],
-        "dist_version": webviz_config.plugins.metadata[name]["dist_version"],
+        "dist_name": webviz_config.plugins.METADATA[name]["dist_name"],
+        "dist_version": webviz_config.plugins.METADATA[name]["dist_version"],
         "deprecated": deprecated is not None,
         "deprecation_text_short": deprecated.short_message if deprecated else "",
         "deprecation_text_long": deprecated.long_message if deprecated else "",
         "has_deprecated_arguments": has_deprecated_arguments,
-        "deprecation_check_code": deprecation_check_code
+        "deprecation_check_code": deprecation_check_code,
     }
 
     return plugin_info

webviz_config/_docs/_create_schema.py

@@ -24,11 +24,7 @@
                     "content": {
                         "description": "Content on the page",
                         "type": "array",
-                        "items": {
-                            "oneOf": [
-                                {"type": "string"},
-                            ]
-                        },
+                        "items": {"oneOf": [{"type": "string"},]},
                     },
                 },
                 "required": ["title", "content"],

webviz_config/_docs/open_docs.py

@@ -27,9 +27,7 @@ def _index() -> str:
     webviz_config.utils.LocalhostOpenBrowser(port, token)
 
     app.run(
-        host="localhost",
-        port=port,
-        debug=False,
+        host="localhost", port=port, debug=False,
     )