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

pluginify/interfaces/class_based_plugin.py

@@ -4,31 +4,84 @@
 """Implements a base class for class-based plugins.
 
 The base class implemented here would expose the call signature of the child plugin
-class as `__call__()` while also providing hooks for pre- and post-processing.
+class as ``__call__()`` while also providing hooks for pre- and post-processing.
 
-The hooks are available as `_pre_call()` and `_post_call()`. They should be used to
+The hooks are available as ``_pre_call()`` and ``_post_call()``. They should be used to
 implement common functionality that all plugins of this type should posess but which we
 don't want developers to need to implement. They are intended to be overridden by the
-child plugin-type class (e.g. BaseReaderPlugin). They should define what kwargs they
+child plugin-type class (e.g. ``BaseReaderPlugin``). They should define what kwargs they
 accept when defined on the plugin-type class but should accept their arguments from
-`**kwargs` from `__call__()`.
-
-The `call()` method should be overridden on the actual plugin class. It should provide
-the data processing for the plugin. `__call__()`'s signature will be identical to that
-of `call()` except that `call()` should not accept `**kwargs`. That should be consumed
-by the hooks.
-
-`__call__()` should not be overridden anywhere.
+``**kwargs`` from ``__call__()``.
+
+The ``call()`` method should be overridden on the actual plugin class. It should provide
+the data processing for the plugin. ``__call__()``'s signature will be identical to that
+of ``call()`` except that ``call()`` should not accept ``**kwargs``. That should be
+consumed by the hooks.
+
+``__call__()`` should not be overridden anywhere.
+
+Required attributes
+-------------------
+interface : str
+    The interface type the plugin belongs to
+    (e.g. ``'configs'``, ``'data_modifiers'``).
+    This is typically provided by the interface-level plugin class and not the
+    individual plugin class.
+family : str
+    The family name of the plugin. This should be defined by the plugin class.
+name : str
+    The specific name of the plugin. This should be defined by the plugin class.
+
+Required methods
+----------------
+call()
+    The main method that performs the plugin's functionality. This method
+    should be implemented by the plugin class.
+_pre_call()
+    A hook method that can be overridden to preprocess data before
+    calling the main ``call()`` method. This method should accept the same
+    arguments as ``call()`` via ``*args`` and ``**kwargs`` and should,
+    typically, be implemented by the interface-level plugin class.
+_post_call()
+    A hook method that can be overridden to post-process data after
+    calling the main ``call()`` method. This method should accept the same
+    arguments as ``call()`` via ``*args`` and ``**kwargs`` and should,
+    typically, be implemented by the interface-level plugin class.
+
+Notes
+-----
+The purpose of ``_pre_call()`` and ``_post_call()`` is to allow for common
+functionality that all plugins of a certain type should possess, without requiring
+developers to implement this functionality in every plugin class. Initially, this
+will be used to convert inputs from DataTree to other formats and back to DataTree
+after processing, but it could be used for other common tasks as well.
 """
 
 from __future__ import annotations
+
 from abc import ABC, abstractmethod
 import functools
 import inspect
+from typing import Any
 
 
-def valid_str_attr(cls, attr_name: str):
-    """Check that the given attribute is a non-empty string."""
+def valid_str_attr(cls: type, attr_name: str) -> None:
+    """Check that the given attribute is a non-empty string.
+
+    Parameters
+    ----------
+    cls : type
+        The class whose attribute should be checked.
+    attr_name : str
+        The name of the attribute to check.
+
+    Raises
+    ------
+    TypeError
+        If the attribute is not a string.
+    ValueError
+        If the attribute is an empty string.
+    """
     attr_value = getattr(cls, attr_name, None)
     if not isinstance(attr_value, str):
         raise TypeError(f"{cls.__name__}.{attr_name} must be a string")
@@ -41,27 +94,35 @@ class BaseClassPlugin(ABC):
 
     All plugins are required to carry the following class attributes:
 
