[Epic] Transparency & Opacity (Fills, Lines, Pictures)

[MHoroszowski]

Problem

Transparency / opacity is the cleanest single-PR cherry-pick available in the upstream queue. Every fill format (<a:solidFill>, <a:gradFill>, <a:blipFill>, <a:pattFill>) and every color format can carry an <a:alpha val=> child to express opacity from 0–100k (per-mille). Today python-pptx exposes no public transparency setter on FillFormat or ColorFormat, so the only way to author a 50%-transparent shape is to splice <a:alpha> into the XML by hand. There has been an open transparency PR since 2014 (scanny/python-pptx#140, FillFormat.transparency) and the most recent and complete implementation is scanny/python-pptx#1090 (spandan-k, 2025-09-11, 517/-1 LOC, updated April 2026 — author still responsive). This PR is the highest-leverage low-effort cherry-pick in the entire roadmap.

Sub-features

• FillFormat.transparency = 0.5 (range 0.0–1.0) emits <a:alpha val=50000/> inside the active fill child
• ColorFormat.transparency setter on the underlying <a:srgbClr>/<a:schemeClr>
• _SolidFill.transparency getter+setter
• _GradientFill.gradient_stops[i].transparency for per-stop alpha
• _BlipFill.transparency (overlaps with Pictures epic; coordinate to avoid duplication)
• _PatternFill.transparency
• Round-trip preservation of existing <a:alpha> elements in unrelated read paths
• LineFormat.transparency for line opacity (<a:ln> carries <a:solidFill> with <a:alpha>)

Prior art

• Open PRs: scanny/python-pptx#1090 (spandan-k, 2025) — highest-quality, most-complete; recommend cherry-pick as basis. scanny/python-pptx#140 (jonastr, 2014) oldest. scanny/python-pptx#154 (hoopes, 2015) dml alpha. scanny/python-pptx#353 chart-fill transparency (asakharov, 2018).
• Forks:
  • secondlayerco/python-pptx — opacity support across dml/color.py + dml/fill.py + transparency oxml (Napkin AI's branded napkin branch).
• User issues this would close: #62, #140, #154, #165, #1020.
• OOXML: DrawingML §20.1.2.3.1 <a:alpha val=> (range 0–100000 per-mille), §20.1.4.1.32 <a:alphaMod>, §20.1.8.10 <a:alphaModFix>, §20.1.8.1 <a:alphaInv>.
• Code paths: src/pptx/dml/fill.py, src/pptx/dml/color.py, src/pptx/dml/line.py, src/pptx/oxml/dml/fill.py.

Acceptance criteria

• shape.fill.solid(); shape.fill.fore_color.transparency = 0.5 produces a half-transparent fill in PowerPoint.
• 20+ unit tests covering each fill type × transparency.
• Existing line-format and chart-fill tests still pass.
• Behave scenarios: solid + gradient + line transparency.

Effort: S

Single-PR cherry-pick (scanny#1090) carries most of the work; remaining is integration, behave coverage, and _BlipFill coordination with the Pictures epic.

Labels

status:quick-win — high user demand, small implementation. Recommended as the FIRST epic to ship after this roadmap is filed.