pyplugy 0.1.0__py3-none-any.whl

pyplugy/__init__.py

@@ -0,0 +1,56 @@
+"""pyPlugy — plugin framework with hooks (pyHooky) and tasks (pyWorkflowy)."""
+
+from __future__ import annotations
+
+from pyplugy._context import PluginContext, current_context
+from pyplugy._manager import (
+    HOOK_PLUGIN_DISABLE,
+    HOOK_PLUGIN_ENABLE,
+    HOOK_PLUGIN_ERROR,
+    HOOK_PLUGIN_LOAD,
+    HOOK_PLUGIN_UNLOAD,
+    PluginManager,
+    current_manager,
+)
+from pyplugy._plugin import (
+    Plugin,
+    PluginInfo,
+    PluginManifest,
+    PluginState,
+    plugin,
+)
+from pyplugy.exceptions import (
+    PluginAlreadyLoadedError,
+    PluginDependencyError,
+    PluginError,
+    PluginLoadError,
+    PluginManifestError,
+    PluginNotFoundError,
+    PluginUnloadError,
+)
+
+__all__ = [
+    "HOOK_PLUGIN_DISABLE",
+    "HOOK_PLUGIN_ENABLE",
+    "HOOK_PLUGIN_ERROR",
+    "HOOK_PLUGIN_LOAD",
+    "HOOK_PLUGIN_UNLOAD",
+    "Plugin",
+    "PluginAlreadyLoadedError",
+    "PluginContext",
+    "PluginDependencyError",
+    "PluginError",
+    "PluginInfo",
+    "PluginLoadError",
+    "PluginManager",
+    "PluginManifest",
+    "PluginManifestError",
+    "PluginNotFoundError",
+    "PluginState",
+    "PluginUnloadError",
+    "current_context",
+    "current_manager",
+    "plugin",
+]
+
+__version__ = "0.1.0"

pyplugy/_context.py

