pyrig-runtime 2.1.2__tar.gz → 2.2.1__tar.gz

{pyrig_runtime-2.1.2 → pyrig_runtime-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyrig-runtime
-Version: 2.1.2
+Version: 2.2.1
 Summary: Runtime dependency and library for projects built with pyrig.
 Keywords: pyrig
 Author: Winipedia

{pyrig_runtime-2.1.2 → pyrig_runtime-2.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pyrig-runtime"
-version = "2.1.2"
+version = "2.2.1"
 description = "Runtime dependency and library for projects built with pyrig."
 readme = "README.md"
 requires-python = ">=3.12"

pyrig_runtime-2.2.1/src/pyrig_runtime/__init__.py

@@ -0,0 +1,5 @@
+"""Runtime support library for pyrig.
+
+Contains code that a project needs at runtime, such as CLI
+invocation.
+"""

{pyrig_runtime-2.1.2 → pyrig_runtime-2.2.1}/src/pyrig_runtime/core/dependencies/discovery.py

@@ -9,8 +9,8 @@ from types import ModuleType
 from pyrig_runtime.core.dependencies.graph import DependencyGraph
 from pyrig_runtime.core.introspection.modules import (
     import_modules,
+    replace_root_module,
     root_module,
-    safe_import_module,
 )
 from pyrig_runtime.core.introspection.packages import (
     discover_subclasses_across_package,
@@ -79,10 +79,7 @@ def discover_equivalent_modules_across_dependents(
     )
 
     for package in deps_depending_on_dep(dependency):
-        package_module_name = module.__name__.replace(
-            dependency.__name__, package.__name__, 1
-        )
-        package_module = safe_import_module(package_module_name, default=None)
+        package_module = replace_root_module(module, package.__name__, default=None)
         if package_module is not None:
             yield package_module
 

{pyrig_runtime-2.1.2 → pyrig_runtime-2.2.1}/src/pyrig_runtime/core/dependencies/subclass.py

@@ -114,7 +114,7 @@ class DependencySubclass(metaclass=DependencySubclassMeta):
             subclasses are found. May be abstract.
 
         Raises:
-            RuntimeError: If more than one subclass is discovered across
+            RuntimeError: If more than one leaf subclass is discovered across
                 the dependent packages.
         """
         subclasses = cls.subclasses()

{pyrig_runtime-2.1.2 → pyrig_runtime-2.2.1}/src/pyrig_runtime/core/graph.py

@@ -105,10 +105,10 @@ class DiGraph(ABC):
 
         Returns:
             List of ancestor node identifiers in topological order.
-            Returns an empty list if the target has no ancestors or is not
-            in the graph.
+            Returns an empty list if the target has no ancestors.
 
         Raises:
+            KeyError: If the target node is not in the graph.
             RuntimeError: If the ancestor subgraph contains a cycle, making
                 topological sorting impossible.
         """
@@ -124,16 +124,19 @@ class DiGraph(ABC):
 
         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.
+            target itself.
+
+        Raises:
+            KeyError: If the target node is not in the graph.
         """
         visited: set[str] = set()
-        queue: deque[str] = deque(self.reverse_edges.get(target, set()))
+        queue: deque[str] = deque(self.reverse_edges[target])
 
         while queue:
             node = queue.popleft()
             if node not in visited:
                 visited.add(node)
-                for neighbor in self.reverse_edges.get(node, set()):
+                for neighbor in self.reverse_edges[node]:
                     if neighbor not in visited:
                         queue.append(neighbor)
 
@@ -164,7 +167,7 @@ class DiGraph(ABC):
         out_degree: dict[str, int] = dict.fromkeys(nodes, 0)
 
         for node in nodes:
-            for dependency in self.edges.get(node, set()):
+            for dependency in self.edges[node]:
                 if dependency in nodes:
                     out_degree[node] += 1
 
@@ -176,7 +179,7 @@ class DiGraph(ABC):
             node = heapq.heappop(heap)
             result.append(node)
 
-            for dependent in self.reverse_edges.get(node, set()):
+            for dependent in self.reverse_edges[node]:
                 if dependent in nodes:
                     out_degree[dependent] -= 1
                     if out_degree[dependent] == 0:

{pyrig_runtime-2.1.2 → pyrig_runtime-2.2.1}/src/pyrig_runtime/core/introspection/functions.py

@@ -24,7 +24,10 @@ def module_functions(
     Yields:
         Each function defined in `module`.
     """
-    for _name, function in obj_members(module):
-        func = unwrap_obj(function)
-        if inspect.isfunction(func) and inspect.getmodule(func) is module:
+    for _name, func in obj_members(module):
+        unwrapped_func = unwrap_obj(func)
+        if (
+            inspect.isfunction(unwrapped_func)
+            and inspect.getmodule(unwrapped_func) is module
+        ):
             yield func

pyrig_runtime-2.2.1/src/pyrig_runtime/core/introspection/modules.py

@@ -0,0 +1,197 @@
+"""Utilities for Python modules."""
+
+import logging
+from collections.abc import Iterable, Iterator
+from importlib import import_module
+from pkgutil import iter_modules as pkgutil_iter_modules
+from types import ModuleType
+from typing import Any, overload
+
+from pyrig_runtime.core.constants import MISSING
+from pyrig_runtime.core.wrappers import safe_call
+
+logger = logging.getLogger(__name__)
+
+
+@overload
+def replace_root_module(module: ModuleType, root: str) -> ModuleType: ...
+@overload
+def replace_root_module[T](
+    module: ModuleType, root: str, default: T
+) -> ModuleType | T: ...
+def replace_root_module(
+    module: ModuleType, root: str, default: Any = MISSING
+) -> ModuleType | Any:
+    """Import the equivalent module under a different root package.
+
+    Replaces the first dotted segment of `module`'s name with `root` and
+    attempts to import the resulting module name. Later segments are left
+    untouched even if they happen to share the old root's name.
+
+    Args:
+        module: Module whose root segment should be swapped.
+        root: Root package name to substitute in.
+        default: Value to return if the import fails. If not provided,
+            the exception propagates unchanged.
+
+    Returns:
+        The imported module at the equivalent sub-path under `root`, or
+        `default` if the import fails and `default` was provided.
+
+    Example:
+        >>> from some_package.subpackage import module
+        >>> replace_root_module(module, "other_package")
+        <module 'other_package.subpackage.module'
+         from '/path/to/other_package/subpackage/module.py'>
+    """
+    return safe_import_module(replace_root_module_name(module, root), default=default)
+
+
+def replace_root_module_name(module: ModuleType, root: str) -> str:
+    """Return the equivalent module name under a different root package.
+
+    Replaces the first dotted segment of `module.__name__` with `root`. Later
+    segments are left untouched even if they happen to share the old root's
+    name.
+
+    Args:
+        module: Module whose root segment should be swapped.
+        root: Root package name to substitute in.
+
+    Returns:
+        The equivalent dotted module name under `root`.
+
+    Example:
+        >>> replace_root_module_name(module, "other_package")
+        'other_package.subpackage.module'
+    """
+    return module.__name__.replace(root_module_name(module), root, 1)
+
+
+def root_module(module: ModuleType) -> ModuleType:
+    """Import and return the top-level package of the given module.
+
+    For a module named `"package.subpackage.module"`, the module corresponding
+    to `"package"` is returned. For a top-level module with no dots in its name,
+    the module for that same name is returned.
+
+    Args:
+        module: Module to resolve the root package for.
+
+    Returns:
+        The module corresponding to the first segment of the dotted name.
+
+    Example:
+        >>> from some_package.subpackage import module
+        >>> root_module(module)
+        <module 'some_package' from '/path/to/some_package/__init__.py'>
+    """
+    return import_module(root_module_name(module))
+
+
+def root_module_name(module: ModuleType) -> str:
+    """Return the name of the top-level package of the given module.
+
+    For a module named `"package.subpackage.module"`, the string `"package"`
+    is returned. For a top-level module with no dots in its name, that same
+    name is returned.
+
+    Args:
+        module: Module to resolve the root package name for.
+
+    Returns:
+        The first segment of the dotted module name.
+
+    Example:
+        >>> from some_package.subpackage import module
+        >>> root_module_name(module)
+        'some_package'
+    """
+    return module.__name__.split(".", 1)[0]
+
+
+@overload
+def safe_import_module(
+    module_name: str,
+    package: str | None = ...,
+    *,
+    exceptions: tuple[type[BaseException], ...] = ...,
+) -> ModuleType: ...
+@overload
+def safe_import_module[T](
+    module_name: str,
+    package: str | None = ...,
+    *,
+    default: T,
+    exceptions: tuple[type[BaseException], ...] = ...,
+) -> ModuleType | T: ...
+def safe_import_module(
+    module_name: str,
+    package: str | None = None,
+    *,
+    default: Any = MISSING,
+    exceptions: tuple[type[BaseException], ...] = (Exception,),
+) -> ModuleType | Any:
+    """Import a module by name, with an optional fallback on failure.
+
+    Any `Exception` raised during import — not just `ImportError` — is
+    handled, so errors at module level (e.g., `ValueError` raised on
+    import) are also covered.
+
+    Args:
+        module_name: Dotted module name (e.g., `"package.subpackage.module"`).
+        package: Anchor package for relative imports, forwarded to `import_module`.
+        default: Value to return if the import raises. If not provided,
+            the exception propagates unchanged.
+        exceptions: Tuple of exception types to catch. Defaults to `(Exception,)`.
+
+    Returns:
+        The imported module, or `default` if an exception is raised and
+        `default` was provided.
+    """
+    return safe_call(
+        import_module,
+        module_name,
+        package,
+        default=default,
+        exceptions=exceptions,
+    )
+
+
+def import_modules(module_names: Iterable[str]) -> Iterator[ModuleType]:
+    """Import multiple modules by name, lazily.
+
+    Modules are imported on demand as the result is iterated, not eagerly.
+
+    Args:
+        module_names: Dotted module names to import.
+
+    Yields:
+        Each imported module, in the order the names are iterated.
+    """
+    return (import_module(name) for name in module_names)
+
+
+def iter_modules(package: ModuleType) -> Iterator[tuple[ModuleType, bool]]:
+    """Import and yield each direct child of a package, in discovery order.
+
+    Only the immediate children are visited; nested sub-packages are not
+    recursed into.
+
+    Args:
+        package: Package to iterate. Must have a `__path__` attribute
+            (i.e., must be a package, not a plain module).
+
+    Yields:
+        `(module, is_package)` pairs where `module` is the imported child and
+        `is_package` is `True` when the child is itself a sub-package.
+
+    Note:
+        Importing each child is a deliberate side effect — any module-level
+        code in those children executes on demand as the iterator is consumed.
+    """
+    for _finder, name, is_package in pkgutil_iter_modules(
+        package.__path__, prefix=package.__name__ + "."
+    ):
+        mod = import_module(name)
+        yield mod, is_package

{pyrig_runtime-2.1.2 → pyrig_runtime-2.2.1}/src/pyrig_runtime/core/strings.py

@@ -68,6 +68,9 @@ def fully_qualified_name(obj: MethodType | FunctionType | type) -> str:
 def distribution_summary(name: str) -> str:
     """Return the summary recorded in an installed distribution's metadata.
 
+    This function assumes that the package is installed and its
+    metadata has a "Summary" field.
+
     Args:
         name: Name of an installed distribution (e.g. `"requests"`).
 

{pyrig_runtime-2.1.2 → pyrig_runtime-2.2.1}/src/pyrig_runtime/core/wrappers.py

@@ -14,8 +14,6 @@ def safe_call[T, D](
     exceptions: tuple[type[BaseException], ...] = ...,
     **kwargs: Any,
 ) -> T | D: ...
-
-
 @overload
 def safe_call[T](
     func: Callable[..., T],
@@ -23,8 +21,6 @@ def safe_call[T](
     exceptions: tuple[type[BaseException], ...] = ...,
     **kwargs: Any,
 ) -> T: ...
-
-
 def safe_call(
     func: Callable[..., Any],
     *args: Any,

{pyrig_runtime-2.1.2 → pyrig_runtime-2.2.1}/src/pyrig_runtime/rig/cli/cli/cli.py

@@ -15,8 +15,7 @@ from pyrig_runtime.core.dependencies.discovery import (
 from pyrig_runtime.core.dependencies.subclass import DependencySubclass
 from pyrig_runtime.core.introspection.functions import module_functions
 from pyrig_runtime.core.introspection.modules import (
-    replace_root_module_name,
-    safe_import_module,
+    replace_root_module,
 )
 from pyrig_runtime.core.strings import (
     distribution_summary,
@@ -144,14 +143,15 @@ class CLI(DependencySubclass):
         level -= step * verbose
         level += step * quiet
 
-        verbose_timestamps = 3
-        verbose_modules = 2
+        verbose_names = 1
+        verbose_modules = verbose_names + 1
+        verbose_timestamps = verbose_modules + 1
 
         if verbose >= verbose_timestamps:
             fmt = "%(asctime)s %(levelname)s [%(name)s] %(message)s"
         elif verbose == verbose_modules:
             fmt = "%(levelname)s [%(name)s] %(message)s"
-        elif verbose == 1:
+        elif verbose == verbose_names:
             fmt = "%(levelname)s: %(message)s"
         else:
             fmt = "%(message)s"
@@ -171,10 +171,9 @@ class CLI(DependencySubclass):
             If the invoking project's subcommands module cannot be imported,
             registration is silently skipped.
         """
-        subcommands_module_name = replace_root_module_name(
-            subcommands, root_module_name=self.package_name()
+        subcommands_module = replace_root_module(
+            subcommands, root=self.package_name(), default=None
         )
-        subcommands_module = safe_import_module(subcommands_module_name, default=None)
 
         if subcommands_module is None:
             return
@@ -258,10 +257,10 @@ class CLI(DependencySubclass):
         return kebab_to_snake_case(self.project_name())
 
     def project_name(self) -> str:
-        """Return the basename of `sys.argv[0]` as the invoking project name.
+        """Return the stem of `sys.argv[0]` as the invoking project name.
 
         When a project is invoked through a registered console-script entry point
         (e.g. `uv run my-project`), `sys.argv[0]` is the path to that script, so
-        its basename is the project name as it was registered.
+        its stem is the project name as it was registered.
         """
-        return Path(sys.argv[0]).name
+        return Path(sys.argv[0]).stem

pyrig_runtime-2.1.2/src/pyrig_runtime/__init__.py

@@ -1,5 +0,0 @@
-"""Runtime support library for pyrig.
-
-Contains code that a project needs at runtime, such as automatic CLI
-invocation.
-"""

pyrig_runtime-2.1.2/src/pyrig_runtime/core/introspection/modules.py

@@ -1,126 +0,0 @@
-"""Utilities for Python modules."""
-
-import logging
-from collections.abc import Iterable, Iterator
-from importlib import import_module
-from pkgutil import iter_modules as pkgutil_iter_modules
-from types import ModuleType
-from typing import Any
-
-from pyrig_runtime.core.constants import MISSING
-from pyrig_runtime.core.wrappers import safe_call
-
-logger = logging.getLogger(__name__)
-
-
-def root_module(module: ModuleType) -> ModuleType:
-    """Import and return the top-level package of the given module.
-
-    For a module named `"package.subpackage.module"`, the module corresponding
-    to `"package"` is returned. For a top-level module with no dots in its name,
-    the module for that same name is returned.
-
-    Args:
-        module: Module to resolve the root package for.
-
-    Returns:
-        The module corresponding to the first segment of the dotted name.
-    """
-    return import_module(module.__name__.split(".")[0])
-
-
-def safe_import_module(
-    module_name: str,
-    *args: Any,
-    default: Any = MISSING,
-    exceptions: tuple[type[BaseException], ...] = (Exception,),
-    **kwargs: Any,
-) -> ModuleType | Any:
-    """Import a module by name, with an optional fallback on failure.
-
-    Any `Exception` raised during import — not just `ImportError` — is
-    handled, so errors at module level (e.g., `ValueError` raised on
-    import) are also covered.
-
-    Args:
-        module_name: Dotted module name (e.g., `"package.subpackage.module"`).
-        *args: Positional arguments forwarded to `import_module`.
-        default: Value to return if the import raises. If not provided,
-            the exception propagates unchanged.
-        exceptions: Tuple of exception types to catch. Defaults to `(Exception,)`.
-        **kwargs: Keyword arguments forwarded to `import_module`.
-
-    Returns:
-        The imported module, or `default` if an exception is raised and
-        `default` was provided.
-    """
-    return safe_call(
-        import_module,
-        module_name,
-        *args,
-        **kwargs,
-        default=default,
-        exceptions=exceptions,
-    )
-
-
-def replace_root_module_name(module: ModuleType, root_module_name: str) -> str:
-    """Replace the root package segment in a module's fully qualified name.
-
-    Only the first segment is replaced; later segments are left untouched even
-    if they happen to share the old root's name.
-
-    Args:
-        module: Module whose name to transform.
-        root_module_name: Root package name to substitute in.
-
-    Returns:
-        The module name with its first dotted segment replaced.
-
-    Example:
-        >>> from types import ModuleType
-        >>> mod = ModuleType("some_package.sub.module")
-        >>> replace_root_module_name(mod, "my_project")
-        'my_project.sub.module'
-    """
-    module_current_start = module.__name__.split(".")[0]
-    return module.__name__.replace(module_current_start, root_module_name, 1)
-
-
-def import_modules(module_names: Iterable[str]) -> Iterator[ModuleType]:
-    """Import multiple modules by name, lazily.
-
-    Modules are imported on demand as the result is iterated, not eagerly.
-
-    Args:
-        module_names: Dotted module names to import.
-
-    Yields:
-        Each imported module, in the order the names are iterated.
-    """
-    return (import_module(name) for name in module_names)
-
-
-def iter_modules(package: ModuleType) -> Iterator[tuple[ModuleType, bool]]:
-    """Import and yield each direct child of a package, in discovery order.
-
-    Only the immediate children are visited; nested sub-packages are not
-    recursed into.
-
-    Args:
-        package: Package to iterate. Must have a `__path__` attribute
-            (i.e., must be a package, not a plain module).
-
-    Yields:
-        `(module, is_package)` pairs where `module` is the imported child and
-        `is_package` is `True` when the child is itself a sub-package.
-
-    Note:
-        Importing each child is a deliberate side effect — any module-level
-        code in those children executes on demand as the iterator is consumed.
-    """
-    for _finder, name, is_package in pkgutil_iter_modules(
-        package.__path__, prefix=package.__name__ + "."
-    ):
-        mod = import_module(name)
-        yield mod, is_package