[Epic] Modernization & Ergonomics — PathLike, UTC datetimes, dev-tooling

[MHoroszowski]

Problem

Developer-experience quality-of-life improvements that don't fit any single feature epic but compound across all of them. python-pptx's API still rejects pathlib.Path inputs (scanny/python-pptx#1123), uses naive datetimes (scanny/python-pptx#957), has Python 3.10 collections deprecation hits (scanny/python-pptx#771), and lacks a clean shape-by-name lookup (scanny/python-pptx#798, #309, #532). The Font.color getter mutates XML by inserting <a:solidFill/> (scanny/python-pptx#1111, #1074) — a long-standing footgun. Slide.background._element returns the wrong element (scanny/python-pptx#1126). Dev-tooling is dated: the upstream is moving toward uv / ruff / pyright (semaverse-pptx fork demonstrates the path) but our fork still uses the older unittest+pytest+behave hybrid.

Sub-features

API ergonomics

• Presentation() and add_picture() accept pathlib.Path (closes scanny/python-pptx#1123 — clean cherry-pick)
• Shapes.by_name(name) lookup helper (closes scanny/python-pptx#798)
• Shapes.iter_leaf_shapes() traversal (closes scanny/python-pptx#435)
• Shapes and SlidePlaceholders fulfill collections.abc.Mapping (scanny/python-pptx#800)
• Shape.find_by_xpath() for power users
• Selection-pane order listing (closes scanny/python-pptx#532)

Bug fixes that pollute every other epic if left unfixed

• Font.color getter must not mutate XML on access (closes #1111, #1074)
• Slide.background._element returns <p:bg> not <p:cSld> (closes #1126)
• UTC-aware datetimes throughout (closes scanny/python-pptx#957)
• Python 3.10+ collections.abc import paths (closes scanny/python-pptx#771)
• PERCENT_40 enum typo (closes #1127)

Dev-tooling modernization

• Migrate to uv for dependency management
• Continue ruff format pass (already done in our fork v1.2.0); add ruff check strict gates
• Add pyright strict-mode gate to CI
• Convert remaining unittest-style tests to flat pytest
• Optional: pytest-syrupy snapshot tests for XML fixtures (semaverse-pptx pattern)
• CI matrix: cover Python 3.9 through 3.13 (already done) + 3.14 once stable

Prior art

• Open PRs: scanny/python-pptx#1123 PathLike (clean, small). scanny/python-pptx#957 UTC datetimes. scanny/python-pptx#771 collections.abc. scanny/python-pptx#798 shapes.by_name. scanny/python-pptx#800 Mapping ABC. scanny/python-pptx#1131 PERCENT_40 typo. scanny/python-pptx#1104 DelimitedList (cleaner alternative to our pyparsing<3 pin).
• Forks:
  • semaverse-ai/semaverse-pptx — uv / ruff / pyright / pytest-syrupy modernization. The reference for our dev-tooling phase.
  • madflow/python-pptx — pure CI maintenance branch (latest Python versions, deprecation fixes).
  • loadfix/python-pptx iter_leaf_shapes, Slide.clear_shapes.
• User issues this would close: #224, #309, #435, #532, #1074, #1111, #1126, #1127.
• Code paths: broad — touches presentation.py, parts/image.py, dml/color.py, text/fonts.py, slide.py, oxml/slide.py, pyproject.toml, tox.ini, GitHub Actions workflows.

Acceptance criteria

• Presentation(Path("deck.pptx")) works without TypeError.
• font.color access on an unstyled run does NOT modify the underlying XML (assert with byte-diff).
• slides[0].shapes.by_name("Title") returns the title shape.
• pyright strict mode runs in CI with zero errors on the public API.
• All 2986+ pytest tests + 981+ behave scenarios continue passing.

Effort: M

Bundle of small wins that compound. Recommend cherry-picking the trivial ones first (scanny/python-pptx#1123 PathLike, scanny/python-pptx#1131 typo, scanny/python-pptx#771 collections) in a single "ergonomics 1" patch release, then bug fixes (Font.color mutation, slide.background) in a second, then dev-tooling modernization (Phase 3).

[MHoroszowski]

Modernization & Ergonomics — Phase wrap-up

All substantive work for this epic is shipped. Status by item:

✅ Shipped (15 items)

Phase 1 (ad7edb80 — feat(ergonomics): PathLike + PERCENT_40 typo + Slide.background.element fix)

• Presentation() / add_picture() accept pathlib.Path (closes Support PathLike image and package file inputs scanny/python-pptx#1123)
• PERCENT_40 enum typo (closes Typo in variable PERCENT_40 scanny/python-pptx#1127)
• Slide.background._element returns <p:bg> (closes Slide.background._element returns <p:cSld>, not <p:bg> — silently corrupts spTree in slide-copy code scanny/python-pptx#1126)

Phase 2 (PR #43 — feat: Font.color non-mutation + UTC-aware datetimes + Shapes.by_name)

• Font.color getter no longer mutates XML on access (closes Font.color getter mutates XML by inserting <a:solidFill/>, breaking theme color inheritance scanny/python-pptx#1111, Accessing @LazyProperty .color on Text.Font causes unintentional side effects scanny/python-pptx#1074)
• UTC-aware datetimes throughout (closes Use UTC-aware datetime objects scanny/python-pptx#957)
• Shapes.by_name(name) (closes Feature: Convenience method to get a shape by its name scanny/python-pptx#798)

Phase 3 (PR #44 — chore: pyright CI gate (public API) + Python 3.13 matrix + pyproject cleanup)

• pyright strict-mode gate on public-API surface (pptx/__init__.py, api.py, presentation.py, util.py, exc.py, types.py)
• Python 3.13 in CI matrix
• collections.abc import paths (closes Compaitibility script no longer breaks to collections changes in 3.10 scanny/python-pptx#771)

Phase 4 (PR #45 — feat: shape-tree ergonomics)

• Shapes.iter_leaf_shapes() traversal (closes feature: add _BaseShapes.iter_leaf_shapes() scanny/python-pptx#435)
• Shapes / SlidePlaceholders Mapping ABC behavior (Let Shapes and SlidePlaceholders fulfill the Mapping interface scanny/python-pptx#800)
• Shape.find_by_xpath() for power users
• Selection-pane order via shapes.in_selection_pane_order (closes Feature Request: General listing that matches Selection Pane scanny/python-pptx#532)

Phase 5 (PR #46 — chore: migrate dependency management to uv)

• uv-managed dependencies in pyproject.toml; requirements*.txt and tox.ini removed; uv.lock committed

Already done before this epic

• unittest → flat pytest conversion: tests/ has zero unittest.TestCase usage
• Ruff format pass: landed in v1.2.0 (PR style: ruff format pass over src and tests (no semantic changes) #10); ruff check + ruff format --check gated in CI

🚧 Open

• CI matrix Python 3.14 — PR chore: add Python 3.14 to CI matrix and pyproject classifiers (Modernization Phase 6) #47 (in flight). Will close this issue on merge.

❌ Not doing (deliberate scope drop)

• pytest-syrupy snapshot tests for XML fixtures. Was marked Optional in the original epic. The existing XML-comparison helpers in tests/unitutil/cxml.py cover the same surface; adding a snapshot framework on top is bookkeeping cost without proportional quality lift. Reconsider if a future feature epic introduces XML diffs that the cxml helpers don't handle well.
• Tightening the ruff select = [...] ruleset (PL*, RET, ARG, ANN, etc.). Current ruleset (C4, COM, E, F, I, PT, SIM, TC, UP*, W) is solid for a public library and gated in CI. Adding strictness categories would generate auto-fix churn without bug-prevention value at this codebase's stability level. Open as a follow-up issue if a specific category proves load-bearing.

Closing on merge of #47.

[MHoroszowski]

Closed by merge of #47. Modernization epic complete; pytest-syrupy and ruff strictness expansion intentionally dropped per closeout comment above.