athena-python-docx 0.22.0__tar.gz → 0.24.0__tar.gz

{athena_python_docx-0.22.0 → athena_python_docx-0.24.0}/AGENTS.md

@@ -481,6 +481,19 @@ Issue numbers reference `python-openxml/python-docx`.
   an older API stores the record under the cell id, where nothing renders
   it and the next edit retires it.
 
+- **Image region citations**: cite a region of an image asset with
+  ``AssetReference(id=<image>)`` + ``PixelRangeAnchor(x=, y=, width=,
+  height=)`` in source image pixels, or with a
+  ``/dashboard/spaces/?asset_ids=<image>&type=image&anchor=pixel_range&x=…&y=…&width=…&height=…``
+  citation string. DOCX Studio stores ``type=image`` and keeps ``excerpt``
+  out of the URL (the record keeps it as the span of the cited paragraph to
+  highlight). Since 0.23.0, ``add_citation`` raises ``ValueError`` for the
+  image citations that chat and Sheets reject (agora
+  ``validate_image_citation_url``): an image URL with ``excerpt`` or
+  ``#:~:text=`` and no anchor, a non-region anchor, a region anchor without
+  x, y, width and height, and an ``AssetMeta(asset_type="image")`` source
+  with a non-region anchor or with an excerpt and no anchor.
+
 - **`Document.export_docx(path=None, *, include_revisions=False)
   -> bytes`** (0.11.4+) — export the document's current state as
   ``.docx`` bytes, optionally writing to ``path``. Closes the gap

