pyspokes 0.1.0a2__py3-none-any.whl

pyspokes/__init__.py

@@ -0,0 +1,49 @@
+from ._constants import LOGGER_NAME
+from .bindings import SpokeBinding, SpokeDef
+from .exceptions import (
+    PySpokesError,
+    SpokeDefinitionError,
+    SpokeLoadError,
+    SpokeNotFoundError,
+    SpokeRawMismatchError,
+)
+from .hub import (
+    UNNAMED,
+    Hub,
+    disable_discovery,
+    get_resolutions,
+    get_spoke,
+    get_spokes,
+    hub,
+    register_spoke,
+    spokes_by_name,
+    track_resolutions,
+)
+from .resolutions import Resolution
+
+__all__ = [
+    # Resolving and registering spokes
+    "get_spoke",
+    "get_spokes",
+    "register_spoke",
+    "disable_discovery",
+    "spokes_by_name",
+    "UNNAMED",
+    # Resolution tracking
+    "get_resolutions",
+    "track_resolutions",
+    "Resolution",
+    # Types
+    "SpokeDef",
+    "SpokeBinding",
+    "Hub",
+    "hub",
+    # Errors
+    "PySpokesError",
+    "SpokeDefinitionError",
+    "SpokeLoadError",
+    "SpokeNotFoundError",
+    "SpokeRawMismatchError",
+    # Logging
+    "LOGGER_NAME",
+]

pyspokes/_constants.py

@@ -0,0 +1,4 @@
+"""Shared package constants."""
+
+ENV_VARS_PREFIX = "PYSPOKES_"
+LOGGER_NAME = "pyspokes"

pyspokes/bindings.py

