From 718edc5cc7332aca539e0b2b8201da182e391fe3 Mon Sep 17 00:00:00 2001 From: Jeffrey 'Alex' Clark Date: Wed, 22 Apr 2026 14:06:09 -0400 Subject: [PATCH 1/7] Add .github/copilot-instructions.md Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/copilot-instructions.md | 102 ++++++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000000..1c49ea88d51 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,102 @@ +# Copilot Instructions for Pillow + +## What this project is + +Pillow is the Python Imaging Library fork — a Python 3.10+ library for opening, +manipulating, and saving many image file formats. It is a mix of Python and C: +pure Python format plugins live in `src/PIL/`, and eight C extension modules +(`_imaging`, `_imagingcms`, `_imagingft`, `_imagingmath`, `_imagingmorph`, +`_imagingtk`, `_avif`, `_webp`) are compiled at install time via `setup.py`. + +## Project layout + +``` +src/PIL/ Python source and C extension stubs (.pyi) +src/thirdparty/ Vendored C libraries (raqm, fribidi-shim, pythoncapi_compat) +Tests/ pytest test suite; Tests/helper.py has shared utilities +docs/ Sphinx documentation (RST) +docs/releasenotes/ Per-release changelog entries +setup.py C extension build configuration +_custom_build/ Custom setuptools build backend +src/PIL/_version.py Version number (PEP 440) +pyproject.toml Project metadata and optional dependency groups +.pre-commit-config.yaml All linting and formatting hooks +``` + +## Install + +```bash +python3 -m pip install -e ".[tests]" +``` + +The C extensions are compiled during install. Native libraries (libjpeg, +libpng, libtiff, libwebp, freetype2, littlecms2, etc.) must already be present +on the system. + +## Test + +```bash +python3 selftest.py # quick sanity check +python3 -m pytest Tests/ # full test suite +python3 -m pytest Tests/ -n auto # parallel (requires pytest-xdist) +``` + +Always run `python3 selftest.py` first. New features and bug fixes must include +tests. Test files follow the naming pattern `Tests/test_*.py`. + +## Lint and format + +```bash +make lint # runs tox -e lint → pre-commit (black, ruff, clang-format, + # bandit, sphinx-lint, pyproject-fmt, and more) +make lint-fix # auto-fixes black and ruff violations +``` + +Or run pre-commit directly: + +```bash +pre-commit run --all-files +``` + +All hooks must pass before a PR can be merged. Separate reformatting commits +from functional commits. + +## Type checking + +```bash +python3 -m tox -e mypy +``` + +## Documentation + +Docs use Sphinx/RST. Build locally with `make docserve`. Release notes go in +`docs/releasenotes/.rst` using the existing section structure +(Security, Backwards incompatible changes, Deprecations, API changes, API +additions, Other changes). Use the `:cve:` RST role for CVE references. +Include a release note entry for any user-visible change. + +## CI checks (must all pass before merge) + +GitHub Actions runs: `test.yml` (pytest on Linux/macOS/Windows), `lint.yml` +(pre-commit), `docs.yml` (Sphinx build), and `wheels.yml` on tag push. + +--- + +## Pillow-specific guidance + +Use `python3` and `python3 -m pip install` — never `python` or bare `pip`. + +`Image.open()` takes a `formats=` argument (list/tuple of format IDs to +allowlist). There is no `format=` parameter. + +`Image.OPEN` is an internal format registry. Do not recommend that users +mutate it as a security or configuration mechanism. + +`pybind11` is a build-time-only dependency used for parallel C compilation, +not for C++/Python bindings. + +Use fully qualified exception names: `Image.DecompressionBombError` and +`Image.DecompressionBombWarning`, not the bare class names. + +Do not embed specific numeric values for thresholds like `MAX_IMAGE_PIXELS` — +they change across releases. Reference the named constant instead. From 17e6f08f83737af4bc184f2400eb89053b0925e8 Mon Sep 17 00:00:00 2001 From: Jeffrey 'Alex' Clark Date: Wed, 22 Apr 2026 16:28:06 -0400 Subject: [PATCH 2/7] Rename copilot-instructions.md -> AGENTS.md --- .github/copilot-instructions.md => AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename .github/copilot-instructions.md => AGENTS.md (99%) diff --git a/.github/copilot-instructions.md b/AGENTS.md similarity index 99% rename from .github/copilot-instructions.md rename to AGENTS.md index 1c49ea88d51..48790964c0b 100644 --- a/.github/copilot-instructions.md +++ b/AGENTS.md @@ -1,4 +1,4 @@ -# Copilot Instructions for Pillow +# Agent Instructions for Pillow ## What this project is From d9fb08b797f928c0ad7b1d199feb970c9c7ea591 Mon Sep 17 00:00:00 2001 From: Jeffrey 'Alex' Clark Date: Wed, 22 Apr 2026 19:52:38 -0400 Subject: [PATCH 3/7] Update AGENTS.md Co-authored-by: Andrew Murray <3112309+radarhere@users.noreply.github.com> --- AGENTS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 48790964c0b..53905d429f8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -69,7 +69,7 @@ python3 -m tox -e mypy ## Documentation -Docs use Sphinx/RST. Build locally with `make docserve`. Release notes go in +Docs use Sphinx/RST. Build locally with `make doc`. Release notes go in `docs/releasenotes/.rst` using the existing section structure (Security, Backwards incompatible changes, Deprecations, API changes, API additions, Other changes). Use the `:cve:` RST role for CVE references. @@ -99,4 +99,4 @@ Use fully qualified exception names: `Image.DecompressionBombError` and `Image.DecompressionBombWarning`, not the bare class names. Do not embed specific numeric values for thresholds like `MAX_IMAGE_PIXELS` — -they change across releases. Reference the named constant instead. +they may be changed by the user at runtime. Reference the named constant instead. From 35c3fcc7e36ba8406cb0dd92f5a887100a6ddd0a Mon Sep 17 00:00:00 2001 From: Jeffrey 'Alex' Clark Date: Wed, 22 Apr 2026 20:02:24 -0400 Subject: [PATCH 4/7] Remove CI checks section from AGENTS.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Not actionable for agents — knowing workflow names and triggers does not help write better code. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- AGENTS.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 53905d429f8..9a3a1d4559b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -75,13 +75,6 @@ Docs use Sphinx/RST. Build locally with `make doc`. Release notes go in additions, Other changes). Use the `:cve:` RST role for CVE references. Include a release note entry for any user-visible change. -## CI checks (must all pass before merge) - -GitHub Actions runs: `test.yml` (pytest on Linux/macOS/Windows), `lint.yml` -(pre-commit), `docs.yml` (Sphinx build), and `wheels.yml` on tag push. - ---- - ## Pillow-specific guidance Use `python3` and `python3 -m pip install` — never `python` or bare `pip`. From 6305a1740194dd17e78ef75e813b68868f660959 Mon Sep 17 00:00:00 2001 From: Andrew Murray Date: Fri, 24 Apr 2026 20:53:43 +1000 Subject: [PATCH 5/7] Update alignment --- AGENTS.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9a3a1d4559b..13b40885b5e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,15 +11,15 @@ pure Python format plugins live in `src/PIL/`, and eight C extension modules ## Project layout ``` -src/PIL/ Python source and C extension stubs (.pyi) -src/thirdparty/ Vendored C libraries (raqm, fribidi-shim, pythoncapi_compat) -Tests/ pytest test suite; Tests/helper.py has shared utilities -docs/ Sphinx documentation (RST) -docs/releasenotes/ Per-release changelog entries -setup.py C extension build configuration -_custom_build/ Custom setuptools build backend -src/PIL/_version.py Version number (PEP 440) -pyproject.toml Project metadata and optional dependency groups +src/PIL/ Python source and C extension stubs (.pyi) +src/thirdparty/ Vendored C libraries (raqm, fribidi-shim, pythoncapi_compat) +Tests/ pytest test suite; Tests/helper.py has shared utilities +docs/ Sphinx documentation (RST) +docs/releasenotes/ Per-release changelog entries +setup.py C extension build configuration +_custom_build/ Custom setuptools build backend +src/PIL/_version.py Version number (PEP 440) +pyproject.toml Project metadata and optional dependency groups .pre-commit-config.yaml All linting and formatting hooks ``` @@ -36,8 +36,8 @@ on the system. ## Test ```bash -python3 selftest.py # quick sanity check -python3 -m pytest Tests/ # full test suite +python3 selftest.py # quick sanity check +python3 -m pytest Tests/ # full test suite python3 -m pytest Tests/ -n auto # parallel (requires pytest-xdist) ``` From 933716f3d3c22f485b623e50efe4711812fb30b1 Mon Sep 17 00:00:00 2001 From: Andrew Murray Date: Fri, 24 Apr 2026 23:30:35 +1000 Subject: [PATCH 6/7] Added CLAUDE.md --- .claude/CLAUDE.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 .claude/CLAUDE.md diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md new file mode 100644 index 00000000000..dba71e970eb --- /dev/null +++ b/.claude/CLAUDE.md @@ -0,0 +1 @@ +@../AGENTS.md From b71096460f20b09961f52352700975968b2f11fb Mon Sep 17 00:00:00 2001 From: Andrew Murray Date: Sat, 25 Apr 2026 11:30:32 +1000 Subject: [PATCH 7/7] Update MANIFEST --- MANIFEST.in | 1 + 1 file changed, 1 insertion(+) diff --git a/MANIFEST.in b/MANIFEST.in index d4623a4a8e5..dfcfd196bcf 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -12,6 +12,7 @@ include .flake8 include LICENSE include Makefile include tox.ini +graft .claude graft Tests graft Tests/images graft checks