-    - interface: The interface type the plugin belongs to
-      (e.g. 'configs', 'data_modifiers').
-      This is typically provided by the interface-level plugin class and not the
-      individual plugin class.
-    - family: The family name of the plugin. This should be defined by the plugin class.
-    - name: The specific name of the plugin. This should be defined by the plugin class.
+    interface : str
+        The interface type the plugin belongs to
+        (e.g. ``'configs'``, ``'data_modifiers'``).
+        This is typically provided by the interface-level plugin class and not the
+        individual plugin class.
+    family : str
+        The family name of the plugin. This should be defined by the plugin class.
+    name : str
+        The specific name of the plugin. This should be defined by the plugin class.
 
     Subclasses of this base class must also implement the following methods:
 
-    - call(): The main method that performs the plugin's functionality. This method
-      should be implemented by the plugin class.
-    - _pre_call(): A hook method that can be overridden to preprocess data before
-      calling the main call() method. This method should accept the same arguments as
-      call() via `*args` and `**kwargs` and should, typically, be implemented by the
-      interface-level plugin class.
-    - _post_call(): A hook method that can be overridden to post-process data after
-      calling the main call() method. This method should accept the same arguments as
-      call() via `*args` and `**kwargs` and should, typically, be implemented by the
-      interface-level plugin class.
-
-    The purpose of `_pre_call()` and `_post_call()` is to allow for common
+    call()
+        The main method that performs the plugin's functionality. This method
+        should be implemented by the plugin class.
+    _pre_call()
+        A hook method that can be overridden to preprocess data before
+        calling the main ``call()`` method. This method should accept the same
+        arguments as ``call()`` via ``*args`` and ``**kwargs`` and should,
+        typically, be implemented by the interface-level plugin class.
+    _post_call()
+        A hook method that can be overridden to post-process data after
+        calling the main ``call()`` method. This method should accept the same
+        arguments as ``call()`` via ``*args`` and ``**kwargs`` and should,
+        typically, be implemented by the interface-level plugin class.
+
+    Notes
+    -----
+    The purpose of ``_pre_call()`` and ``_post_call()`` is to allow for common
     functionality that all plugins of a certain type should possess, without requiring
     developers to implement this functionality in every plugin class. Initially, this
     will be used to convert inputs from DataTree to other formats and back to DataTree
@@ -78,55 +139,100 @@ class BaseClassPlugin(ABC):
     __plugin_abstract__: bool = False
 
     def _check_interface_attribute(cls):
-        """Check the validity of the 'interface' attribute.
+        """Check that the 'interface' attribute is valid.
 
-        Checks to be sure that the interface attribute is a non-empty string and that it
-        is a known plugin interface.
+        Ensures the attribute is a non-empty string and a known plugin interface.
+
+        Parameters
+        ----------
+        cls : type
+            The class whose interface attribute should be checked.
         """
         valid_str_attr(cls, "interface")
 
     def _check_family_attribute(cls):
-        """Check the validity of the 'family' attribute."""
+        """Check that the 'family' attribute is valid.
+
+        Ensures the attribute is a non-empty string.
+
+        Parameters
+        ----------
+        cls : type
+            The class whose family attribute should be checked.
+        """
         valid_str_attr(cls, "family")
 
     def _check_name_attribute(cls):
-        """Check the validity of the 'name' attribute."""
+        """Check that the 'name' attribute is valid.
+
+        Ensures the attribute is a non-empty string.
+
+        Parameters
+        ----------
+        cls : type
+            The class whose name attribute should be checked.
+        """
         valid_str_attr(cls, "name")
 
     @abstractmethod
-    def call(self, *args, **kwargs):
-        """Callable method to be implemented by the plugin class."""
+    def call(self, *args: Any, **kwargs: Any) -> Any:
+        """Callable method to be implemented by the plugin class.
+
+        Returns
+        -------
+        Any
+            The result of the plugin's processing.
+        """
         pass
 
     # hooks are intentionally loose; document their accepted kwargs
-    def _pre_call(self, data=None, *args, **kwargs):
+    def _pre_call(self, data: Any = None, *args: Any, **kwargs: Any) -> Any:
         """Preprocess the data before calling the main plugin method.
 
         Parameters
         ----------
-        data : The input data for the plugin.
+        data : Any
+            The input data for the plugin.
 
         Returns
         -------