@@ -0,0 +1,147 @@
+"""Core spoke definitions and runtime wrappers."""
+
+import importlib
+import inspect
+import logging
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Generic, TypeVar
+
+from ._constants import LOGGER_NAME
+from .exceptions import SpokeLoadError
+
+logger = logging.getLogger(LOGGER_NAME)
+
+
+@dataclass
+class SpokeDef:
+    """One spoke declaration, as written in ``spokes.yaml`` or passed to ``register_spoke``.
+
+    :param path: Location of the class or function, relative to its package.
+    :param name: A label requests can filter on.
+    :param priority: Higher wins when several spokes match the same request.
+    :param raw: Hand out the class or function itself instead of calling it.
+    """
+
+    path: str
+    name: str | None = None
+    priority: int = 1
+    raw: bool = False
+
+
+T = TypeVar("T")
+
+
+class SpokeBinding(Generic[T]):
+    """A declaration bound to the class or function it points to.
+
+    :ivar def_: The declaration.
+    :ivar module: The package that provides the spoke.
+    :ivar class_or_method: The imported class or function.
+    :ivar type_: The type the spoke answers to.
+    """
+
+    def __init__(self, spoke_def: SpokeDef, module: str, class_or_method: type | Callable | None = None):
+        """
+        Create a SpokeBinding instance.
+
+        :param spoke_def: The spoke definition
+        :param module:  The name of the module where the spoke is defined
+        :param class_or_method: Optional direct reference to the class or method (for __main__ module)
+        """
+        self._obj: Any = None
+        self.type_: type[T] | None = None
+        self.class_or_method: Callable[..., Any]
+        self.def_: SpokeDef = spoke_def
+        self.module = module
+
+        names = spoke_def.path.rsplit(".", 1)
+        module = module + ("." + names[0] if len(names) > 1 else "")
+
+        try:
+            start = time.time()
+            if class_or_method is not None:
+                self.class_or_method = class_or_method
+                logger.debug(f"registering {class_or_method} by direct reference")
+            else:
+                self.class_or_method = getattr(importlib.import_module(module), names[-1])
+                logger.debug(f"imported {module} in {time.time() - start:.3f}s")
+            self.type_ = SpokeBinding.get_type(self.class_or_method)
+            obj = None
+            if not self.type_:
+                obj = self.class_or_method()
+
+            if obj is not None:
+                self._obj = obj
+                self.type_ = SpokeBinding.get_type(type(obj))
+                logger.warning(
+                    "%s has no return annotation, so it was called at registration time to find its type. "
+                    "Annotate its return type to defer the call until the spoke is requested.",
+                    self.class_or_method,
+                )
+
+            logger.debug(f"resolved spoke target {self.class_or_method}")
+        except Exception as error:
+            raise SpokeLoadError(f"Cannot import {names[-1]} from {module}: {type(error).__name__}: {error}") from error
+
+    def get(self, singleton: bool = True) -> Any:
+        """Return the spoke's value, building it on first use; a generator yields its next item."""
+        result: Any = None
+        if singleton and self._obj is not None:
+            result = self._obj
+
+        if result is None:
+            result = self.class_or_method if self.def_.raw else self.class_or_method()
+
+        if singleton:
+            self._obj = result
+
+        if inspect.isgenerator(result):
+            return next(result)
+
+        return result
+
+    def matches(self, target_type: type) -> bool:
+        """Return whether this spoke can answer a request for ``target_type``."""
+        if self.type_ == target_type:
+            return True
+        # Special case: if target_type is 'type', match any class
+        if target_type is type and inspect.isclass(self.type_):
+            return True
+        try:
+            spoke_type = SpokeBinding.get_type(self.class_or_method)
+            if spoke_type and inspect.isclass(spoke_type) and inspect.isclass(target_type):
+                return issubclass(spoke_type, target_type)
+        except TypeError:
+            # issubclass raises TypeError for non-class types
+            pass
+        return False
+
+    @staticmethod
+    def get_type(spoke):
+        """Return the type represented by a spoke class, function, or instance."""
+        if inspect.isclass(spoke):
+            return spoke
+        if inspect.isfunction(spoke) or inspect.ismethod(spoke):
+            signature = inspect.signature(spoke)
+            return None if signature.return_annotation is inspect.Signature.empty else signature.return_annotation
+        return type(spoke)
+
+    def __str__(self):
+        """Return the spoke metadata as a formatted string."""
+        return (
+            f"Module: {self.module}\n"
+            f"Class or Method: {self.class_or_method}\n"
+            f"Type: {self.type_}\n"
+            f"Object: {self._obj}\n"
+            f"SpokeBinding Definition:\n"
+            f"  Name: {self.def_.name}\n"
+            f"  Path: {self.def_.path}\n"
+            f"  Priority: {self.def_.priority}\n"
+            f"  Raw: {self.def_.raw}\n"
+        )
+
+    def __repr__(self):
+        """Return the official string representation."""
+        return self.__str__()

pyspokes/cli/__init__.py

@@ -0,0 +1,20 @@
+"""Command-line interface for pyspokes.
+
+The CLI needs the optional ``cli`` extra (``pip install "pyspokes[cli]"``). Nothing in this
+package is imported by the core library, so ``import pyspokes`` never requires it.
+"""
+
+import sys
+
+_CLI_DEPENDENCIES = {"typer", "rich", "click"}
+
+
+def main():
+    """Main entry point for the CLI."""
+    try:
+        from .app import run
+    except ModuleNotFoundError as error:
+        if error.name is None or error.name.split(".")[0] not in _CLI_DEPENDENCIES:
+            raise
+        sys.exit(f"The pyspokes command line needs the 'cli' extra ({error.name} is not installed).\nInstall it with: pip install \"pyspokes[cli]\"")
+    run()

pyspokes/cli/app.py

