SSPM 1.0.0__py3-none-any.whl

sspm/__init__.py

@@ -0,0 +1,5 @@
+from .plugin import Plugin
+from .plugin_base import PluginBase
+from .pluginmanager import PluginManager
+
+__all__ = ["PluginManager", "Plugin", "PluginBase"]

sspm/plugin.py

@@ -0,0 +1,110 @@
+from configparser import ConfigParser
+
+from packaging.version import Version
+
+# Defaults used for any [Documentation] field a plugin's info file doesn't specify.
+_DOCUMENTATION_DEFAULTS = {
+    "Author": "Unknown",
+    "Version": "0.0",
+    "Website": "None",
+    "Copyright": "Unknown",
+    "Description": "",
+}
+
+
+class Plugin:
+    """
+    Represents a single plugin: the metadata parsed from its info file (name, version, author,
+    copyright, website, description) plus, once PluginManager has instantiated it, the
+    plugin_object itself.
+
+    Metadata is backed by a configparser.ConfigParser (see `details`). Values are read with a
+    fallback, so a plugin's info file only needs to specify what it wants to override -- the
+    fallback values themselves are never written back into `details`, so `details` reflects
+    only what was actually parsed from the info file (plus whatever `name`/`path`/etc. setters
+    have explicitly been called with).
+    """
+
+    def __init__(self, plugin_name, plugin_path):
+        # Used as the fallback for name/path if `details` doesn't specify Core/Name or
+        # Core/Module -- see __read().
+        self.__default_name = plugin_name
+        self.__default_path = plugin_path
+        self.__details = ConfigParser()
+
+        # Set by PluginManager once the plugin's module class has been instantiated; None until then.
+        self.plugin_object = None
+
+    def __read(self, section: str, option: str, default: str) -> str:
+        return self.__details.get(section, option, fallback=default)
+
+    def __write(self, section: str, option: str, value: str) -> None:
+        if not self.__details.has_section(section):
+            self.__details.add_section(section)
+        self.__details.set(section, option, value)
+
+    @property
+    def details(self) -> ConfigParser:
+        return self.__details
+
+    @details.setter
+    def details(self, config_details: ConfigParser) -> None:
+        self.__details = config_details
+
+    @property
+    def name(self):
+        return self.__read("Core", "Name", self.__default_name)
+
+    @name.setter
+    def name(self, name):
+        self.__write("Core", "Name", name)
+
+    @property
+    def path(self):
+        return self.__read("Core", "Module", self.__default_path)
+
+    @path.setter
+    def path(self, path):
+        self.__write("Core", "Module", path)
+
+    @property
+    def version(self):
+        return Version(self.__read("Documentation", "Version", _DOCUMENTATION_DEFAULTS["Version"]))
+
+    @version.setter
+    def version(self, ver):
+        if isinstance(ver, Version):
+            ver = str(ver)
+        self.__write("Documentation", "Version", ver)
+
+    @property
+    def author(self):
+        return self.__read("Documentation", "Author", _DOCUMENTATION_DEFAULTS["Author"])
+
+    @author.setter
+    def author(self, author):
+        self.__write("Documentation", "Author", author)
+
+    @property
+    def copyright(self):
+        return self.__read("Documentation", "Copyright", _DOCUMENTATION_DEFAULTS["Copyright"])
+
+    @copyright.setter
+    def copyright(self, copyright):
+        self.__write("Documentation", "Copyright", copyright)
+
+    @property
+    def website(self):
+        return self.__read("Documentation", "Website", _DOCUMENTATION_DEFAULTS["Website"])
+
+    @website.setter
+    def website(self, website):
+        self.__write("Documentation", "Website", website)
+
+    @property
+    def description(self):
+        return self.__read("Documentation", "Description", _DOCUMENTATION_DEFAULTS["Description"])
+
+    @description.setter
+    def description(self, description):
+        self.__write("Documentation", "Description", description)

sspm/plugin_base.py

