Skip to content

CLAUDE.md

Latest commit

 

History

History
80 lines (51 loc) · 6.68 KB

CLAUDE.md

File metadata and controls

80 lines (51 loc) · 6.68 KB
Raw

python-pptx-extended — Contributor & Agent Guide

This is MHoroszowski/python-pptx, a fork of scanny/python-pptx published on PyPI as python-pptx-extended. Commit 253dbc87 on master (PR #30 — transparency & opacity, issue #17) is the canonical example of a feature PR in this repo.

This file documents project rules that apply to every contributor — human or AI — working in this codebase. Claude Code auto-merges it into any session opened in this directory.

1. Editable install resolves to the path it was installed against

Run pip show python-pptx-extended (or python-pptx, depending on what's installed) to see the package location. With an editable install (pip install -e .), that location points at the clone the install was run against — typically THIS directory's src/.

Consequence for git worktree: pytest in a parallel worktree still imports from the original install location, not the worktree's src/. Edits in the worktree are invisible to the test runner. Tests appear to "fail mysteriously" against the new code because the new code never loads.

Two acceptable workflows:

  • Single feature at a time: create a feature branch directly in the main checkout. No worktree. Editable install Just Works.
  • Parallel checkouts via worktree: every pytest invocation MUST set PYTHONPATH=src, e.g. PYTHONPATH=src python3 -m pytest tests/ -q. No exceptions.

If you skip this and run plain pytest from a worktree, you will spend hours debugging "test failures" that are actually phantom imports.

2. Manual port over git cherry-pick for upstream fixes

This fork's master had a repo-wide ruff format pass (PR #10). Upstream scanny/python-pptx master did not. git cherry-pick of upstream PRs will conflict on whitespace across nearly every touched file. Always manually apply the semantic changes from upstream PRs onto the ruff-formatted base. Reuse the design and tests from upstream; redo the diff against current master.

3. Test discipline (non-negotiable for any feature PR)

  • Unit tests: new tests in tests/ mirroring source layout. Aim for ≥30 new tests for a meaningful surface (PR #30 added 31 in tests/dml/test_transparency.py).
  • Behave acceptance: python3 -m behave features/ --no-color 2>&1 | tail -5 must show 0 failed (current baseline: 981 scenarios).
  • Pytest: python3 -m pytest tests/ -q must show 0 failed (current baseline: 3017 passed on master, ef8ee6a8).
  • Ruff: both ruff format src tests (no diff or applied cleanly) and ruff check src tests (All checks passed).

Run pytest at least once during implementation, not just at the end. TDD ordering is the most reliable way to get there: write the first failing test, run it, see it fail with the expected error, implement, see it pass, then expand. Writing everything before running anything is how subtle indentation bugs and stale-import gotchas turn into hour-long debugging sessions.

4. Tooling

  • Ruff: install via pip install ruff if it isn't on PATH already. Locate with which ruff. Used for both lint (ruff check) and format (ruff format).
  • Pytest, behave: invoke as python3 -m pytest tests/ and python3 -m behave features/.
  • gh CLI: target this fork as MHoroszowski/python-pptx.

5. Commit message format

Reference git log 253dbc87 --format=%B -n1 for the canonical shape: scope, design notes, test counts, Closes #N (or Refs #N if partial). Long-form, not terse.

6. Branch / PR workflow

  1. git checkout -b feature/<slug> off master
  2. Implement → test → ruff → commit
  3. Drop a uat_<slug>.py at the repo root (untracked) — small Python script that builds a .pptx exercising the new API and prints a round-trip read-back. PR #30 used this for issue #17 review.
  4. The maintainer runs the UAT. Opens the .pptx in PowerPoint or Keynote, gives signoff.
  5. Then push the branch and open a PR.

Automated runs must not push or open PRs without maintainer approval. The approval-gated UAT step is the rule, not a suggestion.

6a. UAT signoff is maintainer-only — HARD RULE for AI agents

AI agents may execute the UAT script to verify the script itself is functional, but PASS from the script does NOT constitute signoff. Signoff requires a human opening the generated .pptx in PowerPoint or Keynote and visually confirming behavior. Unless the maintainer has explicitly delegated signoff in a specific case, the agent does not claim UAT acceptance.

Concretely:

  • Agents author the UAT script (it's part of the deliverable per §6.3).
  • Agents may run the UAT — after the §7 trinity is green — to verify the script doesn't crash, exits non-zero on failure, and actually asserts what it claims to assert. This is QA on the test itself, not acceptance of the feature.
  • Agents must not report or imply UAT signoff in commit messages, PR bodies, or summaries. Acceptable: "UAT script runs clean — pending maintainer visual signoff in PowerPoint/Keynote." Not acceptable: "UAT: PASS — round-trip confirmed."
  • UAT files should be stored under the ./uat subdirectory.
  • The §7 reporting trinity below (pytest + ruff + behave) is the agent's full self-verification surface. UAT execution output may be included as an attachment but it is not the fourth gate.
  • Round-trip / behavioral evidence within agent-runnable scope still goes through pytest integration tests that exercise save+reopen. If pytest can fully cover it, the UAT is just a maintainer convenience; if pytest can't, UAT becomes the maintainer's primary acceptance path.
  • If unsure whether the maintainer has delegated signoff for a particular case, the agent stops and asks.

Why: the .pptx rendering in PowerPoint or Keynote is the actual acceptance surface — agents can't open it, and a green script exit only proves byte-level round-tripping, not visual correctness. Claiming "UAT PASS" in a summary creates false-confidence pressure to merge; the explicit signoff-vs-execution split removes that pressure.

7. AI agent reporting contract

When an AI agent or automated workflow finishes implementation work in this repo, the wrap-up report MUST include the literal output of:

python3 -m pytest tests/ -q | tail -3
ruff check src tests | tail -3
python3 -m behave features/ --no-color 2>&1 | tail -3

Pasted verbatim. If any shows a failure, the agent stops there and reports verification-failed rather than committing. Self-attestation ("tests pass") without the captured output is not acceptable — too easy to skip the actual run and inherit a false sense of done.

UAT output is NOT part of this trinity. Per §6a, agents do not run the UAT. The maintainer runs it after seeing the trinity is green and reviewing the diff.