@@ -0,0 +1,44 @@
+"""Typer application wiring the pyspokes commands together."""
+
+import logging
+from logging import ERROR
+
+import typer
+
+from pyspokes._constants import LOGGER_NAME
+
+from .check import check_spoke as check_spoke_cmd
+from .inventory import inventory as inventory_cmd
+
+cli_app = typer.Typer()
+
+logger = logging.getLogger(LOGGER_NAME)
+if not logger.hasHandlers():
+    handler = logging.StreamHandler()
+    formatter = logging.Formatter("%(asctime)s %(levelname)s %(name)s: %(message)s")
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+
+# Register commands
+cli_app.command()(inventory_cmd)
+cli_app.command(name="check")(check_spoke_cmd)
+
+
+@cli_app.command(name="status")
+def status_cmd(
+    path: str | None = typer.Argument(None, help="Path to scan for spoke invocations. Defaults to current path."),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Enable verbose output"),
+):
+    """Check spoke status (alias for check --format table)."""
+    return check_spoke_cmd(path=path, format="table", verbose=verbose)
+
+
+def run():
+    """Run the CLI application."""
+    # Keep CLI logging quiet without changing the library logger during import.
+    logger.setLevel(ERROR)
+    cli_app()
+
+
+if __name__ == "__main__":
+    run()

pyspokes/cli/check.py

