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

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

@@ -222,22 +222,6 @@ Issue numbers reference `python-openxml/python-docx`.
   the same `Hyperlink` class the read path already exposes. Also
   available as `Run.add_hyperlink` for convenience.
 
-- **`Paragraph.add_citation(*, source, text=None, anchor=None,
-  display_value=None, label=None) -> str`** + **`Document.remove_citation
-  (*, citation_id, soft=True)`** — source-citation markers (Athena
-  studio-linking; no python-docx analog, `issue=None`). Attaches a
-  Word-style superscript citation marker pointing at an Athena asset
-  (`source`, an `AssetReference`), optionally narrowed by `anchor` (a
-  sheet range, PDF page, …). Renders in Olympus as a clickable superscript
-  with a hover preview + Citations-panel entry — the same unified
-  citation system as sheets / PPTX / native docs; clicking opens the
-  source in a new tab. Routes through `CreateCitation` / `RemoveCitation`;
-  the studio server derives the openable `citation_string` from
-  `source_ref` + `source_anchor` via `@athenaintel/references` (single
-  canonical serializer). `docx/_references.py` mirrors the pptx
-  `AssetReference` + anchor re-exports off the shared `athena-references`
-  package.
-
 - **`Run.add_field(kind, *, args=None, cached_result=None) -> Field`**
   + **`Document.fields: Fields`** — generic Word field insertion.
   Supports `"PAGE"`, `"NUMPAGES"`, `"DATE"`, `"TIME"`, `"AUTHOR"`,
@@ -617,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.19.0 → athena_python_docx-0.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.19.0
+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>
@@ -11,7 +11,6 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.11
-Requires-Dist: athena-references>=0.1.0
 Requires-Dist: requests>=2.28
 Requires-Dist: urllib3>=1.26.6
 Provides-Extra: dev

