feat(dml): add transparency support for solid fills and colors (closes #17)

[MHoroszowski]

Closes #17

Implements transparency / opacity support across ColorFormat, FillFormat, and _SolidFill — the longest-standing user request in upstream history (open since scanny/python-pptx#62, 2014).

Surface

shape.fill.solid()
shape.fill.fore_color.rgb = RGBColor(0xFF, 0x00, 0x00)
shape.fill.transparency = 0.5  # 50% transparent
shape.fill.fore_color.transparency = 0.3  # set via color directly

• 0.0 = fully opaque (no <a:alpha> element written — optimal XML)
• 1.0 = fully transparent (<a:alpha val="0"/>)
• 0.5 = 50% transparent (<a:alpha val="50000"/>)

Provenance

Cherry-picked from upstream PR scanny/python-pptx#1090 (spandan-k @ secondlayerco, last updated April 2026), ported manually to keep the fork's ruff-formatted layout clean.

Files touched

File	Change
src/pptx/dml/color.py	ColorFormat.transparency + _Color.transparency + _validate_transparency_value
src/pptx/dml/fill.py	FillFormat.transparency, base _Fill raises TypeError, _SolidFill delegates to fore-color
src/pptx/oxml/dml/color.py	alpha/alphaMod/alphaOff as ZeroOrOne on _BaseColorElement; add_* and clear_alpha helpers; new CT_PositiveFixedPercentage element
src/pptx/oxml/__init__.py	Register a:alpha, a:alphaMod, a:alphaOff
tests/dml/test_transparency.py	NEW — 31 tests across 4 Describe classes
tests/oxml/unitdata/dml.py	a_alpha, a_alphaMod, a_alphaOff builders

Verification

• pytest tests/ — 3017 passed (was 2986; +31 new transparency tests)
• behave features/ — 981 scenarios passed, 0 failed
• ruff check src tests — clean
• ruff format --check src tests — clean

Errors

color.transparency = 1.5     # ValueError: transparency must be number in range 0.0 to 1.0
color.transparency = -0.1    # ValueError
none_color.transparency = 0.5  # ValueError: can't set transparency when color.type is None
shape.fill.transparency      # TypeError: fill type _NoFill has no transparency, call .solid() first  (when fill not solid)

Out of scope (filed as follow-ups)

• _GradientFill.gradient_stops[i].transparency (per-stop alpha)
• LineFormat.transparency
• _BlipFill.transparency — coordinate with Pictures epic
• _PatternFill.transparency
• alphaMod / alphaOff Python API (XML elements registered, no public surface yet)

Round-trip safety

Existing <a:alpha> elements in unrelated read paths (effects, theme.xml) are preserved — these were already serialized verbatim through lxml since the elements weren't registered with custom classes; registering them with CT_PositiveFixedPercentage does not change the bytes written for unmodified parts.