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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.6.0
+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.6.0 → 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.6.0"
+__version__ = "0.6.1"
 
 from docx.api import Document
 from docx._buffer import flush_all

{athena_python_docx-0.6.0 → 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.6.0 → 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.6.0 → 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.6.0 → athena_python_docx-0.6.1}/docx/enum/text.py

@@ -13,6 +13,19 @@ 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.
@@ -58,6 +71,20 @@ 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

{athena_python_docx-0.6.0 → 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.6.0 → 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

{athena_python_docx-0.6.0 → athena_python_docx-0.6.1}/docx/table.py

@@ -3,12 +3,41 @@
 from __future__ import annotations
 
 import sys
+import warnings
 from typing import TYPE_CHECKING
 
 from docx._batching import run_sync
 from docx.errors import ValidationError
 from docx.shared import Length, Pt
 
+
+class PendingTableClearWarning(UserWarning):
+    """Emitted when a ``Table`` / ``_Row`` / ``_Column`` / ``_Cell``
+    setter is asked to clear a property (``None`` assignment) that
+    python-docx 1.x supports but SuperDoc 1.8 has no clear-op for.
+
+    Covers: ``Table.alignment / direction / autofit``,
+    ``_Row.height / height_rule``, ``_Column.width``,
+    ``_Cell.width / vertical_alignment``. SuperDoc's
+    ``tables.set_layout`` / ``set_row_height`` / ``set_column_width``
+    / ``set_cell_properties`` require explicit values — the wire
+    can't represent the python-docx "revert to inherited" intent.
+    The warning surfaces the silent-divergence so agent runs see
+    the gap. Tracked in
+    ``docx-studio/SUPERDOC_UPSTREAM_REQUESTS.md``.
+    """
+
+
+def _warn_table_clear(prop: str, *, cls: str = "Table") -> None:
+    warnings.warn(
+        f"{cls}.{prop} = None was IGNORED — SuperDoc 1.8 has no "
+        f"clear-op for this property. The {cls.lower()} keeps its "
+        f"previous value. Tracked in "
+        f"docx-studio/SUPERDOC_UPSTREAM_REQUESTS.md.",
+        PendingTableClearWarning,
+        stacklevel=3,
+    )
+
 if TYPE_CHECKING:
     from docx.client import Session
     from docx.enum.table import (
@@ -420,12 +449,28 @@ class Table:
         from docx.enum.table import WD_TABLE_ALIGNMENT
 
         if value is None:
+            _warn_table_clear("alignment")
             return
-        v: str = (
-            value.to_superdoc()
-            if isinstance(value, WD_TABLE_ALIGNMENT)
-            else str(value).lower()
-        )
+        if isinstance(value, WD_TABLE_ALIGNMENT):
+            v: str = value.to_superdoc()
+        elif isinstance(value, str):
+            # python-docx coerces strings through the enum and raises
+            # ``ValueError`` for non-member values. Mirror that here
+            # instead of shipping bogus ``str(value).lower()`` to
+            # SuperDoc, which would silently swallow unknowns.
+            try:
+                v = WD_TABLE_ALIGNMENT(value).to_superdoc()
+            except (ValueError, KeyError) as exc:
+                raise ValueError(
+                    f"Table.alignment = {value!r}: not a valid "
+                    f"WD_TABLE_ALIGNMENT. Expected one of "
+                    f"{[m.value for m in WD_TABLE_ALIGNMENT]}."
+                ) from exc
+        else:
+            raise TypeError(
+                f"Table.alignment requires WD_TABLE_ALIGNMENT, str, "
+                f"or None; got {type(value).__name__}",
+            )
         # SuperDoc 1.8.1: alignment is a setLayout field, not a
         # setTableOptions field. The earlier setTableOptions call
         # silently dropped the value (Zod validated, AnyDoc punt let
@@ -456,12 +501,24 @@ class Table:
         from docx.enum.table import WD_TABLE_DIRECTION
 
         if value is None:
+            _warn_table_clear("direction")
             return
-        v: str = (
-            value.to_superdoc()
-            if isinstance(value, WD_TABLE_DIRECTION)
-            else str(value).lower()
-        )
+        if isinstance(value, WD_TABLE_DIRECTION):
+            v: str = value.to_superdoc()
+        elif isinstance(value, str):
+            try:
+                v = WD_TABLE_DIRECTION(value).to_superdoc()
+            except (ValueError, KeyError) as exc:
+                raise ValueError(
+                    f"Table.direction = {value!r}: not a valid "
+                    f"WD_TABLE_DIRECTION. Expected one of "
+                    f"{[m.value for m in WD_TABLE_DIRECTION]}."
+                ) from exc
+        else:
+            raise TypeError(
+                f"Table.direction requires WD_TABLE_DIRECTION, str, "
+                f"or None; got {type(value).__name__}",
+            )
         # SuperDoc's setLayout takes ``tableDirection`` (not
         # ``direction``). Same diagnostic as alignment above —
         # setTableOptions silently swallowed the field.
@@ -488,7 +545,15 @@ class Table:
     @autofit.setter
     def autofit(self, value: bool | None) -> None:
         if value is None:
+            _warn_table_clear("autofit")
             return
+        if not isinstance(value, bool):
+            raise TypeError(
+                f"Table.autofit requires bool or None; got "
+                f"{type(value).__name__} {value!r}. python-docx 1.x "
+                f"is a ``_OnOff`` setter and rejects truthy non-bool "
+                f"here too.",
+            )
         run_sync(
             self._session.doc.tables.set_layout(
                 {
@@ -614,6 +679,7 @@ class _Row:
     @height.setter
     def height(self, value: "Length | int | None") -> None:
         if value is None:
+            _warn_table_clear("height", cls="_Row")
             return
         # Mirror python-docx: row height is stored as unsigned twips
         # (``ST_TwipsMeasure``), so negative inputs raise ``ValueError``
@@ -663,12 +729,27 @@ class _Row:
         from docx.enum.table import WD_ROW_HEIGHT_RULE
 
         if value is None:
+            _warn_table_clear("height_rule", cls="_Row")
             return
-        rule: str = (
-            value.to_superdoc()
-            if isinstance(value, WD_ROW_HEIGHT_RULE)
-            else str(value)
-        )
+        if isinstance(value, WD_ROW_HEIGHT_RULE):
+            rule: str = value.to_superdoc()
+        elif isinstance(value, str):
+            # python-docx coerces strings through the enum and raises
+            # on misses. Was: ``str(value)`` shipped any value to the
+            # wire (SuperDoc swallowed unknowns silently).
+            try:
+                rule = WD_ROW_HEIGHT_RULE(value).to_superdoc()
+            except (ValueError, KeyError) as exc:
+                raise ValueError(
+                    f"_Row.height_rule = {value!r}: not a valid "
+                    f"WD_ROW_HEIGHT_RULE. Expected one of "
+                    f"{[m.value for m in WD_ROW_HEIGHT_RULE]}."
+                ) from exc
+        else:
+            raise TypeError(
+                f"_Row.height_rule requires WD_ROW_HEIGHT_RULE, str, "
+                f"or None; got {type(value).__name__}",
+            )
         h = self.height
         h_pt: float = float(h.pt) if isinstance(h, Length) else 12.0
         run_sync(
@@ -719,6 +800,7 @@ class _Column:
     @width.setter
     def width(self, value: "Length | int | None") -> None:
         if value is None:
+            _warn_table_clear("width", cls="_Column")
             return
         # Mirror python-docx: width must be non-negative. Upstream
         # uses Emu which raises ``ValueError`` for negatives. Previously
@@ -1038,16 +1120,31 @@ class _Cell:
         from docx.styles.style import ParagraphStyle
         from docx.text.paragraph import Paragraph
 
-        # Normalize style — ParagraphStyle → style_id, str → str, None → None.
-        # Any other type lands as ``str(style)`` which Word will then
-        # treat as an unknown style id (Word falls back to Normal).
+        # python-docx 1.x: ``text`` is ``str`` (lxml TypeErrors on
+        # non-str). Was: any value flowed straight to the wire
+        # ``text`` field — SuperDoc's permissive parser swallowed or
+        # rejected silently.
+        if not isinstance(text, str):
+            raise TypeError(
+                f"_Cell.add_paragraph text requires str; got "
+                f"{type(text).__name__} {text!r}",
+            )
+        # ``style`` is ``str | ParagraphStyle | None``. Was: catch-all
+        # ``str(style)`` shipped garbage like ``"<MyStyle object at
+        # 0x...>"`` as a style id — Word silently fell back to Normal.
         style_id: str | None
         if style is None:
             style_id = None
         elif isinstance(style, ParagraphStyle):
             style_id = style.style_id
+        elif isinstance(style, str):
+            style_id = style
         else:
-            style_id = str(style)
+            raise TypeError(
+                f"_Cell.add_paragraph style requires str, "
+                f"ParagraphStyle, or None; got "
+                f"{type(style).__name__} {style!r}",
+            )
 
         ids = self._inner_paragraph_ids()
         if ids:
@@ -1266,6 +1363,7 @@ class _Cell:
         from docx.enum.table import WD_ALIGN_VERTICAL
 
         if value is None:
+            _warn_table_clear("vertical_alignment", cls="_Cell")
             return
         if isinstance(value, WD_ALIGN_VERTICAL):
             v: str = value.to_superdoc()
@@ -1301,6 +1399,7 @@ class _Cell:
     @width.setter
     def width(self, value: "Length | int | None") -> None:
         if value is None:
+            _warn_table_clear("width", cls="_Cell")
             return
         # Mirror python-docx + ``_Column.width``: cell width is unsigned
         # twips; negative widths previously round-tripped to the wire