athena-python-docx 0.18.3__tar.gz → 0.20.0__tar.gz

{athena_python_docx-0.18.3 → athena_python_docx-0.20.0}/CLAUDE.md

@@ -601,6 +601,80 @@ natively, the SDK should swap to the upstream signature in place;
 this section is the canonical reference for what each Athena
 extension wires up.
 
+### Behavioral-parity deviations (2026 deep-dive, v0.19.0)
+
+A deep behavioral audit against python-docx 1.2.0 (the structural
+parity ratchet only sees shape, not runtime behavior) fixed ~40
+divergences so they now match upstream exactly — `Pt`/`RGBColor`
+coercion, `Font.size` bare-int-is-EMU, `Font.underline`
+SINGLE→`True`/NONE→`False`, `line_spacing` integer multipliers,
+`line_spacing_rule` rule-only members, `Hyperlink.url`/`.address`,
+`Table.autofit`/`_Row.cells`/`_Column.cells`, `Section`
+orientation/start-type defaults + `Sections` slicing,
+`Styles.get_by_id`/`get_style_id`/`default(LIST)`/`add_style`,
+`Document.add_heading` (`ValueError`), `add_paragraph` strict heading
+routing, `add_picture` native size + aspect ratio, `WD_BUILTIN_STYLE`
+(now the 132-member int enum aliased to `WD_STYLE`),
+`docx.enum.shape.WD_INLINE_SHAPE`, `InlineShape.type`/zero-dimensions,
+and `CoreProperties` validation. These are not deviations — they close
+gaps. The items below are the **residual intentional deviations** that
+remain because matching upstream would break the asset-backed/HTTP
+architecture or a SuperDoc constraint:
+
+- **`WD_*` enum `.value` is the SuperDoc wire string, not the MS Word
+  integer constant.** `WD_ALIGN_PARAGRAPH.CENTER.value == "center"`
+  (upstream: `1`); `int(member)` / `member == 1` / `WD_*(1)` therefore
+  differ. The string value is load-bearing — every command serializes
+  `enum.value` directly onto the wire (`underline=value.value`,
+  `WD_COLOR_INDEX(v).value`, …), so int-valuing the enums would require
+  re-plumbing the entire command layer. Members are accessed by name
+  (`WD_ALIGN_PARAGRAPH.CENTER`), so the drift is academic for normal
+  use. (`WD_STYLE`/`WD_BUILTIN_STYLE` and `WD_INLINE_SHAPE_TYPE` are NOT
+  wire-load-bearing and DO carry the upstream int values.)
+
+- **`RGBColor.from_string` additionally accepts a leading `#`.** Upstream
+  rejects `"#FF0000"`; agents routinely pass it, so a single `#` is
+  stripped before the (otherwise byte-identical) upstream slice parse.
+  A strict superset — every value upstream accepts parses identically.
+
+- **`_Cell.vertical_alignment` setter accepts the four SuperDoc wire
+  tokens** (`"top"`/`"center"`/`"bottom"`/`"both"`) in addition to
+  `WD_ALIGN_VERTICAL` members. Upstream rejects all plain strings; this
+  is an ergonomic superset (typos like `"middle"` still raise
+  `ValueError`).
+
+- **`Table.cell(row, col)` bounds-checks each axis independently** and
+  raises `IndexError` for an out-of-range row or column. Upstream
+  indexes a single flat row-major `_cells` list, so a column overflow
+  spills into the next row and `cell(-1, -1)` resolves against the flat
+  list (NOT the bottom-right cell). Athena's per-axis contract is the
+  more intuitive, stricter behavior for an HTTP-backed proxy that can't
+  cheaply enumerate every cell. `(0,0)` and in-range negative indices
+  behave identically to upstream.
+
+- **`BaseStyle.style_id` returns the display name for built-ins** (so
+  `style_id == name`). The SDK is HTTP-only and can't read `styles.xml`
+  to recover the OOXML styleId (`"Heading 1"` → `"Heading1"`); the wire
+  format also uses the display name as the style id. Consequently
+  `get_by_id("Heading1", …)` / `"Heading1" in styles` won't resolve the
+  OOXML-id form (use the display name).
+
+- **`Document.add_table(rows, cols)` requires `rows >= 1` and
+  `cols >= 1`.** Upstream allows a 0-row/0-col grid you later populate,
+  but SuperDoc's ProseMirror table node can't represent one; the SDK
+  raises eagerly rather than failing opaquely on the wire.
+
+- **`Comment.comment_id` returns `str`, not `int`.** SuperDoc uses
+  non-numeric entity ids (`"c-42"`), so the upstream `int` contract
+  can't be honored. Tracked in `SUPERDOC_UPSTREAM_REQUESTS.md`.
+
+- **`Section` dimension setters and `ParagraphFormat.line_spacing_rule
+  = None` warn-and-preserve on a clear** rather than raising (upstream
+  accepts `None` to clear, but SuperDoc's merging mutation ops have no
+  single-attribute clear). They emit a `Pending…ClearWarning` and leave
+  the value intact instead of destructively clearing the whole block.
+  Tracked in `SUPERDOC_UPSTREAM_REQUESTS.md`.
+
 ### If you need a deviation
 
 If there is a genuine technical reason why a deviation from python-docx is necessary:

