pluginify 0.0.0.post1.dev0__py3-none-any.whl → 0.1.0__py3-none-any.whl

pluginify/_version.py

@@ -3,5 +3,5 @@
 
 # DO NOT EDIT
 # managed by poetry-dynamic-versioning
-__version__ = "0.0.0.post1.dev0"
-__version_tuple__ = (0, 0, 0, "post1", "dev0")
+__version__ = "0.1.0"
+__version_tuple__ = (0, 1, 0)

pluginify/commandline_typer.py

@@ -56,8 +56,8 @@ def configure_logging(level=logging.INFO):
     root = logging.getLogger()
 
     # Avoid duplicate handlers if CLI is called multiple times
-    if root.handlers:
-        return
+    # if root.handlers:
+    #     return
 
     root.setLevel(level)
 
@@ -131,6 +131,10 @@ class DocstringTyper(typer.Typer):
             if doc.long_description:
                 new_doc += "\n\n" + doc.long_description
 
+            # Keep examples portion in command's help output if specified
+            if doc.examples:
+                new_doc += "\n\nExamples\n--------\n" + doc.examples[0].description
+
             func.__doc__ = new_doc
 
             new_params = []
@@ -165,10 +169,32 @@ class DocstringTyper(typer.Typer):
         return wrapper
 
 
-app = DocstringTyper(context_settings={"help_option_names": ["-h", "--help"]})
+app = DocstringTyper(
+    context_settings={"help_option_names": ["-h", "--help"]},
+    help="pluginify command line interface.",
+)
 config_app = DocstringTyper()
-
-app.add_typer(config_app, name="config", help="Configuration commands for pluginify.")
+config_set_app = DocstringTyper()
+
+config_variable_help = (
+    "NAMESPACE specifies the default namespace in which pluginify will manage "
+    "registries.\n"
+    "REGISTRY_DIRECTORY specifies the base directory where registries and their "
+    "supporting directory structure will be written.\n"
+    "REBUILD_REGISTRIES informs pluginify whether or not to rebuild registries at "
+    "runtime if a plugin cannot be located."
+)
+
+app.add_typer(
+    config_app,
+    name="config",
+    help=f"Configure pluginify.\n\n{config_variable_help}",
+)
+config_app.add_typer(
+    config_set_app,
+    name="set",
+    help=f"Set pluginify configuration variables.\n\n{config_variable_help}",
+)
 
 
 @app.command()
@@ -177,7 +203,37 @@ def create(
     packages: Optional[List[str]] = None,
     save_type: Literal["json", "yaml"] = "json",
 ):
-    """Create plugin registry files for one or more packages under a given namespace.
+    """Create plugin registries.
+
+    Plugin registries are low-level files which contain dictionaries of metadata for all
+    plugins implemented in one or more packages registered under a common namespace.
+
+    Pluginify creates and makes use of these registry files to properly load and
+    instantiate your plugins.
+
+    Examples
+    --------
+    Namespace: packageX.plugin_packages
+    Directory structure:
+
+        packageX/
+            plugins/
+            interfaces/
+            utils/
+            registered_plugins.json [will create]
+        packageY/
+            plugins/
+            registered_plugins.json [will create]
+
+    JSON registry files are faster to load and are used by default. YAML
+    extensions are also supported for easier viewing.
+
+    CLI examples
+    ------------
+    pluginify create
+    pluginify create -n packageX.plugin_packages
+    pluginify create -s yaml
+    pluginify create -n packageX.plugin_packages -p packageY
 
     Parameters
     ----------
@@ -199,7 +255,35 @@ def delete(
     namespace: str = NAMESPACE,
     packages: Optional[List[str]] = None,
 ):
-    """Delete plugin registry files for one or more packages under a given namespace.
+    """Delete plugin registries.
+
+    Plugin registries are low-level files which contain dictionaries of metadata for all
+    plugins implemented in one or more packages registered under a common namespace.
+
+    By default, this command will delete every .json and .yaml instance of registry
+    files for every package registered under a given namespace. If you only want to
+    delete registry files from a subset of packages, use the '-p' flag to specify those
+    packages.
+
+    Examples
+    --------
+    Namespace: packageX.plugin_packages
+    Directory structure:
+
+        packageX/
+            plugins/
+            interfaces/
+            utils/
+            registered_plugins.json [will delete]
+        packageY/
+            plugins/
+            registered_plugins.json [will delete]
+
+    CLI examples
+    ------------
+    pluginify delete
+    pluginify delete -n packageX.plugin_packages
+    pluginify delete -n packageX.plugin_packages -p packageY
 
     Parameters
     ----------