{athena_python_docx-0.22.0 → athena_python_docx-0.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: athena-python-docx
-Version: 0.22.0
+Version: 0.24.0
 Summary: Drop-in replacement for python-docx that connects to Athena's DOCX Studio collaborative document stack
 Project-URL: Homepage, https://athenaintelligence.ai
 Author-email: Athena Intelligence <engineering@athenaintelligence.ai>

{athena_python_docx-0.22.0 → athena_python_docx-0.24.0}/docx/__init__.py

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

{athena_python_docx-0.22.0 → athena_python_docx-0.24.0}/docx/_citations.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import uuid
+from collections.abc import Mapping
 from typing import Any
 from urllib.parse import parse_qs, urlparse
 
@@ -34,6 +35,87 @@ def source_ref_to_dict(source: AssetReference) -> dict[str, Any]:
     return source.to_dict()
 
 
+_IMAGE_REGION_ANCHOR_TYPES: tuple[str, ...] = ("pixel_range", "rect")
+_IMAGE_REGION_FIELDS: tuple[str, ...] = ("x", "y", "width", "height")
+
+
+def _is_number(value: object) -> bool:
+    """True for what agora's anchor parser reads as a number (``float(...)``)."""
+    if isinstance(value, bool):
+        return False
+    if isinstance(value, (int, float)):
+        return True
+    if isinstance(value, str):
+        try:
+            float(value)
+        except ValueError:
+            return False
+        return True
+    return False
+
+
+def check_image_citation(
+    *,
+    anchor_type: str | None,
+    has_excerpt: bool,
+    region: Mapping[str, object] | None = None,
+) -> None:
+    """Reject an image citation that chat and Sheets reject.
+
+    The same rules as agora's ``validate_citation_url`` for an image: an
+    image is cited by a region (``anchor=pixel_range`` with numeric x, y,
+    width and height in source image pixels), never by a page, a text anchor
+    or an excerpt. ``region`` holds the x, y, width and height values of a
+    region anchor (``None`` for a missing one).
+    """
+    if anchor_type and anchor_type not in _IMAGE_REGION_ANCHOR_TYPES:
+        raise ValueError(
+            f"An image citation cannot use anchor={anchor_type}. Cite a region "
+            "of the image: anchor=pixel_range with x, y, width and height in "
+            "source image pixels (PixelRangeAnchor)."
+        )
+    if not anchor_type and has_excerpt:
+        raise ValueError(
+            "An image citation cannot use an excerpt or a #:~:text= fragment: "
+            "an image has no text to find. Cite a region of the image: "
+            "anchor=pixel_range with x, y, width and height in source image "
+            "pixels (PixelRangeAnchor), and put the label in display_value."
+        )
+    if not anchor_type or region is None:
+        return
+    missing = [field for field in _IMAGE_REGION_FIELDS if region.get(field) is None]
+    if missing:
+        raise ValueError(
+            f"An image citation with anchor={anchor_type} needs x, y, width "
+            f"and height. Missing: {', '.join(missing)}."
+        )
+    not_numbers = [field for field in _IMAGE_REGION_FIELDS if not _is_number(region[field])]
+    if not_numbers:
+        raise ValueError(
+            f"An image citation with anchor={anchor_type} needs numbers for "
+            f"x, y, width and height. Not a number: {', '.join(not_numbers)}."
+        )
+
+
+def _check_image_citation_url(query: str, fragment: str) -> None:
+    # Blank values are dropped, as agora's validator parses the query.
+    params = parse_qs(query)
+
+    def first(key: str) -> str | None:
+        values = params.get(key)
+        return values[0] if values else None
+
+    asset_type = (first("asset_type") or first("type") or "").lower()
+    if asset_type != "image":
+        return
+    anchor_type = (first("anchor") or "").lower() or None
+    check_image_citation(
+        anchor_type=anchor_type,
+        has_excerpt=first("excerpt") is not None or fragment.startswith(":~:text="),
+        region={field: first(field) for field in _IMAGE_REGION_FIELDS},
+    )
+
+
 def normalize_citation_string(citation_string: str) -> str:
     value = citation_string.strip()
     if not value:
@@ -49,6 +131,7 @@ def normalize_citation_string(citation_string: str) -> str:
             asset_ids = parse_qs(parsed.query).get("asset_ids")
             if not asset_ids or not asset_ids[0]:
                 raise ValueError("Athena Spaces citation URLs must include asset_ids")
+            _check_image_citation_url(parsed.query, parsed.fragment)
         return value
 
     if not parsed.scheme and value.startswith("/"):
@@ -61,6 +144,7 @@ def normalize_citation_string(citation_string: str) -> str:
         if relative.path.rstrip("/") == "/dashboard/spaces":
             asset_ids = parse_qs(relative.query).get("asset_ids")
             if asset_ids and asset_ids[0]:
+                _check_image_citation_url(relative.query, relative.fragment)
                 return value
             raise ValueError("Athena Spaces citation URLs must include asset_ids")
 
@@ -106,6 +190,35 @@ def destination_anchor_to_dict(destination_anchor: object) -> dict[str, Any]:
     )
 
 