{athena_python_docx-0.18.3 → athena_python_docx-0.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.18.3
+Version: 0.20.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.18.3 → athena_python_docx-0.20.0}/docx/__init__.py

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

{athena_python_docx-0.18.3 → athena_python_docx-0.20.0}/docx/_buffer.py

@@ -41,7 +41,7 @@ from docx._execution import (
 )
 from docx._timeouts import timeout_for_commands
 from docx.commands import Command, is_response_bearing, must_flush_immediately
-from docx.errors import DocxError, FlushAllError
+from docx.errors import DocxError, DocxUnsupportedCommandError, FlushAllError
 
 
 def _apply_proxy_id_rewrites(
@@ -467,8 +467,17 @@ class CommandBuffer:
     def flush(self) -> list[Any]:
         """Flush pending commands as one HTTP batch.
 
-        Returns the list of per-command result dicts. Empty list if nothing
-        was pending. Cancels any active idle timer.
+        Returns the per-command result list, positionally aligned with the
+        flushed commands (skipped commands occupy their slot as ``None``).
+        Empty list if nothing was pending. Cancels any active idle timer.
+
+        This is the FIRE-AND-FORGET path: callers here don't await an
+        individual command's result, so an unsupported command that the
+        server skipped is simply warned (inside ``execute_batch``) and its
+        slot left ``None`` — the supported commands still applied. (A caller
+        that DOES need a single command's result goes through
+        :meth:`_eager_flush_with`, which raises on a skipped trailing command
+        rather than returning the wrong slot.)
 
         After the batch returns, walks per-cmd results for
         ``real_node_id`` / ``real_entity_id`` echoes and updates any
@@ -490,7 +499,7 @@ class CommandBuffer:
         if not pending:
             return []
         try:
-            results = self._client.execute_batch(
+            results, _skipped_by_index = self._client.execute_batch(
                 self._asset_id,
                 pending,
                 change_mode=change_mode,
@@ -554,8 +563,11 @@ class CommandBuffer:
             proxy_id_refs = self._proxy_id_refs
             self._proxy_id_refs = {}
         all_cmds: list[Command] = [*pending, cmd]
+        trailing_index = len(all_cmds) - 1
         try:
-            results: list[Any] = self._client.execute_batch(
+            results: list[Any]
+            skipped_by_index: dict[int, dict[str, Any]]
+            results, skipped_by_index = self._client.execute_batch(
                 self._asset_id,
                 all_cmds,
                 change_mode=change_mode,
@@ -576,10 +588,32 @@ class CommandBuffer:
             _ptc_emit_end_batch(all_cmds, is_error=True)
             raise
         _ptc_emit_end_batch(all_cmds, is_error=False)
+        # Proxy-id rewrites still run for the buffered prefix that DID apply —
+        # the trailing skip (if any) doesn't strand the supported Creates that
+        # flushed alongside it.
         _apply_proxy_id_rewrites(results, proxy_id_refs)
+        # This is the AWAITED-result path: the caller is about to read the
+        # trailing command's result. If the server skipped that command
+        # (capability gap), there is no result to return — returning some
+        # earlier applied mutation's slot would be silent WRONG DATA. Fail
+        # loud instead. (Fire-and-forget mutations never reach here; they go
+        # through :meth:`flush`, which keeps the skip+warn behavior.)
+        if trailing_index in skipped_by_index:
+            skip = skipped_by_index[trailing_index]
+            reason = skip.get("reason") if isinstance(skip, dict) else None
+            raise DocxUnsupportedCommandError(
+                f"docx-studio skipped command {type(cmd).__name__!r} but the "
+                f"SDK was awaiting its result" + (f": {reason}" if reason else ".")
+            )
         if not results:
             return {}
-        return results[-1]
+        # Trailing command applied: its slot holds the result dict (or ``{}``
+        # for a non-dict result). A ``None`` here would only arise if the
+        # server omitted the trailing command's index from ``applied[]``
+        # without listing it in ``skipped[]`` — fall back to ``{}`` to match
+        # the legacy "no result" behavior rather than handing back ``None``.
+        trailing = results[-1]
+        return trailing if trailing is not None else {}
 
     def _reset_timer_locked(self) -> None:
         # Caller must hold self._lock.

{athena_python_docx-0.18.3 → athena_python_docx-0.20.0}/docx/_http_doc.py

@@ -31,6 +31,7 @@ from __future__ import annotations
 
 import json
 import os
+import warnings
 from typing import Any
 
 import requests
@@ -172,6 +173,7 @@ from docx.errors import (
     BlockNotFoundError,
     DocxError,
     DocxStudioTemporarilyUnavailable,
+    DocxUnsupportedCommandWarning,
     NotFoundError,
     SessionError,
 )
@@ -662,6 +664,29 @@ def _http_post_json(
     )
 
 
+def _warn_skipped_commands(skipped: list[Any]) -> None:
+    """Emit one :class:`DocxUnsupportedCommandWarning` per server-reported
+    skipped command.
+
+    Each entry is the wire-shape ``{index, type, reason}`` dict the applier
+    records when a command raises ``UnsupportedDocxEditorCommandError``. The
+    batch still succeeded for every supported command; warning (rather than
+    raising) is the graceful-degradation contract so a script that ends with
+    an unsupported op doesn't abort into an empty document.
+
+    Tolerant of malformed entries: anything that isn't a dict is summarized
+    generically rather than crashing the (otherwise successful) batch.
+    """
+    for entry in skipped:
+        if isinstance(entry, dict):
+            cmd_type = entry.get("type", "<unknown>")
+            reason = entry.get("reason") or "not supported by the docx-editor engine yet"
+            message = f"Skipped unsupported command {cmd_type!r}: {reason}"
+        else:
+            message = f"Skipped unsupported command: {entry!r}"
+        warnings.warn(message, DocxUnsupportedCommandWarning, stacklevel=2)
+
+
 # ---------------------------------------------------------------------------
 # HttpClient — the bare HTTP transport. Stateless wrt batching.
 # ---------------------------------------------------------------------------
@@ -706,8 +731,22 @@ class HttpClient:
         *,
         change_mode: str | None = None,
         user: dict[str, str] | None = None,
-    ) -> list[Any]:
-        """POST a batch of typed commands, return per-command result dicts.
+    ) -> tuple[list[Any], dict[int, dict[str, Any]]]:
+        """POST a batch of typed commands.
+
+        Returns ``(results, skipped_by_index)``:
+
+        - ``results`` is **positionally aligned** with ``commands``: one slot
+          per input command, in order. An applied command's slot holds its
+          ``result`` dict (or ``{}`` for a non-dict result); a SKIPPED
+          command's slot holds ``None``. Positional alignment is what lets a
+          caller awaiting a single command's result (``_eager_flush_with``)
+          map ``results[-1]`` back to *its* command and detect that the
+          command was skipped (``None``) rather than silently returning some
+          earlier applied mutation's result.
+        - ``skipped_by_index`` maps the input index of each skipped command to
+          its ``{index, type, reason}`` entry, so callers awaiting a result a
+          skipped command can't provide can raise a precise error.
 
         Envelope fields:
             change_mode: ``"direct"`` | ``"tracked"`` | ``None``. When
@@ -720,14 +759,22 @@ class HttpClient:
                 opens the per-asset session for the first time; ignored
                 on subsequent batches against the same pooled session.
 
-        On success, length matches len(commands). On 207 partial-failure,
-        the server returns 207 with `applied` (the successful prefix) plus
-        an `error` for the failing command — :func:`_http_post_json`
-        translates that to a :class:`DocxError`. We don't pad partial
-        results because the doc state is undefined.
+        On success, ``len(applied) + len(skipped) == len(commands)``. The
+        server's ``skipped[]`` array carries commands the docx-editor engine
+        doesn't implement yet; each is surfaced as a
+        :class:`DocxUnsupportedCommandWarning` (graceful degradation — one
+        unsupported FIRE-AND-FORGET mutation no longer aborts the whole batch
+        into an empty document). Fire-and-forget mutations don't read their
+        result, so a warning + skip is correct for them. A skipped command
+        that a caller IS awaiting (a query / response-bearing op routed
+        through ``_eager_flush_with``) is detected positionally and raised by
+        that caller. On 207 partial-failure, the server returns 207 with
+        `applied` (the successful prefix) plus an `error` for the failing
+        command — :func:`_http_post_json` translates that to a
+        :class:`DocxError`.
         """
         if not commands:
