pluginify 1.0.0.post16.dev0__py3-none-any.whl → 1.0.0.post48.dev0__py3-none-any.whl

pluginify/plugins/classes/data_modifiers/cuboid.py

@@ -6,6 +6,8 @@
 This is a 'dummy' plugin which is strictly used for testing pluginify.
 """
 
+from typing import Any
+
 from pluginify.interfaces.class_based.data_modifiers import BaseDataModifierPlugin
 
 
@@ -19,21 +21,21 @@ class CuboidDataModifierPlugin(BaseDataModifierPlugin):
     interface = "data_modifiers"
     family = "standard"
 
-    def call(self, data, config):
+    def call(self, data: Any, config: dict) -> Any:
         """Modify the cuboid-like dataset using parameters from 'config'.
 
         Parameters
         ----------
-        data: xarray.Dataset
-            - The incoming xarray.Dataset to modify.
-        config: dict
-            - A dictionary representing the configuration plugin used to modify this
-              dataset.
+        data : Any
+            The incoming dataset to modify.
+        config : dict
+            A dictionary representing the configuration plugin used to modify this
+            dataset.
 
         Returns
         -------
-        xarray.Dataset
-            - The modified dataset based on the parameters set in 'config'.
+        Any
+            The modified dataset based on the parameters set in 'config'.
         """
         for md_key, md_val in config["spec"].items():
             data[md_key] = md_val

pluginify/pydantic_models/v1/configs.py

@@ -4,8 +4,14 @@
 """
 Pydantic model for pluginify configuration plugins.
 
-NOTE: these plugins are not intended to be used. They are just provided as an example to
-see how the plugin registry functions and for testing this package.
+These models define the schema for YAML-based configuration plugins at API version
+``pluginify/v1``. The ``ConfigPluginModel`` is the top-level model that
+``PluginRegistry.load_plugin()`` dispatches to when ``apiVersion`` is
+``pluginify/v1`` and ``interface`` is ``configs``.
+
+NOTE: these plugins are not intended for production. They are provided as a reference
+implementation to demonstrate how the Pydantic validation and plugin registry systems
+work, and to support unit tests for this package.
 """
 
 from typing import Literal, Optional, Union

pluginify/utils/__init__.py

@@ -1,30 +1,49 @@
 # # # This source code is subject to the license referenced at
 # # # https://github.com/NRLMMD-GEOIPS.
 
-"""Pluginify utility module."""
+"""Utility functions for pluginify.
+
+Provides generic helpers used throughout the package:
+
+- ``merge_nested_dicts`` — recursively merge two dictionaries while
+  preserving existing values in the destination.
+
+See Also
+--------
+pluginify.utils.validators : Plugin registry validation helpers.
+pluginify.utils.context_managers : Optional import context manager.
+"""
 
 from copy import deepcopy
 
 
-def merge_nested_dicts(dest, src, in_place=True, replace=False):
-    """Perform an in-place merge of src into dest.
+def merge_nested_dicts(
+    dest: dict, src: dict, in_place: bool = True, replace: bool = False
+) -> dict | None:
+    """Merge ``src`` into ``dest`` recursively.
 
-    Performs an in-place merge of src into dest while preserving any values that already
-    exist in dest.
+    Performs an in-place merge of ``src`` into ``dest`` while preserving any values
+    that already exist in ``dest``. If ``replace`` is ``True``, matching keys in
+    ``dest`` are overwritten by ``src`` instead.
 
     Parameters
     ----------
-    dest: dict
-        - The destination dictionary to merge to
-    src: dict
-        - The source dictionary to merge into dest
-    in_place: bool, default=True
-        - Whether or not to merge directly into dest or to create a deepcopy of dest
-          and return that as the final result. By default, this function will merge
-          directly into dest.
-    replace: boo, default=False
-        - Whether or not to override duplicate keys in src and dest with the contents of
-          src. By default, replace is set to false and overriding will not occur.
+    dest : dict
+        The destination dictionary to merge to.
+    src : dict
+        The source dictionary to merge into ``dest``.
+    in_place : bool, optional
+        Whether to merge directly into ``dest`` (``True``) or to create a deepcopy
+        of ``dest`` and return that as the result (``False``). Defaults to ``True``.
+    replace : bool, optional
+        Whether to override duplicate keys in ``dest`` with the contents of
+        ``src``. Defaults to ``False``.
+
+    Returns
+    -------
+    dict or None
+        The merged dict when ``in_place`` is ``False``, or ``None`` when
+        ``in_place`` is ``True``.
     """
     if not in_place:
         final_dest = deepcopy(dest)
