pyplugy 0.2.0__tar.gz → 0.3.0__tar.gz

{pyplugy-0.2.0 → pyplugy-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyplugy
-Version: 0.2.0
+Version: 0.3.0
 Summary: Plugin framework with hooks (pyHooky) and tasks (pyWorkflowy).
 Project-URL: Homepage, https://github.com/kiliansen/pyPlugy
 Project-URL: Issues, https://github.com/kiliansen/pyPlugy/issues
@@ -40,8 +40,9 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Requires-Dist: packaging>=24.0
+Requires-Dist: pydantic>=2.0
 Requires-Dist: pyhooky>=0.1.0
-Requires-Dist: pyworkflowy>=0.1.0
+Requires-Dist: pyworkflowy>=0.2.0
 Provides-Extra: tasks
 Requires-Dist: pyworkflowy>=0.1.0; extra == 'tasks'
 Description-Content-Type: text/markdown

{pyplugy-0.2.0 → pyplugy-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pyplugy"
-version = "0.2.0"
+version = "0.3.0"
 description = "Plugin framework with hooks (pyHooky) and tasks (pyWorkflowy)."
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -22,7 +22,8 @@ classifiers = [
 dependencies = [
     "pyhooky>=0.1.0",
     "packaging>=24.0",
-    "pyworkflowy>=0.1.0",
+    "pyworkflowy>=0.2.0",
+    "pydantic>=2.0",
 ]
 
 [project.optional-dependencies]
@@ -35,6 +36,7 @@ Issues = "https://github.com/kiliansen/pyPlugy/issues"
 
 
 
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
@@ -120,6 +122,7 @@ exclude_commit_patterns = ["^chore\\(release\\):"]
 
 
 
+
 [dependency-groups]
 dev = [
     "pytest>=8.0",

{pyplugy-0.2.0 → pyplugy-0.3.0}/src/pyplugy/__init__.py

@@ -22,11 +22,15 @@ from pyplugy._plugin import (
 )
 from pyplugy.exceptions import (
     PluginAlreadyLoadedError,
+    PluginConfigValidationError,
+    PluginConflictError,
     PluginDependencyError,
     PluginError,
     PluginLoadError,
     PluginManifestError,
+    PluginMissingDependencyError,
     PluginNotFoundError,
+    PluginPeerDependencyError,
     PluginUnloadError,
 )
 
@@ -39,6 +43,8 @@ __all__ = [
     "HOOK_PLUGIN_UNLOAD",
     "Plugin",
     "PluginAlreadyLoadedError",
+    "PluginConfigValidationError",
+    "PluginConflictError",
     "PluginContext",
     "PluginDependencyError",
     "PluginError",
@@ -47,7 +53,9 @@ __all__ = [
     "PluginManager",
     "PluginManifest",
     "PluginManifestError",
+    "PluginMissingDependencyError",
     "PluginNotFoundError",
+    "PluginPeerDependencyError",
     "PluginState",
     "PluginUnloadError",
     "current_context",

{pyplugy-0.2.0 → pyplugy-0.3.0}/src/pyplugy/_context.py

@@ -90,6 +90,8 @@ class PluginContext:
 
     __slots__ = (
         "_config",
+        "_config_model",
+        "_events",
         "_logger",
         "_manifest",
         "_registry",
@@ -121,6 +123,12 @@ class PluginContext:
         self._scheduler = scheduler
         self._tasks: list[Any] = []
         self._logger = logging.getLogger(f"pyplugy.{manifest.name}")
+        # Populated by the manager once it has the Plugin instance and can
+        # consult ``plugin.config_model``. Stays None when no model is declared.
+        self._config_model: Any | None = None
+        # Populated by the manager from ``plugin.events`` — one HookPoint per
+        # declared key, namespaced as ``"<plugin_name>:<key>"``.
+        self._events: dict[str, Any] = {}
 
     # ---------- exposed surface ----------
 
@@ -142,6 +150,30 @@ class PluginContext:
         """Mutable per-plugin config dict — populated by the manager."""
         return self._config
 
+    @property
+    def events(self) -> dict[str, Any]:
+        """Typed :class:`~pyhooky.HookPoint` instances keyed by ``Plugin.events``.
+
+        Empty when the plugin didn't declare any. Each ``HookPoint`` is
+        bound to the manager's registry; listeners attached to them are
+        auto-tagged for cleanup.
+        """
+        return self._events
+
+    @property
+    def config_model(self) -> Any | None:
+        """Validated config model instance, or ``None`` when the plugin declared no schema.
+
+        The manager populates this when the plugin declares
+        ``config_model``. After :meth:`PluginManager.update_config` runs,
+        the model is re-validated from the (now-updated) ``config`` dict.
+        If a plugin mutates ``ctx.config`` directly, ``config_model``
+        won't pick up the change until the next ``update_config`` call —
+        explicit mutation is the loose path, validated updates are the
+        sharp one.
+        """
+        return self._config_model
+
     @property
     def logger(self) -> logging.Logger:
         """A :class:`logging.Logger` named ``pyplugy.<plugin-name>``."""
@@ -203,6 +235,146 @@ class PluginContext:
             return _hook(target, registry=self._registry, **kwargs)
         return _hook(target, fn, registry=self._registry, **kwargs)
 
+    # ---------- typed events (pyHooky HookPoint factory) ----------
+
+    def event(self, name: str, schema: Any) -> Any:
+        """Return a pyHooky :class:`~pyhooky.HookPoint` bound to this manager.
+
+        ``schema`` is a pydantic :class:`~pydantic.BaseModel` subclass.
+        The returned ``HookPoint`` dispatches through the same registry
+        the manager owns, so listeners attached inside the plugin's
+        lifecycle are tagged with the plugin name automatically (via
+        the existing ``tag_scope`` block) and torn down with it.
+
+        Plugins typically bind the result locally::
+
+            login = ctx.event("auth:login", LoginEvent)
+            @login.listen
+            def audit(evt: LoginEvent): ...
+            login.trigger(user="alice")
+        """
+        from pyhooky import HookPoint
+
+        return HookPoint(name, schema, registry=self._registry)
+
+    # ---------- dependency access ----------
+
+    def dep(self, name: str) -> PluginContext | None:
+        """Return the :class:`PluginContext` of a declared dependency.
+
+        ``name`` must appear in this plugin's ``requires`` or
+        ``optional_requires``; otherwise a :class:`PluginDependencyError`
+        is raised so the manifest stays the single source of truth for the
+        plugin graph. For hard deps the manager guarantees the slot exists
+        (load order resolves dependencies first). For optional deps that
+        aren't currently loaded, returns ``None``.
+
+        Must be called inside a lifecycle hook (``on_load`` / ``on_enable``
+        / etc.) so that :func:`~pyplugy._manager.current_manager` is set.
+        """
+        from pyplugy._manager import current_manager
+        from pyplugy.exceptions import PluginDependencyError
+
+        declared = set(self._manifest.requires) | set(self._manifest.optional_requires)
+        # Strip version specifiers — match by name only.
+        from pyplugy._depgraph import parse_requirement
+
+        declared_names = {parse_requirement(r)[0] for r in declared}
+        if name not in declared_names:
+            raise PluginDependencyError(
+                f"plugin {self._manifest.name!r} did not declare dep {name!r}; "
+                f"add it to requires or optional_requires"
+            )
+        manager = current_manager()
+        if manager is None:
+            raise PluginDependencyError(
+                f"ctx.dep({name!r}) called outside an active lifecycle hook; no current manager"
+            )
+        slot = manager._plugins.get(name)
+        if slot is None:
+            # Optional dep that isn't loaded — silently absent.
+            if name in {parse_requirement(r)[0] for r in self._manifest.optional_requires}:
+                return None
+            # Hard dep should always be present at this point.
+            raise PluginDependencyError(
+                f"plugin {self._manifest.name!r} requires {name!r} but it is not loaded"
+            )
+        return slot.ctx
+
+    depends_on = dep
+
+    def export(self, obj: Any) -> Any:
+        """Publish ``obj`` as this plugin's API for dependents.
+
+        ``ctx.api_of(name)`` returns whatever was last passed here.
+        Must be called inside a lifecycle hook (``on_load`` / ``on_enable``).
+        Calling more than once is allowed — the latest call wins, which
+        makes it safe to call from both ``on_load`` and ``on_enable``.
+
+        When the plugin declares ``api_model`` (a pydantic
+        :class:`~pydantic.BaseModel` subclass), ``obj`` is validated
+        against it: a dict is parsed into the model, an existing model
+        instance is type-checked, and anything else raises
+        :class:`PluginManifestError`-equivalent error from pydantic.
+
+        Returns the stored value (the validated model, or ``obj``
+        verbatim when no ``api_model`` is declared).
+        """
+        from pyplugy._manager import current_manager
+        from pyplugy.exceptions import PluginError
+
+        manager = current_manager()
+        if manager is None:
+            raise PluginError(
+                f"ctx.export(...) called outside an active lifecycle hook for "
+                f"plugin {self._manifest.name!r}"
+            )
+        slot = manager._plugins.get(self._manifest.name)
+        if slot is None:
+            raise PluginError(
+                f"ctx.export(...) called for {self._manifest.name!r} but the "
+                "manager has no slot for it — was on_load aborted?"
+            )
+        validated = _validate_against_model(obj, slot.plugin.api_model)
+        slot.api = validated
+        return validated
+
+    def api_of(self, name: str) -> Any:
+        """Return the API another plugin published via :meth:`export`.
+
+        ``name`` must appear in this plugin's
+        ``requires`` / ``optional_requires`` / ``peer_requires`` — the
+        same declaration check that :meth:`dep` enforces. Returns ``None``
+        if the dep is loaded but never called ``export``, or if it's an
+        unsatisfied optional dep.
+        """
+        from pyplugy._depgraph import parse_requirement
+        from pyplugy._manager import current_manager
+        from pyplugy.exceptions import PluginDependencyError
+
+        declared = {
+            parse_requirement(r)[0]
+            for r in (
+                *self._manifest.requires,
+                *self._manifest.optional_requires,
+                *self._manifest.peer_requires,
+            )
+        }
+        if name not in declared:
+            raise PluginDependencyError(
+                f"plugin {self._manifest.name!r} did not declare dep {name!r}; "
+                f"add it to requires / optional_requires / peer_requires"
+            )
+        manager = current_manager()
+        if manager is None:
+            raise PluginDependencyError(
+                f"ctx.api_of({name!r}) called outside an active lifecycle hook"
+            )
+        slot = manager._plugins.get(name)
+        if slot is None:
+            return None
+        return slot.api
+
     # ---------- task passthroughs ----------
 
     def task(self, fn: Callable[..., Any] | None = None, **kwargs: Any) -> Any:
@@ -215,6 +387,25 @@ class PluginContext:
         Both bare (``@ctx.task``) and parameterised (``@ctx.task(retries=3)``)
         decorator forms work — same call shape as ``@pyworkflowy.task``.
         """
+
+        def _record(task_obj: Any) -> Any:
+            self._tasks.append(task_obj)
+            return task_obj
+
+        # pyWorkflowy class form: ``ctx.task(MyTaskClass)`` — instantiating
+        # a TaskBase subclass returns a Task directly (via TaskBase.__new__),
+        # so we register that instance and return it. Lazy import keeps
+        # pyworkflowy optional for plugins that only use the decorator form.
+        # Handled before the tasky-required check so this form works even
+        # when the manager has no tasky configured.
+        if isinstance(fn, type):
+            try:
+                from pyworkflowy import TaskBase
+            except ImportError:
+                TaskBase = None  # type: ignore[assignment]
+            if TaskBase is not None and issubclass(fn, TaskBase):
+                return _record(fn())
+
         if self._tasky is None:
             raise RuntimeError(
                 f"plugin {self._manifest.name!r} called ctx.task but no task backend is "
@@ -224,10 +415,6 @@ class PluginContext:
 
         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)
@@ -253,6 +440,40 @@ class PluginContext:
         )
 
 
+def _validate_against_model(obj: Any, model: Any | None) -> Any:
+    """Coerce/validate ``obj`` against ``model`` (a pydantic ``BaseModel`` subclass).
+
+    ``model=None`` → return ``obj`` as-is. ``obj`` already an instance of
+    ``model`` → returned unchanged. ``obj`` is a dict → parsed via
+    ``model.model_validate``. Anything else with a non-None model raises
+    :class:`PluginManifestError` so misuses fail loudly at the boundary.
+    """
+    from pydantic import BaseModel, ValidationError
+
+    from pyplugy.exceptions import PluginManifestError
+
+    if model is None:
+        return obj
+    if isinstance(obj, model):
+        return obj
+    if isinstance(obj, dict):
+        try:
+            return model.model_validate(obj)
+        except ValidationError as exc:
+            raise PluginManifestError(
+                f"export payload failed validation against {model.__name__}: {exc}"
+            ) from exc
+    if isinstance(obj, BaseModel):
+        raise PluginManifestError(
+            f"export payload is a {type(obj).__name__} instance but {model.__name__} "
+            "was declared as api_model; types don't match"
+        )
+    raise PluginManifestError(
+        f"export payload of type {type(obj).__name__} cannot be coerced to {model.__name__}; "
+        "pass a dict or an instance of the declared model"
+    )
+
+
 def _activate(ctx: PluginContext) -> Any:
     """Internal helper used by :class:`PluginManager` to publish ``ctx`` via contextvar.
 

{pyplugy-0.2.0 → pyplugy-0.3.0}/src/pyplugy/_depgraph.py

@@ -19,7 +19,12 @@ from typing import TYPE_CHECKING
 from packaging.specifiers import InvalidSpecifier, SpecifierSet
 from packaging.version import InvalidVersion, Version
 
-from pyplugy.exceptions import PluginDependencyError
+from pyplugy.exceptions import (
+    PluginConflictError,
+    PluginDependencyError,
+    PluginMissingDependencyError,
+    PluginPeerDependencyError,
+)
 
 if TYPE_CHECKING:
     from collections.abc import Iterable
@@ -27,7 +32,7 @@ if TYPE_CHECKING:
     from pyplugy._plugin import Plugin
 
 
-__all__ = ["parse_requirement", "resolve_load_order"]
+__all__ = ["compute_reverse_graph", "parse_requirement", "resolve_load_order"]
 
 
 # Plugin names are loose — we just split on the first specifier operator.
@@ -73,11 +78,18 @@ def _parse_version(name: str, version_str: str) -> Version | 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.
+    - Raises :class:`PluginMissingDependencyError` when a hard-required
+      plugin is missing. The exception carries the missing dep name so
+      resolvers can fetch it and retry.
+    - Raises :class:`PluginDependencyError` when the available version
+      doesn't satisfy the specifier.
+    - Raises :class:`PluginConflictError` when two plugins declare each
+      other (or are declared by each other) in ``conflicts``.
+    - Raises :class:`PluginDependencyError` on cycles, naming all plugins
+      in the cycle for easy debugging.
+
+    ``optional_requires`` contribute ordering edges only when the named
+    plugin is present; missing optional deps are silently ignored.
     """
     plugins_list = list(plugins)
     by_name: dict[str, Plugin] = {}
@@ -87,18 +99,30 @@ def resolve_load_order(plugins: Iterable[Plugin]) -> list[Plugin]:
             raise PluginDependencyError(f"duplicate plugin name {name!r} in resolve_load_order")
         by_name[name] = p
 
+    # Conflicts first — fail fast before building the graph.
+    for plugin_obj in plugins_list:
+        consumer = plugin_obj.manifest.name
+        for foe in plugin_obj.manifest.conflicts:
+            if foe in by_name:
+                raise PluginConflictError(
+                    f"plugin {consumer!r} conflicts with {foe!r}; cannot load together"
+                )
+
     # 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
+        # Hard requires — missing is an error.
         for req in plugin_obj.manifest.requires:
             dep_name, spec = parse_requirement(req)
             if dep_name not in by_name:
-                raise PluginDependencyError(
+                raise PluginMissingDependencyError(
                     f"plugin {consumer!r} requires {dep_name!r} which is not loaded "
-                    f"(requirement {req!r})"
+                    f"(requirement {req!r})",
+                    missing=dep_name,
+                    consumer=consumer,
                 )
             dep_plugin = by_name[dep_name]
             if spec:
@@ -115,6 +139,55 @@ def resolve_load_order(plugins: Iterable[Plugin]) -> list[Plugin]:
                     )
             incoming[consumer].add(dep_name)
             outgoing[dep_name].add(consumer)
+        # Peer requires — must be present, but resolvers don't auto-fetch.
+        # Use a dedicated exception class so the manager's resolver retry
+        # loop (which catches PluginMissingDependencyError) skips peers.
+        for req in plugin_obj.manifest.peer_requires:
+            dep_name, spec = parse_requirement(req)
+            if dep_name not in by_name:
+                raise PluginPeerDependencyError(
+                    f"plugin {consumer!r} requires peer {dep_name!r} which is not loaded "
+                    f"(requirement {req!r}); the host must supply it"
+                )
+            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 peer {req!r}, but {dep_name!r} "
+                        f"reports non-PEP440 version {dep_plugin.manifest.version!r}; "
+                        "cannot check"
+                    )
+                if parsed not in spec:
+                    raise PluginDependencyError(
+                        f"plugin {consumer!r} requires peer {req!r}, but {dep_name!r} "
+                        f"version {dep_plugin.manifest.version!r} does not satisfy "
+                        "the specifier"
+                    )
+            incoming[consumer].add(dep_name)
+            outgoing[dep_name].add(consumer)
+        # Optional requires — missing is silent, version mismatch still raises.
+        for req in plugin_obj.manifest.optional_requires:
+            dep_name, spec = parse_requirement(req)
+            if dep_name not in by_name:
+                continue
+            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} optionally requires {req!r}, but "
+                        f"{dep_name!r} reports non-PEP440 version "
+                        f"{dep_plugin.manifest.version!r}; cannot check"
+                    )
+                if parsed not in spec:
+                    raise PluginDependencyError(
+                        f"plugin {consumer!r} optionally requires {req!r}, but "
+                        f"{dep_name!r} version {dep_plugin.manifest.version!r} does "
+                        f"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)
@@ -133,3 +206,27 @@ def resolve_load_order(plugins: Iterable[Plugin]) -> list[Plugin]:
         cycle = sorted(n for n, deps in incoming.items() if deps)
         raise PluginDependencyError(f"cyclic plugin dependency involving: {', '.join(cycle)}")
     return ordered
+
+
+def compute_reverse_graph(plugins: Iterable[Plugin]) -> dict[str, set[str]]:
+    """Return ``{dep_name: {consumer_name, ...}}`` over ``plugins``.
+
+    Hard ``requires`` and ``peer_requires`` edges are included — both
+    represent a "the consumer genuinely needs this loaded" relationship,
+    and both block teardown of the dependency. ``optional_requires``
+    are excluded: an optional dep can disappear without breaking the
+    consumer, so it does not pin the dependency.
+    """
+    reverse: dict[str, set[str]] = {}
+    names = {p.manifest.name for p in plugins}
+    for p in plugins:
+        consumer = p.manifest.name
+        for req in p.manifest.requires:
+            dep_name, _ = parse_requirement(req)
+            if dep_name in names:
+                reverse.setdefault(dep_name, set()).add(consumer)
+        for req in p.manifest.peer_requires:
+            dep_name, _ = parse_requirement(req)
+            if dep_name in names:
+                reverse.setdefault(dep_name, set()).add(consumer)
+    return reverse