try claude - add a basic config and play around with some quality of life changes i was offputting

.claude/settings.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv run pytest:*)",
+      "Bash(git add:*)",
+      "Bash(uv run mypy:*)",
+      "Bash(uv run pre-commit:*)"
+
+    ],
+    "deny": []
+  }
+}

.gitignore

@@ -67,3 +67,6 @@ pip-wheel-metadata/
 
 # pytest-benchmark
 .benchmarks/
+
+# Claude Code local settings
+.claude/settings.local.json

.pre-commit-config.yaml

@@ -48,4 +48,4 @@ repos:
     -   id: mypy
         files: ^(src/|testing/)
         args: []
-        additional_dependencies: [pytest]
+        additional_dependencies: [pytest, types-greenlet]

CLAUDE.md

@@ -0,0 +1,50 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Pluggy is a minimalist production-ready plugin system that serves as the core framework for pytest, datasette and devpi.
+It provides hook specification and implementation mechanisms through a plugin manager system.
+
+## Development Commands
+
+### Testing
+- `uv run pytest` - Run all tests, prefer runnign all tests to quickly get feedback
+- `uv run pytest testing/benchmark.py` runs the benchmark tests
+
+### Code Quality
+- `uv run pre-commit run -a` - Run all pre-commit hooks - gives linting and typing errors + corrects files
+- reread files that get fixed by pre-commit
+
+
+## Development process
+
+- always read `src/pluggy/*.py` to get a full picture
+- consider backward compatibility
+- always run all tests
+- always run pre-commit before try to commit
+- prefer running full pre-commit over ruff/mypy alone
+
+
+
+## Core Architecture
+
+### Main Components
+
+- **PluginManager** (`src/pluggy/_manager.py`): Central registry that manages plugins and coordinates hook calls
+- **HookCaller** (`src/pluggy/_hooks.py`): Executes hook implementations with proper argument binding
+- **HookImpl/HookSpec** (`src/pluggy/_hooks.py`): Represent hook implementations and specifications
+- **Result** (`src/pluggy/_result.py`): Handles hook call results and exception propagation
+- **Multicall** (`src/pluggy/_callers.py`): Core execution engine for calling multiple hook implementations
+
+### Package Structure
+- `src/pluggy/` - Main package source
+- `testing/` - Test suite using pytest
+- `docs/` - Sphinx documentation and examples
+- `changelog/` - Towncrier fragments for changelog generation
+
+## Configuration Files
+- `pyproject.toml` - Project metadata, build system, tool configuration (ruff, mypy, setuptools-scm)
+- `tox.ini` - Multi-environment testing configuration
+- `.pre-commit-config.yaml` - Code quality automation (ruff, mypy, flake8, etc.)

pyproject.toml

@@ -35,16 +35,23 @@ readme = {file = "README.rst", content-type = "text/x-rst"}
 requires-python = ">=3.9"
 
 dynamic = ["version"]
+
 [project.optional-dependencies]
-dev = ["pre-commit", "tox"]
-testing = ["pytest", "pytest-benchmark", "coverage"]
+async = ["greenlet"]
+
+[dependency-groups]
+dev = ["pre-commit", "tox", "mypy", "ruff"]
+testing = ["pytest", "pytest-benchmark", "coverage", "greenlet", "types-greenlet"]
+
+
 
 [tool.setuptools]
 packages = ["pluggy"]
 package-dir =  {""="src"}
 package-data = {"pluggy" = ["py.typed"]}
 
 
+
 [tool.ruff.lint]
 extend-select = [
   "I",  # isort
@@ -67,6 +74,9 @@ lines-after-imports = 2
 
 [tool.setuptools_scm]
 
+[tool.uv]
+default-groups = ["dev", "testing"]
+
 [tool.towncrier]
 package = "pluggy"
 package_dir = "src/pluggy"
@@ -107,6 +117,7 @@ template = "changelog/_template.rst"
 
 [tool.mypy]
 mypy_path = "src"
+python="3.9"
 check_untyped_defs = true
 # Hopefully we can set this someday!
 # disallow_any_expr = true

src/pluggy/__init__.py

@@ -3,32 +3,43 @@
     "PluginManager",
     "PluginValidationError",
     "HookCaller",
+    "HistoricHookCaller",
     "HookCallError",
     "HookspecOpts",
     "HookimplOpts",
+    "HookspecConfiguration",
+    "HookimplConfiguration",
     "HookImpl",
     "HookRelay",
     "HookspecMarker",
     "HookimplMarker",
+    "ProjectSpec",
     "Result",
     "PluggyWarning",
     "PluggyTeardownRaisedWarning",
 ]
-from ._hooks import HookCaller
-from ._hooks import HookImpl
-from ._hooks import HookimplMarker
-from ._hooks import HookimplOpts
-from ._hooks import HookRelay
-from ._hooks import HookspecMarker
-from ._hooks import HookspecOpts
+from ._hook_callers import HistoricHookCaller
+from ._hook_callers import HookCaller
+from ._hook_callers import HookImpl
+from ._hook_callers import HookRelay
+from ._hook_config import HookimplConfiguration
+from ._hook_config import HookimplOpts
+from ._hook_config import HookspecConfiguration
+from ._hook_config import HookspecOpts
+from ._hook_markers import HookimplMarker
+from ._hook_markers import HookspecMarker
 from ._manager import PluginManager
 from ._manager import PluginValidationError
+from ._project import ProjectSpec
 from ._result import HookCallError
 from ._result import Result
 from ._warnings import PluggyTeardownRaisedWarning
 from ._warnings import PluggyWarning
 
 
+__version__: str
+
+
 def __getattr__(name: str) -> str:
     if name == "__version__":
         from importlib.metadata import version

src/pluggy/_async.py