-            return []
+            return [], {}
 
         url: str = f"{self._base_url}/docs/{asset_id}/commands"
         body: dict[str, Any] = {
@@ -747,6 +794,12 @@ class HttpClient:
             timeout=timeout_for_commands(commands=commands),
         )
         applied = resp.get("applied")
+        # Commands the engine doesn't implement yet are reported in
+        # ``skipped[]`` (non-fatal). Warn per skip and count them toward the
+        # batch total — they're a success, not a failure.
+        skipped_raw = resp.get("skipped")
+        skipped = skipped_raw if isinstance(skipped_raw, list) else []
+        _warn_skipped_commands(skipped)
         # An empty applied list paired with an `error` field is the
         # 'all-commands-failed' shape — surface it rather than returning
         # an empty result list to a caller that's about to index [-1].
@@ -758,19 +811,37 @@ class HttpClient:
                 f"docx-studio response missing applied[]: {resp!r}",
             )
 
-        if len(applied) != len(commands):
+        # Applied + skipped together must account for every command. A short
+        # ``applied`` is only legitimate when the remainder were skipped.
+        if len(applied) + len(skipped) != len(commands):
             raise DocxError(
-                f"docx-studio applied {len(applied)} of {len(commands)} commands",
+                f"docx-studio applied {len(applied)} (+{len(skipped)} skipped) "
+                f"of {len(commands)} commands",
             )
 
