athena-python-docx 0.16.0__tar.gz → 0.17.0__tar.gz

{athena_python_docx-0.16.0 → athena_python_docx-0.17.0}/CLAUDE.md

@@ -93,6 +93,21 @@ remaining work* for the exact wire-op shape needed to unblock each.
 These differ from stock python-docx because the SDK is asset-backed,
 not file-backed. Each is documented in the relevant docstring.
 
+- **`add_picture` accepts an image URL or `data:` URI, not just a path
+  or stream.** Stock python-docx routes ``image_path_or_stream`` through
+  ``docx.image.image.Image.from_file``, which opens a ``str`` as a local
+  filesystem path and has no networking — so ``add_picture("https://…")``
+  raises ``FileNotFoundError``. Agents (and humans) routinely pass a
+  remote image URL, so ``Document.add_picture`` / ``Run.add_picture``
+  additionally fetch ``http(s)://`` URLs (via the already-required
+  ``requests`` dependency, 30s timeout) and decode ``data:[…;base64],…``
+  URIs. Local paths and file-like streams behave exactly as upstream.
+  The dispatch lives in ``docx._image_utils.load_image_bytes``; a failed
+  fetch/decode raises a ``ValueError`` at the call site rather than a
+  bare transport error. This is the only image-input deviation — the
+  resulting bytes still flow through the same magic-byte
+  ``sniff_content_type`` → base64 ``data:`` URI → ``create.image`` path.
+
 - **Built-in table style friendly names resolve to OOXML styleIds.**
   Word's ``styles.xml`` ships built-in table styles whose styleIds
   (``LightGrid-Accent1``, ``MediumShading1-Accent2``, …) differ from

{athena_python_docx-0.16.0 → athena_python_docx-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.16.0
+Version: 0.17.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.16.0 → athena_python_docx-0.17.0}/docx/__init__.py

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

{athena_python_docx-0.16.0 → athena_python_docx-0.17.0}/docx/_buffer.py

@@ -130,6 +130,21 @@ if TYPE_CHECKING:
 _PTC_EMIT_TOOLS: frozenset[str] = frozenset({"CreateParagraph", "CreateHeading", "CreateTable"})
 
 