@@ -49,7 +68,7 @@ def merge_nested_dicts(dest, src, in_place=True, replace=False):
     try:
         final_dest.update(src | final_dest)
     except (AttributeError, TypeError):
-        return
+        return None
     try:
         for key, val in final_dest.items():  # NOQA
             try:
@@ -60,3 +79,4 @@ def merge_nested_dicts(dest, src, in_place=True, replace=False):
         raise
     if not in_place:
         return final_dest
+    return None

pluginify/utils/context_managers.py

@@ -1,24 +1,37 @@
 # # # This source code is subject to the license referenced at
 # # # https://github.com/NRLMMD-GEOIPS.
 
-"""Module for handling optional dependencies throughout pluginify."""
+"""Context managers for handling optional dependencies throughout pluginify."""
 
 import logging
 from contextlib import contextmanager
 import traceback
+from typing import Generator
 
 LOG = logging.getLogger(__name__)
 
 
 @contextmanager
-def import_optional_dependencies(loglevel="info"):
+def import_optional_dependencies(loglevel: str = "info") -> Generator[None, None, None]:
     """Attempt to import a package and log the event if the import fails.
 
+    Use as a context manager wrapping potentially-failing imports:
+
+    .. code-block:: python
+
+        with import_optional_dependencies():
+            import some_optional_package
+
     Parameters
     ----------
-    loglevel : str
-        Name of the log level to write to. May be any valid log level (e.g. debug, info,
-        etc.).
+    loglevel : str, optional
+        Name of the log level to write to. May be any valid log level (e.g.
+        ``"debug"``, ``"info"``, etc.). Defaults to ``"info"``.
+
+    Yields
+    ------
+    None
+        Does not yield a value; the wrapped block executes in-place.
     """
     try:
         yield None
@@ -29,4 +42,3 @@ def import_optional_dependencies(loglevel="info"):
         err_str += "If you need it, install it."
 
         getattr(LOG, loglevel)(err_str)
-        # print(err_str)

pluginify/utils/validators.py

@@ -1,9 +1,11 @@
 # # # This source code is subject to the license referenced at
 # # # https://github.com/NRLMMD-GEOIPS.
 
-"""Pluginify validators module.
+"""Unit-testing support for validating plugin registry contents.
 
-Currently only implements a PluginRegistryValidator class.
+Provides the ``PluginRegistryValidator`` class, a subclass of ``PluginRegistry``
+that adds methods to verify the structural correctness of registry files and the
+plugins they contain.
 """
 
 from importlib import metadata, import_module
@@ -17,15 +19,42 @@ from pluginify.plugin_registry import PluginRegistry
 
 
 class PluginRegistryValidator(PluginRegistry):
-    """Subclass of PluginRegistry which adds functionality for unit testing."""
+    """Subclass of ``PluginRegistry`` which adds functionality for unit testing.
 
-    def __init__(self, namespace, fpaths=None):
-        """Initialize TestPluginRegistry Class."""
+    Provides methods to validate that registry files have the correct top-level
+    structure, that all required plugin attributes are present, and that
+    registered interfaces reference known interface names.
+    """
+
+    def __init__(self, namespace: str, fpaths: list[str] | None = None) -> None:
+        """Initialize a ``PluginRegistryValidator``.
+
+        Parameters
+        ----------
+        namespace : str
+            The plugin-package namespace to operate on.
+        fpaths : list of str, optional
+            Explicit list of registry file paths to use. If ``None``, registry
+            files are located automatically from the namespace.
+        """
         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."""