-        results: list[Any] = []
+        # Build a positionally-aligned result list (one slot per input
+        # command). Applied slots carry the result dict; skipped slots stay
+        # ``None``. Each entry's ``index`` field places it at the right slot —
+        # we don't assume ``applied[]`` is a contiguous prefix once skips can
+        # appear anywhere in the batch.
+        results: list[Any] = [None] * len(commands)
         for entry in applied:
-            if isinstance(entry, dict):
-                result = entry.get("result")
-                results.append(result if isinstance(result, dict) else {})
-            else:
-                results.append({})
-        return results
+            if not isinstance(entry, dict):
+                continue
+            idx = entry.get("index")
+            if not isinstance(idx, int) or not (0 <= idx < len(results)):
+                continue
+            result = entry.get("result")
+            results[idx] = result if isinstance(result, dict) else {}
+
+        skipped_by_index: dict[int, dict[str, Any]] = {}
+        for entry in skipped:
+            if not isinstance(entry, dict):
+                continue
+            idx = entry.get("index")
+            if isinstance(idx, int) and 0 <= idx < len(commands):
+                skipped_by_index[idx] = entry
+        return results, skipped_by_index
 
 
 # ---------------------------------------------------------------------------

{athena_python_docx-0.18.3 → athena_python_docx-0.20.0}/docx/_image_utils.py