@@ -0,0 +1,239 @@
+"""The :class:`PluginContext` handed to a plugin's setup / lifecycle methods.
+
+A context bundles everything a plugin needs to register hooks, schedule tasks,
+read config, and talk to its manager. The manager always runs ``on_load``
+inside a ``pyhooky.tag_scope(plugin_name)`` block, so *every* hook registered
+through the context (or directly via ``pyhooky``'s module helpers) is
+auto-tagged with the plugin's name. That auto-tagging is the central
+mechanism enabling clean unload via ``HookRegistry.clear_tag``.
+
+The task helpers on the context use the :mod:`pyplugy._tasky_protocol` so
+plugins don't need pyWorkflowy installed at import time. When the manager has no
+``tasky`` configured, ``ctx.task`` raises a clear :class:`RuntimeError`
+pointing at the ``pyplugy[tasks]`` extra.
+"""
+
+from __future__ import annotations
+
+import logging
+from contextvars import ContextVar
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping
+
+    from pyhooky import HookRegistry
+
+    from pyplugy._plugin import PluginManifest
+    from pyplugy._tasky_protocol import SchedulerProtocol, TaskyProtocol
+
+
+__all__ = ["PluginContext", "current_context"]
+
+
+_current_context: ContextVar[PluginContext | None] = ContextVar(
+    "pyplugy_current_context", default=None
+)
+
+
+def current_context() -> PluginContext | None:
+    """Return the :class:`PluginContext` for the plugin currently being loaded, if any.
+
+    Set by :class:`PluginManager` for the duration of an ``on_load`` /
+    ``on_unload`` / ``on_enable`` / ``on_disable`` call. Contextvar-based, so
+    it propagates across asyncio tasks and threads spawned during setup.
+    """
+    return _current_context.get()
+
+
+class PluginContext:
+    """Per-plugin handle for hook registration, task wiring, config, and logging.
+
+    :class:`PluginContext` is constructed by :class:`PluginManager` and passed
+    to every lifecycle method. All hook-registration helpers (:meth:`before`,
+    :meth:`after`, :meth:`around`, :meth:`on`, :meth:`on_error`) are thin
+    passthroughs to the bound :class:`pyhooky.HookRegistry` — they target the
+    registry the manager owns by default, but a custom one may be passed at
+    construction.
+
+    Because the manager wraps every call to a plugin's lifecycle methods in
+    ``pyhooky.tag_scope(plugin.name)``, the ``tag=`` argument can be omitted —
+    every registration in the block picks up the plugin name automatically.
+    Helpers exposed here merely make that intent explicit and route through
+    the manager-owned registry.
+    """
+
+    __slots__ = (
+        "_config",
+        "_logger",
+        "_manifest",
+        "_registry",
+        "_scheduler",
+        "_tasks",
+        "_tasky",
+    )
+
+    def __init__(
+        self,
+        manifest: PluginManifest,
+        *,
+        registry: HookRegistry,
+        config: Mapping[str, Any] | None = None,
+        tasky: TaskyProtocol | None = None,
+        scheduler: SchedulerProtocol | None = None,
+    ) -> None:
+        self._manifest = manifest
+        self._registry = registry
+        self._config: dict[str, Any] = dict(config or {})
+        self._tasky = tasky
+        self._scheduler = scheduler
+        self._tasks: list[Any] = []
+        self._logger = logging.getLogger(f"pyplugy.{manifest.name}")
+
+    # ---------- exposed surface ----------
+
+    @property
+    def name(self) -> str:
+        return self._manifest.name
+
+    @property
+    def manifest(self) -> PluginManifest:
+        return self._manifest
+
+    @property
+    def hooks(self) -> HookRegistry:
+        """The :class:`pyhooky.HookRegistry` hooks land in by default."""
+        return self._registry
+
+    @property
+    def config(self) -> dict[str, Any]:
+        """Mutable per-plugin config dict — populated by the manager."""
+        return self._config
+
+    @property
+    def logger(self) -> logging.Logger:
+        """A :class:`logging.Logger` named ``pyplugy.<plugin-name>``."""
+        return self._logger
+
+    @property
+    def scheduler(self) -> SchedulerProtocol | None:
+        """The optional shared scheduler. ``None`` when none is configured."""
+        return self._scheduler
+
+    @property
+    def tasks(self) -> tuple[Any, ...]:
+        """Tasks registered via :meth:`task`, in registration order."""
+        return tuple(self._tasks)
+
+    # ---------- hook passthroughs ----------
+
+    def before(self, target: Any, fn: Any = None, **kwargs: Any) -> Any:
+        from pyhooky import before as _before
+
+        return _before(target, fn, registry=self._registry, **kwargs)
+
+    def after(self, target: Any, fn: Any = None, **kwargs: Any) -> Any:
+        from pyhooky import after as _after
+
+        return _after(target, fn, registry=self._registry, **kwargs)
+
+    def around(self, target: Any, fn: Any = None, **kwargs: Any) -> Any:
+        from pyhooky import around as _around
+
+        return _around(target, fn, registry=self._registry, **kwargs)
+
+    def on(self, target: Any, fn: Any = None, **kwargs: Any) -> Any:
+        from pyhooky import on as _on
+
+        return _on(target, fn, registry=self._registry, **kwargs)
+
+    def on_error(self, target: Any, fn: Any = None, **kwargs: Any) -> Any:
+        from pyhooky import on_error as _on_error
+
+        return _on_error(target, fn, registry=self._registry, **kwargs)
+
+    def hook(self, target: Any = None, fn: Any = None, **kwargs: Any) -> Any:
+        """Wrap a callable so plugin hooks fire around it — passthrough to :func:`pyhooky.hook`.
+
+        Supports the same call shapes as :func:`pyhooky.hook`: bare callable,
+        bare invocation, explicit string target, or direct ``(name, fn)`` pair.
+        """
+        from pyhooky import hook as _hook
+
+        # Bare callable form — `@ctx.hook` directly on a function. The bare
+        # overload of `pyhooky.hook` doesn't accept registry=, so wrap it.
+        if callable(target) and not isinstance(target, str) and fn is None and not kwargs:
+            wrapped = self._registry.wrap(getattr(target, "__name__", None) or repr(target), target)
+            return wrapped
+        if target is None and fn is None:
+            return _hook(registry=self._registry, **kwargs)
+        if isinstance(target, str) and fn is None:
+            return _hook(target, registry=self._registry, **kwargs)
+        return _hook(target, fn, registry=self._registry, **kwargs)
+
+    # ---------- task passthroughs ----------
+
+    def task(self, fn: Callable[..., Any] | None = None, **kwargs: Any) -> Any:
+        """Register a task with the plugin's task scope.
+
+        Requires a :mod:`pyplugy._tasky_protocol`-compatible object on the
+        manager (real pyWorkflowy or a test stub). Without one, raises a
+        :class:`RuntimeError` pointing at the ``pyplugy[tasks]`` extra.
+
+        Both bare (``@ctx.task``) and parameterised (``@ctx.task(retries=3)``)
+        decorator forms work — same call shape as ``@pyworkflowy.task``.
+        """
+        if self._tasky is None:
+            raise RuntimeError(
+                f"plugin {self._manifest.name!r} called ctx.task but no task backend is "
+                "configured on the manager. Install pyWorkflowy (`pip install pyplugy[tasks]`) "
+                "or pass tasky= to PluginManager(...)."
+            )
+
+        decorator = self._tasky.task
+
+        def _record(task_obj: Any) -> Any:
+            self._tasks.append(task_obj)
+            return task_obj
+
+        if fn is None:
+            # Parameterised — `@ctx.task(retries=3)`
+            inner = decorator(**kwargs)
+
+            def wrap(real_fn: Callable[..., Any]) -> Any:
+                return _record(inner(real_fn))
+
+            return wrap
+
+        if callable(fn) and not kwargs:
+            # Bare — `@ctx.task` directly on the function.
+            return _record(decorator(fn))
+
+        # Mixed form: `ctx.task(fn, retries=3)` — uncommon but legal.
+        return _record(decorator(fn, **kwargs))
+
+    # ---------- introspection ----------
+
+    def __repr__(self) -> str:
+        return (
+            f"PluginContext(name={self._manifest.name!r}, "
+            f"registry={self._registry.name!r}, tasks={len(self._tasks)})"
+        )
+
+
+def _activate(ctx: PluginContext) -> Any:
+    """Internal helper used by :class:`PluginManager` to publish ``ctx`` via contextvar.
+
+    Returns a contextmanager that restores the previous context on exit.
+    """
+    from contextlib import contextmanager
+
+    @contextmanager
+    def _scope() -> Any:
+        token = _current_context.set(ctx)
+        try:
+            yield ctx
+        finally:
+            _current_context.reset(token)
+
+    return _scope()