@@ -0,0 +1,6 @@
+class PluginBase:
+    """
+    Marker base class for plugins. Subclass this (directly or via your own intermediate base class,
+    e.g. to define a plugin category) so PluginManager can find and categorize your plugin.
+    """
+    pass

sspm/pluginmanager.py

@@ -0,0 +1,193 @@
+import importlib.util
+import inspect
+import logging
+import pathlib
+import sys
+import threading
+from configparser import ConfigParser
+
+from .plugin import Plugin
+
+
+class PluginManager:
+    """
+    A basic python plugin manager. Plugins live one per subdirectory of a user-specified plugin
+    folder, each with a Python module and an info file (see plugin.py) describing it.
+
+    Safe to use from multiple threads: all reads and mutations of the manager's internal plugin
+    state (import_plugins, rescan, remove_plugin, get_active_plugin, active_plugins,
+    categorized_plugins) are serialized with an internal lock, and active_plugins/
+    categorized_plugins return snapshots rather than live references, so a caller iterating one
+    won't be affected by a concurrent import_plugins()/rescan()/remove_plugin() call.
+    """
+
+    def __init__(self, plugin_folder: str, plugin_info_ext="info", log=logging):
+        """
+        This is the initialization method. User must set the plugin folder location. They can also set their own
+        logging should they have their own.
+        :param plugin_folder: Base dir for plugins.
+        :param plugin_info_ext: Allows user to define a custom extension for their plugin info files.
+        :param log: Python logging.
+        """
+        self.__logging = log
+        self.__plugin_folder = pathlib.Path(plugin_folder)
+        self.__plugin_config_ext = plugin_info_ext
+        self.__imported_plugins = dict()
+        self.__categorized_plugins = dict()
+        self.__lock = threading.Lock()
+
+    # Follows the recipe in the Python docs for importing a source file directly:
+    # https://docs.python.org/3/library/importlib.html#importing-a-source-file-directly
+    # This is a better and more flexible solution than the python path modification. This also allows for
+    # subdirectories within the provided plugin directory.
+    def __load_plugin_src(self, name: str, plugin_path: str):
+        """
+        Import a Python source file and return the loaded module.
+
+        :param name: The name for the loaded module. It may contain `.` and even characters
+            that would normally not be allowed (e.g., `-`).
+        :param plugin_path: The full path to the source file. It may contain characters like
+            `.` or `-`.
+        :return: The imported module.
+        :raises ImportError: If the file cannot be imported (e.g., if it's not a `.py` file or
+            if it does not exist).
+        :raises Exception: Any exception that is raised while executing the module (e.g., a
+            `SyntaxError`). These are errors made by the author of the module!
+        """
+        spec = importlib.util.spec_from_file_location(name, plugin_path)
+        if spec is None:
+            raise ImportError(f"Could not load spec for module '{name}' at: {plugin_path}")
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[name] = module
+        try:
+            spec.loader.exec_module(module)
+        except FileNotFoundError as e:
+            raise ImportError(f"{e.strerror}: {plugin_path}") from e
+        return module
+
+    def __import_plugin_info(self, plugin_info_path: pathlib.Path) -> None:
+        """
+        Loads a single plugin from its info file and, if successful, registers it. Shared by
+        import_plugins() and rescan(); callers are expected to hold self.__lock.
+        """
+        config_parser = ConfigParser()
+        config_parser.read(plugin_info_path)
+        try:
+            if config_parser.get("Core", "Module"):
+                module_name = config_parser.get("Core", "Module")
+                module_parent_dir = plugin_info_path.parent
+                module_path = module_parent_dir.joinpath(f"{module_name}.py").resolve().as_posix()
+                importlib.invalidate_caches()
+                module = self.__load_plugin_src(module_name, module_path)
+                if module:
+                    if config_parser.get("Core", "Name"):
+                        plugin = Plugin(config_parser.get("Core", "Name"), module_path)
+                        plugin.details = config_parser
+
+                        cls_names = [m[0] for m in inspect.getmembers(module, inspect.isclass) if
+                                     m[1].__module__ == module.__name__]
+
+                        cls_name = [cls for cls in cls_names
+                                    if "PluginBase" in [x.__name__ for x in type.mro(getattr(module, cls))]]
+
+                        if cls_name.__len__() != 1:
+                            self.__logging.error(
+                                f"Illegal action: expected exactly one plugin class in module. "
+                                f"The plugin file: {module_name} contains {len(cls_name)} plugin classes.")
+                            return
+
+                        _cls = getattr(module, cls_name[0])
+                        plugin.plugin_object = _cls()
+
+                        self.__imported_plugins[plugin.name] = plugin
+                        self.__categorize_plugin(plugin)
+
+                        self.__logging.info(f"{plugin.name} imported successfully.")
+                else:
+                    self.__logging.warning(f"Missing Module for Plugin: {plugin_info_path.absolute().as_posix()}")
+            else:
+                raise ValueError("Plugin Config file is missing necessary parameters.")
+        except ModuleNotFoundError:
+            self.__logging.warning(f"Missing Module for Plugin: {plugin_info_path.absolute().as_posix()}")
+
+    def import_plugins(self) -> None:
+        """
+        Imports all plugins in the user-defined plugin directory. Each subdirectory containing a matching
+        plugin info file is expected to hold exactly one module defining exactly one PluginBase subclass;
+        plugins that don't meet that contract, or whose module can't be found, are skipped and logged
+        rather than raised.
+
+        Every matching plugin is (re)imported and its plugin_object (re)instantiated, even ones
+        already active from a previous call -- to pick up only newly-added plugins without
+        disturbing already-loaded ones, use rescan() instead.
+        """
+        with self.__lock:
+            for plugin_info_path in pathlib.Path(self.__plugin_folder).glob(f"**/*.{self.__plugin_config_ext}"):
+                self.__import_plugin_info(plugin_info_path)
+
+    def rescan(self) -> None:
+        """
+        Scans the plugin directory for plugins that aren't already active and imports those,
+        leaving already-active plugins (matched by the Name in their info file) untouched -- their
+        existing plugin_object is not re-instantiated or replaced. Use this to pick up plugins
+        dropped into the plugin directory after the initial import_plugins() call, while the
+        process is still running.
+        """
+        with self.__lock:
+            for plugin_info_path in pathlib.Path(self.__plugin_folder).glob(f"**/*.{self.__plugin_config_ext}"):
+                config_parser = ConfigParser()
+                config_parser.read(plugin_info_path)
+                name = config_parser.get("Core", "Name", fallback=None)
+                if name is not None and name in self.__imported_plugins:
+                    continue
+                self.__import_plugin_info(plugin_info_path)
+
+    def __categorize_plugin(self, plugin) -> None:
+        """
+        Indexes a plugin under the name of each base class its plugin_object directly subclasses, so it can
+        later be looked up by category via categorized_plugins. Callers are expected to hold self.__lock.
+        :param plugin: The Plugin to index.
+        """
+        plugin_types = [x.__name__ for x in type(plugin.plugin_object).__bases__]
+
+        for plugin_type in plugin_types:
+            if plugin_type not in self.__categorized_plugins:
+                self.__categorized_plugins[plugin_type] = {plugin.name: plugin}
+            else:
+                plugins_store = self.__categorized_plugins.get(plugin_type)
+                plugins_store[plugin.name] = plugin
+
+    def get_active_plugin(self, plugin_name: str) -> Plugin:
+        """
+        Retrieves a plugin from the active plugins.
+        :param plugin_name: User defined name of plugin from plugin info file
+        :return: The matching Plugin, or None if no plugin with that name is active.
+        """
+        with self.__lock:
+            return self.__imported_plugins.get(plugin_name)
+
+    def remove_plugin(self, plugin_name) -> None:
+        """
+        Removes a loaded plugin.
+        :param plugin_name: the name of the plugin to be removed
+        :return: None
+        :raises KeyError: if no plugin with that name is currently active.
+        """
+        with self.__lock:
+            del self.__imported_plugins[plugin_name]
+            self.__logging.info(f"{plugin_name} removed successfully.")
+
+    @property
+    def active_plugins(self):
+        """A snapshot dict of all successfully imported plugins, keyed by plugin name."""
+        with self.__lock:
+            return dict(self.__imported_plugins)
+
+    @property
+    def categorized_plugins(self):
+        """
+        A snapshot dict mapping each PluginBase subclass name to a dict of the plugins (keyed by
+        plugin name) whose plugin_object directly subclasses it.
+        """
+        with self.__lock:
+            return {plugin_type: dict(plugins) for plugin_type, plugins in self.__categorized_plugins.items()}