@@ -0,0 +1,198 @@
+"""
+Async support for pluggy using greenlets.
+
+This module provides async functionality for pluggy, allowing hook implementations
+to return awaitable objects that are automatically awaited when running in an
+async context.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+from collections.abc import Awaitable
+from collections.abc import Callable
+from collections.abc import Generator
+from typing import Any
+from typing import TYPE_CHECKING
+from typing import TypeVar
+
+
+_T = TypeVar("_T")
+_Y = TypeVar("_Y")
+_S = TypeVar("_S")
+_R = TypeVar("_R")
+
+if TYPE_CHECKING:
+    import greenlet
+
+
+def make_greenlet(func: Callable[..., Any]) -> greenlet.greenlet:
+    """indirection to defer import"""
+    import greenlet
+
+    return greenlet.greenlet(func)
+
+
+class Submitter:
+    # practice we expect te root greenlet to be the key submitter
+    _active_submitter: greenlet.greenlet | None
+
+    def __init__(self) -> None:
+        self._active_submitter = None
+
+    def __repr__(self) -> str:
+        return f"<Submitter active={self._active_submitter is not None}>"
+
+    def maybe_submit(self, coro: Awaitable[_T]) -> _T | Awaitable[_T]:
+        """await an awaitable if active, else return it
+
+        this enables backward compatibility for datasette
+        and https://simonwillison.net/2020/Sep/2/await-me-maybe/
+        """
+        active = self._active_submitter
+        if active is not None:
+            # We're in a greenlet context, switch with the awaitable
+            # The parent will await it and switch back with the result
+            res: _T = active.switch(coro)
+            return res
+        else:
+            return coro
+
+    def require_await(self, coro: Awaitable[_T]) -> _T:
+        """await an awaitable, raising an error if not in async context
+
+        this is for cases where async context is required
+        """
+        active = self._active_submitter
+        if active is not None:
+            # Switch to the active submitter greenlet with the awaitable
+            # The active submitter will await it and switch back with the result
+            res: _T = active.switch(coro)
+            return res
+        else:
+            raise RuntimeError("require_await called outside of async context")
+
+    async def run(self, sync_func: Callable[[], _T]) -> _T:
+        """Run a synchronous function with async support."""
+        try:
+            import greenlet
+        except ImportError:
+            raise RuntimeError("greenlet is required for async support")
+
+        if self._active_submitter is not None:
+            raise RuntimeError("Submitter is already active")
+
+        # Set the current greenlet as the main async context
+        main_greenlet = greenlet.getcurrent()
+        result: _T | None = None
+        exception: BaseException | None = None
+
+        def greenlet_func() -> None:
+            nonlocal result, exception
+            try:
+                result = sync_func()
+            except BaseException as e:
+                exception = e
+
+        # Create the worker greenlet
+        worker_greenlet = greenlet.greenlet(greenlet_func)
+        # Set the active submitter to the main greenlet so maybe_submit can switch back
+        self._active_submitter = main_greenlet
+
+        try:
+            # Switch to the worker greenlet and handle any awaitables it passes back
+            awaitable = worker_greenlet.switch()
+            while awaitable is not None:
+                # Await the awaitable and send the result back to the greenlet
+                awaited_result = await awaitable
+                awaitable = worker_greenlet.switch(awaited_result)
+        except Exception as e:
+            # If something goes wrong, try to send the exception to the greenlet
+            try:
+                worker_greenlet.throw(e)
+            except BaseException as inner_e:
+                exception = inner_e
+        finally:
+            self._active_submitter = None
+
+        if exception is not None:
+            raise exception
+        if result is None:
+            raise RuntimeError("Function completed without setting result")
+        return result
+
+
+def async_generator_to_sync(
+    async_gen: AsyncGenerator[_Y, _S], submitter: Submitter
+) -> Generator[_Y, _S, None]:
+    """Convert an async generator to a sync generator using a Submitter.
+
+    This helper allows wrapper implementations to use async generators while
+    maintaining compatibility with the sync generator interface expected by
+    the hook system.
+
+    Args:
+        async_gen: The async generator to convert
+        submitter: The Submitter to use for awaiting async operations
+
+    Yields:
+        Values from the async generator
+
+    Returns:
+        None (async generators don't return values)
+
+    Example:
+        async def my_async_wrapper():
+            yield  # Setup phase
+            result = await some_async_operation()
+
+        # In a wrapper hook implementation:
+        def my_wrapper_hook():
+            async_gen = my_async_wrapper()
+            gen = async_generator_to_sync(async_gen, submitter)
+            try:
+                while True:
+                    value = next(gen)
+                    yield value
+            except StopIteration:
+                return
+    """
+    try:
+        # Start the async generator
+        value = submitter.require_await(async_gen.__anext__())
+
+        while True:
+            try:
+                # Yield the value and get the sent value
+                sent_value = yield value
+
+                # Send the value to the async generator and get the next value
+                try:
+                    value = submitter.require_await(async_gen.asend(sent_value))
+                except StopAsyncIteration:
+                    # Async generator completed
+                    return
+
+            except GeneratorExit:
+                # Generator is being closed, close the async generator
+                try:
+                    submitter.require_await(async_gen.aclose())
+                except StopAsyncIteration:
+                    pass
+                raise
+
+            except BaseException as exc:
+                # Exception was thrown into the generator,
+                #  throw it into the async generator
+                try:
+                    value = submitter.require_await(async_gen.athrow(exc))
+                except StopAsyncIteration:
+                    # Async generator completed
+                    return
+                except StopIteration as sync_stop_exc:
+                    # Re-raise StopIteration as it was passed through
+                    raise sync_stop_exc
+
+    except StopAsyncIteration:
+        # Async generator completed normally
+        return