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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.5.3
+Version: 0.6.1
 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.1}/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.1"
 
 from docx.api import Document
 from docx._buffer import flush_all

{athena_python_docx-0.5.3 → athena_python_docx-0.6.1}/docx/comments.py

@@ -314,6 +314,26 @@ class Comments:
         Use :meth:`Document.add_comment` to thread a run-anchored
         target — this method creates an unanchored comment.
         """
+        # python-docx 1.x routes ``text`` / ``author`` / ``initials``
+        # through lxml's element setters which TypeError on non-str.
+        # Was: any value shipped to wire (text) or stashed as-is on
+        # the local info dict (author/initials) — caller's intent was
+        # lost when they passed a wrong type.
+        if not isinstance(text, str):
+            raise TypeError(
+                f"Comments.add_comment text requires str; got "
+                f"{type(text).__name__} {text!r}",
+            )
+        if not isinstance(author, str):
+            raise TypeError(
+                f"Comments.add_comment author requires str; got "
+                f"{type(author).__name__} {author!r}",
+            )
+        if initials is not None and not isinstance(initials, str):
+            raise TypeError(
+                f"Comments.add_comment initials requires str or None; "
+                f"got {type(initials).__name__} {initials!r}",
+            )
         result: object = run_sync(
             self._session.doc.comments.create({"text": text}),
         )

{athena_python_docx-0.5.3 → athena_python_docx-0.6.1}/docx/document.py

@@ -596,9 +596,24 @@ class Document:
 
         # Coerce ParagraphStyle instances to their style id so the rest
         # of this method can treat `style` as an Optional[str].
-        style_str: str | None = (
-            style.style_id if isinstance(style, ParagraphStyle) else style
-        )
+        # python-docx 1.x accepts ``str | ParagraphStyle | None`` and
+        # raises ``TypeError`` at the style-lookup layer for anything
+        # else. Mirror that — the previous code accepted ``style`` as
+        # the literal value when it wasn't a ParagraphStyle, so e.g.
+        # ``add_paragraph(style=42)`` shipped ``42`` as the style id.
+        style_str: str | None
+        if style is None:
+            style_str = None
+        elif isinstance(style, ParagraphStyle):
+            style_str = style.style_id
+        elif isinstance(style, str):
+            style_str = style
+        else:
+            raise TypeError(
+                f"Document.add_paragraph style requires str, "
+                f"ParagraphStyle, or None; got "
+                f"{type(style).__name__} {style!r}",
+            )
 
         # Use Superdoc's canonical primitive `doc.create.paragraph`. It
         # accepts an `at` anchor and a `text` body; an empty `text` creates
@@ -624,8 +639,9 @@ class Document:
         # heavy lifting.
         normalized: str = self._normalize_text(text)
         has_control_chars = any(ch in "\t\n\r" for ch in normalized)
+        wire_text: str = "" if has_control_chars else normalized
         params: dict = {
-            "text": "" if has_control_chars else normalized,
+            "text": wire_text,
             "at": {"kind": "documentEnd"},
         }
         # When inside ``with doc.batch():`` we pre-assign a client UUID
@@ -650,8 +666,13 @@ class Document:
                 raise RuntimeError(
                     f"Superdoc did not return a nodeId for add_paragraph: {result!r}",
                 )
+        # Seed the text-length cache so the next ``p.add_run(...)``
+        # call can skip its ``get_node_by_id`` HTTP round-trip.
         para = Paragraph(
-            session=self._session, node_id=node_id, node_type="paragraph",
+            session=self._session,
+            node_id=node_id,
+            node_type="paragraph",
+            text_len=len(wire_text),
         )
         if client_node_id is not None:
             self._register_proxy_for_batch(client_node_id, para)
@@ -722,6 +743,7 @@ class Document:
                 session=self._session,
                 node_id=node_id,
                 node_type="paragraph",
+                text_len=len(wire_text),
             )
             if client_node_id is not None:
                 self._register_proxy_for_batch(client_node_id, paragraph)
@@ -753,7 +775,10 @@ class Document:
                     f"Superdoc did not return a nodeId for add_heading: {result!r}",
                 )
         heading = Paragraph(
-            session=self._session, node_id=node_id, node_type="heading",
+            session=self._session,
+            node_id=node_id,
+            node_type="heading",
+            text_len=len(wire_text),
         )
         if client_node_id is not None:
             self._register_proxy_for_batch(client_node_id, heading)

{athena_python_docx-0.5.3 → athena_python_docx-0.6.1}/docx/enum/section.py

@@ -4,6 +4,17 @@ from __future__ import annotations
 
 from enum import Enum
 
+from docx.enum.text import _warn_enum_coercion
+
+__all__ = [
+    "WD_HEADER_FOOTER",
+    "WD_HEADER_FOOTER_INDEX",
+    "WD_ORIENT",
+    "WD_ORIENTATION",
+    "WD_SECTION",
+    "WD_SECTION_START",
+]
+
 
 class WD_ORIENTATION(Enum):
     PORTRAIT = "portrait"
@@ -31,6 +42,13 @@ class WD_SECTION_START(Enum):
             return "evenPage"
         if self == WD_SECTION_START.ODD_PAGE:
             return "oddPage"
+        if self == WD_SECTION_START.NEW_PAGE:
+            return "nextPage"
+        # NEW_COLUMN — SuperDoc 1.8 doesn't have a column-break section
+        # type, so we collapse to "nextPage" but emit
+        # PendingEnumCoercionWarning so callers don't silently get a
+        # page break when they asked for a column break.
+        _warn_enum_coercion(self, "nextPage")
         return "nextPage"
 
 

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

@@ -2,14 +2,62 @@
 
 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
 
 
+_INT_TO_ALIGN: "dict[int, str]" = {
+    0: "LEFT",
+    1: "CENTER",
+    2: "RIGHT",
+    3: "JUSTIFY",
+    4: "DISTRIBUTE",
+    5: "JUSTIFY_MED",
+    7: "JUSTIFY_HI",
+    8: "JUSTIFY_LOW",
+    9: "THAI_JUSTIFY",
+}
+
+
+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)."""
 