@@ -211,4 +211,163 @@ def _decode_image_data_uri(uri: str) -> bytes:
         raise ValueError(f"add_picture could not decode data: URI: {exc}") from exc
 
 
-__all__ = ["load_image_bytes", "sniff_content_type"]
+# ---------------------------------------------------------------------------
+# Native dimension / DPI sniffing — parity with python-docx's add_picture
+# native-size + aspect-ratio behavior (no Pillow dependency).
+# ---------------------------------------------------------------------------
+
+_EMU_PER_INCH: int = 914400
+
+
+def _png_dimensions(b: bytes) -> "tuple[int, int, float, float] | None":
+    # IHDR (width/height) sits right after the 8-byte signature in the
+    # first chunk: [4-byte len][b"IHDR"][4-byte width][4-byte height]...
+    if len(b) < 24 or b[12:16] != b"IHDR":
+        return None
+    px_w = int.from_bytes(b[16:20], "big")
+    px_h = int.from_bytes(b[20:24], "big")
+    if px_w <= 0 or px_h <= 0:
+        return None
+    horz_dpi = vert_dpi = 72.0  # python-docx's PNG default
+    # Optional pHYs chunk carries pixels-per-unit; unit 1 == metre.
+    idx = b.find(b"pHYs")
+    if idx != -1 and idx + 13 <= len(b):
+        ppu_x = int.from_bytes(b[idx + 4 : idx + 8], "big")
+        ppu_y = int.from_bytes(b[idx + 8 : idx + 12], "big")
+        unit = b[idx + 12]
+        if unit == 1 and ppu_x > 0 and ppu_y > 0:
+            # python-docx rounds DPI to an int (``int(round(ppu*0.0254))``),
+            # so match that to produce identical native EMU dimensions.
+            horz_dpi = float(round(ppu_x * 0.0254))
+            vert_dpi = float(round(ppu_y * 0.0254))
+    return px_w, px_h, horz_dpi, vert_dpi
+
+
+def _gif_dimensions(b: bytes) -> "tuple[int, int, float, float] | None":
+    if len(b) < 10:
+        return None
+    px_w = int.from_bytes(b[6:8], "little")
+    px_h = int.from_bytes(b[8:10], "little")
+    if px_w <= 0 or px_h <= 0:
+        return None
+    # GIF carries no resolution; python-docx defaults to 72 DPI.
+    return px_w, px_h, 72.0, 72.0
+
+
+def _bmp_dimensions(b: bytes) -> "tuple[int, int, float, float] | None":
+    if len(b) < 26:
+        return None
+    px_w = int.from_bytes(b[18:22], "little", signed=True)
+    px_h = abs(int.from_bytes(b[22:26], "little", signed=True))
+    if px_w <= 0 or px_h <= 0:
+        return None
+    horz_dpi = vert_dpi = 96.0  # python-docx's BMP default
+    if len(b) >= 46:
+        ppm_x = int.from_bytes(b[38:42], "little", signed=True)
+        ppm_y = int.from_bytes(b[42:46], "little", signed=True)
+        if ppm_x > 0 and ppm_y > 0:
+            horz_dpi = float(round(ppm_x * 0.0254))
+            vert_dpi = float(round(ppm_y * 0.0254))
+    return px_w, px_h, horz_dpi, vert_dpi
+
+
+def _jpeg_dimensions(b: bytes) -> "tuple[int, int, float, float] | None":
+    # Default density per python-docx's JFIF handling.
+    horz_dpi = vert_dpi = 72.0
+    px_w = px_h = 0
+    n = len(b)
+    pos = 2  # skip SOI (FF D8)
+    while pos + 4 <= n:
+        if b[pos] != 0xFF:
+            pos += 1
+            continue
+        marker = b[pos + 1]
+        if marker in (0xD8, 0xD9) or 0xD0 <= marker <= 0xD7:
+            pos += 2
+            continue
+        seg_len = int.from_bytes(b[pos + 2 : pos + 4], "big")
+        if seg_len < 2:
+            break
+        seg = b[pos + 4 : pos + 2 + seg_len]
+        if marker == 0xE0 and seg[:5] == b"JFIF\x00" and len(seg) >= 12:
+            units = seg[7]
+            dx = int.from_bytes(seg[8:10], "big")
+            dy = int.from_bytes(seg[10:12], "big")
+            if units == 1 and dx and dy:  # dots per inch
+                horz_dpi, vert_dpi = float(dx), float(dy)
+            elif units == 2 and dx and dy:  # dots per cm
+                horz_dpi, vert_dpi = dx * 2.54, dy * 2.54
+        # SOFn frame markers carry the actual dimensions.
+        elif marker in (
+            0xC0, 0xC1, 0xC2, 0xC3, 0xC5, 0xC6, 0xC7,
+            0xC9, 0xCA, 0xCB, 0xCD, 0xCE, 0xCF,
+        ) and len(seg) >= 5:
+            px_h = int.from_bytes(seg[1:3], "big")
+            px_w = int.from_bytes(seg[3:5], "big")
+            break
+        pos += 2 + seg_len
+    if px_w <= 0 or px_h <= 0:
+        return None
+    return px_w, px_h, horz_dpi, vert_dpi
+
+
+def sniff_image_dimensions(image_bytes: bytes) -> "tuple[int, int, float, float] | None":
+    """Return ``(px_width, px_height, horz_dpi, vert_dpi)`` for raster
+    image bytes, or ``None`` if the format/dimensions can't be parsed.
+
+    Mirrors the header parsers in python-docx's ``docx.image`` (PNG,
+    JPEG, GIF, BMP) without requiring Pillow. DPI defaults match
+    python-docx (72 for PNG/JPEG/GIF, 96 for BMP) when the image carries
+    no embedded resolution.
+    """
+    if image_bytes.startswith(_PNG_MAGIC):
+        return _png_dimensions(image_bytes)
+    if image_bytes.startswith(_JPEG_MAGIC):
+        return _jpeg_dimensions(image_bytes)
+    if image_bytes.startswith(_GIF87_MAGIC) or image_bytes.startswith(_GIF89_MAGIC):
+        return _gif_dimensions(image_bytes)
+    if image_bytes.startswith(_BMP_MAGIC):
+        return _bmp_dimensions(image_bytes)
+    return None
+
+
+def scaled_dimensions_emu(
+    image_bytes: bytes,
+    width_emu: "int | None",
+    height_emu: "int | None",
+) -> "tuple[int, int] | None":
+    """Resolve the render size (in EMU) for ``add_picture``, mirroring
+    python-docx's ``Image.scaled_dimensions``.
+
+    - both width and height given -> use them verbatim.
+    - neither given -> the image's native size (from px + DPI).
+    - exactly one given -> compute the other to preserve aspect ratio.
+
+    Returns ``None`` only when a dimension must be derived but native
+    dimensions can't be sniffed — the caller then falls back to its
+    legacy fixed default.
+    """
+    if width_emu is not None and height_emu is not None:
+        return width_emu, height_emu
+    dims = sniff_image_dimensions(image_bytes)
+    if dims is None:
+        return None
+    px_w, px_h, dpi_x, dpi_y = dims
+    nat_w = int(round(px_w / dpi_x * _EMU_PER_INCH))
+    nat_h = int(round(px_h / dpi_y * _EMU_PER_INCH))
+    if width_emu is None and height_emu is None:
+        return nat_w, nat_h
+    if height_emu is None:  # width supplied, scale height
+        scale = (float(width_emu) / float(nat_w)) if nat_w else 1.0
+        return width_emu, int(round(nat_h * scale))
+    # height supplied, scale width
+    scale = (float(height_emu) / float(nat_h)) if nat_h else 1.0
+    return int(round(nat_w * scale)), height_emu
+
+
+__all__ = [
+    "load_image_bytes",
+    "sniff_content_type",
+    "sniff_image_dimensions",
+    "scaled_dimensions_emu",
+]