+def _check_typed_image_citation(
+    *,
+    source_ref: dict[str, Any],
+    source_anchor: dict[str, Any] | None,
+    excerpt: str | None,
+) -> None:
+    """Apply the image citation rules to an ``AssetReference`` source.
+
+    A ``PixelRangeAnchor`` / ``RectAnchor`` source is an image region:
+    DOCX Studio names it ``type=image`` and keeps the excerpt out of its URL
+    (the record keeps it as the span of the cited paragraph to highlight).
+    A source that ``AssetMeta(asset_type="image")`` names an image must use
+    one of those anchors.
+    """
+    anchor = source_anchor or source_ref.get("anchor")
+    anchor_type = anchor.get("type") if isinstance(anchor, dict) else None
+    meta = source_ref.get("meta")
+    asset_type = meta.get("assetType") if isinstance(meta, dict) else None
+    is_region = anchor_type in _IMAGE_REGION_ANCHOR_TYPES
+    if not is_region and str(asset_type or "").lower() != "image":
+        return
+    meta_excerpt = meta.get("excerpt") if isinstance(meta, dict) else None
+    check_image_citation(
+        anchor_type=anchor_type,
+        has_excerpt=excerpt is not None or meta_excerpt is not None,
+        region=anchor if is_region and isinstance(anchor, dict) else None,
+    )
+
+
 def build_add_citation_command(
     *,
     destination_anchor: object,
@@ -142,11 +255,19 @@ def build_add_citation_command(
     if source_ref is None and anchor is not None:
         raise ValueError("anchor requires an AssetReference source; encode the anchor in citation_string instead")
 
+    source_anchor = anchor_to_dict(anchor)
+    if source_ref is not None:
+        _check_typed_image_citation(
+            source_ref=source_ref,
+            source_anchor=source_anchor,
+            excerpt=excerpt,
+        )
+
     citation_id = new_citation_id()
     return citation_id, AddCitation(
         destination_anchor=destination_anchor_to_dict(destination_anchor),
         source_ref=source_ref,
-        source_anchor=anchor_to_dict(anchor),
+        source_anchor=source_anchor,
         citation_string=normalized_citation_string,
         citation_id=citation_id,
         excerpt=excerpt,

athena_python_docx-0.24.0/docx/_run_order.py

@@ -0,0 +1,217 @@
+"""Run order of a paragraph, as ``Paragraph.add_run`` created its runs.
+
+A picture takes no text offset, so two runs can end at the same offset:
+``r1 = p.add_run("A"); r2 = p.add_run(); r2.add_picture(img)`` puts ``r2`` and
+its picture at offset 1, where ``r1`` ends. The offset alone cannot tell the
+server whether content for ``r1`` goes before or after that picture. The SDK
+knows: ``add_run`` appends each run to the end of its paragraph.
+
+This module keeps a record of each such run (its range and the pictures that
+its ``add_picture`` added), in creation order, and gives:
+
+- the run identity of a run-end insert (:func:`run_ref`): the first picture
+  that a later run holds at the same offset (for a read segment that ends
+  inside its run, also the run's own picture there). The server puts the
+  content in front of it; without it, after the pictures at the offset.
+- current ranges: when a run grows or shrinks, its pictures and the runs after
+  it move (:func:`note_length_change`), and so do the live run proxies. A
+  replace cuts every record that it touches.
+
+A record lives as long as its paragraph proxy, not as long as its run proxy,
+so ``p.add_run().add_picture(img)`` keeps the picture's place. The records of
+every paragraph proxy of one block (``doc.paragraphs`` makes new ones) are one
+order. A read run (``paragraph.runs``) stands for the recorded run that holds
+its last character; a read run over text that no recorded run holds counts as
+a run before all of them. The order lives in the SDK process only; the
+document stores none of it.
+"""
+
+from __future__ import annotations
+
+import itertools
+import weakref
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from docx.text.run import Run
+
+_SEQ = itertools.count()
+
+
+@dataclass(eq=False)
+class RunRecord:
+    """One run that ``add_run`` created."""
+
+    seq: int
+    range: tuple[int, int]
+    run: "weakref.ref[Run]"
+    # ``(picture id, offset)`` of each picture that the run's ``add_picture`` added.
+    pictures: list[tuple[str, int]] = field(default_factory=list)
+
+
+# Paragraph proxy -> the records of the runs its ``add_run`` created. A record
+# holds no reference to the paragraph or session, so an entry goes with its
+# paragraph proxy. Keyed by the proxy, not by its id: the first flush moves a
+# new paragraph from its client id to the server id, and the runs created
+# before that keep the client id.
+_ORDERS: "weakref.WeakKeyDictionary[Any, list[RunRecord]]" = weakref.WeakKeyDictionary()
+
+
+def _records_of(run: "Run") -> list[RunRecord]:
+    paragraph = getattr(run, "_paragraph", None)
+    ids = {run._block_id}
+    if paragraph is not None:
+        ids.add(paragraph._node_id)
+    records: list[RunRecord] = []
+    for owner, owner_records in list(_ORDERS.items()):
+        if owner is paragraph or (owner._session is run._session and owner._node_id in ids):
+            records.extend(owner_records)
+    records.sort(key=lambda record: record.seq)
+    return records
+
+
+def register_run(run: "Run") -> None:
+    """Record ``run`` as the last run of its paragraph (``Paragraph.add_run``)."""
+    record = RunRecord(seq=next(_SEQ), range=run._range, run=weakref.ref(run))
+    _ORDERS.setdefault(run._paragraph, []).append(record)
+    run._run_record = record
+
+
+def forget_paragraph(paragraph: Any) -> None:
+    """Drop the order of a paragraph whose runs are gone (``Paragraph.text = ...``)."""
+    for owner in list(_ORDERS.keys()):
+        if owner is paragraph or (owner._session is paragraph._session and owner._node_id == paragraph._node_id):
+            _ORDERS.pop(owner, None)
+
+
+def _place(
+    run: "Run", span: tuple[int, int], records: list[RunRecord] | None = None
+) -> tuple[RunRecord | None, list[RunRecord]]:
+    """The record of ``run`` (over ``span``), if any, and the records after it."""
+    if records is None:
+        records = _records_of(run)
+    # The run itself, or the text that its ``add_text`` returned.
+    own = getattr(run, "_run_record", None) or getattr(run, "_owner_record", None)
+    for index, record in enumerate(records):
+        if record is own:
+            return record, records[index + 1 :]
+    # ``paragraph.runs`` makes a new proxy of a kept run: over the same range,
+    # or over a part of it (a read splits a run at a tab, a break or a change
+    # of format). The proxy stands for the run that holds its last character.
+    if span[0] != span[1]:
+        last = span[1] - 1
+        for index, record in enumerate(records):
+            if record.range[0] <= last < record.range[1]:
+                return record, records[index + 1 :]
+    return None, records
+
+
+def _set_range(record: RunRecord, value: tuple[int, int]) -> None:
+    record.range = value
+    proxy = record.run()
+    if proxy is not None:
+        proxy._range = value
+
+
+def note_length_change(
+    run: "Run",
+    at: int,
+    delta: int,
+    *,
+    replaced: tuple[int, int] | None = None,
+    before: str | None = None,
+) -> None:
+    """``run`` (already over its new range) changed its text by ``delta`` units.
+
+    Without ``replaced``: an insert of ``delta`` units at ``at`` (the end of
+    ``run``), in front of the picture ``before`` when the command named one
+    (else after the pictures at ``at``). With ``replaced``: ``Run.text``
+    replaced the old range ``replaced``; the server keeps the pictures at its
+    start and end and removes the ones inside.
+
+    The text belongs to the record of ``run`` (see :func:`_place`). Every
+    record that the replaced range touches is cut; the records and pictures
+    after the change move.
+    """
+    if delta == 0 and replaced is None:
+        return
+    records = _records_of(run)
+    if replaced is None:
+        start = end = at
+        inserted = delta
+        old_span = (run._range[0], run._range[1] - delta)
+    else:
+        start, end = replaced
+        inserted = (end - start) + delta
+        old_span = replaced
+    owner = _place(run, old_span, records)[0]
+    owner_index = records.index(owner) if owner is not None else -1
+    removed = end - start
+
+    def cut(x: int) -> int:
+        return x if x <= start else start if x < end else x - removed
+
+    # The pictures at ``at`` that an insert goes in front of: ``before`` and
+    # the ones after it, in document order (records in order, then the
+    # pictures of each record in order).
+    moved_at: set[str] = set()
+    if replaced is None and before is not None:
+        order = [pid for record in records for pid, off in record.pictures if off == at]
+        if before in order:
+            moved_at = set(order[order.index(before) :])
+
+    for index, record in enumerate(records):
+        rec_start, rec_end = cut(record.range[0]), cut(record.range[1])
+        if record is owner:
+            rec_end += inserted
+        elif index > owner_index and rec_start >= start:
+            rec_start, rec_end = rec_start + inserted, rec_end + inserted
+        _set_range(record, (rec_start, rec_end))
+        pictures: list[tuple[str, int]] = []
+        for pid, off in record.pictures:
+            if replaced is None:
+                pictures.append((pid, off + delta if off > at or pid in moved_at else off))
+            elif off <= start:
+                pictures.append((pid, off))
+            elif off >= end:
+                pictures.append((pid, off + delta))
+        # The moves keep document order; a stable sort by offset keeps it so.
+        pictures.sort(key=lambda item: item[1])
+        record.pictures = pictures
+
+
+def note_picture(run: "Run", picture_id: str, offset: int, *, before: str | None = None) -> None:
+    """``run.add_picture`` put the picture ``picture_id`` at ``offset``, in front of ``before``.
+
+    A record keeps its pictures in document order: the new one goes in front
+    of ``before``, else after the pictures at ``offset`` and before the ones
+    after it (the server puts a picture after the pictures at its offset).
+    """
+    record = _place(run, run._range)[0]
+    if record is None:
+        return
+    ids = [pid for pid, _ in record.pictures]
+    if before in ids:
+        index = ids.index(before)
+    else:
+        index = next((i for i, (_, off) in enumerate(record.pictures) if off > offset), len(ids))
+    record.pictures.insert(index, (picture_id, offset))
+
+
+def run_ref(run: "Run") -> dict[str, str] | None:
+    """``{"beforeImageId": id}``: the picture that an insert at the end of ``run`` goes in front of.
+
+    The first picture of a later run where ``run`` ends. A read segment that
+    ends inside its run (a picture of the run between two of its texts) also
+    puts the insert in front of the run's own picture there, right after the
+    segment's text.
+    """
+    end = run._range[1]
+    record, later = _place(run, run._range)
+    candidates = ([record] if record is not None and end < record.range[1] else []) + later
+    for candidate in candidates:
+        for picture_id, offset in candidate.pictures:
+            if offset == end:
+                return {"beforeImageId": picture_id}
+    return None

{athena_python_docx-0.22.0 → athena_python_docx-0.24.0}/docx/commands.py

@@ -109,12 +109,19 @@ class CreateTable(Command):
     client_node_id: str | None = None
 
 
+# Run identity of a run-end insert (``Run.add_text`` / ``add_tab`` /
+# ``add_break`` / ``add_picture``, ``Run.text`` on an empty run):
+# ``{"beforeImageId": <picture id>}``, the first picture that a later run
+# holds at the same offset (see ``docx._run_order``). The server puts the
+# content in front of it. ``None`` (not sent): after the pictures there.
+# ``Insert``, ``InsertTab`` and ``InsertLineBreak`` carry it too.
 @dataclass
 class CreateImage(Command):
     src: str
     size: dict[str, Any]
     at: dict[str, Any]
     client_node_id: str | None = None
+    run: dict[str, Any] | None = None
 
 
 @dataclass
@@ -142,6 +149,7 @@ class Insert(Command):
     inherit_marks: bool | None = None
     placement: str | None = None
     content: dict[str, Any] | None = None
+    run: dict[str, Any] | None = None
 
 
 @dataclass
@@ -181,12 +189,14 @@ class Replace(Command):
 class InsertLineBreak(Command):
     block_id: str
     offset: int
+    run: dict[str, Any] | None = None
 
 
 @dataclass
 class InsertTab(Command):
     block_id: str
     offset: int
+    run: dict[str, Any] | None = None
 
 
 @dataclass
@@ -490,10 +500,15 @@ class SetImageSize(Command):
 class SetImageAltText(Command):
     """Set alt-text on an inline image. Mirrors DOCX Studio's
     ``doc.images.setAltText``. Used by accessibility flows that need
-    a text alternative for screen readers."""
+    a text alternative for screen readers.
+
+    ``alt_text`` is Word's description (``wp:docPr/@descr``). ``title`` is
+    Word's title (``wp:docPr/@title``); ``None`` leaves it unchanged, and an
+    older docx-studio ignores the field."""
 
     image_id: str
     alt_text: str
+    title: str | None = None
 
 
 @dataclass
@@ -551,7 +566,9 @@ class GetNode(Command):
 
 @dataclass
 class ImagesList(Command):
-    pass
+    # ``False`` leaves out each picture's ``src`` (a data URI can be MBs); an
+    # older docx-studio ignores the field and sends ``src``.
+    include_src: bool | None = None
 
 
 @dataclass

{athena_python_docx-0.22.0 → athena_python_docx-0.24.0}/docx/shape.py

@@ -65,6 +65,19 @@ def _strip_data_uri(src: str) -> tuple[bytes, str | None]:
         return b"", mime
 
 
+def _picture_id_parts(node_id: str) -> tuple[str, str, str | None]:
+    """``(paraId, fingerprint, persisted id)`` of a picture id.
+
+    A picture id is ``<paraId>:<index>:<fingerprint>``, with a fourth part
+    ``:<persisted id>`` when the room stores one; an older docx-studio gives
+    only ``<paraId>`` or ``<paraId>:<index>``.
+    """
+    parts = node_id.split(":")
+    fingerprint = parts[2] if len(parts) > 2 else ""
+    persisted = parts[3] if len(parts) > 3 else None
+    return parts[0], fingerprint, persisted
+
+
 class InlineShape:
     """An inline image/shape in the document."""
 
@@ -177,15 +190,75 @@ class InlineShape:
     @alt_text.setter
     @athena_extension(issue="PR#1530", description="InlineShape.alt_text setter.")
     def alt_text(self, value: str | None) -> None:
+        text = "" if value is None else str(value)
+        if self._can_address(stacklevel=3):
+            self._send_alt_text(alt_text=text, title=None)
+            self._info["altText"] = text
+
+    def _can_address(self, *, stacklevel: int) -> bool:
+        """``False`` (with a warning) for a shape that has no id.
+
+        A listed picture on an older docx-studio, whose ``ImagesList`` sends
+        no ``nodeId``, cannot be addressed, and an empty ``imageId`` fails the
+        whole batch there. The setter then sends nothing and keeps the old
+        value, so the shape does not report a change that the document does
+        not have.
+        """
+        from docx.errors import DocxUnsupportedCommandWarning
+
+        if self._node_id:
+            return True
+        warnings.warn(
+            "InlineShape alt text / title / decorative was not set: this picture has "
+            "no id. Read the shape again from doc.inline_shapes after "
+            "docx-studio is updated.",
+            DocxUnsupportedCommandWarning,
+            stacklevel=stacklevel + 1,
+        )
+        return False
+
+    def _send_alt_text(self, *, alt_text: str, title: str | None) -> None:
         from docx.commands import SetImageAltText
 
-        text = "" if value is None else str(value)
         run_sync(
             self._session.send_command(
-                SetImageAltText(image_id=self._node_id, alt_text=text),
+                SetImageAltText(image_id=self._node_id, alt_text=alt_text, title=title),
             ),
         )
-        self._info["altText"] = text
+
+    def _stored_alt_text(self) -> str:
+        """The description that the document stores for this picture now.
+
+        Another shape for the same picture can change the description after
+        this shape read it. ``ImagesList`` gives the current value, without
+        the image data; the cached value is the fallback when the list does
+        not name the picture (an older docx-studio). The read flushes pending
+        commands first, so a client id is the real id after it.
+        """
+        rows = InlineShapes(session=self._session)._items(include_src=False)
+        node_id = self._node_id
+        para_id, fingerprint, persisted = _picture_id_parts(node_id)
+        same: list[dict] = []
+        for row in rows:
+            row_id = str(row.get("nodeId") or "")
+            if row_id == node_id:
+                same = [row]
+                break
+            row_para, row_fingerprint, row_persisted = _picture_id_parts(row_id)
+            # A persisted id names one picture, in any paragraph and position.
+            if persisted is not None and row_persisted is not None:
+                if row_persisted == persisted:
+                    same = [row]
+                    break
+                continue
+            # A room without persisted ids (an older editor removed them):
+            # the paragraph and the fingerprint, as the server does.
+            if row_para != para_id:
+                continue
+            if ":" not in node_id or (fingerprint and row_fingerprint == fingerprint):
+                same.append(row)
+        stored = same[0].get("altText") if len(same) == 1 else None
+        return stored if isinstance(stored, str) else self.alt_text
 
     @property
     @athena_extension(issue="PR#1530", description="InlineShape.title — image title.")
@@ -202,14 +275,15 @@ class InlineShape:
     @title.setter
     @athena_extension(issue="PR#1530", description="InlineShape.title setter.")
     def title(self, value: str | None) -> None:
-        from docx.commands import SetImageAltText
-
         text = "" if value is None else str(value)
-        run_sync(
-            self._session.send_command(
-                SetImageAltText(image_id=self._node_id, alt_text=text),
-            ),
-        )
+        if not self._can_address(stacklevel=3):
+            return
+        # The command always carries the description: an older docx-studio
+        # requires ``altText`` and ignores ``title``. Sending the stored
+        # description keeps it; before, the title text replaced it.
+        alt_text = self._stored_alt_text()
+        self._send_alt_text(alt_text=alt_text, title=text)
+        self._info["altText"] = alt_text
         self._info["title"] = text
 
     @property
@@ -228,6 +302,8 @@ class InlineShape:
     def decorative(self, value: bool) -> None:
         from docx.commands import SetImageDecorative
 
+        if not self._can_address(stacklevel=3):
+            return
         run_sync(
             self._session.send_command(
                 SetImageDecorative(image_id=self._node_id, decorative=bool(value)),
@@ -283,8 +359,9 @@ class InlineShapes:
     def __init__(self, *, session: "Session") -> None:
         self._session: "Session" = session
 
-    def _items(self) -> list[dict]:
-        info: object = run_sync(self._session.doc.images.list({}))
+    def _items(self, *, include_src: bool = True) -> list[dict]:
+        params: dict = {} if include_src else {"includeSrc": False}
+        info: object = run_sync(self._session.doc.images.list(params))
         if isinstance(info, dict):
             items: object = info.get("items") or info.get("images") or []
             if isinstance(items, list):

{athena_python_docx-0.22.0 → athena_python_docx-0.24.0}/docx/text/paragraph.py

@@ -7,6 +7,7 @@ from typing import TYPE_CHECKING, Any
 
 from docx._athena_extension import athena_extension
 from docx._batching import run_sync
+from docx._run_order import forget_paragraph, register_run
 
 if TYPE_CHECKING:
     from docx._references import AssetReference
@@ -431,6 +432,8 @@ 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)
+        # The runs of the paragraph are gone, as in python-docx.
+        forget_paragraph(self)
         # Content changed — drop the prefetched snapshot so a follow-up
         # ``.text`` / ``.runs`` read reflects the replacement.
         self._invalidate_node_info()
@@ -1232,6 +1235,12 @@ class Paragraph:
             in_cell=self._in_cell,
             cell_ooxml_address=self._cell_ooxml_address,
         )
+        # The paragraph's run order, so a run-end insert at an offset that two
+        # runs share goes to the right run (see ``docx._run_order``).
+        register_run(run_obj)
+        # A new empty run has no formatting of its own yet: its first text
+        # does not take the formatting of the run before it.
+        run_obj._fresh = not text_str
         if style is not None:
             style_id: str = (
                 style.style_id if isinstance(style, CharacterStyle) else style
@@ -1501,7 +1510,12 @@ class Paragraph:
         Pass either a serialized citation URL via ``citation_string`` /
         positional ``source`` string, or an ``AssetReference`` from
         ``docx._references`` plus an optional source ``anchor`` such as a
-        spreadsheet ``SheetRangeAnchor`` or a media ``TimeRangeAnchor``.
+        spreadsheet ``SheetRangeAnchor``, a media ``TimeRangeAnchor`` or an
+        image ``PixelRangeAnchor`` (a region in source image pixels). An
+        image citation that chat and Sheets reject raises ``ValueError``: an
+        excerpt with no region anchor, a page or text anchor, or a region
+        without numeric x, y, width and height. An excerpt beside a region
+        anchor is allowed; it names the span of this paragraph to highlight.
 
         A paragraph inside a table cell is citable too. ``cell.paragraphs[0]``
         stands for the whole cell, so the citation covers the text of the