@@ -23,10 +71,27 @@ class WD_ALIGN_PARAGRAPH(Enum):
     JUSTIFY_LOW = "justifyLow"
     THAI_JUSTIFY = "thaiJustify"
 
+    @classmethod
+    def from_int(cls, value: int) -> "WD_ALIGN_PARAGRAPH | None":
+        """Coerce a python-docx-style int alignment to the enum.
+
+        python-docx 1.x's ``WD_ALIGN_PARAGRAPH`` is keyed on int (its
+        ``BaseXmlEnum`` mapping: LEFT=0, CENTER=1, RIGHT=2, JUSTIFY=3,
+        DISTRIBUTE=4, JUSTIFY_MED=5, JUSTIFY_HI=7, JUSTIFY_LOW=8,
+        THAI_JUSTIFY=9). Callers passing ``paragraph.alignment = 1``
+        get CENTER. We mirror that without changing our enum's
+        string-valued definition.
+        """
+        name = _INT_TO_ALIGN.get(value)
+        return getattr(cls, name) if name is not None else None
+
     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 +99,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 +148,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 +159,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.1}/docx/section.py

@@ -83,6 +83,66 @@ def _emu_to_pt(emu: int) -> float:
     return emu / 12700.0
 
 
+def _reject_none_dimension(prop: str, value: object) -> None:
+    """Raise ``TypeError`` if ``value`` is None for a dimension setter
+    that python-docx 1.2.0 doesn't accept None for.
+
+    Upstream ``Section.page_width = None`` (and every margin /
+    header_distance / footer_distance / gutter setter) routes through
+    ``Emu(value).twips`` which raises ``TypeError`` on ``None``. Our
+    setters previously early-returned silently, swallowing the
+    intent. Raise to match upstream behavior — callers who actually
+    want a clear must pass ``Inches(0)`` (or similar) explicitly.
+    """
+    if value is None:
+        raise TypeError(
+            f"Section.{prop} = None is not supported. python-docx "
+            f"1.2.0 raises TypeError here too — its Emu(None).twips "
+            f"fails with the same shape. Pass an explicit Length "
+            f"(e.g. Inches(0)) if you want to zero the dimension."
+        )
+
+
+class PendingSectionOnOffClearWarning(UserWarning):
+    """Emitted when ``Section.different_first_page_header_footer = None``.
+
+    python-docx 1.x semantics: ``None`` clears the OOXML
+    ``<w:titlePg/>`` element back to inherited. SuperDoc 1.8's
+    ``sections.set_title_page`` only accepts ``enabled: bool`` — the
+    wire can't represent the clear-intent. The warning surfaces
+    silent-divergence. Tracked in
+    ``docx-studio/SUPERDOC_UPSTREAM_REQUESTS.md``.
+    """
+
+
+def _warn_section_onoff_clear(prop: str) -> None:
+    warnings.warn(
+        f"Section.{prop} = None was IGNORED — SuperDoc 1.8 has no "
+        f"clear-op for this OnOff property. The section keeps its "
+        f"previous value. Tracked in "
+        f"docx-studio/SUPERDOC_UPSTREAM_REQUESTS.md.",
+        PendingSectionOnOffClearWarning,
+        stacklevel=3,
+    )
+
+
+def _require_section_bool(prop: str, value: object) -> bool:
+    """Reject non-bool input on Section OnOff setters.
+
+    python-docx 1.x's ``_OnOff`` typed-attribute setter raises
+    ``ValueError`` for non-bool input. Our previous ``bool(value)``
+    coercion silently turned ``"yes"`` / ``1`` / ``[]`` into True/False
+    without surfacing the type mismatch.
+    """
+    if not isinstance(value, bool):
+        raise TypeError(
+            f"Section.{prop} requires bool or None; got "
+            f"{type(value).__name__} {value!r}. python-docx 1.x's "
+            f"``_OnOff`` setter rejects truthy non-bool here too.",
+        )
+    return value
+
+
 class Section:
     """A document section — page size, margins, headers/footers, break type."""
 