{athena_python_docx-0.18.3 → athena_python_docx-0.20.0}/docx/comments.py

@@ -217,8 +217,12 @@ class Comment:
         self._info["creatorName"] = value
 
     @property
-    def initials(self) -> str:
-        return str(self._info.get("initials") or "")
+    def initials(self) -> str | None:
+        # python-docx's CT_Comment.initials is OptionalAttribute(str), so
+        # an absent/None initials reads back as None (not ""), letting
+        # callers distinguish "no initials set" from "empty initials".
+        val = self._info.get("initials")
+        return None if val is None else str(val)
 
     @initials.setter
     def initials(self, value: str) -> None:

{athena_python_docx-0.18.3 → athena_python_docx-0.20.0}/docx/document.py

@@ -1525,14 +1525,18 @@ class Document:
         #
         # For heading styles we still dispatch to add_heading, which uses
         # `doc.create.heading` (also canonical, takes `level`).
-        if style_str and style_str.lower().startswith("heading"):
-            try:
-                level: int = int(style_str.rsplit(" ", 1)[-1])
-            except ValueError:
-                level = 1
-            return self.add_heading(text=text, level=level)
-        if style_str and style_str.lower() == "title":
-            return self.add_heading(text=text, level=0)
+        if style_str is not None:
+            low: str = style_str.lower()
+            # Only the canonical built-in heading ids (``Heading 1`` ..
+            # ``Heading 9``) route to add_heading. A custom style whose
+            # name merely starts with "heading" (e.g. "Heading Box",
+            # "Heading Note") must be applied verbatim — the previous
+            # loose ``startswith("heading")`` + parse-or-default-to-1
+            # silently relabeled every such style as Heading 1.
+            if low in {f"heading {n}" for n in range(1, 10)}:
+                return self.add_heading(text=text, level=int(low.rsplit(" ", 1)[-1]))
+            if low == "title":
+                return self.add_heading(text=text, level=0)
 
         # python-docx parity: tabs and line breaks in `text` must
         # round-trip as Word ``<w:tab/>`` / ``<w:br/>`` elements, not
