python-hwpx 4.2.0__py3-none-any.whl → 5.0.2__py3-none-any.whl

hwpx/__init__.py

@@ -13,13 +13,15 @@
 
 import importlib
 import warnings
-from importlib.metadata import PackageNotFoundError, version as _metadata_version
+from dataclasses import dataclass
+from typing import Literal
 
 
 def _resolve_version() -> str:
-    """패키지 메타데이터에서 현재 배포 버전을 조회합니다."""
+    """패키지 메타데이터에서 배포 버전을 조회합니다(import는 함수 스코프 유지)."""
+    from importlib.metadata import PackageNotFoundError, version
     try:
-        return _metadata_version("python-hwpx")
+        return version("python-hwpx")
     except PackageNotFoundError:
         return "0+unknown"
 
@@ -48,12 +50,11 @@ _EXPERIMENTAL_EXPORTS = {
     "render_document_viewer": "hwpx.tools.document_viewer",
 }
 
-_DEPRECATED_EXPORTS = {
-    "analyze_template_formfit": "hwpx.template_formfit",
-    "apply_template_formfit": "hwpx.template_formfit",
-    "TEMPLATE_FORMFIT_BASELINE_SCHEMA_VERSION": "hwpx.template_formfit",
-    "TEMPLATE_FORMFIT_PLAN_SCHEMA_VERSION": "hwpx.template_formfit",
-}
+# Emptied in 5.0. The 4.x notice on these names said they would go in the next
+# major, and this is it: analyze_template_formfit, apply_template_formfit and the
+# two schema-version constants are gone with hwpx.template_formfit. Use
+# hwpx.table_patch.fill_cells, or the MCP form-fill trio.
+_DEPRECATED_EXPORTS: dict[str, str] = {}
 
 # deprecated formfit 표면의 공통 대체 경로 안내.
 _FORMFIT_REPLACEMENT = (
@@ -78,6 +79,197 @@ def _deprecated_message(name: str) -> str:
     )
 
 
