pyspokes 0.1.0a2__tar.gz

pyspokes-0.1.0a2/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.3
+Name: pyspokes
+Version: 0.1.0a2
+Summary: Type-based spoke discovery and resolution for Python applications
+Author: AI Helpers
+Requires-Dist: pyyaml>=6.0.1,<7
+Requires-Dist: typer>=0.20.0,<0.21 ; extra == 'cli'
+Requires-Dist: rich>=13.0.0,<16 ; extra == 'cli'
+Requires-Python: >=3.13
+Provides-Extra: cli
+Description-Content-Type: text/markdown
+
+![Tests](docs/_static/badges/test-badge.svg)
+![Coverage](docs/_static/badges/coverage-badge.svg)
+
+# pyspokes
+
+pyspokes is a plugin system built around one idea: your application is the hub, and every implementation it can plug in is a spoke.
+Packages declare their spokes in a `spokes.yaml` file, and the application asks the hub for the interface it needs.
+
+See the full documentation at <https://ai-helpers.github.io/pyspokes>
+
+## Table of Contents (ToC)
+
+- [pyspokes](#pyspokes)
+  - [Table of Contents (ToC)](#table-of-contents-toc)
+  - [Usage](#usage)
+  - [Getting Started](#getting-started)
+    - [Prerequisites](#prerequisites)
+    - [Install dependencies](#install-dependencies)
+    - [Common tasks](#common-tasks)
+    - [Build the documentation](#build-the-documentation)
+  - [Contributing](#contributing)
+
+## Usage
+
+A package declares its spokes in a `spokes.yaml` file at its root:
+
+```yaml
+# notify_app/spokes.yaml
+- path: channels.EmailNotifier
+  name: email
+
+- path: channels.SlackNotifier
+  name: slack
+  priority: 5
+```
+
+```python
+# notify_app/channels.py
+from notify_app.notifier import Notifier
+
+
+class EmailNotifier(Notifier):
+    def send(self, recipient: str, message: str) -> str:
+        return f"email to {recipient}: {message}"
+
+
+class SlackNotifier(Notifier):
+    def send(self, recipient: str, message: str) -> str:
+        return f"slack DM to {recipient}: {message}"
+```
+
+Once the package is installed, the application asks the hub for the interface and never imports
+an implementation:
+
+```python
+from notify_app.notifier import Notifier
+from pyspokes import get_spoke, get_spokes
+
+notifier = get_spoke(Notifier)                 # highest priority: SlackNotifier
+print(notifier.send("ada", "build finished"))  # slack DM to ada: build finished
+
+email = get_spoke(Notifier, name="email")      # pick one by name
+channels = get_spokes(Notifier)                # all of them, highest priority first
+```
+
+Adding a channel means installing a package that ships a `spokes.yaml`; the code above does not
+change. The [quickstart](https://ai-helpers.github.io/pyspokes/quickstart.html) walks through the
+whole example.
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.13+
+- [uv](https://docs.astral.sh/uv/)
+
+### Install dependencies
+
+```bash
+uv sync --all-groups
+```
+
+### Common tasks
+
+Day-to-day commands are exposed as make tasks (run `make help` to list them all):
+
+```bash
+make check-tests     # run the unit tests with pytest
+make checkers        # run all the checkers (lock, format, quality, types, coverage)
+make formatters      # format the sources and tests with ruff
+make badges          # regenerate the test and coverage badges shown above
+make documenters     # build the documentation
+```
+
+### Build the documentation
+
+The documentation is built with [Sphinx](https://www.sphinx-doc.org/) and the
+[furo](https://github.com/pradyunsg/furo) theme, and is deployed to GitHub Pages
+on every push to `main`.
+
+```bash
+make documenters
+```
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for the development setup,
+the checks to run before pushing, and the coding conventions.

pyspokes-0.1.0a2/README.md

@@ -0,0 +1,108 @@
+![Tests](docs/_static/badges/test-badge.svg)
+![Coverage](docs/_static/badges/coverage-badge.svg)
+
+# pyspokes
+
+pyspokes is a plugin system built around one idea: your application is the hub, and every implementation it can plug in is a spoke.
+Packages declare their spokes in a `spokes.yaml` file, and the application asks the hub for the interface it needs.
+
+See the full documentation at <https://ai-helpers.github.io/pyspokes>
+
+## Table of Contents (ToC)
+
+- [pyspokes](#pyspokes)
+  - [Table of Contents (ToC)](#table-of-contents-toc)
+  - [Usage](#usage)
+  - [Getting Started](#getting-started)
+    - [Prerequisites](#prerequisites)
+    - [Install dependencies](#install-dependencies)
+    - [Common tasks](#common-tasks)
+    - [Build the documentation](#build-the-documentation)
+  - [Contributing](#contributing)
+
+## Usage
+
+A package declares its spokes in a `spokes.yaml` file at its root:
+
+```yaml
+# notify_app/spokes.yaml
+- path: channels.EmailNotifier
+  name: email
+
+- path: channels.SlackNotifier
+  name: slack
+  priority: 5
+```
+
+```python
+# notify_app/channels.py
+from notify_app.notifier import Notifier
+
+
+class EmailNotifier(Notifier):
+    def send(self, recipient: str, message: str) -> str:
+        return f"email to {recipient}: {message}"
+
+
+class SlackNotifier(Notifier):
+    def send(self, recipient: str, message: str) -> str:
+        return f"slack DM to {recipient}: {message}"
+```
+
+Once the package is installed, the application asks the hub for the interface and never imports
+an implementation:
+
+```python
+from notify_app.notifier import Notifier
+from pyspokes import get_spoke, get_spokes
+
+notifier = get_spoke(Notifier)                 # highest priority: SlackNotifier
+print(notifier.send("ada", "build finished"))  # slack DM to ada: build finished
+
+email = get_spoke(Notifier, name="email")      # pick one by name
+channels = get_spokes(Notifier)                # all of them, highest priority first
+```
+
+Adding a channel means installing a package that ships a `spokes.yaml`; the code above does not
+change. The [quickstart](https://ai-helpers.github.io/pyspokes/quickstart.html) walks through the
+whole example.
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.13+
+- [uv](https://docs.astral.sh/uv/)
+
+### Install dependencies
+
+```bash
+uv sync --all-groups
+```
+
+### Common tasks
+
+Day-to-day commands are exposed as make tasks (run `make help` to list them all):
+
+```bash
+make check-tests     # run the unit tests with pytest
+make checkers        # run all the checkers (lock, format, quality, types, coverage)
+make formatters      # format the sources and tests with ruff
+make badges          # regenerate the test and coverage badges shown above
+make documenters     # build the documentation
+```
+
+### Build the documentation
+
+The documentation is built with [Sphinx](https://www.sphinx-doc.org/) and the
+[furo](https://github.com/pradyunsg/furo) theme, and is deployed to GitHub Pages
+on every push to `main`.
+
+```bash
+make documenters
+```
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for the development setup,
+the checks to run before pushing, and the coding conventions.

pyspokes-0.1.0a2/pyproject.toml

@@ -0,0 +1,75 @@
+[project]
+name = "pyspokes"
+version = "0.1.0a2"
+description = "Type-based spoke discovery and resolution for Python applications"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = ["pyyaml>=6.0.1,<7"]
+
+[[project.authors]]
+name = "AI Helpers"
+
+[project.optional-dependencies]
+cli = [
+    "typer>=0.20.0,<0.21",
+    "rich>=13.0.0,<16",
+]
+
+[project.scripts]
+pyspokes = "pyspokes.cli:main"
+
+[dependency-groups]
+dev = [
+    "ruff>=0.8.2,<0.9",
+    "mypy>=1.13,<2",
+    "types-pyyaml>=6.0.12",
+]
+test = [
+    "pyspokes[cli]",
+    "pytest>=8.3.4,<9",
+    "coverage>=7.11.0,<8",
+    "anybadge>=1.16.0,<2",
+]
+docs = [
+    "sphinx>=8.2,<9",
+    "furo>=2024.8.6",
+    "myst-parser>=4.0,<5",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+files = ["src"]
+check_untyped_defs = true
+
+[tool.ruff]
+line-length = 150
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "W",
+    "F",
+    "I",
+    "B",
+    "C4",
+    "N",
+    "D",
+    "UP",
+]
+ignore = [
+    "C901",
+    "W191",
+    "D401",
+    "D205",
+    "D100",
+    "D104",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "pep257"
+
+[build-system]
+requires = ["uv_build>=0.8.0,<1"]
+build-backend = "uv_build"

pyspokes-0.1.0a2/pyproject.toml.orig

@@ -0,0 +1,75 @@
+[project]
+name = "pyspokes"
+version = "0.1.0a2"
+description = "Type-based spoke discovery and resolution for Python applications"
+authors = [{ name = "AI Helpers" }]
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "pyyaml>=6.0.1,<7",
+]
+
+[project.optional-dependencies]
+cli = [
+    "typer>=0.20.0,<0.21",
+    "rich>=13.0.0,<16",
+]
+
+[project.scripts]
+pyspokes = "pyspokes.cli:main"
+
+[dependency-groups]
+dev = [
+    "ruff>=0.8.2,<0.9",
+    "mypy>=1.13,<2",
+    "types-pyyaml>=6.0.12",
+]
+test = [
+    "pyspokes[cli]",
+    "pytest>=8.3.4,<9",
+    "coverage>=7.11.0,<8",
+    "anybadge>=1.16.0,<2",
+]
+docs = [
+    "sphinx>=8.2,<9",
+    "furo>=2024.8.6",
+    "myst-parser>=4.0,<5",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+files = ["src"]
+check_untyped_defs = true
+
+[tool.ruff]
+line-length = 150
+
+[tool.ruff.lint]
+select = [
+    "E", # pycodestyle errors
+    "W", # pycodestyle warnings
+    "F", # pyflakes
+    "I", # isort
+    "B", # flake8-bugbear
+    "C4", # flake8-comprehensions
+    "N", # PEP8 naming convetions
+    "D", # pydocstyle
+    "UP", # pyupgrade
+]
+ignore = [
+    "C901", # too complex
+    "W191", # indentation contains tabs
+    "D401", # imperative mood
+    "D205", # 1 blank line required between summary line and description
+    "D100", # Missing docstring in public module
+    "D104", # Missing docstring in public package
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "pep257"
+
+[build-system]
+requires = ["uv_build>=0.8.0,<1"]
+build-backend = "uv_build"

pyspokes-0.1.0a2/src/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-0.1.0a2/src/pyspokes/_constants.py

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

pyspokes-0.1.0a2/src/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-0.1.0a2/src/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-0.1.0a2/src/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()