+def _should_emit_ptc(cmd: Command) -> bool:
+    """Whether ``cmd`` should produce a PTC sub-tool-card.
+
+    Only allow-listed block creates emit, and only when they target the
+    **body** story. Creates carrying an ``in_`` story locator (header,
+    footer, footnote, …) are skipped: the frontend locate affordance
+    scans the body editor only, so a header/footer card would highlight
+    an unrelated body block or nothing at all. Skip until the frontend
+    can route by ``args.in``.
+    """
+    if type(cmd).__name__ not in _PTC_EMIT_TOOLS:
+        return False
+    return getattr(cmd, "in_", None) is None
+
+
 def _ptc_emit_end_batch(cmds: list[Command], *, is_error: bool) -> None:
     """Emit a PTC ``end`` event for every cmd that received a ``begin``.
 
@@ -414,7 +429,7 @@ class CommandBuffer:
         # commands still flow through the buffer (and through the batched
         # HTTP POST), they just don't produce a sub-tool-card. ``emit_end``
         # is automatically skipped because no ``_ptc_call_id`` was set.
-        if type(cmd).__name__ in _PTC_EMIT_TOOLS:
+        if _should_emit_ptc(cmd):
             try:
                 cmd._ptc_call_id = _ptc.emit_begin(  # type: ignore[attr-defined]
                     type(cmd).__name__,

athena_python_docx-0.17.0/docx/_image_utils.py

@@ -0,0 +1,214 @@
+"""Image format / content-type helpers shared by ``Run.add_picture``
+and ``Document.add_picture``.
+
+The previous implementations sniffed only by file extension, which
+silently mistyped streams (default ``image/png``) and was wrong on
+files with mismatched extensions (e.g. ``screenshot.png`` containing
+JPEG bytes — common from OS screen-capture flows).
+
+We sniff by **magic bytes** for the four formats SuperDoc accepts as
+inline image data URIs (PNG, JPEG, GIF, WebP), with extension as a
+secondary fallback for unknown / off-format streams.
+"""
+
+from __future__ import annotations
+
+import base64
+from typing import BinaryIO
+
+# Magic-byte signatures for the formats SuperDoc accepts inline.
+# (mime, signature_bytes, signature_offset). Most are at offset 0;
+# WebP needs a two-part check (RIFF header + WEBP marker at offset 8).
+_PNG_MAGIC: bytes = b"\x89PNG\r\n\x1a\n"
+_JPEG_MAGIC: bytes = b"\xff\xd8\xff"
+_GIF87_MAGIC: bytes = b"GIF87a"
+_GIF89_MAGIC: bytes = b"GIF89a"
+_WEBP_RIFF: bytes = b"RIFF"
+_WEBP_MARKER: bytes = b"WEBP"
+_BMP_MAGIC: bytes = b"BM"
+_TIFF_LE_MAGIC: bytes = b"II*\x00"
+_TIFF_BE_MAGIC: bytes = b"MM\x00*"
+_SVG_HINT_DECL: bytes = b"<?xml"
+_SVG_HINT_TAG: bytes = b"<svg"
+
+
+def sniff_content_type(image_bytes: bytes, *, fallback_path: str = "") -> str:
+    """Return a SuperDoc-acceptable image MIME for ``image_bytes``.
+
+    Magic-byte detection in priority order; if no signature matches,
+    fall back to the file extension on ``fallback_path``; if that
+    also fails, default to ``"image/png"`` (matches the prior
+    silent-default behavior so callers that previously got away with
+    it keep working).
+
+    Athena extension beyond python-docx 1.x: also detects SVG, BMP,
+    and TIFF. python-docx upstream supports PNG/JPEG/GIF/BMP/TIFF; SVG
+    and WEBP are missing from upstream (issues #651, #717, #1399).
+    """
+    if image_bytes.startswith(_PNG_MAGIC):
+        return "image/png"
+    if image_bytes.startswith(_JPEG_MAGIC):
+        return "image/jpeg"
+    if image_bytes.startswith(_GIF87_MAGIC) or image_bytes.startswith(_GIF89_MAGIC):
+        return "image/gif"
+    if (
+        len(image_bytes) >= 12
+        and image_bytes.startswith(_WEBP_RIFF)
+        and image_bytes[8:12] == _WEBP_MARKER
+    ):
+        return "image/webp"
+    if image_bytes.startswith(_BMP_MAGIC):
+        return "image/bmp"
+    if image_bytes.startswith(_TIFF_LE_MAGIC) or image_bytes.startswith(_TIFF_BE_MAGIC):
+        return "image/tiff"
+    # SVG: probe first ~1KB for either an XML declaration or a literal
+    # ``<svg`` tag. Case-insensitive on the tag because legitimate SVG
+    # files sometimes carry ``<SVG`` after author tools.
+    head = image_bytes[:1024]
+    if _SVG_HINT_TAG in head or _SVG_HINT_TAG in head.lower():
+        return "image/svg+xml"
+    if head.startswith(_SVG_HINT_DECL) and b"<svg" in head.lower():
+        return "image/svg+xml"
+
+    if fallback_path:
+        lower = fallback_path.lower()
+        if lower.endswith((".jpg", ".jpeg")):
+            return "image/jpeg"
+        if lower.endswith(".gif"):
+            return "image/gif"
+        if lower.endswith(".webp"):
+            return "image/webp"
+        if lower.endswith(".png"):
+            return "image/png"
+        if lower.endswith(".svg"):
+            return "image/svg+xml"
+        if lower.endswith(".bmp"):
+            return "image/bmp"
+        if lower.endswith((".tif", ".tiff")):
+            return "image/tiff"
+
+    return "image/png"
+
+
+# Generous default so large remote images over a slow link still land, while a
+# dead host fails the call instead of hanging the agent's code-exec forever.
+_URL_FETCH_TIMEOUT_SECONDS: float = 30.0
+# Hard cap so a giant (or accidentally non-image) URL can't balloon memory in
+# the document-exec sandbox — the bytes get base64-encoded into the doc next.
+_MAX_REMOTE_IMAGE_BYTES: int = 10 * 1024 * 1024  # 10 MiB
+
+
+def load_image_bytes(image_path_or_stream: "str | BinaryIO") -> tuple[bytes, str]:
+    """Read raw image bytes from a local path, ``http(s)://`` URL, ``data:``
+    URI, or binary stream.
+
+    Returns ``(image_bytes, fallback_path)`` where ``fallback_path`` feeds the
+    extension-based MIME fallback in :func:`sniff_content_type` (empty when the
+    source carries no usable filename).
+
+    Athena extension beyond python-docx: upstream ``add_picture`` only accepts a
+    local path or file-like object — a ``str`` is always opened as a filesystem
+    path. Agents routinely pass an image URL or a ``data:`` URI, so the Athena
+    SDK additionally fetches ``http(s)://`` URLs (via ``requests``) and decodes
+    ``data:`` URIs here. Local paths and streams behave exactly as in
+    python-docx.
+
+    URL fetching runs inside the document-exec sandbox, which already executes
+    arbitrary agent-authored code (hence arbitrary outbound requests), so this
+    grants no network capability the caller lacks — it is not an SSRF allowlist
+    boundary. It does cap the download at ``_MAX_REMOTE_IMAGE_BYTES`` so an
+    oversized response can't exhaust sandbox memory.
+    """
+    if isinstance(image_path_or_stream, str):
+        descriptor = image_path_or_stream
+        # URI schemes are case-insensitive (RFC 3986): dispatch on a lowercased
+        # scheme, but fetch/open the original value unchanged.
+        scheme = descriptor.split(":", 1)[0].lower() if ":" in descriptor else ""
+        if scheme in ("http", "https"):
+            from urllib.parse import urlsplit
+
+            # Sniff fallback off the URL *path* only — a signed URL's query
+            # string (``?token=…``) would otherwise defeat the extension check.
+            return _fetch_image_url(descriptor), urlsplit(descriptor).path
+        if scheme == "data":
+            return _decode_image_data_uri(descriptor), ""
+        with open(descriptor, "rb") as f:
+            return f.read(), descriptor
+    # Duck-type the stream: python-docx accepts anything with ``.read()`` (it
+    # never isinstance-checks), so a BinaryIO that doesn't subclass io.IOBase
+    # must work too.
+    reader = getattr(image_path_or_stream, "read", None)
+    if callable(reader):
+        data = reader()
+        if not isinstance(data, (bytes, bytearray)):
+            raise TypeError(
+                f"Image stream .read() returned {type(data).__name__}, expected bytes",
+            )
+        return bytes(data), ""
+    raise TypeError(
+        "Expected a path str, http(s) URL, data: URI, or binary stream, got "
+        f"{type(image_path_or_stream).__name__}",
+    )
+
+
+def _fetch_image_url(url: str) -> bytes:
+    """Download image bytes from an ``http(s)://`` URL, capped at
+    ``_MAX_REMOTE_IMAGE_BYTES`` (Athena extension — see
+    :func:`load_image_bytes`)."""
+    # Lazy import: ``requests`` is already a hard SDK dependency (HTTP transport),
+    # but keep this format helper importable without paying for it up front.
+    import requests
+    from urllib.parse import urlsplit, urlunsplit
+
+    def _redact(raw: str) -> str:
+        # Drop query + fragment so signed-URL tokens don't leak into errors/logs.
+        parts = urlsplit(raw)
+        return urlunsplit((parts.scheme, parts.netloc, parts.path, "", ""))
+
+    try:
+        with requests.get(url, timeout=_URL_FETCH_TIMEOUT_SECONDS, stream=True) as resp:
+            resp.raise_for_status()
+            declared = resp.headers.get("content-length")
+            if declared is not None and declared.isdigit() and int(declared) > _MAX_REMOTE_IMAGE_BYTES:
+                raise ValueError(
+                    f"add_picture image at {_redact(url)!r} declares {declared} bytes, "
+                    f"over the {_MAX_REMOTE_IMAGE_BYTES}-byte cap"
+                )
+            chunks: list[bytes] = []
+            total = 0
+            for chunk in resp.iter_content(chunk_size=65536):
+                if not chunk:
+                    continue
+                total += len(chunk)
+                if total > _MAX_REMOTE_IMAGE_BYTES:
+                    raise ValueError(
+                        f"add_picture image at {_redact(url)!r} exceeds the "
+                        f"{_MAX_REMOTE_IMAGE_BYTES}-byte cap"
+                    )
+                chunks.append(chunk)
+            return b"".join(chunks)
+    except requests.RequestException as exc:
+        raise ValueError(f"add_picture could not fetch image URL {_redact(url)!r}: {exc}") from exc
+
+
+def _decode_image_data_uri(uri: str) -> bytes:
+    """Decode a ``data:[<mediatype>][;base64],<payload>`` URI to raw bytes
+    (Athena extension — see :func:`load_image_bytes`)."""
+    header, sep, payload = uri.partition(",")
+    if not sep or not payload:
+        raise ValueError("add_picture received a data: URI with no payload")
+    # ``;base64`` is a discrete, case-insensitive token (RFC 2397) — match it as
+    # a token, not a substring (so ``;notbase64x`` doesn't false-match), and use
+    # strict decoding so malformed base64 fails loudly instead of silently.
+    is_base64 = any(token.strip().lower() == "base64" for token in header.split(";")[1:])
+    try:
+        if is_base64:
+            return base64.b64decode(payload, validate=True)
+        from urllib.parse import unquote_to_bytes
+
+        return unquote_to_bytes(payload)
+    except Exception as exc:
+        raise ValueError(f"add_picture could not decode data: URI: {exc}") from exc
+
+
+__all__ = ["load_image_bytes", "sniff_content_type"]

{athena_python_docx-0.16.0 → athena_python_docx-0.17.0}/docx/commands.py

@@ -519,6 +519,11 @@ class ImagesGet(Command):
 class BlocksList(Command):
     node_types: list[str] | None = None
     include_text: bool | None = None
+    # Ask the server to inline each paragraph/heading block's run breakdown
+    # (``paragraph.inlines``) so ``Document.paragraphs`` can hydrate
+    # ``Paragraph.text``/``.runs``/``.style`` from one list instead of a
+    # ``get_node_by_id`` per paragraph. Serialized to ``includeRuns`` on the wire.
+    include_runs: bool | None = None
 
 
 @dataclass

{athena_python_docx-0.16.0 → athena_python_docx-0.17.0}/docx/document.py

@@ -15,7 +15,6 @@ Phase 1 supported methods:
 from __future__ import annotations
 
 import base64
-import io
 import sys
 from contextlib import contextmanager
 from typing import TYPE_CHECKING, BinaryIO, Generator, Iterator
@@ -359,12 +358,23 @@ class Document:
         # Include "heading" too so iterating over paragraphs covers both —
         # python-docx does not distinguish headings from paragraphs at the
         # Document.paragraphs level either (they're all Paragraph instances).
+        # ``includeRuns`` asks the server to inline each block's run breakdown
+        # (``paragraph.inlines``) so we can hydrate every returned proxy's
+        # ``.text`` / ``.runs`` / ``.style`` from this single list — instead of
+        # one ``get_node_by_id`` round-trip per paragraph per property. A
+        # read-heavy restyle loop over a large doc drops from ~N×3 round-trips
+        # to 1. See ``docx-studio/PERFORMANCE_BATCHING_ANALYSIS.md``.
         raw: object = run_sync(
             self._session.doc.blocks.list(
-                {"nodeTypes": ["paragraph", "heading"], "includeText": False},
+                {
+                    "nodeTypes": ["paragraph", "heading"],
+                    "includeText": True,
+                    "includeRuns": True,
+                },
             ),
         )
-        # Real shape: {"blocks": [{"kind":"block","nodeType":..,"nodeId":..}], ...}
+        # Real shape: {"blocks": [{"kind":"block","nodeType":..,"nodeId":..,
+        # "styleId":..,"text":..,"paragraph":{"inlines":[..]}}], ...}
         if isinstance(raw, dict):
             blocks_obj: object = raw.get("blocks", [])
             blocks: list = blocks_obj if isinstance(blocks_obj, list) else []
@@ -380,11 +390,20 @@ class Document:
             if node_id:
                 nt_raw = b.get("nodeType")
                 nt: str = nt_raw if isinstance(nt_raw, str) and nt_raw else "paragraph"
+                # Seed the read cache when the server inlined this block's runs.
+                # The snapshot is ``get_node_by_id``-shaped so
+                # ``Paragraph._node_info`` and the text/runs/style getters consume
+                # it unchanged. Blocks without an ``inlines`` payload (e.g.
+                # tables) fall back to live queries.
+                snapshot: dict | None = (
+                    {"node": b} if isinstance(b.get("paragraph"), dict) else None
+                )
                 out.append(
                     Paragraph(
                         session=self._session,
                         node_id=node_id,
                         node_type=nt,
+                        node_info_snapshot=snapshot,
                     ),
                 )
         return out
@@ -1854,26 +1873,20 @@ class Document:
 
         Mirrors python-docx ``Document.add_picture`` — returns the new
         :class:`InlineShape` proxy.
+
+        ``image_path_or_stream`` accepts a local file path, a binary stream
+        (e.g. ``io.BytesIO``), an ``http(s)://`` image URL (fetched
+        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 sniff_content_type
+        from docx._image_utils import load_image_bytes, sniff_content_type
         from docx.shape import InlineShape
         from docx.text.run import _build_inline_shape_info
 
         self._ensure_open()
         self._reset_list_chain()
 
-        image_bytes: bytes
-        fallback_path: str = ""
-        if isinstance(image_path_or_stream, str):
-            with open(image_path_or_stream, "rb") as f:
-                image_bytes = f.read()
-            fallback_path = image_path_or_stream
-        elif isinstance(image_path_or_stream, io.IOBase):
-            image_bytes = image_path_or_stream.read()
-        else:
-            raise TypeError(
-                f"Expected path str or binary stream, got {type(image_path_or_stream).__name__}",
-            )
+        image_bytes, fallback_path = load_image_bytes(image_path_or_stream)
         # An empty payload (closed file, empty BytesIO, truncated stream
         # that's already been read to EOF) would silently produce a
         # ``data:image/png;base64,`` URI — SuperDoc accepts that and

{athena_python_docx-0.16.0 → athena_python_docx-0.17.0}/docx/text/paragraph.py

@@ -226,6 +226,7 @@ class Paragraph:
         in_cell: bool = False,
         cell_ooxml_address: "tuple[str | None, int, int, int, int] | None" = None,
         cell: "object | None" = None,
+        node_info_snapshot: dict | None = None,
     ) -> None:
         self._session: "Session" = session
         self._node_id: str = node_id
@@ -272,6 +273,36 @@ class Paragraph:
         # — defensive for paragraph proxies built outside the _Cell
         # construction paths.
         self._cell: object | None = cell
+        # Prefetched ``get_node_by_id``-shaped snapshot
+        # (``{"node": {..., "paragraph": {"inlines": [...]}}}``) seeded by
+        # ``Document.paragraphs`` via the bulk ``blocks.list(includeRuns=True)``
+        # read. When present, ``text`` / ``runs`` / ``style`` read it instead of
+        # issuing a per-property ``get_node_by_id`` round-trip. It is a
+        # point-in-time snapshot (consistent with ``Document.paragraphs`` already
+        # returning a snapshot list) and is dropped by ``_invalidate_node_info``
+        # the moment this proxy mutates its own content.
+        self._node_info_snapshot: dict | None = node_info_snapshot
+
+    def _node_info(self) -> object:
+        """Return this paragraph's ``get_node_by_id``-shaped node info.
+
+        Served from the prefetch snapshot when one was seeded (one bulk
+        ``blocks.list`` for the whole document instead of one
+        ``get_node_by_id`` per ``.text`` / ``.runs`` / ``.style`` access);
+        otherwise a live query. ``_invalidate_node_info`` clears the snapshot
+        after a content mutation so the next read re-queries.
+        """
+        snapshot = self._node_info_snapshot
+        if snapshot is not None:
+            return snapshot
+        return run_sync(
+            self._session.doc.get_node_by_id({"id": self._node_id}),
+        )
+
+    def _invalidate_node_info(self) -> None:
+        """Drop the prefetched node snapshot after a content mutation, so the
+        next ``text`` / ``runs`` / ``style`` read reflects the new state."""
+        self._node_info_snapshot = None
 
     def _check_cell_inner(self, op: str, **format_props: Any) -> bool:
         """Return ``True`` if this paragraph is inside a table cell and
@@ -356,7 +387,7 @@ class Paragraph:
     @property
     def text(self) -> str:
         """Return the plain-text content of this paragraph."""
-        return _node_text(self._session, self._node_id)
+        return _extract_text(self._node_info())
 
     @text.setter
     def text(self, value: str) -> None:
@@ -399,6 +430,9 @@ class Paragraph:
         # We just replaced the entire paragraph contents with ``value``;
         # the new text-address length is simply ``len(value)``.
         self._text_len = len(value)
+        # Content changed — drop the prefetched snapshot so a follow-up
+        # ``.text`` / ``.runs`` read reflects the replacement.
+        self._invalidate_node_info()
 
     @property
     def runs(self) -> list["Run"]:
@@ -413,9 +447,7 @@ class Paragraph:
         """
         from docx.text.run import Run
 
-        info: object = run_sync(
-            self._session.doc.get_node_by_id({"id": self._node_id}),
-        )
+        info: object = self._node_info()
         inlines: list[dict] = _walk_inlines(info)
         runs: list["Run"] = []
         offset: int = 0
@@ -479,9 +511,7 @@ class Paragraph:
         from docx.styles.style import ParagraphStyle
         from docx.enum.style import WD_STYLE_TYPE
 
-        info: object = run_sync(
-            self._session.doc.get_node_by_id({"id": self._node_id}),
-        )
+        info: object = self._node_info()
         if not isinstance(info, dict):
             return None
         node: object = info.get("node")
@@ -537,6 +567,10 @@ class Paragraph:
                 },
             ),
         )
+        # Style changed — drop the prefetched snapshot so a follow-up ``.style``
+        # read reflects the new style instead of the stale prefetched value
+        # (the restyle-loop read-after-write this PR's prefetch targets).
+        self._invalidate_node_info()
 
     @property
     def alignment(self) -> "WD_ALIGN_PARAGRAPH | None":
@@ -1227,6 +1261,9 @@ class Paragraph:
                 )
             offset += 1
             i = j + 1
+        # Inserted content — drop the prefetched node snapshot so a follow-up
+        # ``.text`` / ``.runs`` read on this proxy reflects the new runs.
+        self._invalidate_node_info()
 
     @athena_extension(
         issue=74,
@@ -1397,6 +1434,11 @@ class Paragraph:
         )
         run_sync(self._session.send_command(cmd))
         self._text_len = end_offset
+        # Appended a hyperlink run — drop the prefetched snapshot so a follow-up
+        # ``.text`` / ``.runs`` read reflects the new content. This path fires
+        # ``CreateHyperlink`` directly via ``send_command`` (it bypasses
+        # ``_insert_run_text_segments``), so it needs its own invalidation.
+        self._invalidate_node_info()
 
         run_dict = {"text": text, "hyperlink": {"url": url, "target": url}}
         return Hyperlink(

{athena_python_docx-0.16.0 → athena_python_docx-0.17.0}/docx/text/run.py

@@ -594,26 +594,18 @@ class Run:
 
         Returns an :class:`InlineShape` proxy for the newly-inserted
         image, matching python-docx ``Run.add_picture``.
+
+        ``image_path_or_stream`` accepts a local file path, a binary stream
+        (e.g. ``io.BytesIO``), an ``http(s)://`` image URL (fetched
+        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 sniff_content_type
+        from docx._image_utils import load_image_bytes, sniff_content_type
         from docx.document import _emu_to_px
         from docx.shape import InlineShape
         import base64
-        import io
-
-        image_bytes: bytes
-        fallback_path: str = ""
-        if isinstance(image_path_or_stream, str):
-            with open(image_path_or_stream, "rb") as f:
-                image_bytes = f.read()
-            fallback_path = image_path_or_stream
-        elif isinstance(image_path_or_stream, io.IOBase):
-            image_bytes = image_path_or_stream.read()
-        else:
-            raise TypeError(
-                "Expected path str or binary stream, "
-                f"got {type(image_path_or_stream).__name__}",
-            )
+
+        image_bytes, fallback_path = load_image_bytes(image_path_or_stream)
         # Empty payload would silently round-trip as
         # ``data:image/png;base64,`` (broken placeholder image). Fail
         # at the call site instead of at render time. Matches the

{athena_python_docx-0.16.0 → athena_python_docx-0.17.0}/pyproject.toml

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

{athena_python_docx-0.16.0 → athena_python_docx-0.17.0}/tests/fidelity/fake_session.py

@@ -296,6 +296,7 @@ class FakeDocState:
 
         if op == "blocks.list":
             types = params.get("nodeTypes") or None
+            include_runs = bool(params.get("includeRuns"))
             out_blocks: list[dict] = []
             for b in self.blocks:
                 if types and b.node_type not in types:
@@ -307,6 +308,12 @@ class FakeDocState:
                     "styleId": b.style_id,
                     "alignment": b.alignment,
                 }
+                # Mirror the real server: when runs are requested, inline each
+                # paragraph/heading block's run breakdown so the SDK hydrates
+                # Paragraph.text/.runs/.style from this one list (no per-node read).
+                if include_runs and b.node_type in ("paragraph", "heading"):
+                    entry["text"] = b.text
+                    entry["paragraph"] = {"inlines": list(b.inlines)}
                 out_blocks.append(entry)
             # Mirror real SuperDoc: when "table" is in the requested
             # nodeTypes, top-level tables come back too. The fake doesn't

{athena_python_docx-0.16.0 → athena_python_docx-0.17.0}/tests/fidelity/op_snapshots/70_add_and_iterate_back.json

@@ -3,9 +3,5 @@
   "create.paragraph",
   "create.paragraph",
   "create.paragraph",
-  "blocks.list",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById"
+  "blocks.list"
 ]