{athena_python_docx-0.19.0 → 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.19.0"
+__version__ = "0.20.0"
 
 from docx.api import Document
 from docx._buffer import flush_all

{athena_python_docx-0.19.0 → 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.19.0 → athena_python_docx-0.20.0}/docx/commands.py

@@ -926,47 +926,6 @@ class RemoveHyperlink(Command):
     target: dict[str, Any] = dataclasses.field(default_factory=dict)
 
 
-# ---------------------------------------------------------------------------
-# Citations (Athena extension — source-citation markers. No python-docx
-# analog; mirrors the PPTX studio's AddSlideCitation / RemoveCitation. The
-# studio server derives the openable ``citation_string`` (Spaces URL) from
-# ``source_ref`` + ``source_anchor`` via @athenaintel/references.)
-# ---------------------------------------------------------------------------
-
-
-@dataclass
-class CreateCitation(Command):
-    """Insert a source-citation marker.
-
-    Either ``text`` inserts a new cited span at ``at`` (a Word-style
-    superscript marker is appended after it), or ``target`` cites an existing
-    range. ``source_ref`` / ``source_anchor`` describe the cited source
-    (AssetReference / Anchor JSON, transited as dicts like ``SetImageAnchor``).
-    ``label`` is the marker glyph (defaults to a running index server-side).
-    ``client_entity_id`` is the client-minted citation id the applier honors
-    as the citation's stable id (the ``docx-editor-citations`` Y.Map key).
-    """
-
-    source_ref: dict[str, Any] = dataclasses.field(default_factory=dict)
-    source_anchor: dict[str, Any] | None = None
-    display_value: str | None = None
-    label: str | None = None
-    text: str | None = None
-    target: dict[str, Any] | None = None
-    at: dict[str, Any] | None = None
-    client_entity_id: str | None = None
-
-
-@dataclass
-class RemoveCitation(Command):
-    """Remove a citation by id — strips the marker mark and, by default,
-    deactivates the metadata record (``active: false``) so the removal is
-    undoable. ``soft=False`` splices the record out entirely."""
-
-    citation_id: str = ""
-    soft: bool = True
-
-
 # ---------------------------------------------------------------------------
 # Fields (Athena extension — python-docx has no field-add API. PAGE,
 # NUMPAGES, DATE, TIME, FILENAME, AUTHOR, NUMWORDS, REF, SEQ, TOC. The
@@ -1755,9 +1714,6 @@ _RESPONSE_BEARING_TYPES: frozenset[str] = frozenset(
         # Athena-extension response-bearing creates — each returns an
         # entity id the caller wraps in a proxy.
         "CreateHyperlink",
-        # CreateCitation eager-flushes so the marker's ``at`` offset stays
-        # correct relative to surrounding text inserts (mirrors CreateHyperlink).
-        "CreateCitation",
         "CreateField",
         "CreateBookmark",
         "CreateFootnote",
@@ -1827,8 +1783,6 @@ def _mark_athena_extension_command(cls: type, issue: "str | None", description:
 for _cls, _issue, _desc in [
     (CreateHyperlink, "python-docx#74", "Hyperlink add"),
     (RemoveHyperlink, "python-docx#74", "Hyperlink remove"),
-    (CreateCitation, None, "Source citation marker create"),
-    (RemoveCitation, None, "Source citation remove"),
     (CreateField, "python-docx#498", "Field insert"),
     (FieldsRefresh, "python-docx#498", "Field refresh"),
     (FieldsList, "python-docx#498", "Field enumeration"),
@@ -1960,8 +1914,6 @@ __all__ = [
     # semantics))
     "CreateHyperlink",
     "RemoveHyperlink",
-    "CreateCitation",
-    "RemoveCitation",
     "CreateField",
     "FieldsRefresh",
     "FieldsList",

{athena_python_docx-0.19.0 → 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.19.0 → athena_python_docx-0.20.0}/docx/document.py

@@ -936,23 +936,6 @@ class Document:
             include_hyperlinks=include_hyperlinks,
         )
 
-    @athena_extension(
-        description="Document.remove_citation — remove a source citation by id.",
-    )
-    def remove_citation(self, *, citation_id: str, soft: bool = True) -> None:
-        """Remove a source citation by id (Athena extension).
-
-        Strips the citation marker and, by default (``soft=True``),
-        deactivates the metadata record so the removal is undoable;
-        ``soft=False`` splices the record out entirely. No-op if the id is
-        unknown. No upstream python-docx analog.
-        """
-        from docx.commands import RemoveCitation
-
-        run_sync(
-            self._session.send_command(RemoveCitation(citation_id=citation_id, soft=soft))
-        )
-
     @athena_extension(issue=179, description="Document.add_chart.")
     def add_chart(
         self,
@@ -1542,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
@@ -1742,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
@@ -1814,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
@@ -1918,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
 
@@ -1948,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
@@ -1965,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()
@@ -1998,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

athena_python_docx-0.20.0/docx/enum/shape.py

@@ -0,0 +1,30 @@
+"""Inline-shape enums — python-docx parity (``docx.enum.shape``).
+
+Mirrors python-docx 1.2.0: ``WD_INLINE_SHAPE_TYPE`` is the canonical
+enum and ``WD_INLINE_SHAPE`` is an alias of it (``WD_INLINE_SHAPE is
+WD_INLINE_SHAPE_TYPE`` is ``True``). It is a plain :class:`enum.Enum`
+(NOT an ``IntEnum``), so ``shape.type == WD_INLINE_SHAPE.PICTURE`` works
+but ``shape.type == 3`` does not — exactly as upstream.
+
+This is purely the return-value surface for :attr:`docx.shape.InlineShape.type`;
+the SDK only models pictures, so ``type`` returns ``PICTURE``.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class WD_INLINE_SHAPE_TYPE(Enum):
+    """The type of an inline shape, e.g. ``PICTURE`` or ``CHART``."""
+
+    CHART = 12
+    LINKED_PICTURE = 4
+    NOT_IMPLEMENTED = -6
+    PICTURE = 3
+    SMART_ART = 15
+
+
+# python-docx exposes ``WD_INLINE_SHAPE`` as an alias of the canonical
+# ``WD_INLINE_SHAPE_TYPE`` (same object).
+WD_INLINE_SHAPE = WD_INLINE_SHAPE_TYPE