test(dml): pin gradient-stop transparency behavior with explicit coverage#60
Merged
Merged
Conversation
…rage PR #30 added ColorFormat.transparency, which flows through to gradient stops transitively because _GradientStop.color returns a ColorFormat. That worked from day one, but no test asserted it — the behavior was load-bearing for issue #17 follow-up (hmeine, post-v1.2.0 release) but only covered by accident of architecture. This change pins it. The trigger was hmeine's comment on issue #17 asking whether gradient stops also expose alpha. Empirically `stop.color.transparency = 0.5` already worked on master and round-tripped to <a:alpha val="50000"/> under the color choice — but only because PR #30's surface naturally inherits. A future refactor of _GradientStop (e.g. switching to a ProxyMixin without ColorFormat-from-parent semantics) could silently regress it. These tests block that. Surface: - tests/dml/test_transparency.py: +11 new tests across two describe classes — DescribeGradientStopTransparency (9 unit tests): reads zero when no alpha, reads alpha under srgbClr, reads alpha under schemeClr, writes alpha under srgbClr, writes alpha under schemeClr (the OOXML placement invariant — <a:alpha> goes inside the color choice element, NOT directly on <a:gs>), clears alpha on zero, rejects out-of-range, rejects set on NoneColor stop, and exposes the property through the _GradientStop proxy. DescribeGradientStopTransparencyRoundTrip (2 integration tests): full Presentation -> fill.gradient() -> set transparency -> save/reload -> assert transparency preserved; and the alpha placement invariant verified post-roundtrip. No production code changed. The transparency surface itself ships in PR #30 / commit 253dbc8. This is belt-and-suspenders coverage. Tests: 3983 passed (+11 new), 1130 behave scenarios all green. Lint: ruff check + ruff format clean. Refs #17.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
PR #30 (commit
253dbc87, closed issue #17) addedColorFormat.transparency. Because_GradientStop.colorreturns aColorFormat, the same surface flows through to gradient stops transitively —stops[i].color.transparency = 0.5already works on master and round-trips to<a:alpha val="50000"/>under the color choice inside<a:gs>.But no test asserted that. The behavior is load-bearing for hmeine's follow-up comment on #17 (tested against
python-pptx-extended==1.2.0, which was tagged the same day PR #30 merged but before the merge — so the released wheel didn't include it). On master it works; this PR pins it down with explicit coverage so a future refactor of_GradientStopcan't silently regress it.What
tests/dml/test_transparency.pygets two new describe classes (+11 tests, no production code changed):DescribeGradientStopTransparency(9 unit tests, parse_xml-based fixtures):<a:alpha><a:alpha>under both<a:srgbClr>and<a:schemeClr><a:alpha>under the color choice element, NOT directly on<a:gs>(the OOXML placement invariant)<a:alpha>when transparency is set back to 0.0-0.1,1.1)_GradientStopproxyDescribeGradientStopTransparencyRoundTrip(2 integration tests):Presentation→fill.gradient()→ set stop transparencies →save→ reopen → assert preservedVerification
UAT
uat/uat_issue17_gradient_alpha.py(untracked per repo convention) builds a 4-slide deck progressing opaque → asymmetric 50% → asymmetric 50% → fully transparent over a red contrast background, then byte-level round-trip asserts all 8 stops. All 8 pass; maintainer's responsibility to open the.pptxin PowerPoint/Keynote for visual signoff.Scope
Tests only. Does NOT change
_GradientStop,ColorFormat, or any production surface. The transparency feature itself shipped in PR #30.Refs #17.