athena-python-docx 0.35.0__tar.gz → 0.36.0__tar.gz

{athena_python_docx-0.35.0 → athena_python_docx-0.36.0}/AGENTS.md

@@ -121,6 +121,21 @@ pinned by focused tests and documented in
   `horz_dpi`, `width`, `scaled_dimensions`, …). A picture in a table cell or
   a header has no id to read its image by, so `.image` raises `ValueError`;
   an older docx-studio does not report pictures, so they are not runs there.
+  `Run.add_picture` puts the picture in that run, as python-docx appends the
+  `w:drawing` to its `w:r`: after what the run holds, and text `add_text`
+  adds goes after it. Against a docx-studio that reports
+  `capabilities.pictureRuns`, `CreateImage` carries `runEdge: "append"` (the
+  run's identity as `add_text` names it), the run's record holds the picture
+  (`pictureRun`), and the run reads as one run whose pictures stand at their
+  places in its text (`pictures`), so `iter_inner_content()` yields its text
+  and each `Drawing` in order (with Word's rendered page breaks where the read
+  places them among the pictures, `afterPictures`), a whole-run format takes
+  its pictures too, and `run.text = ...` takes every one of them out
+  (`wholeRun`). A picture's run (no text) formats its picture at once, named
+  by its identity (`laterRuns`), so `r = p.add_run(); r.bold = True;
+  r.add_picture(img)` writes the bold `w:rPr` beside the `w:drawing`. An older
+  docx-studio puts the picture in a run of its own (`tests/test_drawing_image.py`,
+  battery `ab_probe/picture_runs.py`).
 - **A run holding only a page or column break yields `""` from
   `Run.iter_inner_content()`,** as python-docx reads a `w:br` of type `page`
   or `column` as empty text; an empty run (a comment reference's) yields

{athena_python_docx-0.35.0 → athena_python_docx-0.36.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: athena-python-docx
-Version: 0.35.0
+Version: 0.36.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.35.0 → athena_python_docx-0.36.0}/docx/__init__.py

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

{athena_python_docx-0.35.0 → athena_python_docx-0.36.0}/docx/_proxy.py

@@ -1,11 +1,35 @@
 """python-docx's ``ElementProxy`` equality, for the SDK's proxies of the
 objects python-docx wraps in one: styles, the styles part, settings, a
-paragraph's or a style's paragraph format, a run's or a style's font."""
+paragraph's or a style's paragraph format, a run's or a style's font, tab
+stops and the latent styles."""
 
 from __future__ import annotations
 
 import weakref
-from typing import Any
+from collections.abc import Iterator
+from typing import Any, Generic, TypeVar
+
+_T = TypeVar("_T")
+
+
+class IdentityWeakSet(Generic[_T]):
+    """A set of objects held weakly, by identity: a ``weakref.WeakSet`` hashes
+    its members, and a proxy that compares by its element
+    (:class:`ElementProxyEquality`) is not hashable, as in python-docx."""
+
+    __slots__ = ("_members",)
+
+    def __init__(self) -> None:
+        self._members: "weakref.WeakValueDictionary[int, _T]" = weakref.WeakValueDictionary()
+
+    def add(self, item: _T) -> None:
+        self._members[id(item)] = item
+
+    def __iter__(self) -> Iterator[_T]:
+        return iter(list(self._members.values()))
+
+    def __len__(self) -> int:
+        return len(self._members)
 
 
 class ElementProxyEquality:

{athena_python_docx-0.35.0 → athena_python_docx-0.36.0}/docx/commands.py

@@ -140,6 +140,10 @@ class CreateImage(Command):
     at: dict[str, Any]
     client_node_id: str | None = None
     run: dict[str, Any] | None = None
+    # ``"append"`` (``Run.add_picture`` against a docx-studio that reports
+    # ``capabilities.pictureRuns``): the picture ends the run that ends at the
+    # anchor's offset, in that run's ``w:r``, as python-docx appends it.
+    run_edge: str | None = None
 
 
 @dataclass

{athena_python_docx-0.35.0 → athena_python_docx-0.36.0}/docx/oxml/__init__.py

@@ -92,6 +92,7 @@ _XML_ELEMENT_ATTRS: frozenset[str] = frozenset(
         "_tc",         # _Cell._tc
         "_tbl",        # Table._tbl
         "_tr",         # _Row._tr
+        "_t",          # _Text._t (the ``w:t`` Run.add_text added)
         "element",     # Run.element / Paragraph.element / Document.element
         "_element",    # private alias used by some python-docx forks
     },

{athena_python_docx-0.35.0 → athena_python_docx-0.36.0}/docx/styles/latent.py

@@ -23,6 +23,7 @@ import warnings
 import weakref
 from typing import TYPE_CHECKING, Any, Iterator
 
+from docx._proxy import ElementProxyEquality, IdentityWeakSet
 from docx.styles import BabelFish
 
 if TYPE_CHECKING:
@@ -52,12 +53,12 @@ _XML_INCOMPATIBLE_MESSAGE = (
 # Session -> every live ``_LatentStyle``, read or added: deleting one moves the
 # others of its name after it up one place (:func:`_removed`), as python-docx's
 # are elements a deletion elsewhere does not move. The sets hold them weakly.
-_LIVE: "weakref.WeakKeyDictionary[Any, weakref.WeakSet[_LatentStyle]]" = weakref.WeakKeyDictionary()
+_LIVE: "weakref.WeakKeyDictionary[Any, IdentityWeakSet[_LatentStyle]]" = weakref.WeakKeyDictionary()
 
 
 def _track(latent_style: "_LatentStyle") -> None:
     try:
-        _LIVE.setdefault(latent_style._session, weakref.WeakSet()).add(latent_style)
+        _LIVE.setdefault(latent_style._session, IdentityWeakSet()).add(latent_style)
     except TypeError:  # no session, or one that takes no weak reference
         return
 
@@ -67,6 +68,7 @@ def _removed(deleted: "_LatentStyle", name: Any) -> None:
     that name after it move up one place, and another object of the same
     exception is out of the document, writing nothing to it, as python-docx's
     removed element is."""
+    deleted._element = removed = object()
     try:
         live = _LIVE.get(deleted._session)
     except TypeError:
@@ -78,6 +80,7 @@ def _removed(deleted: "_LatentStyle", name: Any) -> None:
             continue
         if other._occurrence == deleted._occurrence:
             other._detached = True
+            other._element = removed
         elif other._occurrence > deleted._occurrence:
             other._occurrence -= 1
 
@@ -140,13 +143,17 @@ def _int(text: object) -> int | None:
         return None
 
 
-class LatentStyles:
+class LatentStyles(ElementProxyEquality):
     """The default behaviors for latent styles in this document, and the
     |_LatentStyle| objects that override them for a named latent style."""
 
     def __init__(self, *, session: "Session | None" = None) -> None:
         self._session: "Session | None" = session
 
+    def _proxy_element(self) -> tuple[object, ...]:
+        # python-docx's LatentStyles wraps the styles part's w:latentStyles.
+        return ("w:latentStyles", self._session)
+
     def _read(self, prop: str | None) -> dict[str, Any]:
         """The latent styles docx-studio reports; a read of ``prop`` from one
         that reports none warns (iterating, an empty collection, does not)."""
@@ -246,7 +253,7 @@ class LatentStyles:
         self._set_default("load_count", "count", None if value is None else int(value))
 
 
-class _LatentStyle:
+class _LatentStyle(ElementProxyEquality):
     """A ``w:lsdException``: display behaviors for a built-in style the
     document does not define yet, overriding the |LatentStyles| defaults."""
 
@@ -260,8 +267,18 @@ class _LatentStyle:
         #: Removed through another object of the same exception: like
         #: python-docx's element out of the part, it writes nothing to the document.
         self._detached = False
+        #: The exception it held once removed, which its other objects hold too.
+        self._element: object | None = None
         _track(self)
 
+    def _proxy_element(self) -> tuple[object, ...]:
+        # python-docx's _LatentStyle wraps its w:lsdException: the exception
+        # of its name at its place among them, or, removed, that exception, as
+        # its other objects are.
+        if self._detached or self._exception is None:
+            return ("w:lsdException", self._element if self._element is not None else id(self))
+        return ("w:lsdException", self._session, self._exception.get("name"), self._occurrence)
+
     def _target(self) -> dict[str, Any]:
         """The exception's address in ``EditLatentStyles``."""
         name = self._exception.get("name")

{athena_python_docx-0.35.0 → athena_python_docx-0.36.0}/docx/styles/style.py

@@ -35,6 +35,7 @@ from docx._batching import run_sync
 from docx._buffer import writes_unapplied
 from docx._proxy import (
     ElementProxyEquality,
+    IdentityWeakSet,
     style_definition,
     style_deleted,
     style_element,
@@ -910,11 +911,13 @@ class _StyleParagraphFormat(ElementProxyEquality):
 
 _TAB_STOPS_REASON = "does not write this style's tab stops: it predates styleTabStops, or does not write the style's formatting"
 
-# Session -> style id -> every live tab stop of that style, read or added: a
-# write moves the others to their new places in the style's list
-# (``_StyleTabStops._moved``), as python-docx's are elements that a change to
-# another does not move. The sets hold them weakly.
-_LIVE_TAB_STOPS: "weakref.WeakKeyDictionary[Any, dict[str, weakref.WeakSet[_StyleTabStop]]]" = (
+# Session -> style definition (``style_element``) -> every live tab stop of
+# that style, read or added: a write moves the others to their new places in
+# the style's list (``_StyleTabStops._moved``), as python-docx's are elements
+# that a change to another does not move. By the definition, not the id: a
+# renamed style keeps its stops, and one made after a style of its id was
+# deleted holds none of the deleted one's. The sets hold them weakly.
+_LIVE_TAB_STOPS: "weakref.WeakKeyDictionary[Any, dict[tuple[object, ...], IdentityWeakSet[_StyleTabStop]]]" = (
     weakref.WeakKeyDictionary()
 )
 
@@ -926,7 +929,7 @@ _REMOVED = "removed"
 _CLEARED = "cleared"
 
 
-class _StyleTabStop:
+class _StyleTabStop(ElementProxyEquality):
     """One tab stop of a style's ``w:tabs``, as python-docx's ``TabStop``
     reads it: ``position`` a ``Length``, ``alignment`` a
     ``WD_TAB_ALIGNMENT`` (a cleared tab's is ``CLEAR``), ``leader`` a
@@ -938,7 +941,7 @@ class _StyleTabStop:
     to another tab stop moves, as python-docx's ``w:tab`` element stays itself;
     one the style no longer holds writes nothing, as a removed element."""
 
-    __slots__ = ("__weakref__", "_detached", "_entry", "_index", "_owner")
+    __slots__ = ("__weakref__", "_detached", "_element", "_entry", "_index", "_owner")
 
     def __init__(
         self, entry: dict[str, Any], owner: "_StyleTabStops | None" = None, index: int | None = None
@@ -947,9 +950,19 @@ class _StyleTabStop:
         self._owner: "_StyleTabStops | None" = owner
         self._index: int | None = index
         self._detached: str | None = None
+        # The w:tab it held once out of the style, which its other objects hold too.
+        self._element: object | None = None
         if owner is not None and index is not None:
             owner._track(self)
 
+    def _proxy_element(self) -> tuple[object, ...]:
+        # python-docx's TabStop wraps its w:tab: a stop at its place in the
+        # style's list is that w:tab; one out of the style is the w:tab taken
+        # out, as are its other objects.
+        if self._owner is not None and self._index is not None and not self._detached:
+            return ("w:tab", *style_element(self._owner._style), self._index)
+        return ("w:tab", self._element if self._element is not None else id(self))
+
     def _wire(self) -> dict[str, Any]:
         """This tab stop as ``SetStyleFormatting``'s ``tabStops`` takes it."""
         leader = self._entry.get("leader")
@@ -1010,7 +1023,7 @@ class _StyleTabStop:
         )
 
 
-class _StyleTabStops:
+class _StyleTabStops(ElementProxyEquality):
     """``ParagraphStyle.paragraph_format.tab_stops``: python-docx's
     ``TabStops`` over the style's own ``w:tabs``.
 
@@ -1030,6 +1043,10 @@ class _StyleTabStops:
     def __init__(self, style: "BaseStyle") -> None:
         self._style: "BaseStyle" = style
 
+    def _proxy_element(self) -> tuple[object, ...]:
+        # python-docx's TabStops wraps the style's w:pPr (its paragraph format wraps the w:style).
+        return ("w:pPr", *style_element(self._style))
+
     def _stashed(self) -> list:
         kept = self._style._overrides
         if "parfmt.tab_stops" not in kept:
@@ -1052,7 +1069,7 @@ class _StyleTabStops:
             styles = _LIVE_TAB_STOPS.setdefault(self._style._session, {})
         except TypeError:  # no session, or one that takes no weak reference
             return
-        styles.setdefault(self._style.style_id, weakref.WeakSet()).add(stop)
+        styles.setdefault(style_element(self._style), IdentityWeakSet()).add(stop)
 
     def _moved(
         self,
@@ -1066,15 +1083,17 @@ class _StyleTabStops:
         new place) gives one, or out of the style (``why``) where ``place``
         gives none."""
         try:
-            live = (_LIVE_TAB_STOPS.get(self._style._session) or {}).get(self._style.style_id)
+            live = (_LIVE_TAB_STOPS.get(self._style._session) or {}).get(style_element(self._style))
         except TypeError:
             return
+        gone: dict[int, object] = {}
         for stop in list(live or ()):
             if stop._detached or stop._index is None:
                 continue
             new = place(stop._index)
             if new is None:
                 stop._detached = why
+                stop._element = gone.setdefault(stop._index, object())
                 continue
             stop._index = new
             if entries and new in entries:

{athena_python_docx-0.35.0 → athena_python_docx-0.36.0}/docx/table.py

@@ -321,6 +321,7 @@ if TYPE_CHECKING:
         WD_TABLE_ALIGNMENT,
         WD_TABLE_DIRECTION,
     )
+    from docx.enum.text import WD_PARAGRAPH_ALIGNMENT
     from docx.styles.style import ParagraphStyle, _TableStyle
     from docx.text.paragraph import Paragraph
 
@@ -1224,14 +1225,17 @@ class Table:
         run_sync(self._session.doc.tables.set_style(params))
 
     @property
-    def alignment(self) -> "WD_TABLE_ALIGNMENT | None":
-        from docx.enum.table import WD_TABLE_ALIGNMENT
+    def alignment(self) -> "WD_PARAGRAPH_ALIGNMENT | None":
+        """The table's ``w:jc``, as python-docx 1.2.0 reads it: through the
+        paragraph ``CT_Jc``, so a member of ``WD_PARAGRAPH_ALIGNMENT``, which
+        compares equal to the ``WD_TABLE_ALIGNMENT`` member of its value."""
+        from docx.enum.text import WD_PARAGRAPH_ALIGNMENT
 
         info: object = run_sync(
             self._session.doc.tables.get_properties({"nodeId": self._fresh_node_id()}),
         )
         if isinstance(info, dict):
-            return WD_TABLE_ALIGNMENT.from_docx_studio(info.get("alignment"))
+            return WD_PARAGRAPH_ALIGNMENT.from_docx_studio(info.get("alignment"))
         return None
 
     @alignment.setter

{athena_python_docx-0.35.0 → athena_python_docx-0.36.0}/docx/text/paragraph.py

@@ -245,9 +245,15 @@ def _node_text(session: "Session", node_id: str, *, final: bool = False) -> str:
 
 def _picture_run_data(inline: dict, drawing: dict) -> dict:
     """The run data of a picture's inline (``{drawing}``): its ``w:r`` holds the
-    picture and no text, and the rendered page breaks docx-studio reads in it,
-    which stand before its drawing (``renderedPageBreaks``)."""
-    data: dict = {"text": "", "drawing": drawing}
+    picture and no text, the rendered page breaks docx-studio reads in it,
+    which stand before its drawing (``renderedPageBreaks``), and the run's
+    formatting it reads (its ``w:rPr``, which python-docx reads beside the
+    ``w:drawing``)."""
+    from docx.text.run import _RUN_READ_KEYS
+
+    data: dict = {key: value for key, value in inline.items() if key in _RUN_READ_KEYS}
+    data["text"] = ""
+    data["drawing"] = drawing
     breaks: object = inline.get("renderedPageBreaks")
     if isinstance(breaks, list):
         data["renderedPageBreaks"] = breaks

{athena_python_docx-0.35.0 → athena_python_docx-0.36.0}/docx/text/run.py

@@ -463,6 +463,28 @@ class Run:
             return None
         return self._later_runs()
 
+    def _picture_run_identity(self) -> int | None:
+        """This run's identity (:meth:`_later_runs`) while it holds a picture
+        and no text (a picture's run, ``drawing``), which a whole-run
+        ``FormatApply`` of its collapsed range formats, untracked, on a
+        docx-studio that reports ``capabilities.pictureRuns``: python-docx
+        formats the run's ``w:r``, and docx-studio its picture. Else None."""
+        if not self._is_collapsed_range or tracking(self._session):
+            return None
+        drawing = self._inline_snapshot.get("drawing")
+        if not isinstance(drawing, dict) or drawing.get("legacy") is True:
+            return None
+        if not server_takes(self._session, "pictureRuns"):
+            return None
+        return self._later_runs()
+
+    def _empty_run_identity(self) -> int | None:
+        """The identity by which a whole-run ``FormatApply`` of this run's
+        collapsed range formats what it holds: a page or column break's
+        (:meth:`_break_run_identity`) or a picture's (:meth:`_picture_run_identity`)."""
+        identity = self._break_run_identity()
+        return identity if identity is not None else self._picture_run_identity()
+
     def _add_run_ref(self, command: dict) -> dict:
         """Add the run identity of an insert at the end of this run.
 
@@ -707,9 +729,10 @@ class Run:
         pending = getattr(self, "_pending_inline", None)
         if not pending:
             return
-        # An empty run that holds a page or column break: docx-studio formats
-        # the break's run, which it tells by the run's identity.
-        identity = self._break_run_identity()
+        # An empty run that holds a page or column break, or a picture:
+        # docx-studio formats the run's break or picture, which it tells by
+        # the run's identity.
+        identity = self._empty_run_identity()
         if self._is_collapsed_range and identity is None:
             return
         self._pending_inline = {}
@@ -724,7 +747,7 @@ class Run:
                     },
                 ),
             )
-            # Its break holds the formatting now, which what it takes next continues.
+            # Its break or picture holds the formatting now, which what it takes next continues.
             self._fresh = False
             return
         # An emptied run's kept formatting turns off each toggle it did not
@@ -827,6 +850,43 @@ class Run:
             yield Drawing(session=self._session, info=drawing)
             if not self._raw_text():
                 return
+        pictures = self._pictures()
+        if pictures:
+            from docx.drawing import Drawing
+
+            # A run that holds pictures beside its text (``run.add_picture``
+            # appends a ``w:drawing`` to the run): the text between them, each
+            # picture and each of Word's rendered page breaks, in order. Where
+            # a break and a picture stand at one place in the text, the read
+            # says how many of the run's pictures come before the break
+            # (``afterPictures``); without it the break comes first, as Word
+            # writes a page that opens with the picture.
+            raw = self._raw_text()
+            font = self._symbol_font() if _SYMBOL_CHARACTERS.search(raw) else None
+            items: list[tuple[int, float, dict, bool]] = [
+                (offset, index, info, True) for index, (offset, info) in enumerate(pictures)
+            ]
+            rendered = self._rendered_page_breaks()
+            for info in rendered:
+                offset = int(info.get("offset", 0) or 0)
+                after = info.get("afterPictures")
+                if not isinstance(after, int) or isinstance(after, bool):
+                    after = sum(1 for at, _ in pictures if at < offset)
+                items.append((offset, after - 0.5, info, False))
+            items.sort(key=lambda item: (item[0], item[1]))
+            cut = 0
+            for offset, _order, info, is_picture in items:
+                at = min(max(offset, cut), len(raw))
+                if _word_text(raw[cut:at], font):
+                    yield _word_text(raw[cut:at], font)
+                if not is_picture:
+                    yield RenderedPageBreak(paragraph=self._page_break_paragraph(), offset=self._range[0] + at, info=info)
+                elif info.get("legacy") is not True:
+                    yield Drawing(session=self._session, info=info)
+                cut = at
+            if _word_text(raw[cut:], font):
+                yield _word_text(raw[cut:], font)
+            return
         if _note_reference(self._inline_snapshot):
             return
         text = _without_ruby(self._raw_text(), self._inline_snapshot)
@@ -923,18 +983,18 @@ class Run:
             return
         self._fastpath_text = None  # type: ignore[attr-defined]
         self._inline_snapshot.pop("renderedPageBreaks", None)
-        drawing = self._inline_snapshot.get("drawing")
-        picture = drawing.get("imageId") if isinstance(drawing, dict) else None
-        if isinstance(picture, str) and picture:
-            # python-docx replaces all of the run's content, its picture too.
+        pictures: list[str] = self._picture_ids()
+        if pictures:
+            # python-docx replaces all of the run's content, its pictures too.
             old_range: tuple[int, int] = self._range
             tracked: bool = tracking(self._session)
-            run_sync(
-                self._session.doc.replace(
-                    {"target": self._text_range, "text": value, "removePictures": [picture]},
-                ),
-            )
+            replace: dict = {"target": self._text_range, "text": value, "removePictures": pictures}
+            if server_takes(self._session, "pictureRuns"):
+                # All of this run: its record then holds the new text alone.
+                replace["wholeRun"] = True
+            run_sync(self._session.doc.replace(replace))
             self._inline_snapshot.pop("drawing", None)
+            self._inline_snapshot.pop("pictures", None)
             if tracked:
                 self._note_tracked_replacement(old_range, value)
             else:
@@ -1029,8 +1089,11 @@ class Run:
         # any pending inline formatting now that there's text to mark.
         self._flush_pending_inline()
 
-    def add_text(self, text: str) -> "Run":
-        """python-docx: append text to the run. Returns a new Run for the added text."""
+    def add_text(self, text: str) -> "_Text":
+        """Append ``text`` to the run, as python-docx does: its tabs and line
+        breaks stay characters. Returns a |_Text| for the added text, as
+        python-docx returns one for the ``w:t`` it adds: it has no public
+        API."""
         check_xml_compatible(text)
         if not isinstance(text, str):
             raise TypeError(
@@ -1039,34 +1102,10 @@ class Run:
             )
         self._refuse_field_write("add_text")
         if self._check_cell_inner("add_text"):
-            # Return a stub Run with the same in_cell flag so chained
-            # ops on the result also short-circuit cleanly. Propagate
-            # the parent's cell_ooxml_address so any subsequent run-
-            # format setter (``.bold = True`` etc.) can stash to the
-            # right cell in ``_post_export_ops`` instead of dropping
-            # silently.
-            return Run(
-                session=self._session,
-                block_id=self._block_id,
-                range_=(self._range[1], self._range[1]),
-                paragraph=self._paragraph,
-                in_cell=True,
-                cell_ooxml_address=getattr(self, "_cell_ooxml_address", None),
-            )
+            return _Text(self)
         self._fastpath_text = None  # type: ignore[attr-defined]
-        new_range = self._append_text(text)
-        added = Run(
-            session=self._session,
-            block_id=self._block_id,
-            range_=new_range,
-            paragraph=self._paragraph,
-            in_cell=self._in_cell,
-            cell_ooxml_address=getattr(self, "_cell_ooxml_address", None),
-        )
-        # The added text is part of this run: when it grows, this run grows
-        # (also through a chain of returned runs).
-        added._owner_record = getattr(self, "_run_record", None) or getattr(self, "_owner_record", None)
-        return added
+        self._append_text(text)
+        return _Text(self)
 
     def _append_text(self, text: str) -> tuple[int, int]:
         """Insert ``text`` at the end of this run; return the new text's range."""
@@ -1440,12 +1479,57 @@ class Run:
         create: dict = {"src": data_uri, "size": {"width": w_px, "height": h_px}, "at": at}
         if at["kind"] == "selection":
             self._add_run_ref(create)
+            if server_takes(self._session, "pictureRuns"):
+                # python-docx appends the ``w:drawing`` to this run's ``w:r``.
+                self._mark_append(create)
         result: object = run_sync(self._session.doc.create.image(create))
         info: dict = _build_inline_shape_info(result, width=w_pt, height=h_pt)
         if at["kind"] == "selection" and info.get("nodeId"):
             note_picture(self, info["nodeId"], self._range[1], before=_before_image(create))
+            if create.get("runEdge") == "append":
+                self._hold_picture({"imageId": info["nodeId"]})
+                # The formatting set on the run while it was empty is its
+                # ``w:rPr``, which python-docx writes beside the picture.
+                self._flush_pending_inline()
         return InlineShape(session=self._session, info=info)
 
+    def _pictures(self) -> list[tuple[int, dict]]:
+        """The pictures this run holds beside its text (``pictures``, which a
+        docx-studio reporting ``capabilities.pictureRuns`` reads): each one's
+        place in the run's text, in characters, and its drawing, in order."""
+        held: object = self._inline_snapshot.get("pictures")
+        pictures: list[tuple[int, dict]] = []
+        for entry in held if isinstance(held, list) else []:
+            drawing: object = entry.get("drawing") if isinstance(entry, dict) else None
+            if not isinstance(drawing, dict):
+                continue
+            offset: object = entry.get("offset")
+            valid = isinstance(offset, int) and not isinstance(offset, bool)
+            pictures.append((offset if valid else 0, drawing))  # type: ignore[arg-type]
+        return pictures
+
+    def _picture_ids(self) -> list[str]:
+        """The id of each picture this run holds: a picture run's (``drawing``)
+        and those beside its text (``pictures``)."""
+        drawings = [self._inline_snapshot.get("drawing"), *(info for _, info in self._pictures())]
+        ids = [d.get("imageId") for d in drawings if isinstance(d, dict)]
+        return [i for i in ids if isinstance(i, str) and i]
+
+    def _hold_picture(self, drawing: dict) -> None:
+        """This run took the picture ``drawing`` at its end (``run.add_picture``),
+        as the next read gives it: a run of a picture alone as a picture's run
+        (``drawing``), else among its pictures (``pictures``) where its text ends."""
+        snapshot = self._inline_snapshot
+        held = self._pictures()
+        alone = snapshot.get("drawing")
+        if not held and not self._raw_text() and not isinstance(alone, dict):
+            snapshot["drawing"] = drawing
+            return
+        if isinstance(alone, dict):
+            held = [(0, snapshot.pop("drawing"))]
+        held.append((len(self._raw_text()), drawing))
+        snapshot["pictures"] = [{"offset": offset, "drawing": info} for offset, info in held]
+
     @athena_extension(
         issue=498,
         description="Run.add_field — generic Word field (PAGE, DATE, REF, SEQ, TOC, ...).",
@@ -1901,10 +1985,11 @@ class Run:
             )
             return
         self._note_inline_applied(kwargs)
-        identity = self._break_run_identity()
+        identity = self._empty_run_identity()
         if identity is not None:
-            # The run holds only a page or column break: python-docx formats its
-            # ``w:r``, and docx-studio its break, which it tells by the run's identity.
+            # The run holds only a page or column break, or a picture: python-docx
+            # formats its ``w:r``, and docx-studio its break or picture, which it
+            # tells by the run's identity.
             run_sync(
                 self._session.doc.format.apply(
                     {
@@ -1915,7 +2000,7 @@ class Run:
                     },
                 ),
             )
-            # Its break holds the formatting now, which what it takes next continues.
+            # Its break or picture holds the formatting now, which what it takes next continues.
             self._fresh = False
             return
         if self._is_collapsed_range:
@@ -2125,6 +2210,22 @@ class Run:
         return Font(self)
 
 
+class _Text:
+    """Proxy object wrapping ``<w:t>`` element: what ``Run.add_text``
+    returns, as python-docx returns one for the ``w:t`` it adds. It has no
+    public API; its element (``_t``) is not available here."""
+
+    def __init__(self, run: "Run") -> None:
+        super().__init__()
+        self._run = run
+
+    def __getattr__(self, name: str) -> Any:
+        from docx.oxml import guard_xml_attr
+
+        guard_xml_attr("_Text", name)
+        raise AttributeError(f"'_Text' object has no attribute {name!r}")
+
+
 class Font(ElementProxyEquality):
     """Font properties of a Run. Accessed via `run.font`; do not instantiate."""