pyrig-runtime 0.1.0__py3-none-any.whl

pyrig_runtime/__init__.py

@@ -0,0 +1 @@
+"""The top-level package for the project."""

pyrig_runtime/core/__init__.py

@@ -0,0 +1 @@
+"""Package initialization."""

pyrig_runtime/core/dependencies/__init__.py

@@ -0,0 +1,6 @@
+"""Introspection primitives for class, module, and package discovery.
+
+Provides the low-level building blocks that power pyrig's cross-package subclass
+discovery: walking package hierarchies, dynamically importing modules, filtering
+class collections, and locating equivalent module paths across dependent packages.
+"""

pyrig_runtime/core/dependencies/discovery.py

@@ -0,0 +1,124 @@
+"""Subclass and module discovery scoped across installed package dependents."""
+
+import logging
+from collections.abc import Iterator
+from functools import cache
+from itertools import chain
+from types import ModuleType
+
+from pyrig_runtime.core.dependencies.graph import DependencyGraph
+from pyrig_runtime.core.introspection.modules import (
+    import_module_with_default,
+    import_modules,
+    root_module,
+)
+from pyrig_runtime.core.introspection.packages import (
+    discover_subclasses_across_package,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def discover_subclasses_across_dependencies[T](
+    cls: type[T],
+    package: ModuleType,
+) -> Iterator[type[T]]:
+    """Yield subclasses of `cls` found in `package` and in every dependent of its root.
+
+    Searches `package` itself first, then each installed package that depends on
+    `package`'s root package. In each dependent, the module path equivalent to
+    `package` is located (e.g., `pyrig.rig` becomes `<dep>.rig`), and every
+    subclass of `cls` defined there is collected.
+
+    Args:
+        cls: Base class whose subclasses should be discovered.
+        package: Module whose dotted path is replicated in each dependent package
+            to locate the modules to search. The root of this module determines
+            which installed packages are searched. For example, passing
+            `pyrig.rig` would search `<dep>.rig` in each dependent of `pyrig`.
+
+    Yields:
+        Subclass types of `cls` found across `package` and all dependent
+        packages, in dependency order (base package first, then dependents).
+    """
+    logger.debug(
+        "Discovering subclasses of %s from modules in packages depending on %s",
+        cls.__name__,
+        package.__name__,
+    )
+
+    return (
+        subclass
+        for pkg in chain(
+            (package,),
+            discover_equivalent_modules_across_dependents(module=package),
+        )
+        for subclass in discover_subclasses_across_package(
+            cls,
+            package=pkg,
+        )
+    )
+
+
+def discover_equivalent_modules_across_dependents(
+    module: ModuleType,
+) -> Iterator[ModuleType]:
+    """Yield the equivalent module from every package that depends on `module`'s root.
+
+    Given a module (e.g., `pyrig.rig.configs`), infers the root package
+    (e.g., `pyrig`), then constructs the equivalent dotted path in each package
+    that depends on that root (e.g., `myapp.rig.configs`), imports it if it
+    exists, and yields it.
+
+    The root package itself is not included in results — only its dependents are
+    iterated. The path transformation replaces the first occurrence of the root
+    package name in `module.__name__` with each dependent package's name, so a
+    consistent directory structure across the ecosystem is assumed.
+
+    Args:
+        module: Template module whose path pattern is replicated in each dependent
+            package (e.g., `pyrig.core` → `<pkg>.core` for every dependent).
+            The root of this module is used to discover dependent packages.
+
+    Yields:
+        Successfully imported module objects in dependency order. Packages whose
+        equivalent module path cannot be imported are silently skipped.
+    """
+    dependency = root_module(module)
+    logger.debug(
+        "Discovering modules equivalent to %s in packages depending on %s",
+        module.__name__,
+        dependency.__name__,
+    )
+
+    for package in deps_depending_on_dep(dependency):
+        package_module_name = module.__name__.replace(
+            dependency.__name__, package.__name__, 1
+        )
+        package_module = import_module_with_default(package_module_name)
+        if package_module is not None:
+            yield package_module
+
+
+@cache
+def deps_depending_on_dep(dependency: ModuleType) -> tuple[ModuleType, ...]:
+    """Return all installed packages that depend on `dependency`, as module objects.
+
+    Find every installed package that depends on `dependency` (directly or
+    transitively), import them, and return the result as a tuple in dependency
+    order. The result is cached per unique `dependency` argument.
+
+    Args:
+        dependency: The package whose dependents should be discovered.
+
+    Returns:
+        Tuple of imported module objects for all packages that depend on
+        `dependency`. Does not include `dependency` itself.
+    """
+    return tuple(
+        import_modules(
+            DependencyGraph.cached(root=dependency.__name__).sorted_ancestors(
+                dependency.__name__
+            )
+        )
+    )

pyrig_runtime/core/dependencies/graph.py

@@ -0,0 +1,69 @@
+"""Directed graph of installed Python package dependency relationships."""
+
+import importlib.metadata
+import logging
+from collections.abc import Iterator
+
+from pyrig_runtime.core.graph import DiGraph
+from pyrig_runtime.core.strings import (
+    dependency_requirement_as_package_name,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class DependencyGraph(DiGraph):
+    """Directed graph of installed Python package dependencies.
+
+    Nodes are package names; an edge A → B means "A depends on B".
+    The graph is built at instantiation by scanning all installed
+    distributions.
+
+    When a `root` package is given, the graph is pruned to retain only
+    that package and every package that depends on it directly or
+    transitively.
+    """
+
+    def __init__(self, root: str | None = None) -> None:
+        """Initialize the dependency graph rooted at the given package.
+
+        Only `root` and packages that depend on it transitively are retained.
+
+        Args:
+            root: Name of the root package. Accepts either the installed name
+                (`some-package`) or the import name (`some_package`).
+        """
+        super().__init__(
+            root=dependency_requirement_as_package_name(root) if root else None
+        )
+
+    def build(self) -> None:
+        """Build the graph from installed Python distributions."""
+        logger.debug("Building dependency graph from installed distributions")
+        for dist in importlib.metadata.distributions():
+            name, deps = self.parse_name_and_deps(dist)
+            self.add_node(name)
+            for dep in deps:
+                self.add_edge(name, dep)  # package → dependency
+        logger.debug("Dependency graph built with %d packages", len(self.nodes()))
+
+    def parse_name_and_deps(
+        self, dist: importlib.metadata.Distribution
+    ) -> tuple[str, Iterator[str]]:
+        """Extract the package name and dependencies from a distribution.
+
+        Both the package name and every dependency name are normalized to
+        snake_case. The dependency iterator is exhausted once consumed; it
+        yields nothing when the distribution declares no dependencies.
+
+        Args:
+            dist: Distribution to extract metadata from.
+
+        Returns:
+            A two-tuple `(name, deps)` where `name` is the normalized package
+            name and `deps` is an iterator over the normalized name of each
+            declared dependency.
+        """
+        return dependency_requirement_as_package_name(dist.name), (
+            dependency_requirement_as_package_name(req) for req in (dist.requires or [])
+        )

pyrig_runtime/core/dependencies/subclass.py

@@ -0,0 +1,180 @@
+"""Abstract base for cross-package subclass discovery without explicit registration."""
+
+import json
+import logging
+from abc import ABC, abstractmethod
+from collections.abc import Iterable, Iterator
+from functools import cache
+from types import ModuleType
+from typing import Any, Self, TypeVar
+
+from pyrig import rig
+
+from pyrig_runtime.core.dependencies.discovery import (
+    discover_subclasses_across_dependencies,
+)
+from pyrig_runtime.core.introspection.classes import (
+    classproperty,
+    discard_abstract_classes,
+    discard_parent_classes,
+)
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T", bound="DependencySubclass")
+
+
+class DependencySubclass(ABC):
+    """Base class that enables the plugin-style extensibility across installed packages.
+
+    Subclasses declare a sub-package scope via `dependency_package()`, and
+    the discovery machinery automatically finds all concrete implementations
+    defined in that sub-package across every installed package that depends
+    on the root package. No explicit registration is required.
+
+    The `sort_key()` hook controls ordering when `subclasses_sorted()` is
+    used. The `L` classproperty provides a cached shortcut to the leaf
+    subclass type, and `I` provides a cached instance of it.
+    """
+
+    def __str__(self) -> str:
+        """Return the fully qualified class name of this instance."""
+        return f"{self.__module__}.{self.__class__.__name__}"
+
+    @classmethod
+    @abstractmethod
+    def dependency_package(cls) -> ModuleType:
+        """Return the sub-package that scopes subclass discovery for this hierarchy.
+
+        Every concrete subclass must override this to return the sub-package
+        where its own implementations are defined. The returned module's root
+        package determines which installed packages are searched.
+
+        The base implementation returns `pyrig.rig`, making it callable via
+        `super()` as a fallback or when calling `subclasses()` directly on
+        `DependencySubclass` itself.
+
+        Returns:
+            Package module whose path pattern is replicated across dependent
+            packages to locate the modules to search.
+        """
+        return rig
+
+    @classmethod
+    def sort_key(cls) -> Any:
+        """Return a stable sort key used by `subclasses_sorted()` to order subclasses.
+
+        Override to sort by priority, numeric position, or any other criterion.
+        The default returns the class name, giving alphabetical ordering.
+
+        Returns:
+            A value comparable by `sorted()`.
+        """
+        return cls.__name__
+
+    @classproperty
+    @cache  # noqa: B019  # false warning bc of custom classproperty decorator
+    def I(cls) -> Self:  # noqa: E743, N802, N805
+        """Return a cached instance of the leaf subclass.
+
+        The instance is created once per class and reused on every subsequent
+        access. Equivalent to instantiating the result of `cls.L`.
+
+        Returns:
+            An instance of the leaf subclass.
+
+        Raises:
+            RuntimeError: If more than one leaf subclass is found.
+        """
+        return cls.L()
+
+    @classproperty
+    @cache  # noqa: B019  # false warning bc of custom classproperty decorator
+    def L(cls) -> type[Self]:  # noqa: N802, N805
+        """Return the cached leaf subclass type.
+
+        Equivalent to `leaf()`, but the result is cached so repeated accesses
+        do not re-run discovery.
+
+        Returns:
+            The single leaf subclass type. May be abstract.
+
+        Raises:
+            RuntimeError: If more than one leaf subclass is found.
+        """
+        return cls.leaf()
+
+    @classmethod
+    def leaf(cls) -> type[Self]:
+        """Return the single leaf subclass found across dependent packages.
+
+        Calls `subclasses()` and expects at most one result. If no subclasses
+        are found, the class itself is returned. Raises `RuntimeError` if
+        multiple subclasses are found, because a leaf must be unambiguous:
+        exactly one active implementation is allowed.
+
+        Returns:
+            The sole leaf subclass type. May be abstract.
+
+        Raises:
+            RuntimeError: If more than one subclass is discovered across
+                the dependent packages.
+        """
+        subclasses = cls.subclasses()
+        leaf = next(subclasses, cls)
+        second = next(subclasses, None)
+        if second is None:
+            return leaf
+
+        msg = f"""Multiple leaf subclasses found for {cls}.
+Defining multiple leaf subclasses is ambiguous.
+This can happen if more than one leaf subclass is defined
+across all the dependent packages.
+
+Found subclasses:
+{json.dumps([str(subcls) for subcls in (leaf, second, *subclasses)], indent=4)}"""
+        raise RuntimeError(msg)
+
+    @classmethod
+    def concrete_subclasses(cls) -> Iterator[type[Self]]:
+        """Yield all non-abstract subclasses discovered across dependent packages.
+
+        Equivalent to `subclasses()` with abstract classes removed.
+
+        Yields:
+            Non-abstract subclass types.
+        """
+        return discard_abstract_classes(cls.subclasses())
+
+    @classmethod
+    def subclasses(cls) -> Iterator[type[Self]]:
+        """Yield all subclasses discovered across the package ecosystem.
+
+        Searches every installed package that depends on the root package of
+        `dependency_package()`. Intermediate parent classes are discarded,
+        leaving only the outermost leaf-level subclasses.
+
+        Yields:
+            Subclass types with intermediate parent classes removed.
+        """
+        return discard_parent_classes(
+            discover_subclasses_across_dependencies(
+                cls,
+                package=cls.dependency_package(),
+            )
+        )
+
+    @classmethod
+    def subclasses_sorted(cls, subclasses: Iterable[type[Self]]) -> list[type[Self]]:
+        """Sort the given subclasses using each subclass's `sort_key()`.
+
+        Does not perform any discovery. Pass any iterable of subclass types
+        to produce a deterministically ordered list.
+
+        Args:
+            subclasses: Subclass types to sort.
+
+        Returns:
+            The same subclass types sorted by their `sort_key()`.
+        """
+        return sorted(subclasses, key=lambda subclass: subclass.sort_key())

pyrig_runtime/core/graph.py

@@ -0,0 +1,201 @@
+"""Abstract directed graph foundation with forward and reverse edge traversal."""
+
+import heapq
+from abc import ABC, abstractmethod
+from collections import deque
+from functools import cache
+from typing import Any, Self
+
+
+class DiGraph(ABC):
+    """Abstract directed graph with forward and reverse adjacency tracking.
+
+    Subclasses implement `build` to populate nodes and edges. At construction,
+    `build` is called first; if a `root` node is given, the graph is then pruned
+    to retain only that node and every node that transitively points to it.
+    """
+
+    @classmethod
+    @cache
+    def cached(cls, *args: Any, **kwargs: Any) -> Self:
+        """Return a cached instance, constructing it only on the first call.
+
+        Repeated calls with identical arguments return the same instance
+        without rebuilding the graph.
+
+        Args:
+            *args: Positional arguments forwarded to the constructor.
+            **kwargs: Keyword arguments forwarded to the constructor.
+
+        Returns:
+            The cached graph instance for the given arguments.
+        """
+        return cls(*args, **kwargs)
+
+    def __init__(self, root: str | None = None) -> None:
+        """Build the graph, then prune it to `root` if one is given."""
+        self.root = root
+        self._nodes: set[str] = set()
+        self._edges: dict[str, set[str]] = {}  # node -> outgoing neighbors
+        self._reverse_edges: dict[str, set[str]] = {}  # node -> incoming neighbors
+        self.build()
+        if self.root is not None:
+            self.prune(self.root)
+
+    @abstractmethod
+    def build(self) -> None:
+        """Populate the graph with nodes and edges.
+
+        Called automatically during construction before any optional pruning.
+        Implementations use `add_node` and `add_edge` to define the graph
+        structure.
+        """
+
+    def prune(self, root: str) -> None:
+        """Remove all nodes that are neither root nor an ancestor of root.
+
+        Keeps `root` and all its ancestors (nodes with a directed path to
+        `root`). All other nodes and their associated edges are removed.
+
+        Args:
+            root: The root node to prune around.
+        """
+        keep = self.ancestors(root) | {root}
+        self._nodes = keep
+        self._edges = {n: self._edges[n] & keep for n in keep}
+        self._reverse_edges = {n: self._reverse_edges[n] & keep for n in keep}
+
+    def add_edge(self, source: str, target: str) -> None:
+        """Add a directed edge from source to target.
+
+        Creates both nodes if they do not already exist.
+
+        Args:
+            source: Edge origin node.
+            target: Edge destination node.
+        """
+        self.add_node(source)
+        self.add_node(target)
+        self._edges[source].add(target)
+        self._reverse_edges[target].add(source)
+
+    def add_node(self, node: str) -> None:
+        """Add a node to the graph. No-op if the node already exists.
+
+        Args:
+            node: Node identifier to add.
+        """
+        self._nodes.add(node)
+        if node not in self._edges:
+            self._edges[node] = set()
+        if node not in self._reverse_edges:
+            self._reverse_edges[node] = set()
+
+    def nodes(self) -> set[str]:
+        """Return all node identifiers currently in the graph."""
+        return self._nodes
+
+    def sorted_ancestors(self, target: str) -> list[str]:
+        """Return all ancestors of the target node sorted in topological order.
+
+        Ancestors are nodes that have a directed path to the target (i.e., nodes
+        that depend on it directly or transitively). The result is sorted so that
+        dependencies appear before their dependents.
+
+        Args:
+            target: Node to find ancestors of.
+
+        Returns:
+            List of ancestor node identifiers, with dependencies first.
+            Returns an empty list if the target is not in the graph.
+
+        Raises:
+            RuntimeError: If the ancestor subgraph contains a cycle, making
+                topological sorting impossible.
+        """
+        return self.topological_sort_subgraph(self.ancestors(target))
+
+    def ancestors(self, target: str) -> set[str]:
+        """Find all nodes that have a directed path to the target node.
+
+        Collects every node that reaches the target directly or transitively.
+        The target itself is excluded from the result.
+
+        Args:
+            target: Node to find ancestors for.
+
+        Returns:
+            Set of all nodes with a directed path to the target, excluding the
+            target itself. Returns an empty set if the target is not in the graph.
+        """
+        visited: set[str] = set()
+        queue: deque[str] = deque(self._reverse_edges.get(target, set()))
+
+        while queue:
+            node = queue.popleft()
+            if node not in visited:
+                visited.add(node)
+                # Iterate directly to avoid creating intermediate set
+                for neighbor in self._reverse_edges.get(node, set()):
+                    if neighbor not in visited:
+                        queue.append(neighbor)
+
+        return visited
+
+    def topological_sort_subgraph(self, nodes: set[str]) -> list[str]:
+        """Sort a subset of nodes in topological order.
+
+        An edge A → B means "A depends on B", so B appears before A in the
+        output. The ordering is deterministic: when multiple nodes are ready to
+        be emitted at the same step, they are emitted in ascending order.
+
+        Only edges whose both endpoints are in `nodes` are considered; edges
+        to or from nodes outside the subset are ignored.
+
+        Args:
+            nodes: The subset of nodes to sort.
+
+        Returns:
+            List of nodes in topological order, with each node's dependencies
+            appearing before the node itself.
+
+        Raises:
+            RuntimeError: If the subgraph contains a cycle, making topological
+                sorting impossible.
+        """
+        # Count outgoing edges (dependencies) for each node in the subgraph
+        # Nodes with 0 outgoing edges have no dependencies
+        out_degree: dict[str, int] = dict.fromkeys(nodes, 0)
+
+        for node in nodes:
+            for dependency in self._edges.get(node, set()):
+                if dependency in nodes:
+                    out_degree[node] += 1
+
+        # Use heapq for O(log n) insertion maintaining sorted order
+        # This replaces O(n log n) sort() + O(n) pop(0) with O(log n) heappop()
+        heap: list[str] = [node for node in nodes if out_degree[node] == 0]
+        heapq.heapify(heap)
+        result: list[str] = []
+
+        while heap:
+            node = heapq.heappop(heap)
+            result.append(node)
+
+            # For each package that depends on this node (reverse edges)
+            for dependent in self._reverse_edges.get(node, set()):
+                if dependent in nodes:
+                    out_degree[dependent] -= 1
+                    if out_degree[dependent] == 0:
+                        heapq.heappush(heap, dependent)
+
+        # Check for cycles
+        if len(result) != len(nodes):
+            msg = (
+                "Graph contains a cycle; topological sort not possible. "
+                "This indicates a circular dependency among the following nodes: "
+                f"{set(nodes) - set(result)}"
+            )
+            raise RuntimeError(msg)
+
+        return result

pyrig_runtime/core/introspection/__init__.py

@@ -0,0 +1,6 @@
+"""Introspection primitives for class, module, and package discovery.
+
+Provides the low-level building blocks that power pyrig's cross-package subclass
+discovery: walking package hierarchies, dynamically importing modules, filtering
+class collections, and locating equivalent module paths across dependent packages.
+"""