+    def validate_plugin_types_exist(self, reg_dict: dict, reg_path: str) -> None:
+        """Test that all top-level plugin types exist in each registry file.
+
+        Parameters
+        ----------
+        reg_dict : dict
+            The contents of a single registry file.
+        reg_path : str
+            The path to the registry file being validated.
+
+        Raises
+        ------
+        PluginRegistryError
+            If an expected plugin type is missing from the registry.
+        """
         expected_plugin_types = ["yaml_based", "class_based", "text_based"]
         for p_type in expected_plugin_types:
             if p_type not in reg_dict:
@@ -33,7 +62,7 @@ class PluginRegistryValidator(PluginRegistry):
                 error_str += f" wasn't. This was in file '{reg_path}'."
                 raise PluginRegistryError(error_str)
 
-    def validate_all_registries(self):
+    def validate_all_registries(self) -> None:
         """Validate all registries in the current installation.
 
         This should be run during testing, but not at runtime.
@@ -44,8 +73,16 @@ class PluginRegistryValidator(PluginRegistry):
             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."""
+    def validate_registry(self, current_registry: dict, fpath: str) -> None:
+        """Test all plugins found in registered plugins for their validity.
+
+        Parameters
+        ----------
+        current_registry : dict
+            The contents of a single registry file.
+        fpath : str
+            The path to the registry file being validated.
+        """
         try:
             self.validate_plugin_types_exist(current_registry, fpath)
         except PluginRegistryError as e:
@@ -93,8 +130,32 @@ class PluginRegistryValidator(PluginRegistry):
                         else:
                             raise PluginRegistryError(e)
 
-    def validate_plugin_attrs(self, plugin_type, interface, name, plugin):
-        """Test non-product plugin for all required attributes."""
+    def validate_plugin_attrs(
+        self,
+        plugin_type: str,
+        interface: str,
+        name: str | tuple[str, str],
+        plugin: dict,
+    ) -> None:
+        """Test a plugin for all required attributes.
+
+        Parameters
+        ----------
+        plugin_type : str
+            The plugin type (``"yaml_based"``, ``"class_based"``).
+        interface : str
+            The interface name (e.g. ``"configs"``, ``"products"``).
+        name : str or tuple of str
+            The plugin name. For product plugins this is a ``(source, name)``
+            tuple.
+        plugin : dict
+            The plugin metadata dictionary from the registry.
+
+        Raises
+        ------
+        PluginRegistryError
+            If the plugin is missing one or more required attributes.
+        """
         missing = []
         if plugin_type == "yaml_based" and interface != "products":
             attrs = [
@@ -137,8 +198,20 @@ class PluginRegistryValidator(PluginRegistry):
                 f"top-level properties: '{missing}'"
             )
 
-    def validate_registry_interfaces(self, current_registry):
-        """Test Plugin Registry interfaces validity."""
+    def validate_registry_interfaces(self, current_registry: dict) -> None:
+        """Validate that registry interfaces reference known interface names.
+
+        Parameters
+        ----------
+        current_registry : dict
+            The contents of a single registry file.
+
+        Raises
+        ------
+        PluginRegistryError
+            If one or more interfaces in the registry do not match a known
+            interface name from any installed package's ``interfaces/__init__.py``.
+        """
         yaml_interfaces = []
         class_interfaces = []
 

