pluginator 0.0.0__py3-none-any.whl

pluginator/__init__.py

@@ -0,0 +1,16 @@
+from . import define
+from .actions import Action, ActionContext
+from .pytest import (
+    CommandLine,
+    install_pytest_plugins,
+)
+from .utils import call_context
+
+__all__ = [
+    "define",
+    "Action",
+    "ActionContext",
+    "CommandLine",
+    "call_context",
+    "install_pytest_plugins",
+]

pluginator/actions.py

@@ -0,0 +1,92 @@
+import importlib
+import typing as t
+
+
+class ActionContext:
+    def update(self, **kwargs):
+        for key, value in kwargs.items():
+            if not hasattr(self, key):
+                raise AttributeError(
+                    f'Action context:{self.__class__.__name__} not contain attribute:"{key}"',
+                )
+            setattr(self, key, value)
+
+    def validate(self):
+        pass
+
+
+class Action:
+    def __init__(self, name: str, module: str, *, enable: bool = True, default_config: dict | None = None):
+        self._name = name
+        self._module = module
+        self._enable = enable
+        self._config = default_config or {}
+        self._func = None
+        self._setup = None
+
+    def __call__(self, context: ActionContext) -> t.Any:
+        if self._enable:
+            context.validate()
+            return self._func(config=self._config, context=context)
+        return None
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def enabled(self) -> bool:
+        return self._enable
+
+    @property
+    def setup(self) -> t.Callable | None:
+        return self._setup
+
+    @property
+    def config(self) -> dict | None:
+        return self._config
+
+    def configure(self, action_config: dict):
+        if self._func:
+            raise RuntimeError("Action already initialized")
+
+        self._enable = action_config.get("enable", self._enable)
+        module = action_config.get("module", self._module)
+
+        self._config = {k: action_config.get("config", {}).get(k, v) for k, v in self._config.items()}
+
+        try:
+            self._module = importlib.import_module(module)
+        except ImportError as e:
+            raise ImportError(f'Failed to import module "{module}": {e}') from e
+
+        func = getattr(self._module, "main", None)
+        if func is None:
+            raise AttributeError(f'Module "{self._module}" does not define a "main" func attribute')
+
+        if not isinstance(func, t.Callable):
+            raise TypeError(f'"{func}" should be a callable object, not {type(func)}')
+
+        self._func = func
+
+        self._setup = getattr(self._module, "setup", None)
+
+
+class ActionManager:
+    def __init__(self):
+        self._actions: dict[str, Action] = {}
+
+    def add_action(self, action: Action, plugin_config: dict | None = None) -> None:
+        if action.name in self._actions:
+            raise RuntimeError("Plugin action already exist")
+
+        action.configure(plugin_config.get("actions", {}).get(action.name, {}))
+        if action.enabled and action.setup:
+            action.setup(action.config)
+
+        self._actions[action.name] = action
+
+    def __call__(self, name: str, context: ActionContext) -> t.Any:
+        if action := self._actions.get(name):
+            return action(context)
+        raise RuntimeError(f'Plugin action "{name}" not found')

pluginator/define.py

@@ -0,0 +1,87 @@
+import typing as t
+
+from .actions import Action
+from .pytest import (
+    BasePlugin,
+    BasePluginMeta,
+    CommandLine,
+    PluginMeta,
+    PluginOption,
+)
+
+
+def plugin(
+    name: str,
+    /,
+    *,
+    config: str | None = None,
+    default_config: dict | None = None,
+    deps: list[str] | None = None,
+    actions: list[Action] | None = None,
+):
+    """
+    Decorator for creating a plugin class.
+
+    Args:
+        name: plugin name.
+        config: yaml config file path.
+        deps: list of dependencies names.
+        default_config: configuration by default.
+        actions: list of actions.
+
+    Returns:
+        Decorator function that returns new plugin class.
+    """
+
+    def wrapper(cls: type) -> type[BasePlugin]:
+        meta = PluginMeta(
+            name=name, actions=actions, config_file=config, default_config=default_config, dependencies=deps
+        )
+        bases = (cls,) if BasePlugin in cls.__mro__ else (cls, BasePlugin)
+
+        return BasePluginMeta(cls.__name__, bases, {"__meta__": meta})
+
+    return wrapper
+
+
+def option(
+    opt_type: type,
+    /,
+    *,
+    strict: bool = True,
+    nullable: bool = False,
+    required: bool = False,
+    env_var: str | None = None,
+    default_from: str | None = None,
+    plugin_config_key: str | None = None,
+    command_line: CommandLine | None = None,
+    hook: t.Callable[[t.Any], t.Any] | None = None,
+) -> PluginOption:
+    """
+    Create a plugin option.
+
+    Args:
+        opt_type: option type.
+        strict: strict type for type casting.
+        nullable: if set True value can be None
+        required: flag for required option.
+        env_var: environment variable name.
+        default_from: name of plugin class property for getting default value.
+        plugin_config_key: name of plugin config key for getting value.
+        command_line: command line object.
+        hook: hook function for prepare option value.
+
+    Returns:
+        New plugin option object.
+    """
+    return PluginOption(
+        opt_type,
+        hook=hook,
+        strict=strict,
+        env_var=env_var,
+        nullable=nullable,
+        required=required,
+        command_line=command_line,
+        default_from=default_from,
+        plugin_config_key=plugin_config_key,
+    )

