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

{athena_python_docx-0.16.1 → 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.1 → athena_python_docx-0.17.0}/PKG-INFO

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

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.1 → 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
@@ -1874,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.1 → 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.1 → athena_python_docx-0.17.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "athena-python-docx"
-version = "0.16.1"
+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.1 → 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"
 ]

{athena_python_docx-0.16.1 → athena_python_docx-0.17.0}/tests/fidelity/op_snapshots/ex18_read_back_large_doc.json

@@ -99,105 +99,5 @@
   "create.paragraph",
   "create.heading",
   "create.paragraph",
-  "blocks.list",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById"
+  "blocks.list"
 ]

{athena_python_docx-0.16.1 → athena_python_docx-0.17.0}/tests/fidelity/op_snapshots/ex19_mutate_all_runs.json

@@ -20,23 +20,18 @@
   "insert",
   "insert",
   "blocks.list",
-  "getNodeById",
   "format.apply",
   "format.apply",
   "format.apply",
-  "getNodeById",
   "format.apply",
   "format.apply",
   "format.apply",
-  "getNodeById",
   "format.apply",
   "format.apply",
   "format.apply",
-  "getNodeById",
   "format.apply",
   "format.apply",
   "format.apply",
-  "getNodeById",
   "format.apply",
   "format.apply",
   "format.apply"

{athena_python_docx-0.16.1 → athena_python_docx-0.17.0}/tests/fidelity/op_snapshots/rw09_bulk_run_iteration.json

@@ -69,15 +69,5 @@
   "getNodeById",
   "getNodeById",
   "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
-  "getNodeById",
   "getNodeById"
 ]