@@ -1725,9 +1729,9 @@ class Document:
         self._ensure_open()
         self._reset_list_chain()
         if not 0 <= level <= 9:
-            raise ValidationError(
-                f"level must be in 0..9; got {level}",
-            )
+            # python-docx raises a builtin ``ValueError`` here (not an
+            # SDK ValidationError) with this exact message.
+            raise ValueError("level must be in range 0-9, got %d" % level)
 
         # python-docx parity: tabs/newlines in `text` must round-trip
         # as Word inlines, not literal characters. SuperDoc's
@@ -1797,9 +1801,18 @@ class Document:
 
         self._ensure_open()
         self._reset_list_chain()
+        # Intentional deviation from python-docx (documented in CLAUDE.md):
+        # upstream allows ``add_table(0, cols)`` to create an empty grid
+        # you then populate with ``add_row()``, but SuperDoc's ProseMirror
+        # table node requires at least one row and one column — a 0-row
+        # table can't be represented — so we reject eagerly with a clear
+        # error rather than failing opaquely on the wire.
         if rows < 1 or cols < 1:
             raise ValidationError(
-                f"rows and cols must be >= 1; got rows={rows} cols={cols}",
+                f"rows and cols must be >= 1; got rows={rows} cols={cols}. "
+                f"SuperDoc cannot represent a 0-row/0-col table — create "
+                f"with the final dimensions (or 1x1, then add_row/"
+                f"add_column).",
             )
 
         # The real param is `columns` (not `cols`). `at` is required to