@@ -124,8 +184,7 @@ class Section:
 
     @page_width.setter
     def page_width(self, value: "Length | int | None") -> None:
-        if value is None:
-            return
+        _reject_none_dimension("page_width", value)
         pt = _emu_to_pt(_emu_from(value))
         self._set_page_setup(width=pt)
 
@@ -140,8 +199,7 @@ class Section:
 
     @page_height.setter
     def page_height(self, value: "Length | int | None") -> None:
-        if value is None:
-            return
+        _reject_none_dimension("page_height", value)
         pt = _emu_to_pt(_emu_from(value))
         self._set_page_setup(height=pt)
 
@@ -201,8 +259,7 @@ class Section:
 
     @left_margin.setter
     def left_margin(self, value: "Length | int | None") -> None:
-        if value is None:
-            return
+        _reject_none_dimension("left_margin", value)
         self._set_margins(left=_emu_to_pt(_emu_from(value)))
 
     @property
@@ -211,8 +268,7 @@ class Section:
 
     @right_margin.setter
     def right_margin(self, value: "Length | int | None") -> None:
-        if value is None:
-            return
+        _reject_none_dimension("right_margin", value)
         self._set_margins(right=_emu_to_pt(_emu_from(value)))
 
     @property
@@ -221,8 +277,7 @@ class Section:
 
     @top_margin.setter
     def top_margin(self, value: "Length | int | None") -> None:
-        if value is None:
-            return
+        _reject_none_dimension("top_margin", value)
         self._set_margins(top=_emu_to_pt(_emu_from(value)))
 
     @property
@@ -231,8 +286,7 @@ class Section:
 
     @bottom_margin.setter
     def bottom_margin(self, value: "Length | int | None") -> None:
-        if value is None:
-            return
+        _reject_none_dimension("bottom_margin", value)
         self._set_margins(bottom=_emu_to_pt(_emu_from(value)))
 
     @property
@@ -241,8 +295,7 @@ class Section:
 
     @gutter.setter
     def gutter(self, value: "Length | int | None") -> None:
-        if value is None:
-            return
+        _reject_none_dimension("gutter", value)
         self._set_margins(gutter=_emu_to_pt(_emu_from(value)))
 
     @property
@@ -256,8 +309,7 @@ class Section:
 
     @header_distance.setter
     def header_distance(self, value: "Length | int | None") -> None:
