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

pluginify/__init__.py

@@ -1,10 +1,23 @@
 # # # This source code is subject to the license referenced at
 # # # https://github.com/NRLMMD-GEOIPS.
 
-"""Pluginify __init__ module."""
+"""Pluginify: plugin registry management for YAML and Python class plugins.
+
+This package provides the ``PluginRegistry`` class and supporting infrastructure
+for registering, retrieving, and creating plugin objects from YAML configuration
+files and Python class definitions. It exposes:
+
+- ``pluginify.interfaces`` — base classes for building custom plugin interfaces.
+- ``pluginify.utils`` — utility functions (dict merging, validators).
+
+Pluginify does not ship production plugins; it is a framework for packages that
+build plugin-based infrastructure (e.g. GeoIPS).
+
+Version information is auto-generated from git tags during build/install.
+"""
 
 # NOTE: _version.py is generated automatically during build/install
-from ._version import __version__, __version_tuple__
+from pluginify._version import __version__, __version_tuple__
 from pluginify import interfaces
 from pluginify import utils
 

pluginify/_version.py

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

pluginify/commandline_typer.py

@@ -23,7 +23,7 @@ import os
 from pathlib import Path
 from platformdirs import user_config_dir
 import sys
-from typing import List, Literal, Optional
+from typing import Any, Callable, Literal
 
 import docstring_parser
 import typer
@@ -33,7 +33,7 @@ from pluginify.config import NAMESPACE
 from pluginify.plugin_registry import PluginRegistry
 
 
-def configure_logging(level=logging.INFO):
+def configure_logging(level: int = logging.INFO) -> None:
     """Configure root logging for the command-line interface.
 
     This function attaches a StreamHandler to the root logger so that all log
@@ -71,12 +71,12 @@ def configure_logging(level=logging.INFO):
     root.addHandler(handler)
 
 
-def update_existing_fields(new_data):
+def update_existing_fields(new_data: dict) -> None:
     """Overwrite fields in pluginify's config file if they exist in 'new_data'.
 
     Parameters
     ----------
-    new_data: dict
+    new_data : dict
         A dictionary containing configuration key, value pairs to overwrite data in
         config_path.
     """
@@ -118,11 +118,11 @@ class DocstringTyper(typer.Typer):
     '--namespace' automatically generates a '-n' flag.
     """
 
-    def command(self, *args, **kwargs):
+    def command(self, *args: Any, **kwargs: Any) -> Callable:
         """Overridden typer.Typer:command decorator."""
         decorator = super().command(*args, **kwargs)
 
-        def wrapper(func):
+        def wrapper(func: Callable) -> Callable:
             """Generate help messages and shorthand aliases for all args of func."""
             sig = inspect.signature(func)
             doc = docstring_parser.parse(func.__doc__ or "")
@@ -136,7 +136,9 @@ class DocstringTyper(typer.Typer):
 
             # Keep examples portion in command's help output if specified
             if doc.examples:
-                new_doc += "\n\nExamples\n--------\n" + doc.examples[0].description
+                new_doc += "\n\nExamples\n--------\n" + (
+                    doc.examples[0].description or ""
+                )
 
             func.__doc__ = new_doc
 
@@ -164,7 +166,7 @@ class DocstringTyper(typer.Typer):
                 new_params.append(param.replace(default=option))
 
             new_sig = sig.replace(parameters=new_params)
-            func.__signature__ = new_sig
+            func.__signature__ = new_sig  # type: ignore[attr-defined]
 
             return decorator(func)
 