pyplugy/_depgraph.py

@@ -0,0 +1,135 @@
+"""Plugin dependency resolution.
+
+Each plugin's :attr:`PluginManifest.requires` entry is a string like
+``"other>=2.0"`` — a PEP 440 specifier prefixed with the dependency's name.
+The leading identifier is the dependency name; anything that follows the name
+is a :class:`packaging.specifiers.SpecifierSet` constraint. A bare name
+(``"other"``) means "any version".
+
+:func:`resolve_load_order` returns a list of plugins ordered so that every
+plugin appears after the ones it depends on. Missing dependencies, version
+mismatches, and cycles all raise :class:`PluginDependencyError`.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+from packaging.specifiers import InvalidSpecifier, SpecifierSet
+from packaging.version import InvalidVersion, Version
+
+from pyplugy.exceptions import PluginDependencyError
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from pyplugy._plugin import Plugin
+
+
+__all__ = ["parse_requirement", "resolve_load_order"]
+
+
+# Plugin names are loose — we just split on the first specifier operator.
+_REQ_SPLIT_RE = re.compile(r"(===|==|!=|<=|>=|~=|<|>)")
+
+
+def parse_requirement(req: str) -> tuple[str, SpecifierSet]:
+    """Split ``"other>=2.0"`` into ``("other", SpecifierSet(">=2.0"))``.
+
+    A bare name returns an empty :class:`SpecifierSet` (matches any version).
+    Raises :class:`PluginDependencyError` if the specifier portion is malformed.
+    """
+    if not req or not isinstance(req, str):
+        raise PluginDependencyError(f"requirement must be a non-empty string, got {req!r}")
+    match = _REQ_SPLIT_RE.search(req)
+    if match is None:
+        return req.strip(), SpecifierSet()
+    name = req[: match.start()].strip()
+    spec_str = req[match.start() :].strip()
+    if not name:
+        raise PluginDependencyError(f"requirement {req!r} has no plugin name before the specifier")
+    try:
+        spec = SpecifierSet(spec_str)
+    except InvalidSpecifier as exc:
+        raise PluginDependencyError(
+            f"requirement {req!r} has an invalid version specifier {spec_str!r}: {exc}"
+        ) from exc
+    return name, spec
+
+
+def _parse_version(name: str, version_str: str) -> Version | None:
+    if not version_str:
+        return None
+    try:
+        return Version(version_str)
+    except InvalidVersion:
+        # Non-PEP440 plugin versions silently disable specifier checks for that
+        # plugin — better than refusing to load. We still warn-via-error if a
+        # *consumer* requires a specifier on a non-PEP440 dep.
+        return None
+
+
+def resolve_load_order(plugins: Iterable[Plugin]) -> list[Plugin]:
+    """Topologically sort ``plugins`` honoring ``manifest.requires``.
+
+    - Raises :class:`PluginDependencyError` when a required plugin is missing.
+    - Raises :class:`PluginDependencyError` when the available version doesn't
+      satisfy the specifier.
+    - Raises :class:`PluginDependencyError` on cycles, naming all plugins in
+      the cycle for easy debugging.
+    """
+    plugins_list = list(plugins)
+    by_name: dict[str, Plugin] = {}
+    for p in plugins_list:
+        name = p.manifest.name
+        if name in by_name:
+            raise PluginDependencyError(f"duplicate plugin name {name!r} in resolve_load_order")
+        by_name[name] = p
+
+    # Build adjacency: dep -> dependents (so we can Kahn-sort).
+    incoming: dict[str, set[str]] = {n: set() for n in by_name}
+    outgoing: dict[str, set[str]] = {n: set() for n in by_name}
+
+    for plugin_obj in plugins_list:
+        consumer = plugin_obj.manifest.name
+        for req in plugin_obj.manifest.requires:
+            dep_name, spec = parse_requirement(req)
+            if dep_name not in by_name:
+                raise PluginDependencyError(
+                    f"plugin {consumer!r} requires {dep_name!r} which is not loaded "
+                    f"(requirement {req!r})"
+                )
+            dep_plugin = by_name[dep_name]
+            if spec:
+                parsed = _parse_version(dep_name, dep_plugin.manifest.version)
+                if parsed is None:
+                    raise PluginDependencyError(
+                        f"plugin {consumer!r} requires {req!r}, but {dep_name!r} reports "
+                        f"non-PEP440 version {dep_plugin.manifest.version!r}; cannot check"
+                    )
+                if parsed not in spec:
+                    raise PluginDependencyError(
+                        f"plugin {consumer!r} requires {req!r}, but {dep_name!r} version "
+                        f"{dep_plugin.manifest.version!r} does not satisfy the specifier"
+                    )
+            incoming[consumer].add(dep_name)
+            outgoing[dep_name].add(consumer)
+
+    # Kahn's algorithm — process plugins whose deps are already emitted.
+    ready = sorted(n for n, deps in incoming.items() if not deps)
+    ordered: list[Plugin] = []
+    while ready:
+        name = ready.pop(0)
+        ordered.append(by_name[name])
+        for dependent in sorted(outgoing[name]):
+            incoming[dependent].discard(name)
+            if not incoming[dependent]:
+                ready.append(dependent)
+        # Keep `ready` sorted for deterministic output.
+        ready.sort()
+
+    if len(ordered) != len(plugins_list):
+        cycle = sorted(n for n, deps in incoming.items() if deps)
+        raise PluginDependencyError(f"cyclic plugin dependency involving: {', '.join(cycle)}")
+    return ordered

pyplugy/_discovery.py

@@ -0,0 +1,178 @@
+"""Plugin discovery — entry points, directory scan, JIT loading.
+
+Three discovery modes feed plugins into the manager:
+
+- **Entry points**: ``manager.load_entry_points(group="myapp.plugins")``
+  resolves each entry point and scans the loaded module for plugins.
+- **Directory scanning**: ``manager.load_directory(path, pattern="*.py")``
+  imports every match through :func:`importlib.util.spec_from_file_location`
+  under a sandboxed module name (``pyplugy._loaded.<stem>``) so we don't
+  pollute the global :data:`sys.modules` namespace.
+- **JIT (just-in-time)**: ``manager.load(target)`` accepts a class, instance,
+  module, dotted path, or filesystem path and figures out what to do.
+
+All three modes converge on :func:`scan_module` — given a module object, it
+returns every :class:`Plugin` instance or class found in it.
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.metadata
+import importlib.util
+import inspect
+import sys
+from pathlib import Path
+from types import ModuleType
+from typing import TYPE_CHECKING
+
+from pyplugy._plugin import Plugin
+from pyplugy.exceptions import PluginLoadError
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Iterator
+
+
+__all__ = [
+    "import_file",
+    "iter_directory_modules",
+    "iter_entry_points",
+    "scan_module",
+]
+
+
+_SANDBOX_PREFIX = "pyplugy._loaded"
+
+
+def scan_module(module: ModuleType) -> list[Plugin]:
+    """Return every plugin defined in ``module``.
+
+    Recognises three shapes:
+
+    - Module-level :class:`Plugin` instances (e.g. produced by the
+      :func:`plugin` decorator).
+    - :class:`Plugin` subclasses defined in the module (instantiated here with
+      no arguments).
+    - A ``setup`` callable wrapped by the :func:`plugin` decorator (already a
+      :class:`Plugin` instance — covered by the first case).
+
+    Items imported *from* other modules are skipped: only definitions whose
+    ``__module__`` matches ``module.__name__`` are considered. That keeps
+    re-imports from accidentally double-registering a plugin discovered via
+    another path.
+    """
+    found: list[Plugin] = []
+    seen_ids: set[int] = set()
+    seen_names: set[str] = set()
+
+    for attr_name in dir(module):
+        if attr_name.startswith("_"):
+            continue
+        obj = getattr(module, attr_name, None)
+
+        # 1) Plugin instances (decorator form)
+        if isinstance(obj, Plugin):
+            if id(obj) in seen_ids:
+                continue
+            seen_ids.add(id(obj))
+            name = obj.manifest.name or attr_name
+            if name in seen_names:
+                continue
+            seen_names.add(name)
+            found.append(obj)
+            continue
+
+        # 2) Plugin subclasses (class form) — only those defined in this module
+        if (
+            inspect.isclass(obj)
+            and issubclass(obj, Plugin)
+            and obj is not Plugin
+            and getattr(obj, "__module__", None) == module.__name__
+        ):
+            try:
+                instance = obj()
+            except Exception as exc:  # pragma: no cover - defensive
+                raise PluginLoadError(
+                    f"failed to instantiate plugin class {obj.__name__!r} from "
+                    f"module {module.__name__!r}: {exc}"
+                ) from exc
+            if instance.manifest.name in seen_names:
+                continue
+            seen_names.add(instance.manifest.name)
+            seen_ids.add(id(instance))
+            found.append(instance)
+
+    return found
+
+
+def iter_entry_points(group: str) -> Iterator[tuple[str, ModuleType]]:
+    """Yield ``(entry_point_name, module)`` for every entry point in ``group``.
+
+    Each entry point is resolved with :func:`importlib.metadata.entry_points`.
+    Targets that don't resolve to a module are imported via dotted-path
+    semantics so plugins published as ``"my.module:setup"`` still work
+    (the manager scans the parent module).
+    """
+    eps = importlib.metadata.entry_points(group=group)
+    for ep in eps:
+        loaded = ep.load()
+        if isinstance(loaded, ModuleType):
+            yield ep.name, loaded
+        else:
+            # ``ep.load()`` may return a class/function — use its parent module.
+            module_name = getattr(loaded, "__module__", None) or ep.value.split(":")[0]
+            module = importlib.import_module(module_name)
+            yield ep.name, module
+
+
+def _sandbox_name(stem: str, *, counter: dict[str, int]) -> str:
+    """Pick a unique sandboxed name like ``pyplugy._loaded.foo`` (or ``foo_1`` on collision)."""
+    base = f"{_SANDBOX_PREFIX}.{stem}"
+    n = counter.get(base, 0)
+    counter[base] = n + 1
+    return base if n == 0 else f"{base}_{n}"
+
+
+def import_file(path: Path, *, sandbox_counter: dict[str, int] | None = None) -> ModuleType:
+    """Import a ``.py`` file under a sandboxed module name.
+
+    Avoids inserting the loaded module under its bare stem in
+    :data:`sys.modules` — that would shadow real top-level packages.
+    """
+    if sandbox_counter is None:
+        sandbox_counter = {}
+    module_name = _sandbox_name(path.stem, counter=sandbox_counter)
+    spec = importlib.util.spec_from_file_location(module_name, path)
+    if spec is None or spec.loader is None:
+        raise PluginLoadError(f"cannot build module spec for {path!r}")
+    module = importlib.util.module_from_spec(spec)
+    # Register before exec so intra-module relative imports resolve.
+    sys.modules[module_name] = module
+    try:
+        spec.loader.exec_module(module)
+    except Exception:
+        sys.modules.pop(module_name, None)
+        raise
+    return module
+
+
+def iter_directory_modules(
+    path: Path,
+    *,
+    recursive: bool = False,
+    pattern: str = "*.py",
+) -> Iterable[ModuleType]:
+    """Yield modules imported from every file matching ``pattern`` under ``path``."""
+    if not path.exists():
+        raise PluginLoadError(f"plugin directory {path!r} does not exist")
+    if not path.is_dir():
+        raise PluginLoadError(f"plugin path {path!r} is not a directory")
+
+    sandbox_counter: dict[str, int] = {}
+    iterator = path.rglob(pattern) if recursive else path.glob(pattern)
+    for file in sorted(iterator):
+        if not file.is_file():
+            continue
+        if file.name == "__init__.py":
+            continue
+        yield import_file(file, sandbox_counter=sandbox_counter)