|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +Pluggy is a minimalist production-ready plugin system that serves as the core framework for pytest, datasette and devpi. |
| 8 | +It provides hook specification and implementation mechanisms through a plugin manager system. |
| 9 | + |
| 10 | +## Development Commands |
| 11 | + |
| 12 | +### Testing |
| 13 | +- `pytest` - Run all tests |
| 14 | +- `pytest testing/test_specific.py` - Run specific test file |
| 15 | +- `tox` - Run tests across multiple Python versions (py39, py310, py311, py312, py313, pypy3) |
| 16 | +- `tox -e py39` - Run tests on specific Python version |
| 17 | +- `tox -e benchmark` - Run benchmarks |
| 18 | +- `tox -e py39-pytestmain` - Test against pytest main branch |
| 19 | + |
| 20 | +### Code Quality |
| 21 | +- `ruff check` - Run linting with Ruff |
| 22 | +- `ruff format` - Format code with Ruff |
| 23 | +- `mypy src/` - Type checking with mypy |
| 24 | +- `pre-commit run --all-files` - Run all pre-commit hooks |
| 25 | + |
| 26 | +### Documentation |
| 27 | +- `tox -e docs` - Build documentation |
| 28 | +- `python scripts/towncrier-draft-to-file.py` - Generate changelog draft to verify |
| 29 | + |
| 30 | +### Release |
| 31 | +- `tox -e release VERSION` - Create release (requires version argument) |
| 32 | + |
| 33 | +## Core Architecture |
| 34 | + |
| 35 | +### Main Components |
| 36 | +- **PluginManager** (`src/pluggy/_manager.py`): Central registry that manages plugins and coordinates hook calls |
| 37 | +- **HookCaller** (`src/pluggy/_hooks.py`): Executes hook implementations with proper argument binding |
| 38 | +- **HookImpl/HookSpec** (`src/pluggy/_hooks.py`): Represent hook implementations and specifications |
| 39 | +- **Result** (`src/pluggy/_result.py`): Handles hook call results and exception propagation |
| 40 | +- **Multicall** (`src/pluggy/_callers.py`): Core execution engine for calling multiple hook implementations |
| 41 | + |
| 42 | +### Key Concepts |
| 43 | +- **Hook Specifications**: Define the interface (`@hookspec` decorator) |
| 44 | +- **Hook Implementations**: Provide the actual functionality (`@hookimpl` decorator) |
| 45 | +- **Plugin Registration**: Plugins are registered with the PluginManager |
| 46 | +- **Hook Calling**: The manager coordinates calls to all registered implementations |
| 47 | + |
| 48 | +### Package Structure |
| 49 | +- `src/pluggy/` - Main package source |
| 50 | +- `testing/` - Test suite using pytest |
| 51 | +- `docs/` - Sphinx documentation and examples |
| 52 | +- `changelog/` - Towncrier fragments for changelog generation |
| 53 | + |
| 54 | +## Configuration Files |
| 55 | +- `pyproject.toml` - Project metadata, build system, tool configuration (ruff, mypy, setuptools-scm) |
| 56 | +- `tox.ini` - Multi-environment testing configuration |
| 57 | +- `.pre-commit-config.yaml` - Code quality automation (ruff, mypy, flake8, etc.) |
| 58 | + |
| 59 | +## Testing Notes |
| 60 | +- Tests are located in `testing/` directory |
| 61 | +- Uses pytest with coverage reporting |
| 62 | +- Benchmark tests in `testing/benchmark.py` |
| 63 | +- Minimum pytest version: 8.0 |
| 64 | +- Test configuration in `[pytest]` section of `tox.ini` |
0 commit comments