@@ -0,0 +1,179 @@
+"""Check-spoke command for scanning spoke invocations."""
+
+import inspect
+import json
+import os
+import traceback
+from pathlib import Path
+from typing import Annotated, Any, Literal
+
+import typer
+
+from .executor import execute_invocation
+from .scanner import find_spoke_invocations, get_python_files
+
+
+def check_spoke(
+    path: str | None = typer.Argument(None, help="Path to scan for spoke invocations. Defaults to current path."),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show detailed invocation report"),
+    format: Annotated[Literal["json", "table"], typer.Option("--format", "-f", help="Output format: 'json' or 'table'", show_default=True)] = "json",
+):
+    """
+    Scan Python files for spoke retrievals in a given path and report them.
+
+    This command recursively scans Python files in the specified path (or current directory)
+    looking for invocations of get_spoke or get_spokes from pyspokes.
+    For each invocation found, it:
+    - Reports the file, line number, function name, and arguments
+    - Executes the invocation with raw=True to get the actual spoke
+    - Includes the result or any error in the report
+
+    Note: resolving the requested types requires executing the scanned files,
+    so only run this against code you trust.
+    """
+    if path is None:
+        path = os.getcwd()
+
+    scan_path = Path(path)
+    if not scan_path.exists():
+        typer.echo(f"Error: Path '{path}' does not exist.", err=True)
+        raise typer.Exit(code=1)
+
+    report = _build_report(scan_path, verbose=verbose)
+
+    if format == "json":
+        _render_json(report)
+    elif format == "table":
+        _render_table(report, verbose=verbose)
+
+
+def _build_report(scan_path: Path, verbose: bool) -> dict:
+    """Scan for invocations, execute each one, and assemble the report."""
+    invocations = find_spoke_invocations(scan_path)
+
+    report: dict[str, Any] = {
+        "scan_path": str(scan_path),
+        "total_files_scanned": len(get_python_files(scan_path)),
+        "total_invocations": len(invocations),
+        "invocations": [],
+    }
+
+    namespace_cache: dict[str, dict[str, Any]] = {}
+    for inv in invocations:
+        requested_type_docstring = None
+        try:
+            execution_result = execute_invocation(inv, namespace_cache)
+            result = execution_result["result"]
+            had_default = execution_result["had_default"]
+            requested_type = execution_result.get("requested_type")
+            status = "success"
+            used_default = result is None and had_default
+            error = None
+            result_field = (
+                {
+                    "type": "default",
+                    "message": "No spoke found, would use default value",
+                }
+                if used_default
+                else _serialize_result(result)
+            )
+            # Extract docstring from requested type
+            if requested_type is not None:
+                requested_type_docstring = _get_docstring(requested_type)
+        except Exception as e:
+            status = "error"
+            error = {"type": type(e).__name__, "message": str(e)}
+            if verbose:
+                error["traceback"] = traceback.format_exc()
+
+            used_default = False
+            result_field = None
+        # Unified report logic
+        inv_report = {
+            "location": f"{inv['file']}:{inv['line']}",
+            "status": status,
+            "result": result_field,
+            "error": error,
+            "used_default": used_default,
+            "args": inv["args"],
+        }
+        if verbose:
+            inv_report.update({"requested_type_docstring": requested_type_docstring, "function": inv["function"], "local_name": inv["local_name"]})
+        report["invocations"].append(inv_report)
+
+    return report
+
+
+def _render_json(report: dict) -> None:
+    """Print the report as indented JSON."""
+    print(json.dumps(report, indent=2))
+
+
+def _render_table(report: dict, verbose: bool) -> None:
+    """Print the report as a rich table."""
+    from rich.console import Console
+    from rich.table import Table
+
+    console = Console()
+    table = Table(*(["Spoke type", "Required", "Has default", "Name", "Status"] + (["Docstring"] if verbose else [])))
+    for invocation in report["invocations"]:
+        args = invocation.get("args", {})
+        req_spoke = (args.get("positional") or ["N/A"])[0]
+        docstring = invocation.get("requested_type_docstring", "N/A")
+        if docstring is None:
+            docstring = "No docstring"
+        is_required = args.get("keyword", {}).get("required", False)
+        has_default = "default" in args.get("keyword", {})
+        table.add_row(
+            *(
+                [
+                    str(req_spoke),
+                    f"[bold yellow]{str(is_required)}[/bold yellow]" if is_required else str(is_required),
+                    str(has_default),
+                    args.get("keyword", {}).get("name", "N/A"),
+                    f"[bold red]{invocation['status']}[/bold red]"
+                    if invocation["status"] == "error"
+                    else f"[bold green]{invocation['status']}[/bold green]",
+                ]
+                + ([docstring] if verbose else [])
+            )
+        )
+    console.print(table)
+
+
+def _serialize_result(obj: Any) -> Any:
+    """Serialize the result for JSON output. Handles various types that might be returned."""
+    if obj is None:
+        return None
+    if isinstance(obj, list):
+        return [_serialize_result(r) for r in obj]
+    if isinstance(obj, type):
+        return {"type": "class", "name": obj.__name__, "module": obj.__module__, "qualname": obj.__qualname__}
+    elif callable(obj):
+        return {
+            "type": "callable",
+            "name": getattr(obj, "__name__", str(obj)),
+            "module": getattr(obj, "__module__", "unknown"),
+            "qualname": getattr(obj, "__qualname__", str(obj)),
+        }
+    else:
+        return {"type": "object", "class": type(obj).__name__, "module": type(obj).__module__, "repr": repr(obj)}
+
+
+def _get_docstring(obj: Any) -> str | None:
+    """
+    Extract and clean the docstring from an object.
+
+    Returns the docstring if available, otherwise None.
+    Only returns the object's own docstring, not inherited ones.
+    """
+    try:
+        # Use __doc__ directly to avoid getting inherited docstrings
+        # inspect.getdoc() would return parent class docstrings
+        doc = obj.__doc__
+        if doc:
+            # Clean up the docstring like inspect.getdoc() does
+            return inspect.cleandoc(doc)
+        return None
+    except Exception:
+        return None

pyspokes/cli/executor.py