@@ -1901,7 +1914,11 @@ class Document:
         server-side), or a ``data:`` URI. The URL and ``data:`` forms are
         Athena extensions beyond python-docx, which is path/stream-only.
         """
-        from docx._image_utils import load_image_bytes, sniff_content_type
+        from docx._image_utils import (
+            load_image_bytes,
+            scaled_dimensions_emu,
+            sniff_content_type,
+        )
         from docx.shape import InlineShape
         from docx.text.run import _build_inline_shape_info
 
@@ -1931,8 +1948,32 @@ class Document:
         b64: str = base64.b64encode(image_bytes).decode("ascii")
         data_uri: str = f"data:{content_type};base64,{b64}"
 
-        w_px: float = _emu_to_px(width) if width is not None else 576.0
-        h_px: float = _emu_to_px(height) if height is not None else 432.0
+        # python-docx parity: with no width/height the picture appears at
+        # its native size (px / DPI); with exactly one dimension the other
+        # is computed to preserve the aspect ratio. Only when the native
+        # dimensions can't be sniffed (unknown/SVG/corrupt) do we keep the
+        # legacy fixed 6" x 4.5" fallback.
+        dims_emu = scaled_dimensions_emu(
+            image_bytes,
+            int(width) if width is not None else None,
+            int(height) if height is not None else None,
+        )
+        if dims_emu is not None:
+            w_emu, h_emu = dims_emu
+        else:
+            # Undecodable native size — legacy 6" x 4.5" fixed fallback
+            # (576px / 432px @ 96 DPI) or the explicit dimension.
+            w_emu = int(width) if width is not None else 5486400
+            h_emu = int(height) if height is not None else 4114800
+        # The ``create.image`` wire wants pixels (96 DPI); the returned
+        # InlineShape's ``size`` is read back as POINTS (the getter wraps
+        # it in ``Pt(...)``, matching the resize setter's ``unit: "pt"``),
+        # so store the two units separately — otherwise ``shape.width``
+        # reads back ~1.33x inflated (px interpreted as pt).
+        w_px: float = _emu_to_px(w_emu)
+        h_px: float = _emu_to_px(h_emu)
+        w_pt: float = w_emu / 12700.0
+        h_pt: float = h_emu / 12700.0
 
         # Pre-mint the client-side UUID so the create can buffer and
         # the InlineShape proxy hands the caller a stable id without
@@ -1948,7 +1989,7 @@ class Document:
         # InlineShape stores its id under ``_info["nodeId"]`` rather than
         # a top-level ``_node_id`` attribute, so route the flush-time
         # rewrite through a small setattr-adapter wrapper.
-        info = _build_inline_shape_info(result, width=w_px, height=h_px)
+        info = _build_inline_shape_info(result, width=w_pt, height=h_pt)
         info["nodeId"] = client_node_id
         shape = InlineShape(session=self._session, info=info)
         buffer = self._buffer()
@@ -1981,6 +2022,22 @@ class Document:
         if start_type is not None:
             if isinstance(start_type, WD_SECTION_START):
                 break_type = start_type.to_superdoc()
+            elif isinstance(start_type, int):
+                # python-docx's WD_SECTION_START members ARE ints
+                # (NEW_PAGE == 2), so ``add_section(2)`` is valid upstream.
+                # Athena's members carry SuperDoc string values, so map the
+                # upstream integer constants to the matching member.
+                _int_to_member = {
+                    0: WD_SECTION_START.CONTINUOUS,
+                    1: WD_SECTION_START.NEW_COLUMN,
+                    2: WD_SECTION_START.NEW_PAGE,
+                    3: WD_SECTION_START.EVEN_PAGE,
+                    4: WD_SECTION_START.ODD_PAGE,
+                }
+                member = _int_to_member.get(int(start_type))
+                if member is None:
+                    raise ValueError(f"{start_type!r} is not a valid WD_SECTION_START")
+                break_type = member.to_superdoc()
             elif isinstance(start_type, str):
                 # python-docx coerces strings through the enum, raising
                 # ``ValueError`` for non-member values. Mirror that here