Repository navigation
Remove the deprecated SoftMask.xref in the next minor release #610
Description
Context
DESIGN.md section 6 (I4, provenance). hayro 0.9 removed the identifier of a soft mask's group (LaurenzV/hayro#1553), so since the move to hayro 0.9 (#18, for 0.2.2) SoftMask.xref is 0 in what Page.content returns, and reading it warns with DeprecationWarning. On 2026-11-04 the owner chose to keep it so, so that the patch release breaks no public API, and to remove it in the next minor release. CONTRIBUTING.md: a minor release is for a change that breaks the public API, after a deprecation.
Goal
The 0.2.3 release removes SoftMask.xref: SoftMask holds its subtype only.
Scope
In: the xref property, the private _xref field behind it, the __init__ that takes xref=, the deprecation note of the class docstring, the API reference, the tests that pass or read xref, and the entry of the 0.2.3 changelog. Out: where a soft mask comes from, which belongs to provenance (#104).
Paths
python/pyropdf/_content.py, docs/en/api/text-and-content.md, tests/test_content_model.py, CHANGELOG.md.
Acceptance
-
SoftMaskhas noxref, andSoftMask(subtype=...)is how it is built. - The changelog of 0.2.3 lists the removal as a breaking change.
Notes
- On 2026-11-06 the owner chose to ship the removal in the 0.2.3 patch release, as an exception to removing public API only in a minor release. The property has been 0 since 0.2.2, so no caller can rely on its value.
- The engine already passes only the type of a mask (
soft_mask_codeincrates/pyropdf-engine/src/extract/model.rs); the change is in Python alone. - Without the property and its
__init__,SoftMaskis again a plain frozen, slotted, keyword-only dataclass, as the other values of the content model are.
Activity
Warn when the deprecated SoftMask.xref is read (#18)
Move to hayro 0.9 with LaurenzV/hayro#1734 patched in, and read strea…
yhay81 commentedon Nov 5, 2026
Prepared on
codex/610-remove-soft-mask-xrefin draft PR #695, headf08e4c8018150b3e52f9dd575ed5e59ba111638c.The property, private field, and constructor keyword are removed; subtype-only construction remains frozen and slotted. Tests cover actual content extraction, removed arguments/attributes, equality/hash/repr, immutability, and pickle. API reference and next-minor breaking changelog are updated. All eight
python3 tools/check.py --lockedchecks passed (7,188 Python tests passed / 692 skipped); targeted content/API-doc tests: 176 passed. All five required CI jobs and the docs build passed on this head; docs deployment is intentionally skipped for the draft.Next action: the owner starts 0.3.0 or a later minor release; refresh/revalidate this draft against that release branch then. Do not merge into a 0.2.x patch release. The owner's standing merge authorization does not remove this explicit release gate. The active claim is released because implementation is prepared; the linked draft keeps this out of the new-work queue.
Ship the SoftMask.xref removal in 0.2.3 (#610)
yhay81 commentedon Nov 6, 2026
Owner chose to ship the removal in 0.2.3 as an exception (2026-11-06). PR #695 merged current main and moved the changelog entry under Unreleased (da55dc8); it is still a draft. Locally ruff, ruff-format and ty pass; pytest has 16 failures unrelated to this change (CRLF line endings in this Windows working copy's tests/assets/broken), and test_content_model passes. Next: CI on the current head, mark ready, then owner review and merge before cutting 0.2.3.
Remove SoftMask.xref in 0.2.3 (#610) (#695)