@@ -0,0 +1,246 @@
+"""Execute scanned spoke invocations to verify they resolve.
+
+Note: resolving the types used at a call site requires importing the scanned
+file's dependencies and executing the file itself, so running this against a
+path executes the code found there.
+"""
+
+import ast
+import builtins
+import inspect
+import logging
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from pyspokes._constants import LOGGER_NAME
+from pyspokes.hub import get_spoke, get_spokes
+
+logger = logging.getLogger(LOGGER_NAME)
+
+# Centralized function name mapping
+SPOKE_FUNC_MAP: dict[str, Callable[..., Any]] = {"get_spoke": get_spoke, "get_spokes": get_spokes}
+
+
+def execute_invocation(invocation: dict, namespace_cache: dict[str, dict[str, Any]] | None = None) -> dict[str, Any]:
+    """
+    Execute a spoke invocation with raw=True and no default.
+
+    This recreates the call but ensures raw=True is set and removes the default parameter.
+    Returns a dict with 'result' and 'had_default' keys.
+    Note: Dynamically imports types from the file to resolve custom classes.
+    Pass a ``namespace_cache`` dict to reuse file namespaces across invocations
+    of one scan, so a file with several invocations is only executed once.
+    """
+    func_name = invocation["function"]
+    func = SPOKE_FUNC_MAP.get(func_name)
+    if not func:
+        raise ValueError(f"Unknown function: {func_name}")
+
+    # Copy builtins so evaluated arguments can't leak names into the real builtins module
+    safe_namespace = dict(vars(builtins))
+
+    # Add imports from the file being analyzed
+    if namespace_cache is not None and invocation["file"] in namespace_cache:
+        file_namespace = namespace_cache[invocation["file"]]
+    else:
+        file_namespace = _build_file_namespace(invocation["file"])
+        if namespace_cache is not None:
+            namespace_cache[invocation["file"]] = file_namespace
+    safe_namespace.update(file_namespace)
+
+    # Parse positional arguments
+    args = []
+    requested_type = None  # Track the first argument (requested type)
+    for i, arg_str in enumerate(invocation["args"]["positional"]):
+        try:
+            arg_value = ast.literal_eval(arg_str)
+            args.append(arg_value)
+        except (ValueError, SyntaxError):
+            try:
+                arg_value = eval(arg_str, {"__builtins__": safe_namespace}, safe_namespace)
+                args.append(arg_value)
+                # Capture the first positional argument as the requested type
+                if i == 0:
+                    requested_type = arg_value
+            except Exception as e:
+                raise ValueError(f"Cannot evaluate positional argument '{arg_str}'. " f"Error: {e}") from e
+
+    # Parse keyword arguments
+    kwargs = {}
+    had_default = False
+    original_default = None
+
+    for key, value_str in invocation["args"]["keyword"].items():
+        if key == "default":
+            had_default = True
+            original_default = value_str
+            continue
+        try:
+            kwargs[key] = ast.literal_eval(value_str)
+        except (ValueError, SyntaxError):
+            try:
+                kwargs[key] = eval(value_str, {"__builtins__": safe_namespace}, safe_namespace)
+            except Exception:
+                kwargs[key] = value_str
+
+    kwargs["raw"] = True
+    result = func(*args, **kwargs)
+    return {"result": result, "had_default": had_default, "original_default": original_default, "requested_type": requested_type}
+
+
+def _build_file_namespace(filepath: str) -> dict[str, Any]:
+    """
+    Build a namespace dictionary from the imports in a Python file.
+
+    This allows us to resolve custom types used in get_spoke calls.
+    """
+    import sys
+
+    namespace: dict[str, Any] = {}
+
+    try:
+        with open(filepath, encoding="utf-8") as f:
+            source = f.read()
+
+        tree = ast.parse(source, filename=filepath)
+
+        # Determine the package path for resolving relative imports
+        file_path = Path(filepath).resolve()
+        package_path = _get_package_path(file_path)
+
+        # Add package parent to sys.path temporarily to enable imports
+        path_added = False
+        if package_path and package_path.parent not in [Path(p) for p in sys.path]:
+            sys.path.insert(0, str(package_path.parent))
+            path_added = True
+
+        try:
+            # First, add classes and functions defined in the file itself
+            # We need to actually execute the code to get the class/function objects
+            try:
+                exec_namespace: dict[str, Any] = {}
+                exec(compile(tree, filepath, "exec"), exec_namespace)
+                # Add all classes and functions to namespace
+                for name, obj in exec_namespace.items():
+                    if not name.startswith("_") and (inspect.isclass(obj) or inspect.isfunction(obj)):
+                        namespace[name] = obj
+            except Exception as e:
+                logger.debug(f"Could not execute file to extract classes/functions: {e}")
+
+            for node in ast.walk(tree):
+                # Handle "from module import name" and "from module import name as alias"
+                if isinstance(node, ast.ImportFrom):
+                    module_name = node.module
+
+                    # Handle relative imports
+                    if node.level > 0:
+                        # This is a relative import
+                        module_name = _resolve_relative_import(file_path, package_path, node.level, node.module)
+                        if not module_name:
+                            # Could not resolve relative import
+                            continue
+
+                    if module_name:
+                        try:
+                            module = __import__(module_name, fromlist=[alias.name for alias in node.names])
+                            for alias in node.names:
+                                if alias.name == "*":
+                                    # Skip wildcard imports for safety
+                                    continue
+                                try:
+                                    obj = getattr(module, alias.name)
+                                    local_name = alias.asname if alias.asname else alias.name
+                                    namespace[local_name] = obj
+                                except AttributeError:
+                                    # Name doesn't exist in module, skip
+                                    continue
+                        except (ImportError, ModuleNotFoundError) as e:
+                            # Module can't be imported, skip
+                            logger.debug(f"Could not import {module_name}: {e}")
+                            continue
+
+                # Handle "import module" and "import module as alias"
+                elif isinstance(node, ast.Import):
+                    for alias in node.names:
+                        try:
+                            module = __import__(alias.name)
+                            local_name = alias.asname if alias.asname else alias.name
+                            namespace[local_name] = module
+                        except (ImportError, ModuleNotFoundError):
+                            # Module can't be imported, skip
+                            continue
+        finally:
+            # Clean up sys.path
+            if path_added:
+                sys.path.remove(str(package_path.parent))
+
+    except Exception as e:
+        # If we can't build namespace, just return empty dict
+        logger.debug(f"Could not build namespace for {filepath}: {e}")
+
+    return namespace
+
+
+def _get_package_path(file_path: Path) -> Path:
+    """
+    Get the package path for a Python file by walking up the directory tree
+    until we find a directory without __init__.py.
+    """
+    current = file_path.parent
+    package_root = current
+
+    while current.parent != current:  # Not at filesystem root
+        parent = current.parent
+        init_file = parent / "__init__.py"
+        if not init_file.exists():
+            break
+        package_root = parent
+        current = parent
+
+    return package_root
+
+
+def _resolve_relative_import(file_path: Path, package_path: Path | None, level: int, module: str | None) -> str | None:
+    """
+    Resolve a relative import to an absolute module name.
+
+    Args:
+        file_path: Path to the file containing the import
+        package_path: Root path of the package
+        level: Number of dots in the relative import (1 for ., 2 for .., etc.)
+        module: The module name after the dots (can be None for imports like "from . import foo")
+
+    Returns:
+        Absolute module name, or None if it cannot be resolved
+    """
+    if not package_path:
+        return None
+
+    # Start from the directory containing the file
+    current = file_path.parent
+
+    # Go up 'level' directories (level 1 means current package, level 2 means parent, etc.)
+    for _ in range(level - 1):
+        if current.parent == current:  # At filesystem root
+            return None
+        current = current.parent
+
+    # Build the module path from the package root
+    try:
+        relative_to_package = current.relative_to(package_path.parent)
+        parts = list(relative_to_package.parts)
+
+        # Add the module name if provided
+        if module:
+            parts.append(module)
+
+        # Convert path parts to module name
+        if parts:
+            return ".".join(parts)
+        else:
+            # This shouldn't happen, but return package name as fallback
+            return package_path.name if package_path else None
+    except ValueError:
+        # current is not relative to package_path.parent
+        return None