sspm/version.py

@@ -0,0 +1,27 @@
+import sys
+from collections import namedtuple
+
+_SSPM_VERSION_CLS = namedtuple("_SSPM_VERSION_CLS", "major minor bugfix pre post dev")
+
+version_tuple = _SSPM_VERSION_CLS(1, 0, 0, None, None, None)
+
+version = "{0.major:d}.{0.minor:d}.{0.bugfix:d}".format(version_tuple)
+if version_tuple.pre is not None:
+    version += version_tuple.pre
+if version_tuple.post is not None:
+    version += ".post{0.post:d}".format(version_tuple)
+if version_tuple.dev is not None:
+    version += ".dev{0.dev:d}".format(version_tuple)
+
+info = """\
+Summary of the SSPM configuration
+---------------------------------
+
+SSPM    %(sspm)s
+Python  %(python)s
+Platform    %(platform)s
+""" % {
+    'sspm': version,
+    'python': sys.version,
+    'platform': sys.platform,
+}

sspm-1.0.0.dist-info/METADATA

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: SSPM
+Version: 1.0.0
+Summary: SSPM: a simple, hands-off Python plugin manager
+Author-email: Steven Nix <stevencnix@gmail.com>
+License: PolyForm-Noncommercial-1.0.0
+Project-URL: Homepage, https://github.com/stevencnix/sspm
+Project-URL: Repository, https://github.com/stevencnix/sspm
+Project-URL: Changelog, https://github.com/stevencnix/sspm/blob/develop/CHANGELOG
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: packaging
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# Super Simple Plugin Manager - SSPM
+
+## About SSPM
+
+Super Simple Plugin Manager - SSPM is a lightweight, hands-off Python plugin manager. Drop a
+plugin's code and a small `.info` file describing it into a plugins directory, and SSPM discovers,
+imports, categorizes, and instantiates it for you — no extra registration step needed.
+
+## Requirements
+
+- Python 3.10+
+- [packaging](https://pypi.org/project/packaging/) (installed automatically as a dependency)
+
+## Installation
+
+The easiest way to install is to use pip:
+
+    pip install SSPM
+
+or if you have cloned the repo:
+
+    cd <path to repo>
+    pip install .
+
+## Writing a Plugin
+
+A plugin is a folder containing two files: a Python module with your plugin's code, and an `.info` file
+(a standard `configparser`/INI file) describing it. Each module must define **exactly one** class that
+subclasses `PluginBase` (or a subclass of it) — SSPM uses that to find and categorize your plugin.
+
+```
+plugins/
+└── add_plugin/
+    ├── add_plugin.py
+    └── add.info
+```
+
+`add_plugin.py`:
+
+```python
+from sspm import PluginBase
+
+
+class AddPlugin(PluginBase):
+
+    def operation(self, x, y):
+        return x + y
+```
+
+`add.info`:
+
+```ini
+[Core]
+Name = Add Plugin
+Module = add_plugin
+
+[Documentation]
+Author = Your Name
+Version = 1.0.0
+Website = None
+Description = Plugin performing basic add operation
+```
+
+`Core.Name` and `Core.Module` are required (`Module` is the module filename, without the `.py`
+extension). Everything under `[Documentation]` is optional — SSPM fills in sensible defaults
+(`Unknown`, `0.0`, etc.) for anything you leave out.
+
+You can subclass `PluginBase` further to create your own plugin categories (e.g. a
+`CalculatorPluginBase`) and group related plugins together — see
+[`examples/`](examples) for a full working example with multiple plugin types.
+
+## Basic Usage
+
+1. Initialize the plugin manager, pointing it at the folder containing your plugins:
+
+    ```python
+    from sspm import PluginManager
+
+    plugin_manager = PluginManager(plugin_folder="./plugins")
+    ```
+
+2. Import the plugins in the plugins directory:
+
+    ```python
+    plugin_manager.import_plugins()
+    ```
+
+3. Get a specific imported plugin by the name from its `.info` file:
+
+    ```python
+    plugin = plugin_manager.get_active_plugin("Add Plugin")
+    result = plugin.plugin_object.operation(1, 2)
+    ```
+
+    or get all active plugins:
+
+    ```python
+    plugins = plugin_manager.active_plugins
+    ```
+
+    or get plugins grouped by their `PluginBase` category:
+
+    ```python
+    calculator_plugins = plugin_manager.categorized_plugins.get("CalculatorPluginBase")
+    ```
+
+A `Plugin` object exposes the metadata from its `.info` file (`name`, `version`, `author`,
+`website`, `copyright`, `description`) as well as `plugin_object`, the instantiated plugin class
+itself.
+
+## Runtime Plugins
+
+`PluginManager` is meant to be used for plugins that come and go while your process is running,
+not just a one-time scan at startup:
+
+- **Adding a plugin after startup**: drop a new plugin's folder into the plugin directory, then
+  call `plugin_manager.rescan()`. Unlike `import_plugins()`, `rescan()` only loads plugins that
+  aren't already active — it won't re-instantiate or replace a plugin that's already loaded.
+- **Removing a plugin**: `plugin_manager.remove_plugin("Plugin Name")` (raises `KeyError` if no
+  plugin with that name is active).
+- **Thread safety**: `PluginManager` is safe to use from multiple threads. All reads and writes go
+  through an internal lock, and `active_plugins`/`categorized_plugins` return a snapshot rather
+  than a live reference, so code iterating one of them won't be affected by a concurrent
+  `import_plugins()`, `rescan()`, or `remove_plugin()` call on another thread.
+
+## More Examples
+
+See the [`examples/`](examples) directory for a runnable calculator example with `Add` and
+`Subtract` plugins, and [`CHANGELOG`](CHANGELOG) for release history.
+
+## License
+
+SSPM is licensed under the [PolyForm Noncommercial License 1.0.0](LICENSE) — free to use, modify,
+and distribute for any noncommercial purpose. Commercial use requires a separate license from the
+author.

sspm-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+sspm/__init__.py,sha256=UFO8Z4la54nrwuULkcNcbylwfOIfwIAxvhNPatlpiKI,157
+sspm/plugin.py,sha256=_lewbtSt3zFMmswXmADMApdm1Ep3SucJ-zKlawLLqY0,3654
+sspm/plugin_base.py,sha256=5fcXZkhIFm9TLnLsdiD2C_lykeB0B6GvBqrDsQ_tIfQ,235
+sspm/pluginmanager.py,sha256=eQQjVW6Fw4puC0Gur24ggrpkrlWQB-vxoouWIQACHOo,9440
+sspm/version.py,sha256=U0uwb3JvG1jJIXdCHkdc1Ue6wYSbF_obwNVRfdUP-HU,743
+sspm-1.0.0.dist-info/licenses/LICENSE,sha256=YAVWzDDyrpBjlrKa69ZGW6HUyVChzZawY2T7b-6RdVU,4639
+sspm-1.0.0.dist-info/METADATA,sha256=QQV0HkfVBDd63xYNSJ_tO5i8pQmIPPyIB-vDAeLAC0A,5109
+sspm-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+sspm-1.0.0.dist-info/top_level.txt,sha256=x80ciy1FOK_VHkApkgYSVIkkw9jF288FnVL6fDrL4q8,5
+sspm-1.0.0.dist-info/RECORD,,

sspm-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sspm-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,75 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+Required Notice: Copyright Steven Nix (https://github.com/stevencnix/sspm)
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

sspm-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sspm