[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.

[hmeine]

Are gradient stops supported as well? I tried python-pptx-extended 1.2.0, and I can see an alpha element in the XML, but it does not seem to be available in the API:

In [3]: [attr for attr in dir(stop) if not attr.startswith('_')]
Out[3]: ['color', 'element', 'position']

In [4]: [attr for attr in dir(stop.color) if not attr.startswith('_')]
Out[4]: ['brightness', 'from_colorchoice_parent', 'rgb', 'theme_color', 'type']

In [5]: list(stop.element.iterdescendants())
Out[5]:
[<CT_SRgbColor '<a:srgbClr>' at 0x1091f6850>,
 <Element {http://schemas.openxmlformats.org/drawingml/2006/main}alpha at 0x10a0b87c0>]

[MHoroszowski]

Good catch — and the answer is yes, gradient stops do support it, but the 1.2.0 wheel you tested doesn't include the fix.

What happened: PR #30 added ColorFormat.transparency, and since _GradientStop.color returns a ColorFormat, gradient stops inherit the API transitively. But PR #30 merged on the same day v1.2.0 was tagged — after the tag was cut — so the released wheel on PyPI doesn't have it. That's why your dir(stop.color) shows the attribute missing despite the <a:alpha> already being present in the XML.

On current master it works:

fill.gradient()
stops = fill.gradient_stops
stops[1].color.transparency = 0.5     # → writes <a:alpha val="50000"/>
                                       #   under the <a:schemeClr>/<a:srgbClr>

Round-trip preserves it through save/reopen.

I just landed PR #60 (#60) with explicit unit + integration test coverage for gradient stops specifically, so this can't silently regress. The next release will include both PR #30 and #60. Apologies for the release-ordering rough edge.