athena-python-docx 0.5.3__tar.gz → 0.6.0__tar.gz

{athena_python_docx-0.5.3 → athena_python_docx-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.5.3
+Version: 0.6.0
 Summary: Drop-in replacement for python-docx that connects to Athena's Superdoc/Keryx collaborative document stack
 Project-URL: Homepage, https://athenaintelligence.ai
 Author-email: Athena Intelligence <engineering@athenaintelligence.ai>

{athena_python_docx-0.5.3 → athena_python_docx-0.6.0}/docx/__init__.py

@@ -6,7 +6,7 @@ See CLAUDE.md for the API parity contract.
 
 from __future__ import annotations
 
-__version__ = "0.5.3"
+__version__ = "0.6.0"
 
 from docx.api import Document
 from docx._buffer import flush_all

{athena_python_docx-0.5.3 → athena_python_docx-0.6.0}/docx/enum/text.py

@@ -2,14 +2,49 @@
 
 Values map to Superdoc primitives where supported; unmapped values
 (e.g. Thai/Arabic justification variants) still parse but serialize to
-their best Superdoc equivalent.
+their best Superdoc equivalent and emit
+:class:`PendingEnumCoercionWarning` so the caller knows the wire-level
+intent was downgraded.
 """
 
 from __future__ import annotations
 
+import warnings
 from enum import Enum
 
 
+class PendingEnumCoercionWarning(UserWarning):
+    """Emitted when an enum member's :meth:`to_superdoc` collapses the
+    value to a different SuperDoc-supported primitive.
+
+    Examples:
+    - ``WD_ALIGN_PARAGRAPH.THAI_JUSTIFY.to_superdoc()`` returns
+      ``"justify"`` because SuperDoc 1.8's ``set_alignment`` rejects
+      ``thaiJustify``.
+    - ``WD_TAB_ALIGNMENT.CLEAR.to_superdoc()`` returns ``"left"``
+      because SuperDoc has no equivalent clear/end/num/start tab
+      vocabulary.
+
+    Tracked in ``docx-studio/SUPERDOC_UPSTREAM_REQUESTS.md``. Pin so a
+    future SuperDoc that lands the full vocabulary can flip the
+    coercion off and these warnings disappear.
+    """
+
+
+def _warn_enum_coercion(enum_member: object, fallback: str) -> None:
+    """Emit a single warning identifying which enum member got
+    coerced to which SuperDoc primitive."""
+    warnings.warn(
+        f"{enum_member!r}.to_superdoc() returns {fallback!r} — "
+        f"SuperDoc 1.8 doesn't surface this value, so the wire ships "
+        f"the closest supported primitive. The visual result may "
+        f"differ from python-docx. Tracked in "
+        f"docx-studio/SUPERDOC_UPSTREAM_REQUESTS.md.",
+        PendingEnumCoercionWarning,
+        stacklevel=3,
+    )
+
+
 class WD_ALIGN_PARAGRAPH(Enum):
     """Paragraph alignment (justification)."""
 
@@ -26,7 +61,10 @@ class WD_ALIGN_PARAGRAPH(Enum):
     def to_superdoc(self) -> str:
         # Superdoc only supports left/center/right/justify; coerce the
         # distributed/thai variants to "justify" so set_alignment doesn't
-        # reject them.
+        # reject them. Emit PendingEnumCoercionWarning so the caller
+        # learns the wire-level intent was downgraded (silently shipping
+        # "justify" when the user asked for thaiJustify is the silent
+        # stub the parity loop is hunting).
         if self in (
             WD_ALIGN_PARAGRAPH.DISTRIBUTE,
             WD_ALIGN_PARAGRAPH.JUSTIFY_MED,
@@ -34,6 +72,7 @@ class WD_ALIGN_PARAGRAPH(Enum):
             WD_ALIGN_PARAGRAPH.JUSTIFY_LOW,
             WD_ALIGN_PARAGRAPH.THAI_JUSTIFY,
         ):
+            _warn_enum_coercion(self, "justify")
             return "justify"
         return self.value
 
@@ -82,6 +121,10 @@ class WD_TAB_ALIGNMENT(Enum):
     START = "start"
 
     def to_superdoc(self) -> str:
+        # Superdoc only supports left/center/right/decimal/bar for tab
+        # alignment. ``LIST`` / ``CLEAR`` / ``END`` / ``NUM`` / ``START``
+        # are upstream-only — emit PendingEnumCoercionWarning so callers
+        # learn the wire-level intent was downgraded to ``"left"``.
         if self in (
             WD_TAB_ALIGNMENT.LIST,
             WD_TAB_ALIGNMENT.CLEAR,
@@ -89,6 +132,7 @@ class WD_TAB_ALIGNMENT(Enum):
             WD_TAB_ALIGNMENT.NUM,
             WD_TAB_ALIGNMENT.START,
         ):
+            _warn_enum_coercion(self, "left")
             return "left"
         return self.value
 

{athena_python_docx-0.5.3 → athena_python_docx-0.6.0}/docx/text/parfmt.py

@@ -11,6 +11,7 @@ Setters accept:
 
 from __future__ import annotations
 
+import warnings
 from typing import TYPE_CHECKING
 
 from docx._batching import run_sync
@@ -22,6 +23,49 @@ if TYPE_CHECKING:
     from docx.text.tabstops import TabStops
 
 
+class PendingParfmtClearWarning(UserWarning):
+    """Emitted when a ``ParagraphFormat`` setter is asked to clear a
+    trivalent (None/True/False) property whose SuperDoc wire op
+    doesn't expose a clear primitive.
+
+    Behavior pinned for parity with python-docx 1.x semantics
+    (``None`` means "inherit from style") even though SuperDoc 1.8 can
+    only set explicit values. The setter is a no-op at the wire level
+    but emits this warning so silent inheritance-vs-set divergence
+    surfaces during agent runs. Tracked in
+    ``docx-studio/SUPERDOC_UPSTREAM_REQUESTS.md``.
+    """
+
+
+def _warn_parfmt_clear(prop: str) -> None:
+    warnings.warn(
+        f"ParagraphFormat.{prop} = None was IGNORED — SuperDoc 1.8 "
+        f"has no clear-op for this trivalent attribute. The value "
+        f"stays whatever it was last set to (or inherited from the "
+        f"paragraph style). Tracked in "
+        f"docx-studio/SUPERDOC_UPSTREAM_REQUESTS.md.",
+        PendingParfmtClearWarning,
+        stacklevel=3,
+    )
+
+
+def _require_bool(prop: str, value: object) -> bool:
+    """Reject non-bool input for trivalent on/off properties.
+
+    ``bool`` is a Python ``int`` subclass, so a bare ``True``/``False``
+    would otherwise hit any ``isinstance(value, int)`` branch first
+    and produce surprising semantics (e.g. ``line_spacing = True``
+    setting a 1× multiplier). Callers must pass real bools.
+    """
+    if not isinstance(value, bool):
+        raise TypeError(
+            f"ParagraphFormat.{prop} requires bool (True/False/None); "
+            f"got {type(value).__name__} {value!r}. python-docx 1.x "
+            f"rejects truthy non-bool input here too.",
+        )
+    return value
+
+
 def _to_twips(value: object) -> int:
     """Coerce a length-ish input to twips (int)."""
     if value is None:
@@ -223,6 +267,16 @@ class ParagraphFormat:
         if value is None:
             self._clear_spacing()
             return
+        # ``bool`` is a subclass of ``int`` in Python, so ``True``/``False``
+        # would otherwise silently hit the ``1 <= value <= 4`` branch
+        # (1× multiplier) or the EMU fallthrough (0). Reject upfront —
+        # python-docx 1.x raises ``TypeError`` for non-Length/numeric.
+        if isinstance(value, bool):
+            raise TypeError(
+                f"line_spacing requires float/int/Length, not bool; "
+                f"got {value!r}. Pass 1.0 / 1.5 / 2.0 for "
+                f"single/1.5×/double, or a Length for exact spacing.",
+            )
         if isinstance(value, Length):
             self._set_spacing(line=value.twips, lineRule="exact")
             return
@@ -268,7 +322,13 @@ class ParagraphFormat:
         from docx.enum.text import WD_LINE_SPACING
 
         if value is None:
+            self._clear_spacing()
             return
+        if not isinstance(value, WD_LINE_SPACING):
+            raise ValueError(
+                f"line_spacing_rule: expected WD_LINE_SPACING, got "
+                f"{type(value).__name__} {value!r}",
+            )
         if value == WD_LINE_SPACING.SINGLE:
             self._set_spacing(line=240, lineRule="auto")
         elif value == WD_LINE_SPACING.ONE_POINT_FIVE:
@@ -279,6 +339,22 @@ class ParagraphFormat:
             self._set_spacing(line=240, lineRule="exact")
         elif value == WD_LINE_SPACING.AT_LEAST:
             self._set_spacing(line=240, lineRule="atLeast")
+        elif value == WD_LINE_SPACING.MULTIPLE:
+            # MULTIPLE without an explicit numeric value is meaningless;
+            # python-docx 1.x raises ``ValueError`` for the same reason.
+            raise ValueError(
+                "line_spacing_rule = WD_LINE_SPACING.MULTIPLE is not "
+                "settable on its own — set line_spacing to a float "
+                "multiplier (e.g. 1.5) instead, which implicitly uses "
+                "the MULTIPLE rule via lineRule='auto'.",
+            )
+        else:
+            # Defensive: any new enum member we haven't mapped to a wire
+            # primitive should surface as ValueError, not silently no-op.
+            raise ValueError(
+                f"line_spacing_rule: unsupported WD_LINE_SPACING "
+                f"member {value!r} — no wire mapping in athena-python-docx.",
+            )
 
     # ---- keep / widow ----
     @property
@@ -290,8 +366,9 @@ class ParagraphFormat:
     @keep_together.setter
     def keep_together(self, value: bool | None) -> None:
         if value is None:
+            _warn_parfmt_clear("keep_together")
             return
-        self._set_keep(keepLines=bool(value))
+        self._set_keep(keepLines=_require_bool("keep_together", value))
 
     @property
     def keep_with_next(self) -> bool | None:
@@ -302,8 +379,9 @@ class ParagraphFormat:
     @keep_with_next.setter
     def keep_with_next(self, value: bool | None) -> None:
         if value is None:
+            _warn_parfmt_clear("keep_with_next")
             return
-        self._set_keep(keepNext=bool(value))
+        self._set_keep(keepNext=_require_bool("keep_with_next", value))
 
     @property
     def widow_control(self) -> bool | None:
@@ -314,8 +392,9 @@ class ParagraphFormat:
     @widow_control.setter
     def widow_control(self, value: bool | None) -> None:
         if value is None:
+            _warn_parfmt_clear("widow_control")
             return
-        self._set_keep(widowControl=bool(value))
+        self._set_keep(widowControl=_require_bool("widow_control", value))
 
     @property
     def page_break_before(self) -> bool | None:
@@ -326,11 +405,16 @@ class ParagraphFormat:
     @page_break_before.setter
     def page_break_before(self, value: bool | None) -> None:
         if value is None:
+            _warn_parfmt_clear("page_break_before")
             return
-        # Superdoc's setFlowOptions handles pageBreakBefore
+        # Superdoc's setFlowOptions handles pageBreakBefore.
+        # Reject non-bool to keep parity with python-docx 1.x's strict
+        # ``_OnOff`` handling — ``bool(non_bool_value)`` silently coerces
+        # garbage to True.
+        coerced: bool = _require_bool("page_break_before", value)
         run_sync(
             self._paragraph._session.doc.format.paragraph.set_flow_options(
-                {"target": self._target(), "pageBreakBefore": bool(value)},
+                {"target": self._target(), "pageBreakBefore": coerced},
             ),
         )
 

{athena_python_docx-0.5.3 → athena_python_docx-0.6.0}/docx/text/tabstops.py

@@ -23,6 +23,59 @@ if TYPE_CHECKING:
     from docx.text.parfmt import ParagraphFormat
 
 
+def _coerce_alignment(value: object) -> str:
+    """Coerce ``WD_TAB_ALIGNMENT`` or its string form to the SuperDoc
+    wire value, rejecting anything else.
+
+    Previously the setter / factory accepted ``str(value)`` for any
+    input, shipping bogus alignment strings to the wire (SuperDoc
+    silently fell back to ``left``). python-docx 1.x validates against
+    the enum at the XML serialization layer.
+    """
+    if isinstance(value, WD_TAB_ALIGNMENT):
+        return value.to_superdoc()
+    if isinstance(value, str):
+        try:
+            return WD_TAB_ALIGNMENT(value).to_superdoc()
+        except ValueError as e:
+            raise ValueError(
+                f"Tab stop alignment {value!r} is not a valid "
+                f"WD_TAB_ALIGNMENT value. Expected one of "
+                f"{[m.value for m in WD_TAB_ALIGNMENT]} or a "
+                f"WD_TAB_ALIGNMENT enum member.",
+            ) from e
+    raise TypeError(
+        f"Tab stop alignment must be WD_TAB_ALIGNMENT or str; "
+        f"got {type(value).__name__} {value!r}",
+    )
+
+
+def _coerce_leader(value: object) -> str:
+    """Coerce ``WD_TAB_LEADER`` or its string form to the SuperDoc
+    wire value, rejecting anything else.
+
+    Same rationale as :func:`_coerce_alignment` — the prior
+    ``str(value)`` accept-anything path silently shipped bogus leader
+    values that SuperDoc swallowed.
+    """
+    if isinstance(value, WD_TAB_LEADER):
+        return value.to_superdoc()
+    if isinstance(value, str):
+        try:
+            return WD_TAB_LEADER(value).to_superdoc()
+        except ValueError as e:
+            raise ValueError(
+                f"Tab stop leader {value!r} is not a valid "
+                f"WD_TAB_LEADER value. Expected one of "
+                f"{[m.value for m in WD_TAB_LEADER]} or a "
+                f"WD_TAB_LEADER enum member.",
+            ) from e
+    raise TypeError(
+        f"Tab stop leader must be WD_TAB_LEADER or str; "
+        f"got {type(value).__name__} {value!r}",
+    )
+
+
 class TabStop:
     """A single tab stop entry. Returned by :class:`TabStops` iteration
     and by :meth:`TabStops.add_tab_stop`.
@@ -63,12 +116,7 @@ class TabStop:
 
     @alignment.setter
     def alignment(self, value: "WD_TAB_ALIGNMENT | str") -> None:
-        from docx.enum.text import WD_TAB_ALIGNMENT
-
-        if isinstance(value, WD_TAB_ALIGNMENT):
-            self._data["alignment"] = value.to_superdoc()
-        else:
-            self._data["alignment"] = str(value)
+        self._data["alignment"] = _coerce_alignment(value)
         self._parent._rewrite_from_data([s._data for s in self._parent._stops()])
 
     @property
@@ -83,12 +131,7 @@ class TabStop:
 
     @leader.setter
     def leader(self, value: "WD_TAB_LEADER | str") -> None:
-        from docx.enum.text import WD_TAB_LEADER
-
-        if isinstance(value, WD_TAB_LEADER):
-            self._data["leader"] = value.to_superdoc()
-        else:
-            self._data["leader"] = str(value)
+        self._data["leader"] = _coerce_leader(value)
         self._parent._rewrite_from_data([s._data for s in self._parent._stops()])
 
 
@@ -170,15 +213,13 @@ class TabStops:
 
         ``alignment`` defaults to ``WD_TAB_ALIGNMENT.LEFT``, ``leader``
         defaults to ``WD_TAB_LEADER.SPACES`` — matching python-docx.
+        Bogus enum-equivalent strings now raise ``ValueError``; a
+        non-enum/non-str input raises ``TypeError``. Previously any
+        ``str(value)`` was shipped to the wire and SuperDoc silently
+        fell back to defaults.
         """
-        align_val: str = (
-            alignment.to_superdoc()
-            if isinstance(alignment, WD_TAB_ALIGNMENT)
-            else str(alignment)
-        )
-        leader_val: str = (
-            leader.to_superdoc() if isinstance(leader, WD_TAB_LEADER) else str(leader)
-        )
+        align_val: str = _coerce_alignment(alignment)
+        leader_val: str = _coerce_leader(leader)
         pos_twips: int = _to_twips(position)
         run_sync(
             self._parfmt._paragraph._session.doc.format.paragraph.set_tab_stop(

{athena_python_docx-0.5.3 → athena_python_docx-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "athena-python-docx"
-version = "0.5.3"
+version = "0.6.0"
 description = "Drop-in replacement for python-docx that connects to Athena's Superdoc/Keryx collaborative document stack"
 readme = "README.md"
 license = "MIT"

{athena_python_docx-0.5.3 → athena_python_docx-0.6.0}/tests/parity/reports/GAP_ANALYSIS.md

@@ -10,10 +10,10 @@ Comparing **athena-python-docx 0.5.2** (39 modules) against **python-docx 1.2.0*
 | `class_missing` | 201 | 0 | 201 |
 | `member_missing` | 71 | 0 | 71 |
 | `member_kind_drift` | 0 | 0 | 0 |
-| `ctor_signature_drift` | 32 | 0 | 32 |
+| `ctor_signature_drift` | 57 | 0 | 57 |
 | `signature_drift` | 1 | 0 | 1 |
 | `return_annotation_drift` | 0 | 0 | 0 |
-| **TOTAL** | **372** | **0** | **372** |
+| **TOTAL** | **397** | **0** | **397** |
 
 ## Intentional deviations (filtered out)
 
@@ -22,6 +22,31 @@ These are documented as intentional in `tests/parity/intentional_deviations.json
 - `docx.comments.Comment` (ctor_signature_drift)
 - `docx.comments.Comments` (ctor_signature_drift)
 - `docx.document.Document` (ctor_signature_drift)
+- `docx.enum.section.WD_HEADER_FOOTER` (ctor_signature_drift)
+- `docx.enum.section.WD_HEADER_FOOTER_INDEX` (ctor_signature_drift)
+- `docx.enum.section.WD_ORIENT` (ctor_signature_drift)
+- `docx.enum.section.WD_ORIENTATION` (ctor_signature_drift)
+- `docx.enum.section.WD_SECTION` (ctor_signature_drift)
+- `docx.enum.section.WD_SECTION_START` (ctor_signature_drift)
+- `docx.enum.style.WD_BUILTIN_STYLE` (ctor_signature_drift)
+- `docx.enum.style.WD_STYLE` (ctor_signature_drift)
+- `docx.enum.style.WD_STYLE_TYPE` (ctor_signature_drift)
+- `docx.enum.table.WD_ALIGN_VERTICAL` (ctor_signature_drift)
+- `docx.enum.table.WD_CELL_VERTICAL_ALIGNMENT` (ctor_signature_drift)
+- `docx.enum.table.WD_ROW_HEIGHT` (ctor_signature_drift)
+- `docx.enum.table.WD_ROW_HEIGHT_RULE` (ctor_signature_drift)
+- `docx.enum.table.WD_TABLE_ALIGNMENT` (ctor_signature_drift)
+- `docx.enum.table.WD_TABLE_DIRECTION` (ctor_signature_drift)
+- `docx.enum.text.WD_ALIGN_PARAGRAPH` (ctor_signature_drift)
+- `docx.enum.text.WD_BREAK` (ctor_signature_drift)
+- `docx.enum.text.WD_BREAK_TYPE` (ctor_signature_drift)
+- `docx.enum.text.WD_COLOR` (ctor_signature_drift)
+- `docx.enum.text.WD_COLOR_INDEX` (ctor_signature_drift)
+- `docx.enum.text.WD_LINE_SPACING` (ctor_signature_drift)
+- `docx.enum.text.WD_PARAGRAPH_ALIGNMENT` (ctor_signature_drift)
+- `docx.enum.text.WD_TAB_ALIGNMENT` (ctor_signature_drift)
+- `docx.enum.text.WD_TAB_LEADER` (ctor_signature_drift)
+- `docx.enum.text.WD_UNDERLINE` (ctor_signature_drift)
 - `docx.opc.coreprops.CoreProperties` (ctor_signature_drift)
 - `docx.section.Section` (ctor_signature_drift)
 - `docx.section.Sections` (ctor_signature_drift)