This page provides an overview of the development setup, tooling, and quality infrastructure for the Rich project. It covers the tools required to build, test, and format the codebase, along with the CI/CD pipeline configuration.
For the step-by-step contribution workflow (forking, branching, pull request process), see Contributing Guide. For detailed documentation of the test suite, coverage configuration, and GitHub Actions matrix, see Testing and CI/CD.
The repository is organized as follows:
| Path | Purpose |
|---|---|
rich/ | Main library source code |
tests/ | pytest test suite |
docs/ | Sphinx documentation source |
examples/ | Standalone runnable example scripts |
benchmarks/ | Performance benchmarks (excluded from linting) |
Makefile | Developer task shortcuts |
tox.ini | Tox multi-environment runner |
.pre-commit-config.yaml | Pre-commit hook configuration |
.github/workflows/pythonpackage.yml | GitHub Actions CI definition |
CONTRIBUTING.md | Contribution guidelines |
Sources: Makefile1-16 tox.ini1-52 CONTRIBUTING.md1-150
Diagram: Developer Toolchain
Sources: Makefile1-16 .pre-commit-config.yaml1-44 tox.ini1-52
Rich uses Poetry for dependency management and packaging. The standard setup sequence is:
poetry install # Install all dependencies into a virtualenv
poetry shell # Activate the virtualenv
The poetry install command installs both runtime and development dependencies. The CI pipeline mirrors this by running poetry install as its first step before any checks.
Sources: CONTRIBUTING.md14-31 .github/workflows/pythonpackage.yml25-33
The Makefile provides short aliases for the most common developer tasks:
| Target | Command | Purpose |
|---|---|---|
make test | TERM=unknown pytest --cov-report term-missing --cov=rich tests/ -vv | Run tests with coverage |
make test-no-cov | TERM=unknown pytest tests/ -vv | Run tests without coverage |
make format-check | black --check . | Verify formatting without modifying files |
make format | black . | Reformat all source files |
make typecheck | mypy -p rich --no-incremental | Run mypy on the rich package |
make typecheck-report | mypy -p rich --html-report mypy_report | Generate HTML type-check report |
make docs | cd docs; make html | Build Sphinx HTML documentation |
Sources: Makefile1-16
Diagram: Code Quality Pipeline (file → tool → artifact)
The project enforces formatting with black. The pre-commit hook is configured at revision 23.11.0 and excludes the benchmarks/ directory. make format-check is used in CI; make format is used locally to apply changes.
Source: .pre-commit-config.yaml32-36 Makefile5-8
Type annotations are required on all new code. The mypy invocation checks the entire rich package: mypy -p rich --no-incremental. The --no-incremental flag ensures a clean analysis in CI.
Source: Makefile9-10 CONTRIBUTING.md74-87
Import ordering is managed by isort using the black compatibility profile (--profile black). Language version is pinned to 3.11 in the pre-commit config.
Source: .pre-commit-config.yaml37-44
pycln removes unused imports. It is run with --all, which removes all unused imports regardless of __all__ declarations.
Source: .pre-commit-config.yaml27-30
All hooks are defined in .pre-commit-config.yaml1-44 The benchmarks/ directory is globally excluded.
| Hook | Source | Purpose |
|---|---|---|
check-ast | pre-commit-hooks | Validates Python syntax |
check-builtin-literals | pre-commit-hooks | Avoids list() instead of [] etc. |
check-case-conflict | pre-commit-hooks | Prevents case-insensitive filename collisions |
check-merge-conflict | pre-commit-hooks | Blocks accidental merge conflict markers |
check-json / check-toml / check-yaml | pre-commit-hooks | Validates config file syntax |
end-of-file-fixer | pre-commit-hooks | Ensures files end with a newline |
trailing-whitespace | pre-commit-hooks | Removes trailing whitespace |
python-no-log-warn | pygrep-hooks | Flags deprecated logging.warn usage |
python-use-type-annotations | pygrep-hooks | Enforces type annotation syntax |
pycln | hadialqattan/pycln | Removes unused imports |
black | psf/black-pre-commit-mirror | Formats code |
isort | PyCQA/isort | Sorts imports |
Sources: .pre-commit-config.yaml1-44
tox.ini defines multi-environment testing. The envlist covers Python 3.8 through 3.13 plus dedicated lint and docs environments.
| Environment | Description | Key Commands |
|---|---|---|
py{38,39,310,311,312,313} | Unit tests per Python version | poetry install, then pytest --cov=rich tests/ |
lint | Formatting and type checks | make format-check, make typecheck |
docs | Sphinx documentation build | sphinx-build -M html source build |
The TERM, CI, GITHUB_*, HOME, and PYTEST_* environment variables are explicitly passed through (passenv) to prevent CI from breaking due to environment isolation.
Sources: tox.ini1-52
CI is triggered on every pull request. The workflow is defined in .github/workflows/pythonpackage.yml1-53
Diagram: CI Job Matrix
| Dimension | Values |
|---|---|
os | ubuntu-latest, macos-latest, windows-latest |
python-version | 3.8, 3.9, 3.10, 3.11, 3.12, 3.13, 3.14 |
| Excluded combination | windows-latest + 3.13 |
The allow-prereleases: true flag on the Python setup action enables testing against 3.14 pre-release builds.
After each test run, the coverage.xml file is uploaded to Codecov using the codecov/codecov-action@v4 action. The upload is tagged with the unittests flag and annotated with the OS and PYTHON environment variables.
Sources: .github/workflows/pythonpackage.yml1-53
| Standard | Tool | Enforcement |
|---|---|---|
| Code formatting | black | Pre-commit + CI make format-check |
| Import ordering | isort (--profile black) | Pre-commit |
| Unused imports | pycln --all | Pre-commit |
| Static typing | mypy -p rich | CI make typecheck |
| Docstrings | Manual review | PR code review |
| Variable naming | No abbreviations (guideline) | PR code review |
Sources: CONTRIBUTING.md39-96 Makefile1-16 .pre-commit-config.yaml1-44
Documentation source lives in docs/. Building requires additional dependencies:
cd docs
pip install -r requirements.txt
cd ..
make docs # runs: cd docs; make html
Output is generated at docs/build/html. The Sphinx builder is configured in the tox.ini docs environment as sphinx-build -M html source build.
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.