-        The processed data.
+        Any
+            The processed data.
         """
         return data
 
-    def _post_call(self, data=None, *args, **kwargs):
+    def _post_call(self, data: Any = None, *args: Any, **kwargs: Any) -> Any:
         """Post-process the data after calling the main plugin method.
 
         Parameters
         ----------
-        data : R
+        data : Any
             The output data from the plugin.
 
         Returns
         -------
+        Any
             The processed data.
         """
         return data
 
-    def _invoke(self, data=None, *args, **kwargs):
+    def _invoke(self, data: Any = None, *args: Any, **kwargs: Any) -> Any:
+        """Invoke the plugin's processing pipeline.
+
+        If data is provided, runs the full ``_pre_call()`` → ``call()`` →
+        ``_post_call()`` pipeline. Otherwise, delegates directly to ``call()``.
+
+        Parameters
+        ----------
+        data : Any, optional
+            The input data for the plugin. If ``None``, ``call()`` is invoked
+            directly with ``*args`` and ``**kwargs``.
+
+        Returns
+        -------
+        Any
+            The result of the plugin's processing pipeline.
+        """
         if data is None:
             data = self.call(*args, **kwargs)
         else:
@@ -135,18 +241,16 @@ class BaseClassPlugin(ABC):
             data = self._post_call(data, *args, **kwargs)
         return data
 
-    def __init__(self, module=None):
-        """
-        Initialize the plugin object inheriting from BaseClasePlugin.
+    def __init__(self, module=None) -> None:
+        """Initialize the plugin object.
 
         Parameters
         ----------
-        module: ModuleType, default=None
+        module : ModuleType, optional
             The module from which the class-based plugin originated. This is used to
             collect metadata from the module and attach it to the plugin object. The
             metadata can then be used during validation to indicate where failing
-            plugins originated. If None, the 'testing' attributes will be set to a
-            string value that can also be used in tests.
+            plugins originated. If ``None``, defaults are set.
         """
         if module:
             self.module_name = module.__name__
@@ -155,28 +259,28 @@ class BaseClassPlugin(ABC):
             self.module_name = "Unknown."
             self.module_path = "Unknown."
 
-    def __init_subclass__(cls, *, abstract=False, **kwargs) -> None:
-        """
-        Initialize a subclass of the plugin.
+    def __init_subclass__(cls, *, abstract: bool = False, **kwargs: Any) -> None:
+        """Initialize a subclass of the plugin.
 
         Parameters
         ----------
         abstract : bool, optional
-            If True, the subclass is treated as abstract. When treated as abstract,
-            validation is disabled in __init_subclass__. Defaults to False.
+            If ``True``, the subclass is treated as abstract. When treated as
+            abstract, validation is disabled in ``__init_subclass__``. Defaults to
+            ``False``.
+
+        Returns
+        -------
+        None
 
         Raises
         ------
         TypeError
             If the subclass does not define the required attributes.
         TypeError
-            If the subclass does not implement the call() method.
+            If the subclass does not implement the ``call()`` method.
         TypeError
-            If the subclass overrides the __call__() method.
-
-        Returns
-        -------
-        None
+            If the subclass overrides the ``__call__()`` method.
         """
         super().__init_subclass__(**kwargs)
 
@@ -204,8 +308,8 @@ class BaseClassPlugin(ABC):
             raise TypeError(f"{cls.__name__} must implement call()")
         call_method = cls.__dict__["call"]
 
-        @functools.wraps(call_method)  # type: ignore[arg-type]
-        def _call(self, data=None, *args, **kwargs):
+        @functools.wraps(call_method)
+        def _call(self, data: Any = None, *args: Any, **kwargs: Any) -> Any:
             return cls._invoke(self, data, *args, **kwargs)
 
         call_sig = inspect.signature(call_method)

pluginify/interfaces/yaml_based/configs.py

@@ -17,6 +17,8 @@ class ConfigsInterface(BaseYamlInterface):
     This is a 'dummy' interface which is strictly used for testing pluginify. All
     plugins of this interface are also 'dummy' plugins strictly used for testing this
     package.
+
+    Uses Pydantic model validation instead of JSON schema validation.
     """
 
     name = "configs"