@@ -213,7 +297,7 @@ def delete(
     plugin_registry.delete_registries(packages=packages)
 
 
-@config_app.command("set-rebuild-registries")
+@config_set_app.command("rebuild-registries")
 def set_rebuild_registries(rebuild_registries: bool):
     """Set pluginify's REBUILD_REGISTRIES config variable.
 
@@ -226,7 +310,7 @@ def set_rebuild_registries(rebuild_registries: bool):
     update_existing_fields({"REBUILD_REGISTRIES": rebuild_registries})
 
 
-@config_app.command("set-namespace")
+@config_set_app.command("namespace")
 def set_namespace(namespace: str):
     """Set pluginify's NAMESPACE config variable.
 
@@ -239,7 +323,7 @@ def set_namespace(namespace: str):
     update_existing_fields({"NAMESPACE": namespace})
 
 
-@config_app.command("set-registry-directory")
+@config_set_app.command("registry-directory")
 def set_registry_directory(registry_directory: Path):
     """Set pluginify's REGISTRY_DIRECTORY config variable.
 

pluginify/utils/validators.py

@@ -0,0 +1,183 @@
+"""Pluginify validators module.
+
+Currently only implements a PluginRegistryValidator class.
+"""
+
+from importlib import metadata, import_module
+import json
+from pprint import pformat
+
+import pytest
+
+from pluginify.errors import PluginRegistryError
+from pluginify.plugin_registry import PluginRegistry
+
+
+class PluginRegistryValidator(PluginRegistry):
+    """Subclass of PluginRegistry which adds functionality for unit testing."""
+
+    def __init__(self, namespace, fpaths=None):
+        """Initialize TestPluginRegistry Class."""
+        self.namespace = namespace
+        super().__init__(self.namespace, _test_registry_files=fpaths)
+
+    def validate_plugin_types_exist(self, reg_dict, reg_path):
+        """Test that all top level plugin types exist in each registry file."""
+        expected_plugin_types = ["yaml_based", "class_based", "text_based"]
+        for p_type in expected_plugin_types:
+            if p_type not in reg_dict:
+                error_str = f"Expected plugin type '{p_type}' to be in the registry but"
+                error_str += f" wasn't. This was in file '{reg_path}'."
+                raise PluginRegistryError(error_str)
+
+    def validate_all_registries(self):
+        """Validate all registries in the current installation.
+
+        This should be run during testing, but not at runtime.
+        Ensure we do not fail catastrophically for a single bad plugin
+        at runtime, so test up front to test validity.
+        """
+        for reg_path in self.registry_files:
+            pkg_plugins = json.load(open(reg_path, "r"))
+            self.validate_registry(pkg_plugins, reg_path)
+
+    def validate_registry(self, current_registry, fpath):
+        """Test all plugins found in registered plugins for their validity."""
+        try:
+            self.validate_plugin_types_exist(current_registry, fpath)
+        except PluginRegistryError as e:
+            # xfail if this is a test, otherwise just raise PluginRegistryError
+            if self._is_test:
+                pytest.xfail(str(e))
+            else:
+                raise PluginRegistryError(e)
+        try:
+            self.validate_registry_interfaces(current_registry)
+        except PluginRegistryError as e:
+            # xfail if this is a test, otherwise just raise PluginRegistryError
+            if self._is_test:
+                pytest.xfail(str(e))
+            else:
+                raise PluginRegistryError(e)
+        for plugin_type in current_registry:
+            for interface in current_registry[plugin_type]:
+                for plugin in current_registry[plugin_type][interface]:
+                    try:
+                        if interface == "products":
+                            for subplg in current_registry[plugin_type][interface][
+                                plugin
+                            ]:
+                                self.validate_plugin_attrs(
+                                    plugin_type,
+                                    interface,
+                                    (plugin, subplg),
+                                    current_registry[plugin_type][interface][plugin][
+                                        subplg
+                                    ],
+                                )
+                        elif plugin_type != "text_based":
+                            self.validate_plugin_attrs(
+                                plugin_type,
+                                interface,
+                                plugin,
+                                current_registry[plugin_type][interface][plugin],
+                            )
+                    except PluginRegistryError as e:
+                        # xfail if this is a test,
+                        # otherwise just raise PluginRegistryError
+                        if self._is_test:
+                            pytest.xfail(str(e))
+                        else:
+                            raise PluginRegistryError(e)
+
+    def validate_plugin_attrs(self, plugin_type, interface, name, plugin):
+        """Test non-product plugin for all required attributes."""
+        missing = []
+        if plugin_type == "yaml_based" and interface != "products":
+            attrs = [
+                "docstring",
+                "family",
+                "interface",
+                "package",
+                "plugin_type",
+                "relpath",
+            ]
+        elif plugin_type == "yaml_based":
+            attrs = [
+                "docstring",
+                "family",
+                "interface",
+                "package",
+                "plugin_type",
+                "product_defaults",
+                "source_names",
+                "relpath",
+            ]
+        else:
+            attrs = [
+                "docstring",
+                "family",
+                "interface",
+                "package",
+                "plugin_type",
+                "signature",
+                "relpath",
+            ]
+        for attr in attrs:
+            try:
+                plugin[attr]
+            except KeyError:
+                missing.append(attr)
+        if missing:
+            raise PluginRegistryError(
+                f"Plugin '{name}' is missing the following required "
+                f"top-level properties: '{missing}'"
+            )
+
+    def validate_registry_interfaces(self, current_registry):
+        """Test Plugin Registry interfaces validity."""
+        yaml_interfaces = []
+        class_interfaces = []
+
+        # NOTE: all <pkg>/interfaces/__init__.py files MUST
+        # contain a "class_based_interfaces" list and a
+        # "yaml_based_interfaces" list - this is how we
+        # identify the valid interface names.
+        # We must avoid actually importing the interfaces within
+        # the pluginify repo - or we will end up with a circular import
+        # due to BaseInterface.
+        for pkg in metadata.entry_points(group=self.namespace):
+            try:
+                mod = import_module(f"{pkg.value}.interfaces")
+            except ModuleNotFoundError as resp:
+                if f"No module named '{pkg.value}.interfaces'" in str(resp):
+                    continue
+                else:
+                    raise ModuleNotFoundError(resp)
+            class_interfaces += mod.class_based_interfaces
+            yaml_interfaces += mod.yaml_based_interfaces
+
+        bad_interfaces = []
+        for plugin_type in ["class_based", "yaml_based"]:
+            for interface in current_registry[plugin_type]:
+                if (
+                    interface not in class_interfaces
+                    and interface not in yaml_interfaces
+                ):
+                    error_str = f"\nPlugin type '{plugin_type}' does not allow "
+                    error_str += f"interface '{interface}'.\n"
+                    error_str += "\nValid interfaces: "
+                    if plugin_type == "class_based":
+                        interface_list = class_interfaces
+                    else:
+                        interface_list = yaml_interfaces
+                    error_str += f"\n{interface_list}\n"
+                    error_str += "\nPlease update the following plugins "
+                    error_str += "to use a valid interface:\n"
+                    error_str += pformat(current_registry[plugin_type][interface])
+                    bad_interfaces.append(error_str)
+        if bad_interfaces:
+            error_str = "The following interfaces were not valid:\n"
+            for error in bad_interfaces:
+                error_str += error
+            raise PluginRegistryError(error_str)

{pluginify-0.0.0.post1.dev0.dist-info → pluginify-0.1.0.dist-info}/METADATA

@@ -1,15 +1,17 @@
 Metadata-Version: 2.4
 Name: pluginify
-Version: 0.0.0.post1.dev0
+Version: 0.1.0
 Summary: Pluginify package
 License: LICENSE
 License-File: LICENSE
 Author: Evan Rose
-Requires-Python: >=3.11.0,<3.13.0
+Requires-Python: >=3.11.0
 Classifier: License :: Other/Proprietary License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Provides-Extra: doc
 Requires-Dist: docstring_parser
 Requires-Dist: jsonschema (>4.18.0)
@@ -49,9 +51,9 @@ git clone https://github.com/NRLMMD-GEOIPS/pluginify.git
 # cd to pluginify's top level dir
 pip install -e .
 ```
-In the future:
+OR
 ```bash
-    pip install pluginify
+pip install pluginify
 ```
 
 Use pluginify

{pluginify-0.0.0.post1.dev0.dist-info → pluginify-0.1.0.dist-info}/RECORD

@@ -1,6 +1,6 @@
 pluginify/__init__.py,sha256=NvdicJtfy-dZZ8tWjR74lDBHGV6rlaH8pAJ7UHyTTog,391
-pluginify/_version.py,sha256=I_xg_zrKOMl6Y8jLXjH6TifTHdty9HEaI8c-DJniO18,237
-pluginify/commandline_typer.py,sha256=v9r7oBnD39pFLBqhoUNefGEwyRFCzDKpiPa3cvXXzCk,8676
+pluginify/_version.py,sha256=RNg2zFDCCvhcMXFL44hFlG_yi0gJFK6LnyG47hjjhqA,209
+pluginify/commandline_typer.py,sha256=g_pT1V8xwAF9KK-ndE-ydIYk2ivZYoO24PBW80CjsoM,11257
 pluginify/config.py,sha256=co4HkXsOrA68M0PlRaUAhz5KMp5pa60ssb7DwLvUuxk,4894
 pluginify/create_plugin_registries.py,sha256=9NGFRzyZIaF7Mj1BMbNLTbyRVtnZWjmwSnCL0qnra_0,48494
 pluginify/errors.py,sha256=kkdipLfxvj8f-Pp53SD3RPnD9QS3samBLlQBjBskZP8,373
@@ -15,8 +15,9 @@ pluginify/plugins/yaml/configs/stucco.yaml,sha256=OXLWzmmzxSAWs-MzSlmEa-OLGJzVJz
 pluginify/pydantic_models/v1/configs.py,sha256=As15amNtdFwAobufh0d6mDlF3mMS23ThwTKQy9q25bc,2122
 pluginify/utils/__init__.py,sha256=gdy4E4yEI9lrHbWPeBn0Bspj7iz4z6r8BAjbmHf_hpM,2088
 pluginify/utils/context_managers.py,sha256=1-bREbijNNc5PrqMIihKqxlxNaK-YZ3hj5XGpHiYmfw,926
-pluginify-0.0.0.post1.dev0.dist-info/METADATA,sha256=YoQUcPZOkt58ozii6zhO33T9-N11vPIxl-uxXl1aWsU,2086
-pluginify-0.0.0.post1.dev0.dist-info/WHEEL,sha256=Vz2fHgx6HFtSwhs8KvkHLqH5Ea4w1_rner5uNVGCeIE,88
-pluginify-0.0.0.post1.dev0.dist-info/entry_points.txt,sha256=kCm7HOEEzSnPyDpy98W-LYYmlLYyTnRqOj40UqxX6-w,111
-pluginify-0.0.0.post1.dev0.dist-info/licenses/LICENSE,sha256=sIBqTiU78gw5bC9MZMySNxzCE7DIlOcDqUWdmflkDsY,7266
-pluginify-0.0.0.post1.dev0.dist-info/RECORD,,
+pluginify/utils/validators.py,sha256=gCESprY4mZgE0KXigjsgHOipjZAg8OUF5n3-SGQ7PG4,7577
+pluginify-0.1.0.dist-info/METADATA,sha256=kfK2YM_CTB5Sy1UWrDE_QG5eMAaa5_f7BhS61QdrYGA,2153
+pluginify-0.1.0.dist-info/WHEEL,sha256=Vz2fHgx6HFtSwhs8KvkHLqH5Ea4w1_rner5uNVGCeIE,88
+pluginify-0.1.0.dist-info/entry_points.txt,sha256=kCm7HOEEzSnPyDpy98W-LYYmlLYyTnRqOj40UqxX6-w,111
+pluginify-0.1.0.dist-info/licenses/LICENSE,sha256=sIBqTiU78gw5bC9MZMySNxzCE7DIlOcDqUWdmflkDsY,7266
+pluginify-0.1.0.dist-info/RECORD,,