Repository navigation
Description
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.transparencysetter on the underlying<a:srgbClr>/<a:schemeClr> -
_SolidFill.transparencygetter+setter -
_GradientFill.gradient_stops[i].transparencyfor 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.transparencyfor 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 acrossdml/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.5produces 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.
Activity
Merge pull request #30 from MHoroszowski:feature/transparency-opacity
hmeine commentedon May 20, 2026
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:
MHoroszowski commentedon May 20, 2026
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.colorreturns aColorFormat, 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 yourdir(stop.color)shows the attribute missing despite the<a:alpha>already being present in the XML.On current
masterit works: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.