@@ -202,7 +204,7 @@ config_app.add_typer(
 @app.command()
 def create(
     namespace: str = NAMESPACE,
-    packages: Optional[List[str]] = None,
+    packages: list[str] | None = None,
     save_type: Literal["json", "yaml"] = "json",
 ):
     """Create plugin registries.
@@ -239,12 +241,12 @@ def create(
 
     Parameters
     ----------
-    namespace: str, default='pluginify.plugin_packages'
+    namespace : str, default='pluginify.plugin_packages'
         The namespace which plugin packages are registered under.
-    packages: Optional[List[str]], default=None
+    packages : list[str] | None, default=None
         A list of strings representing plugin packages to create registries for. If
         None, create registry files for all plugin packages found under 'namespace'.
-    save_type: Literal['json', 'yaml'], default='json'
+    save_type : Literal['json', 'yaml'], default='json'
         The file extension to save the registry files as. Defaults to 'json', 'yaml'
         can be specified as well.
     """
@@ -255,7 +257,7 @@ def create(
 @app.command()
 def delete(
     namespace: str = NAMESPACE,
-    packages: Optional[List[str]] = None,
+    packages: list[str] | None = None,
 ):
     """Delete plugin registries.
 
@@ -289,9 +291,9 @@ def delete(
 
     Parameters
     ----------
-    namespace: str, default='pluginify.plugin_packages'
+    namespace : str, default='pluginify.plugin_packages'
         The namespace which plugin packages are registered under.
-    packages: Optional[List[str]], default=None
+    packages : list[str] | None, default=None
         A list of strings representing plugin packages to create registries for. If
         None, create registry files for all plugin packages found under 'namespace'.
     """
@@ -305,7 +307,7 @@ def set_rebuild_registries(rebuild_registries: bool):
 
     Parameters
     ----------
-    rebuild_registries: bool
+    rebuild_registries : bool
         The default setting for whether or not pluginify should rebuild registries by
         default. This will persist between terminal sessions if set.
     """
@@ -318,7 +320,7 @@ def set_namespace(namespace: str):
 
     Parameters
     ----------
-    namespace: str
+    namespace : str
         The default namespace you want to pluginify to operate on. This will persist
         between terminal sessions if set.
     """
@@ -331,14 +333,14 @@ def set_registry_directory(registry_directory: Path):
 
     Parameters
     ----------
-    registry_directory: Path
+    registry_directory : Path
         The default path to the directory you want to write registry files to. This will
         persist between terminal sessions if set.
     """
     update_existing_fields({"REGISTRY_DIRECTORY": registry_directory})
 
 
-def main():
+def main() -> None:
     """Entrypoint function for pluginify's CLI."""
     configure_logging(logging.INFO)
     app()

pluginify/config.py

@@ -3,13 +3,18 @@
 
 """Module containing configuration variables needed for pluginify to run."""
 
+from __future__ import annotations
 
-def _get_env_name():
+from pathlib import Path
+from typing import Any
+
+
+def _get_env_name() -> str:
     """Determine the name of the environment that this code is being executed under.
 
     Returns
     -------
-    env_name: str
+    env_name : str
         The name of the environment which was active when this code was ran. If running
         under the base environment, return 'base_env'.
     """
@@ -35,7 +40,7 @@ def _get_env_name():
     return env_name
 
 
-def _env_to_variable(name, default):
+def _env_to_variable(name: str, default: Any) -> Any:
     """Convert an environment variable (str) to a python variable (Any).
 
     If an environment variable under 'name' has been set, convert it to a python
@@ -44,14 +49,14 @@ def _env_to_variable(name, default):
 
     Parameters
     ----------
-    name: str
+    name : str
         The name of the environment variable to convert.
-    default: Any
+    default : Any
         The default value for the environment variable named 'name'..
 
     Returns
     -------
-    converted: Any
+    converted : Any
         - The converted value of the environment variable.
     """
     # imports buried to avoid polluting this module's import namespace
@@ -72,7 +77,7 @@ def _env_to_variable(name, default):
     return default
 
 
-def _load_config_values():
+def _load_config_values() -> tuple[str, bool, Path]:
     """Load and override pluginify configuration variables if they exist.
 
     The configuration file for this package is expected to be found at
@@ -120,26 +125,28 @@ def _load_config_values():
     return NAMESPACE, REBUILD_REGISTRIES, REGISTRY_DIRECTORY
 
 
+# These module-level variables are resolved at import time from env vars,
+# config file (~/.config/pluginify/config.yaml), and built-in defaults.
 NAMESPACE, REBUILD_REGISTRIES, REGISTRY_DIRECTORY = _load_config_values()
 
 
-def get_registry_cache_dir(namespace, package):
+def get_registry_cache_dir(namespace: str, package: str) -> Path:
     """Return the path to the parent directory of where to write registry files to.
 
     Where the path is formatted '~/.cache/{env_name}/{namespace}/{package}'.
 
     Parameters
     ----------
-    namespace: str
+    namespace : str
         Namespace that your plugin packages fall under. The argument parser defaults
         this value to 'pluginify.plugin_packages', but a user can create separate
         namespaces if developing interfaces outside of pluginify.
-    package: str
+    package : str
         Name of a plugin package that is registered under 'namespace'.
 
     Returns
     -------
-    cache_dir: Path
+    cache_dir : Path
         Full path to the parent directory in which registry files should be written
         for a package under namespace.
     """