{pluginify-1.0.0.post16.dev0.dist-info → pluginify-1.0.0.post48.dev0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pluginify
-Version: 1.0.0.post16.dev0
+Version: 1.0.0.post48.dev0
 Summary: Pluginify package
 License: LICENSE
 License-File: LICENSE
@@ -14,12 +14,14 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: 3.15
 Provides-Extra: doc
+Requires-Dist: brassy (>=0.4.1) ; extra == "doc"
 Requires-Dist: docstring_parser
 Requires-Dist: jsonschema (>4.18.0)
 Requires-Dist: lexeme-type
 Requires-Dist: platformdirs
 Requires-Dist: pydantic (>=2.10.0)
 Requires-Dist: pyyaml
+Requires-Dist: rich ; extra == "doc"
 Requires-Dist: sphinxcontrib-typer ; extra == "doc"
 Requires-Dist: typer
 Project-URL: Repository, https://github.com/NRLMMD-GEOIPS/pluginify

pluginify-1.0.0.post48.dev0.dist-info/RECORD

@@ -0,0 +1,23 @@
+pluginify/__init__.py,sha256=kA6eydjcn5rZXGaRLNbPaNv9xSE_7j4LFm_fd7KPKK4,1019
+pluginify/_version.py,sha256=H9eXYFYOjedMKbny5RUj8E7M1NurC6fZ_9_TCskJa5o,239
+pluginify/commandline_typer.py,sha256=8HhuDL2lfd-fSRWDfCAkODm9r9vToXYJ8HA94Fi6HRo,11514
+pluginify/config.py,sha256=9HlYVvUD5LsbPm3uCddfjiM93a6HnWNc3ckcvciBuog,5303
+pluginify/create_plugin_registries.py,sha256=CE7s-oblRmx9I98OPVNjwzo82nXgT0ANoZOGRJ919Go,52349
+pluginify/errors.py,sha256=xOvJa9fvg1txxxnB9woBFWcGYYfQM7LmMGlkg013lZs,687
+pluginify/interfaces/__init__.py,sha256=WvZcABXn9abFARK276ObZANmMaM0o22TIz90sesKHa0,873
+pluginify/interfaces/base.py,sha256=Oy7Vbp6WlB4Pklhfk1ZQgioVlFu3VR8nP0R0r0z84Aw,29041
+pluginify/interfaces/class_based/data_modifiers.py,sha256=euPMP8cuEIyUaepn7JAmlqP3CN4W2UFrgo4EFLivo3I,1160
+pluginify/interfaces/class_based_plugin.py,sha256=cyGDNmzCqBd_csY9Z-oyI4wKma7TrBnbN8udlvesubA,11656
+pluginify/interfaces/yaml_based/configs.py,sha256=QSXQQd14-iStJVPwklE6Sc1HTHFJ2g3SEhapbP9AHss,879
+pluginify/plugin_registry.py,sha256=X-hETQD7W7jjNJaTWx8IKKEiTIUSyMMgoE5iVhENruQ,44269
+pluginify/plugins/classes/data_modifiers/cuboid.py,sha256=nVBwc_xPCLMcfeIkdmwmZF9zByZWv-Bi6XFw_X7MLAM,1218
+pluginify/plugins/yaml/configs/stucco.yaml,sha256=OXLWzmmzxSAWs-MzSlmEa-OLGJzVJzrVQZwgGPL2jqE,376
+pluginify/pydantic_models/v1/configs.py,sha256=SAA9hJOrw0qaUJppV5JQ16FpiWIPxGUMg6pPpUhKLes,2568
+pluginify/utils/__init__.py,sha256=tbEpiNRhkg3c9bUeRMpR-T977QYbeSVpBm6yGRb96Ik,2657
+pluginify/utils/context_managers.py,sha256=E75ziUTBhGz47Q4Dcikkvl1oPZhj2hwYCQK5KGuRD-U,1308
+pluginify/utils/validators.py,sha256=-s1np0qd0D9cjzLU1TkX8Hxf68UhKypux9T5Mk83Xoc,10052
+pluginify-1.0.0.post48.dev0.dist-info/METADATA,sha256=SbeYGYsj43G4ucn0qfB-623nfWz7TkVbwangHYE2tvo,2265
+pluginify-1.0.0.post48.dev0.dist-info/WHEEL,sha256=L-WvLdSBvJWHXv5zrQxDvNRnIgoBzLUpcbuiw19KCuQ,88
+pluginify-1.0.0.post48.dev0.dist-info/entry_points.txt,sha256=kCm7HOEEzSnPyDpy98W-LYYmlLYyTnRqOj40UqxX6-w,111
+pluginify-1.0.0.post48.dev0.dist-info/licenses/LICENSE,sha256=sIBqTiU78gw5bC9MZMySNxzCE7DIlOcDqUWdmflkDsY,7266
+pluginify-1.0.0.post48.dev0.dist-info/RECORD,,

pluginify-1.0.0.post16.dev0.dist-info/RECORD

@@ -1,23 +0,0 @@
-pluginify/__init__.py,sha256=NvdicJtfy-dZZ8tWjR74lDBHGV6rlaH8pAJ7UHyTTog,391
-pluginify/_version.py,sha256=imnhJ-_dm5JxhJEQNyiL-oXxluDKdxh2Iv533XHd1Ok,239
-pluginify/commandline_typer.py,sha256=i0aVQEABfS8oL6ATUmzMqgtQQLhw0nMQmYzwpPzTF8k,11361
-pluginify/config.py,sha256=ffmzSyAjPNePkSZrqinu20ZJkbmG-L4TREgRfFmPL4M,4997
-pluginify/create_plugin_registries.py,sha256=LokHQRfNPKeIYIAFaNSNhNZWxy1_fX5-N7YJ5BD4U5k,50382
-pluginify/errors.py,sha256=kkdipLfxvj8f-Pp53SD3RPnD9QS3samBLlQBjBskZP8,373
-pluginify/interfaces/__init__.py,sha256=OkhHHE8WUEh12n3VrAWfMUv2-AAz7wfy5OcEyY-KtTc,461
-pluginify/interfaces/base.py,sha256=CMgPG2NpodrECXXJbayTIVt8Vqrrxd_QADAgGM5qgUk,26749
-pluginify/interfaces/class_based/data_modifiers.py,sha256=INQCUaXWpUpRIljjhvg-ndUB_sRoMt7pzEVVEM3PeAQ,1094
-pluginify/interfaces/class_based_plugin.py,sha256=IA1bo33yior-udeaX_Cv8X8AA8syufI3rvxeMdv5hls,8431
-pluginify/interfaces/yaml_based/configs.py,sha256=3U_nKCm2mIVfA_cRl-VUmu8JrQQQ3u24eshH46a9GI0,808
-pluginify/plugin_registry.py,sha256=PB2k7g4lnONNkMPEebbgZTSH3hEYmo_9wcSvlS5aUAI,43416
-pluginify/plugins/classes/data_modifiers/cuboid.py,sha256=1pRE04bL5L5MHRHnky_hvKx2W-OkhzRLxgBPbbfMvMo,1211
-pluginify/plugins/yaml/configs/stucco.yaml,sha256=OXLWzmmzxSAWs-MzSlmEa-OLGJzVJzrVQZwgGPL2jqE,376
-pluginify/pydantic_models/v1/configs.py,sha256=KfWsIveOqPOi_J53odFFY6gFOHNYPpwQdPDqRXCfpnI,2226
-pluginify/utils/__init__.py,sha256=gdy4E4yEI9lrHbWPeBn0Bspj7iz4z6r8BAjbmHf_hpM,2088
-pluginify/utils/context_managers.py,sha256=1-bREbijNNc5PrqMIihKqxlxNaK-YZ3hj5XGpHiYmfw,926
-pluginify/utils/validators.py,sha256=ssfcUsvUlYfhWt5AjncU66KD4qDSv0N1BdR99ytvQjY,7681
-pluginify-1.0.0.post16.dev0.dist-info/METADATA,sha256=KJc6Hg4VEUOYgjeTLS2RVoGObQn5Z5a9FYe8k9Z-gCU,2179
-pluginify-1.0.0.post16.dev0.dist-info/WHEEL,sha256=L-WvLdSBvJWHXv5zrQxDvNRnIgoBzLUpcbuiw19KCuQ,88
-pluginify-1.0.0.post16.dev0.dist-info/entry_points.txt,sha256=kCm7HOEEzSnPyDpy98W-LYYmlLYyTnRqOj40UqxX6-w,111
-pluginify-1.0.0.post16.dev0.dist-info/licenses/LICENSE,sha256=sIBqTiU78gw5bC9MZMySNxzCE7DIlOcDqUWdmflkDsY,7266
-pluginify-1.0.0.post16.dev0.dist-info/RECORD,,