Add CLAUDE.md with development guidance

also add uv based tooling to ease things

Co-Authored-By: Claude <[email protected]>

- add ruff/mypy
- allow claude to run some commands directly

Author: RonnyPfannschmidt

.claude/settings.json

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

.gitignore

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

CLAUDE.md

@@ -0,0 +1,64 @@
+# 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
+- `pytest` - Run all tests
+- `pytest testing/test_specific.py` - Run specific test file
+- `tox` - Run tests across multiple Python versions (py39, py310, py311, py312, py313, pypy3)
+- `tox -e py39` - Run tests on specific Python version
+- `tox -e benchmark` - Run benchmarks
+- `tox -e py39-pytestmain` - Test against pytest main branch
+
+### Code Quality
+- `ruff check` - Run linting with Ruff
+- `ruff format` - Format code with Ruff
+- `uv run mypy src/` - Type checking with mypy
+- `pre-commit run --all-files` - Run all pre-commit hooks
+
+### Documentation
+- `tox -e docs` - Build documentation
+- `python scripts/towncrier-draft-to-file.py` - Generate changelog draft to verify
+
+### Release
+- `tox -e release VERSION` - Create release (requires version argument)
+
+## 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
+
+### Key Concepts
+- **Hook Specifications**: Define the interface (`@hookspec` decorator)
+- **Hook Implementations**: Provide the actual functionality (`@hookimpl` decorator)
+- **Plugin Registration**: Plugins are registered with the PluginManager
+- **Hook Calling**: The manager coordinates calls to all registered 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.)
+
+## Testing Notes
+- Tests are located in `testing/` directory
+- Uses pytest with coverage reporting
+- Benchmark tests in `testing/benchmark.py`
+- Minimum pytest version: 8.0
+- Test configuration in `[pytest]` section of `tox.ini`

pyproject.toml

@@ -35,10 +35,11 @@ readme = {file = "README.rst", content-type = "text/x-rst"}
 requires-python = ">=3.9"
 
 dynamic = ["version"]
-[project.optional-dependencies]
-dev = ["pre-commit", "tox"]
+[dependency-groups]
+dev = ["pre-commit", "tox", "mypy", "ruff"]
 testing = ["pytest", "pytest-benchmark", "coverage"]
 
+
 [tool.setuptools]
 packages = ["pluggy"]
 package-dir =  {""="src"}
@@ -67,6 +68,9 @@ lines-after-imports = 2
 
 [tool.setuptools_scm]
 
+[tool.uv]
+default-groups = ["dev", "testing"]
+
 [tool.towncrier]
 package = "pluggy"
 package_dir = "src/pluggy"

tox.ini

@@ -9,7 +9,7 @@ commands=
 setenv=
   _PYTEST_SETUP_SKIP_PLUGGY_DEP=1
   coverage: _PLUGGY_TOX_CMD=coverage run -m pytest
-extras=testing
+dependency_groups=testing
 deps=
   coverage: coverage
   pytestmain: git+https://github.com/pytest-dev/pytest.git@main