pluginator/pytest.py

@@ -0,0 +1,339 @@
+import os
+import typing as t
+from copy import deepcopy
+from dataclasses import dataclass, field
+from functools import cached_property
+
+import yaml
+from _pytest.config import Config
+from _pytest.config.argparsing import OptionGroup, Parser
+from _pytest.main import Session
+from qools.funcutils import called_once
+
+from .actions import (
+    Action,
+    ActionContext,
+    ActionManager,
+)
+from .utils import call_context
+
+PLUGINATOR_OPTIONS_ATTRIBUTE = "__pluginator_options__"
+EXCLUDED_TYPES = (list, tuple, set, frozenset)
+
+
+class CommandLine:
+    """
+    Define a command line settings for pytest.
+    """
+
+    def __init__(self, opt: str, /, *args, **kwargs):
+        self.opt = opt
+
+        self.args = args
+        self.kwargs = kwargs
+
+    def register_once(self, opt_type: type, parser: Parser, *, group: OptionGroup | None = None):
+        """
+        Register the option once in pytest option parser.
+
+        Args:
+            opt_type: The type of the option.
+            parser: The option parser instance.
+            group: The option group instance.
+        """
+        pluginator_options = getattr(parser, PLUGINATOR_OPTIONS_ATTRIBUTE, [])
+
+        if self.opt not in pluginator_options:
+            if "group" in self.kwargs:
+                group = parser.getgroup(self.kwargs.pop("group"))
+
+            if (
+                "type" not in self.kwargs
+                and self.kwargs.get("action") not in ("store_true", "store_false")
+                and opt_type not in EXCLUDED_TYPES
+            ):
+                self.kwargs["type"] = opt_type
+
+            (group or parser).addoption(self.opt, *self.args, **self.kwargs)
+            pluginator_options.append(self.opt)
+
+        setattr(parser, PLUGINATOR_OPTIONS_ATTRIBUTE, pluginator_options)
+
+
+class PluginOption:
+    """
+    A plugin option.
+    """
+
+    # pylint: disable=used-before-assignment
+    def __init__(
+        self,
+        opt_type: type,
+        /,
+        *,
+        nullable: bool = False,
+        required: bool = False,
+        env_var: str | None = None,
+        default_from: str | None = None,
+        plugin_config_key: str | None = None,
+        command_line: CommandLine | None = None,
+        hook: t.Callable[[t.Any], t.Any] | None = None,
+        strict: bool = True,
+    ):
+        self._type = opt_type
+
+        self._env_var = env_var
+        self._nullable = nullable
+        self._required = required
+        self._default_from = default_from
+        self._command_line = command_line
+        self._hook = hook
+        self._plugin_config_key = plugin_config_key
+        self._strict = strict
+
+        self._name: str | None = None
+
+    @property
+    def type(self):
+        return self._type
+
+    @property
+    def command_line(self):
+        return self._command_line
+
+    def __set_name__(self, _, name: str):
+        self._name = name
+
+    def _prepare_value(self, value: t.Any) -> t.Any:
+        if callable(self._hook):
+            return self._type(self._hook(value)) if self._strict else self._hook(value)
+        return self._type(value) if self._strict else value
+
+    def __get__(self, instance: "BasePlugin", _):
+        if instance is None:
+            return self
+
+        if self._plugin_config_key is not None:
+            plugin_config_value = instance.plugin_config.get(self._plugin_config_key, object)
+
+            if plugin_config_value is not object:
+                return self._prepare_value(plugin_config_value)
+
+        if self._env_var is not None:
+            env_var_value = os.getenv(self._env_var)
+
+            if env_var_value is not None:
+                return self._prepare_value(env_var_value)
+
+        if self._command_line is not None:
+            cli_opt_value = instance.pytest_config.getoption(self._command_line.opt)
+
+            if cli_opt_value is not None:
+                return self._prepare_value(cli_opt_value)
+
+        if self._default_from is not None:
+            default_from_value = getattr(instance, self._default_from)
+
+            if default_from_value is not None:
+                return self._prepare_value(default_from_value)
+
+        if self._required:
+            raise ValueError(f'{instance.__class__}: option "{self._name}" is required')
+
+        return None if self._nullable else self._type()
+
+    def init_command_line(self, parser: Parser, *, group: OptionGroup | None = None):
+        """
+        Init command line settings for the option.
+
+        Args:
+            parser: The option parser instance.
+            group: The option group instance.
+        """
+        if self._command_line is not None:
+            self._command_line.register_once(self._type, parser, group=group)
+
+
+@dataclass
+class PluginMeta:
+    """
+    Plugin meta information.
+    """
+
+    name: str
+    actions: list[Action] = field(kw_only=True, default=None)
+    config_file: str | None = field(kw_only=True, default=None)
+    default_config: dict | None = field(kw_only=True, default=None)
+    dependencies: t.Iterable[str] | None = field(kw_only=True, default=None)
+
+
+class BasePluginMeta(type):
+    def __new__(mcs, name, bases, attrs):
+        cls = type.__new__(mcs, name, bases, attrs)
+
+        if hasattr(cls, "pytest_addoption"):
+            cls.pytest_addoption = called_once(cls.pytest_addoption)
+
+        return cls
+
+
+class BasePlugin(metaclass=BasePluginMeta):
+    """
+    Base plugin class.
+    """
+
+    __meta__: PluginMeta
+
+    def __init__(self):
+        assert hasattr(self, "__meta__"), f'meta object does not defined for "{self.__class__.__name__}"'
+
+        self.__pytest_config: Config | None = None
+        self._actions: ActionManager = ActionManager()
+
+        if self.__meta__.actions is not None:
+            for action in self.__meta__.actions:
+                self._actions.add_action(action, self.plugin_config)
+
+    def __repr__(self):
+        return f"<{self.__class__.__name__}: {self.meta.name}>"
+
+    def action(self, name: str, context: ActionContext, *, lazy: bool = False):
+        if lazy:
+
+            def wrapper(**kwargs):
+                ctx = deepcopy(context)
+                ctx.update(**kwargs)
+                return self._actions(name, ctx)
+
+            return wrapper
+        return self._actions(name, context)
+
+    @property
+    def meta(self) -> PluginMeta:
+        return self.__meta__
+
+    @property
+    def pytest_config(self) -> Config:
+        if not self.__pytest_config:
+            raise AssertionError(
+                f'Config is not initialized yet in "{self.__class__.__name__}"',
+            )
+        return self.__pytest_config
+
+    @cached_property
+    def plugin_config(self) -> dict:
+        if self.meta.config_file is None:
+            return {}
+
+        default_config = self.meta.default_config or {}
+
+        if not os.path.exists(self.meta.config_file):
+            return default_config
+
+        with open(self.meta.config_file, encoding="utf-8") as f:
+            config_data = yaml.full_load(f)
+
+            if isinstance(config_data, dict):
+                return default_config | config_data
+
+            return default_config
+
+    @property
+    def plugin_options(self) -> t.Iterable[PluginOption]:
+        for attr in dir(self.__class__):
+            value = getattr(self.__class__, attr, None)
+
+            if isinstance(value, PluginOption):
+                yield value
+
+    def init_plugin_options(self, parser: Parser) -> None:
+        group = parser.getgroup(self.meta.name)
+
+        for plugin_option in self.plugin_options:
+            plugin_option.init_command_line(parser, group=group)
+
+    def init_pytest_config(self, config: Config) -> None:
+        self.__pytest_config = config
+
+    def install(self):
+        if not self.__pytest_config:
+            raise AssertionError(
+                f'Plugin "{self.__class__.__name__}" is not ready to install, '
+                f'please call to "init_options" and "init_config" before that',
+            )
+
+        name = self.__pytest_config.pluginmanager.register(self, name=self.meta.name)
+        self.__pytest_config.add_cleanup(lambda: self.__pytest_config.pluginmanager.unregister(name=name))
+
+
+def install_pytest_plugins(
+    *plugins,
+    check_deps: bool = True,  # TODO: remove flag for new minor version
+    context: dict[str, t.Any] | None = None,
+) -> None:
+    """
+    Install pytest plugins in context.
+
+    Args:
+        plugins: The plugins to install.
+        check_deps: Check dependencies if True else no check.
+        context: The context to install plugins in.
+    """
+    context = call_context() if context is None else context
+
+    ctx_pytest_addoption = context.get("pytest_addoption", lambda parser: None)
+    ctx_pytest_configure = context.get("pytest_configure", lambda config: None)
+    ctx_pytest_collection_finish = context.get("pytest_collection_finish", lambda session: None)
+
+    failed_deps = []
+    plugin_name_to_failed_deps = {}
+
+    def pytest_addoption(parser: Parser):
+        ctx_pytest_addoption(parser)
+
+        for plugin in plugins:
+            plugin.init_plugin_options(parser)
+
+    def pytest_configure(config: Config):
+        ctx_pytest_configure(config)
+
+        for plugin in plugins:
+            plugin.init_pytest_config(config)
+            plugin.install()
+
+            configure_callback = getattr(plugin, "configure", None)
+
+            if configure_callback is not None:
+                configure_callback()
+
+    def pytest_collection_finish(session: Session):
+        ctx_pytest_collection_finish(session)
+
+        if check_deps:
+            for plugin in plugins:
+                for dep_name in plugin.__meta__.dependencies or []:
+                    if not session.config.pluginmanager.get_plugin(dep_name):
+                        failed_deps.append(dep_name)
+
+                if failed_deps:
+                    plugin_name_to_failed_deps[plugin.meta.name] = failed_deps
+
+            if plugin_name_to_failed_deps:
+                fails = plugin_name_to_failed_deps.items()
+                message = 'Plugin "{}" needs "{}" dependencies, but does not installed'
+
+                raise AssertionError(*map(lambda i: message.format(i[0], ", ".join(i[1])), fails))
+
+    context["pytest_addoption"] = pytest_addoption
+    context["pytest_configure"] = pytest_configure
+    context["pytest_collection_finish"] = pytest_collection_finish
+
+
+__all__ = [
+    "BasePlugin",
+    "PluginMeta",
+    "CommandLine",
+    "PluginOption",
+    "BasePluginMeta",
+    "install_pytest_plugins",
+]