+# --- 5.0에서 이동한 이름 -------------------------------------------------
+#
+# 응용 워크플로는 companion 패키지가 소유한다. 여기 남는 것은 **표뿐**이다 —
+# 그 패키지를 import하지 않는다. 설치돼 있는지에 따라 core의 동작이 달라지면
+# 의존 방향이 뒤집히고, 그건 5.0이 없애려던 바로 그 결합이다.
+#
+# 표가 하는 일은 오류 메시지 하나다. 기본 Python 오류는 이름이 사라졌다는 것만
+# 알려주고 어디로 갔는지는 말해주지 않는다.
+_SurfaceKind = Literal["symbol", "module", "renamed", "retired"]
+
+
+@dataclass(frozen=True, slots=True)
+class _CompanionSurface:
+    """One executable migration hint without importing the companion."""
+
+    kind: _SurfaceKind
+    target_module: str | None = None
+    target_name: str | None = None
+    replacement: str | None = None
+
+    def import_statement(self, legacy_name: str) -> str | None:
+        if self.kind == "retired":
+            return None
+        if self.target_module is None:
+            raise AssertionError(f"{legacy_name}: target_module is required")
+        if self.kind == "module" or (
+            self.kind == "renamed" and self.target_name is None
+        ):
+            return f"import {self.target_module} as {legacy_name}"
+        target_name = self.target_name or legacy_name
+        alias = f" as {legacy_name}" if target_name != legacy_name else ""
+        return f"from {self.target_module} import {target_name}{alias}"
+
+
+def _symbol(target_module: str, target_name: str | None = None) -> _CompanionSurface:
+    return _CompanionSurface("symbol", target_module, target_name)
+
+
+def _module(target_module: str) -> _CompanionSurface:
+    return _CompanionSurface("module", target_module)
+
+
+def _renamed(
+    target_module: str,
+    target_name: str | None = None,
+) -> _CompanionSurface:
+    return _CompanionSurface("renamed", target_module, target_name)
+
+
+_MOVED_TO_COMPANION: dict[str, _CompanionSurface] = {
+    "AUTHORING_REPORT_VERSION": _symbol("hwpx_automation.office.authoring"),
+    "DEFAULT_STYLE_PRESET": _symbol("hwpx_automation.office.authoring"),
+    "DOCUMENT_PLAN_SCHEMA_VERSION": _symbol("hwpx_automation.office.authoring"),
+    "DocumentBlock": _symbol("hwpx_automation.office.authoring"),
+    "DocumentPlan": _symbol("hwpx_automation.office.authoring"),
+    "DocumentStylePreset": _symbol("hwpx_automation.office.authoring"),
+    "OFFICIAL_DOCUMENT_STYLE_REPORT_VERSION": _symbol(
+        "hwpx_automation.office.compliance.official_lint"
+    ),
+    "PlanValidationIssue": _symbol("hwpx_automation.office.authoring"),
+    "PlanValidationReport": _symbol("hwpx_automation.office.authoring"),
+    "STYLE_PROFILE_COMPARISON_SCHEMA_VERSION": _symbol(
+        "hwpx_automation.office.authoring.style_profile"
+    ),
+    "STYLE_PROFILE_SCHEMA_VERSION": _symbol(
+        "hwpx_automation.office.authoring.style_profile"
+    ),
+    "TABLE_COMPUTE_REPORT_VERSION": _symbol("hwpx_automation.office.utilities"),
+    "TEMPLATE_REGISTRY_SCHEMA_VERSION": _symbol(
+        "hwpx_automation.office.authoring.style_profile"
+    ),
+    "agent": _module("hwpx_automation.office.agent"),
+    "apply_style_profile_to_plan": _symbol(
+        "hwpx_automation.office.authoring.style_profile"
+    ),
+    "approval_box": _symbol("hwpx_automation.office.authoring.builder"),
+    "authoring": _module("hwpx_automation.office.authoring"),
+    "build_comparison_table_plan": _symbol(
+        "hwpx_automation.office.document_ops"
+    ),
+    "build_image_grid": _symbol("hwpx_automation.office.authoring"),
+    "build_meeting_nameplates": _symbol(
+        "hwpx_automation.office.authoring.advanced_generators"
+    ),
+    "build_organization_chart": _symbol(
+        "hwpx_automation.office.authoring.advanced_generators"
+    ),
+    "builder": _module("hwpx_automation.office.authoring.builder"),
+    "compare_style_profiles": _symbol(
+        "hwpx_automation.office.authoring.style_profile"
+    ),
+    "create_document_from_plan": _symbol("hwpx_automation.office.authoring"),
+    "describe_template": _symbol(
+        "hwpx_automation.office.authoring.style_profile"
+    ),
+    "design": _module("hwpx_automation.office.authoring.design"),
+    "evalplan_fill": _renamed("hwpx_automation.office.evalplan"),
+    "exam": _module("hwpx_automation.office.exam"),
+    "extract_style_profile": _symbol(
+        "hwpx_automation.office.authoring.style_profile"
+    ),
+    "fill_residue": _module(
+        "hwpx_automation.office.form_fill.fill_residue"
+    ),
+    "form_fill": _module("hwpx_automation.office.form_fill"),
+    "formfill_quality": _renamed(
+        "hwpx_automation.office.form_fill.quality"
+    ),
+    "get_document_plan_schema": _symbol("hwpx_automation.office.authoring"),
+    "guidance_scan": _renamed(
+        "hwpx_automation.office.form_fill.guidance"
+    ),
+    "inspect_document_authoring_quality": _symbol(
+        "hwpx_automation.office.authoring"
+    ),
+    "inspect_official_document_style": _symbol(
+        "hwpx_automation.office.compliance.official_lint"
+    ),
+    "inspect_operating_plan_quality": _symbol(
+        "hwpx_automation.office.authoring"
+    ),
+    "list_templates": _symbol(
+        "hwpx_automation.office.authoring.style_profile"
+    ),
+    "mail_merge": _renamed(
+        "hwpx_automation.office.document_ops",
+        "build_mail_merge",
+    ),
+    "normalize_document_plan": _symbol("hwpx_automation.office.authoring"),
+    "placeholder_fill_report": _symbol(
+        "hwpx_automation.office.authoring.style_profile"
+    ),
+    "presets": _module("hwpx_automation.office.authoring.presets"),
+    "register_template": _symbol(
+        "hwpx_automation.office.authoring.style_profile"
+    ),
+    "table_compute": _symbol("hwpx_automation.office.utilities"),
+    "template_formfit": _module(
+        "hwpx_automation.office.form_fill.template_formfit"
+    ),
+    "validate_document_plan": _symbol("hwpx_automation.office.authoring"),
+    "visual": _renamed("hwpx_automation.office.rendering"),
+}
+
+_RETIRED_SURFACES: dict[str, _CompanionSurface] = {
+    "analyze_template_formfit": _CompanionSurface(
+        "retired",
+        replacement=(
+            "MCP analyze_form_fill → apply_form_fill → verify_form_fill 경로를 "
+            "사용하세요."
+        ),
+    ),
+    "apply_template_formfit": _CompanionSurface(
+        "retired",
+        replacement=(
+            "MCP analyze_form_fill → apply_form_fill → verify_form_fill 경로를 "
+            "사용하세요."
+        ),
+    ),
+    "TEMPLATE_FORMFIT_BASELINE_SCHEMA_VERSION": _CompanionSurface(
+        "retired",
+        replacement="새 form-fill ToolSpec 스키마를 사용하세요.",
+    ),
+    "TEMPLATE_FORMFIT_PLAN_SCHEMA_VERSION": _CompanionSurface(
+        "retired",
+        replacement="새 form-fill ToolSpec 스키마를 사용하세요.",
+    ),
+}
+
+
+class MovedToCompanion(ImportError):
+    """이동한 이름에 접근했다.
+
+    ImportError인 이유. ``from hwpx import X``는 모듈 ``__getattr__``이 던진
+    AttributeError를 잡아 자기만의 밋밋한 ImportError로 바꿔버린다 — 행선지를
+    적어 넣어도 사용자에게 닿지 않는다는 뜻이다. ImportError로 던지면 그대로
+    올라간다. 공개 코드에서 깨지는 형태가 압도적으로 ``from hwpx import X``라
+    그쪽을 택했다.
+
+    대가는 ``hasattr(hwpx, "...")``이다. Python의 hasattr은 AttributeError만
+    잡으므로 False 대신 예외가 나간다. 둘 다 상속해서 해결하려 했지만
+    ImportError와 AttributeError는 C 레벨 레이아웃이 충돌해 불가능하다.
+    예외가 나가더라도 메시지가 이유를 말해주므로 조용히 False가 되는 것보다는
+    낫다고 판단했다.
+    """
+
+
+class RetiredSurface(ImportError):
+    """A removed compatibility surface whose replacement is not another import."""
+
+
 def __getattr__(name: str) -> object:
     """Resolve dynamic module attributes.
 
@@ -90,14 +282,43 @@ def __getattr__(name: str) -> object:
 
     module_name = _EXPERIMENTAL_EXPORTS.get(name)
     if module_name is not None:
+        if module_name != "hwpx" and not module_name.startswith("hwpx."):
+            raise AttributeError(
+                "hwpx lazy-export targets must remain inside the 'hwpx' package"
+            )
         warnings.warn(_experimental_message(name), DeprecationWarning, stacklevel=2)
         return getattr(importlib.import_module(module_name), name)
 
     module_name = _DEPRECATED_EXPORTS.get(name)
     if module_name is not None:
+        if module_name != "hwpx" and not module_name.startswith("hwpx."):
+            raise AttributeError(
+                "hwpx lazy-export targets must remain inside the 'hwpx' package"
+            )
         warnings.warn(_deprecated_message(name), DeprecationWarning, stacklevel=2)
         return getattr(importlib.import_module(module_name), name)
 
+    moved = _MOVED_TO_COMPANION.get(name)
+    if moved is not None:
+        statement = moved.import_statement(name)
+        assert statement is not None
+        raise MovedToCompanion(
+            f"{name}은(는) python-hwpx 5.0에서 companion 패키지로 이동했습니다.\n"
+            f"    pip install python-hwpx-automation\n"
+            f"    {statement}\n"
+            f'4.x를 계속 쓰려면: pip install "python-hwpx<5"\n'
+            f"전체 대체표: docs/migration-5.0.md"
+        )
+
+    retired = _RETIRED_SURFACES.get(name)
+    if retired is not None:
+        raise RetiredSurface(
+            f"{name}은(는) 예고대로 python-hwpx 5.0에서 제거되었습니다. "
+            f"{retired.replacement}\n"
+            f'4.x를 계속 쓰려면: pip install "python-hwpx<5"\n'
+            f"전체 대체표: docs/migration-5.0.md"
+        )
+
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 
@@ -118,15 +339,9 @@ from .tools.text_extractor import (
     TextExtractor,
 )
 from .tools.object_finder import FoundElement, ObjectFinder
-from .tools.advanced_generators import (
-    build_image_grid,
-    build_meeting_nameplates,
-    build_organization_chart,
-)
 from .tools.doc_diff import (
     DOC_DIFF_REPORT_VERSION,
     REFERENCE_CONSISTENCY_REPORT_VERSION,
-    build_comparison_table_plan,
     diff_paragraphs,
     doc_diff,
     inspect_reference_consistency,
@@ -135,15 +350,7 @@ from .tools.mail_merge import (
     MAIL_MERGE_REPORT_VERSION,
     inspect_mail_merge_placeholders,
     load_mail_merge_rows,
-    mail_merge,
-)
-from .tools.table_compute import (
-    TABLE_COMPUTE_REPORT_VERSION,
-    table_compute,
-)
-from .tools.official_lint import (
-    OFFICIAL_DOCUMENT_STYLE_REPORT_VERSION,
-    inspect_official_document_style,
+    merge_template_rows,
 )
 from .tools.package_validator import (
     EditorOpenSafetyReport,
@@ -151,18 +358,6 @@ from .tools.package_validator import (
     validate_editor_open_safety,
     validate_package,
 )
-from .tools.style_profile import (
-    STYLE_PROFILE_COMPARISON_SCHEMA_VERSION,
-    STYLE_PROFILE_SCHEMA_VERSION,
-    TEMPLATE_REGISTRY_SCHEMA_VERSION,
-    apply_style_profile_to_plan,
-    compare_style_profiles,
-    describe_template,
-    extract_style_profile,
-    list_templates,
-    placeholder_fill_report,
-    register_template,
-)
 from .ingest import HwpxMarkdownConverter
 from .errors import HwpxError
 from .mutation_report import (
@@ -178,23 +373,6 @@ from .patch import (
 )
 from .document import HwpxDocument
 from .package import HwpxPackage
-from .authoring import (
-    AUTHORING_REPORT_VERSION,
-    DEFAULT_STYLE_PRESET,
-    DOCUMENT_PLAN_SCHEMA_VERSION,
-    DocumentBlock,
-    DocumentPlan,
-    DocumentStylePreset,
-    PlanValidationIssue,
-    PlanValidationReport,
-    create_document_from_plan,
-    get_document_plan_schema,
-    inspect_document_authoring_quality,
-    inspect_operating_plan_quality,
-    normalize_document_plan,
-    validate_document_plan,
-)
-from .builder import approval_box
 from .quality import (
     QualityPolicy,
     SavePipeline,
@@ -202,18 +380,20 @@ from .quality import (
 )
 
 __all__ = [
+    "inspect_reference_consistency",
+    "doc_diff",
+    "diff_paragraphs",
+    "REFERENCE_CONSISTENCY_REPORT_VERSION",
+    "DOC_DIFF_REPORT_VERSION",
+    "merge_template_rows",
+    "load_mail_merge_rows",
+    "inspect_mail_merge_placeholders",
+    "MAIL_MERGE_REPORT_VERSION",
     "QualityPolicy",
     "SavePipeline",
     "VisualCompleteReport",
     "__version__",
-    "AUTHORING_REPORT_VERSION",
     "DEFAULT_NAMESPACES",
-    "DEFAULT_STYLE_PRESET",
-    "DOCUMENT_PLAN_SCHEMA_VERSION",
-    "get_document_plan_schema",
-    "DocumentBlock",
-    "DocumentPlan",
-    "DocumentStylePreset",
     "EditorOpenSafetyReport",
     "ParagraphInfo",
     "PackageValidationReport",
@@ -221,7 +401,6 @@ __all__ = [
     "HwpxError",
     "MutationReport",
     "PreservationDowngradeError",
-    "PlanValidationReport",
     "ParagraphTextPatch",
     "PatchApplied",
     "PatchSkipped",
@@ -230,43 +409,9 @@ __all__ = [
     "FoundElement",
     "HwpxMarkdownConverter",
     "ObjectFinder",
-    "OFFICIAL_DOCUMENT_STYLE_REPORT_VERSION",
-    "DOC_DIFF_REPORT_VERSION",
-    "REFERENCE_CONSISTENCY_REPORT_VERSION",
-    "MAIL_MERGE_REPORT_VERSION",
-    "STYLE_PROFILE_COMPARISON_SCHEMA_VERSION",
-    "STYLE_PROFILE_SCHEMA_VERSION",
-    "TEMPLATE_REGISTRY_SCHEMA_VERSION",
-    "TABLE_COMPUTE_REPORT_VERSION",
-    "apply_style_profile_to_plan",
-    "build_comparison_table_plan",
-    "build_image_grid",
-    "build_meeting_nameplates",
-    "build_organization_chart",
-    "diff_paragraphs",
-    "doc_diff",
-    "compare_style_profiles",
-    "PlanValidationIssue",
     "HwpxDocument",
     "HwpxPackage",
-    "create_document_from_plan",
-    "approval_box",
-    "describe_template",
-    "extract_style_profile",
-    "inspect_document_authoring_quality",
-    "inspect_mail_merge_placeholders",
-    "inspect_official_document_style",
-    "inspect_reference_consistency",
-    "inspect_operating_plan_quality",
-    "list_templates",
-    "load_mail_merge_rows",
-    "mail_merge",
-    "normalize_document_plan",
-    "placeholder_fill_report",
-    "validate_document_plan",
     "validate_editor_open_safety",
     "validate_package",
     "paragraph_patch",
-    "register_template",
-    "table_compute",
 ]

hwpx/_document/__init__.py

@@ -1,2 +1,2 @@
 # SPDX-License-Identifier: Apache-2.0
-"""Domain owners behind the HwpxDocument facade (S-084)."""
+"""Domain owners behind the HwpxDocument facade."""

hwpx/_document/_units.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-"""Shared HWPUNIT conversion helpers for the HwpxDocument owner modules (S-084)."""
+"""Shared HWPUNIT conversion helpers for the HwpxDocument owner modules."""
 
 from __future__ import annotations
 

hwpx/_document/fields.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-"""Form-field domain owner behind the :class:`HwpxDocument` facade (S-084)."""
+"""Form-field domain owner behind the :class:`HwpxDocument` facade."""
 
 from __future__ import annotations
 

hwpx/_document/layout.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-"""Formatting and page-layout domain owner behind the HwpxDocument facade (S-084)."""
+"""Formatting and page-layout domain owner behind the HwpxDocument facade."""
 
 from __future__ import annotations
 

hwpx/_document/media.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-"""Picture/image domain owner behind the HwpxDocument facade (S-084)."""
+"""Picture/image domain owner behind the HwpxDocument facade."""
 
 from __future__ import annotations
 

hwpx/_document/memos.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-"""Memo domain owner behind the :class:`HwpxDocument` facade (S-084)."""
+"""Memo domain owner behind the :class:`HwpxDocument` facade."""
 
 from __future__ import annotations
 

hwpx/_document/persistence.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-"""Save/validate/export domain owner behind the HwpxDocument facade (S-084)."""
+"""Save/validate/export domain owner behind the HwpxDocument facade."""
 
 from __future__ import annotations
 

hwpx/_document/shapes.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-"""Shape/control/note domain owner behind the HwpxDocument facade (S-084)."""
+"""Shape/control/note domain owner behind the HwpxDocument facade."""
 
 from __future__ import annotations
 
@@ -29,7 +29,13 @@ def add_shape(
     run_attributes: dict[str, str] | None = None,
     **extra_attrs: str,
 ) -> HwpxOxmlInlineObject:
-    """Insert an inline shape into a new paragraph."""
+    """Insert an inline shape into a new paragraph.
+
+    Low-level escape hatch — writes only the element and attributes it is
+    handed, so the result is not openable by Hancom until the required OWPML
+    children are supplied.  Warns while they are missing.  Prefer
+    :func:`add_line`, :func:`add_rectangle`, and :func:`add_ellipse`.
+    """
 
     paragraph = doc.add_paragraph(
         "",
@@ -62,7 +68,12 @@ def add_control(
     run_attributes: dict[str, str] | None = None,
     **extra_attrs: str,
 ) -> HwpxOxmlInlineObject:
-    """Insert a control inline object into a new paragraph."""
+    """Insert a control inline object into a new paragraph.
+
+    Low-level escape hatch — an ``<hp:ctrl>`` means nothing without the child
+    element that carries the control, and Hancom refuses to open a document
+    containing an empty one, so this warns until a child is appended.
+    """
 
     paragraph = doc.add_paragraph(
         "",

hwpx/_document/tracked.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-"""Tracked-change authoring owner behind the :class:`HwpxDocument` facade (S-084)."""
+"""Tracked-change authoring owner behind the :class:`HwpxDocument` facade."""
 
 from __future__ import annotations
 
@@ -48,6 +48,36 @@ def _paragraph_has_deletable_text(
     return False
 
 
+def _paragraph_has_replaceable_text(
+    paragraph: "HwpxOxmlParagraph",
+    match: str,
+) -> bool:
+    """Return whether *match* can be wrapped inside one inline text segment.
+
+    A match that only exists after concatenating text across inline markup is
+    present but cannot be rewritten safely.  Detect that before allocating
+    tracked-change header IDs so a rejected replacement leaves no orphan
+    metadata behind.
+    """
+
+    crosses_inline_markup = False
+    for run in paragraph.runs:
+        model = run.to_model()
+        run_text = "".join(span.text for span in model.text_spans)
+        if match not in run_text:
+            continue
+        for span in model.text_spans:
+            if match in span.leading_text or any(
+                match in markup.trailing_text for markup in span.marks
+            ):
+                return True
+        crosses_inline_markup = True
+
+    if crosses_inline_markup:
+        raise ValueError("match crosses inline markup and cannot be wrapped safely")
+    return False
+
+
 def add_tracked_insert(
     doc: "HwpxDocument",
     paragraph: "HwpxOxmlParagraph",
@@ -111,16 +141,30 @@ def add_tracked_replace(
 ) -> tuple[int, int]:
     """Represent a replacement as tracked delete of *old* plus tracked insert of *new*."""
 
-    delete_change_id = doc.add_tracked_delete(
-        paragraph,
-        match=old,
-        author=author,
+    if old == "":
+        raise ValueError("match must be a non-empty string")
+    if not _paragraph_has_replaceable_text(paragraph, old):
+        raise ValueError("match text was not found in the paragraph")
+    sanitized = _sanitize_tracked_text(new)
+    if not sanitized:
+        raise ValueError("tracked insert text must be non-empty")
+
+    delete_change_id = doc.add_track_change(
+        "Delete",
+        author_name=author,
         date=date,
     )
-    insert_change_id = doc.add_tracked_insert(
-        paragraph,
-        new,
-        author=author,
+    insert_change_id = doc.add_track_change(
+        "Insert",
+        author_name=author,
         date=date,
     )
+    first_mark_id = doc._root.next_track_change_mark_id()
+    paragraph._add_tracked_replace(
+        old,
+        sanitized,
+        delete_change_id=delete_change_id,
+        insert_change_id=insert_change_id,
+        first_mark_id=first_mark_id,
+    )
     return delete_change_id, insert_change_id

hwpx/body_patch.py

@@ -451,8 +451,8 @@ def strip_runs_by_color(
         sections = {n: z.read(n).decode("utf-8") for n in names if re.search(r"section\d+\.xml$", n)}
 
     # 계열 매칭(잔존 게이트와 정렬): 대상 색의 _color_family에 드는 모든 charPr.
-    from .guidance_scan import _color_family
-    target_families = {_color_family(h) for h in targets}
+    from .oxml.color import color_family
+    target_families = {color_family(h) for h in targets}
     ids = set()
     for cm in re.finditer(r"<(?:[A-Za-z_][\w.-]*:)?charPr\b[^>]*?>", header_xml):
         tag = cm.group(0)
@@ -461,7 +461,7 @@ def strip_runs_by_color(
         if not (idm and colm):
             continue
         col = colm.group(1).upper()
-        if col in targets or _color_family(col) in target_families:
+        if col in targets or color_family(col) in target_families:
             ids.add(idm.group(1))
     transcript: list[dict[str, Any]] = []
     changed: set[str] = set()