-        if value is None:
-            return
+        _reject_none_dimension("header_distance", value)
         run_sync(
             self._session.doc.sections.set_header_footer_margins(
                 {"target": self._address, "header": _emu_to_pt(_emu_from(value))},
@@ -275,8 +327,7 @@ class Section:
 
     @footer_distance.setter
     def footer_distance(self, value: "Length | int | None") -> None:
-        if value is None:
-            return
+        _reject_none_dimension("footer_distance", value)
         run_sync(
             self._session.doc.sections.set_header_footer_margins(
                 {"target": self._address, "footer": _emu_to_pt(_emu_from(value))},
@@ -335,14 +386,18 @@ class Section:
     @different_first_page_header_footer.setter
     def different_first_page_header_footer(self, value: bool | None) -> None:
         if value is None:
+            _warn_section_onoff_clear("different_first_page_header_footer")
             return
+        enabled = _require_section_bool(
+            "different_first_page_header_footer", value
+        )
         run_sync(
             self._session.doc.sections.set_title_page(
                 # SuperDoc's wire field is ``enabled`` (DocSectionsSet
                 # TitlePageParams). The earlier ``titlePage`` name was
                 # rejected silently because the apps/api applier punts
                 # SuperDoc's strict types via ``AnyDoc``.
-                {"target": self._address, "enabled": bool(value)},
+                {"target": self._address, "enabled": enabled},
             ),
         )
 
@@ -622,8 +677,20 @@ class _HeaderFooter:
             style_str = None
         elif isinstance(style, ParagraphStyle):
             style_str = style.style_id
+        elif isinstance(style, str):
+            style_str = style
         else:
-            style_str = str(style)
+            # python-docx 1.x's ``add_paragraph(style=...)`` accepts
+            # ``str | ParagraphStyle | None`` and raises ``TypeError``
+            # at the style-lookup layer for anything else. The
+            # previous ``str(style)`` silently shipped garbage like
+            # ``<MyStyle object at 0x...>`` as a style id, which
+            # SuperDoc would swallow or reject without a clear signal.
+            raise TypeError(
+                f"_HeaderFooter.add_paragraph style requires str, "
+                f"ParagraphStyle, or None; got "
+                f"{type(style).__name__} {style!r}",
+            )
 
         result: object = run_sync(
             self._section._session.doc.create.paragraph(

{athena_python_docx-0.5.3 → athena_python_docx-0.6.1}/docx/shape.py

@@ -7,6 +7,7 @@ to image binary / metadata round-trips through `doc.images.get`.
 from __future__ import annotations
 
 import base64
+import warnings
 from typing import TYPE_CHECKING
 
 from docx._batching import run_sync
@@ -16,6 +17,29 @@ if TYPE_CHECKING:
     from docx.client import Session
 
 
+class PendingInlineShapeClearWarning(UserWarning):
+    """Emitted when ``InlineShape.width`` or ``.height`` is set to
+    ``None`` (python-docx semantics: "revert to natural sizing").
+
+    SuperDoc 1.8 has no clear-op for image dimensions — its
+    ``images.setSize`` requires explicit ``width`` and ``height``. The
+    SDK can't represent a "revert to natural" intent on the wire, so
+    ``image.width = None`` is a no-op. The warning surfaces the
+    silent-divergence pattern so agent runs see the gap. Tracked in
+    ``docx-studio/SUPERDOC_UPSTREAM_REQUESTS.md``.
+    """
+
+
+def _warn_inline_shape_clear(prop: str) -> None:
+    warnings.warn(
+        f"InlineShape.{prop} = None was IGNORED — SuperDoc 1.8 has no "
+        f"clear-op for image dimensions. The image keeps its previous "
+        f"size. Tracked in docx-studio/SUPERDOC_UPSTREAM_REQUESTS.md.",
+        PendingInlineShapeClearWarning,
+        stacklevel=3,
+    )
+
+
 def _strip_data_uri(src: str) -> tuple[bytes, str | None]:
     """If ``src`` is a ``data:`` URI, return (decoded_bytes, mime).
     Otherwise return ``(b"", None)``."""
@@ -63,6 +87,7 @@ class InlineShape:
     @width.setter
     def width(self, value: "Length | int | None") -> None:
         if value is None:
+            _warn_inline_shape_clear("width")
             return
         pt: float = value.pt if isinstance(value, Length) else float(value) / 12700.0
         h = self.height
@@ -92,6 +117,7 @@ class InlineShape:
     @height.setter
     def height(self, value: "Length | int | None") -> None:
         if value is None:
+            _warn_inline_shape_clear("height")
             return
         pt: float = value.pt if isinstance(value, Length) else float(value) / 12700.0
         w = self.width