pluginator/utils.py

@@ -0,0 +1,8 @@
+import inspect
+
+
+def call_context():
+    """
+    Returns the context of the caller.
+    """
+    return dict(inspect.getmembers(inspect.stack()[2][0]))["f_globals"]

pluginator-0.0.0.dist-info/METADATA

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: pluginator
+Version: 0.0.0
+Summary: Plugin management system
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: qools>=0.0.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-cov>=5.0; extra == "test"
+Requires-Dist: pytest-mock>=3.0; extra == "test"
+Requires-Dist: ruff>=0.15.0; extra == "test"
+Requires-Dist: pyhamcrest>=2.0; extra == "test"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.5; extra == "docs"
+Requires-Dist: mkdocs-material>=9.0; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
+
+# pluginator
+
+Plugin management system
+
+## Installation
+
+```bash
+pip install pluginator
+```
+
+## Quick Start
+
+```python
+from pluginator import define
+
+@define.plugin('my-plugin', config='config.yml')
+class MyPlugin:
+    name = define.option(str, required=True, env_var='PLUGIN_NAME')
+
+    def configure(self):
+        print(f'Configured: {self.name}')
+```
+
+## Documentation
+
+Full documentation: https://qarium.github.io/pluginator/

pluginator-0.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+pluginator/__init__.py,sha256=CMJv2uG2SZbbhyUwaFuAVtysBSxaqIc14_vo23xkQSo,298
+pluginator/actions.py,sha256=ReiEwnnLYBz-RMUc7oNS4UZ3Ck9rtqLE5ATfMXAA_00,2865
+pluginator/define.py,sha256=mweHrj9WDovj3fS_WUE9mlDB3XgMh-RsAqCj1Rpja9s,2253
+pluginator/pytest.py,sha256=4PNurKW1kL69rWohv17ksShuRFd70aGdtAUS20pAlI0,10434
+pluginator/utils.py,sha256=skuT5HKY6fSNiczD0GYbWmDJexmGQ2fsROhOgSEuYdA,164
+pluginator-0.0.0.dist-info/METADATA,sha256=UU2RZukmKNtnZz541GOn3mRQJfnrernI8kEvKPDfcjY,1424
+pluginator-0.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pluginator-0.0.0.dist-info/top_level.txt,sha256=s-5LW15-ww9J184xm1Nq3gYSg3g0-0jj0KpnZuqB4dI,11
+pluginator-0.0.0.dist-info/RECORD,,

pluginator-0.0.0.dist-info/WHEEL

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

pluginator-0.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pluginator