athena-python-docx 0.31.0__tar.gz → 0.33.0__tar.gz

{athena_python_docx-0.31.0 → athena_python_docx-0.33.0}/AGENTS.md

@@ -107,6 +107,12 @@ 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.
+- **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
+  nothing. docx-studio's read marks such a run with `break`, and
+  `Run.add_break` marks the run it adds one to. Against an older docx-studio,
+  which sends no `break`, a re-read run yields nothing.
 - **`Styles.latent_styles`** (`docx.styles.latent.LatentStyles`) reads
   the document's `<w:latentStyles>` (defaults and each `w:lsdException`)
   from docx-studio's `Info` (`includeStyles` → `latentStyles`), as python-docx

{athena_python_docx-0.31.0 → athena_python_docx-0.33.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: athena-python-docx
-Version: 0.31.0
+Version: 0.33.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.31.0 → athena_python_docx-0.33.0}/docx/__init__.py

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

{athena_python_docx-0.31.0 → athena_python_docx-0.33.0}/docx/_run_order.py

@@ -332,6 +332,45 @@ def note_picture(run: "Run", picture_id: str, offset: int, *, before: str | None
     record.pictures.insert(index, (picture_id, offset))
 
 
+def read_stamp() -> int:
+    """The moment a read gives its runs (``Paragraph.runs``): a run ``add_run``
+    creates after it has a higher ``seq``."""
+    return next(_SEQ)
+
+
+def later_runs_at_end(run: "Run") -> int | None:
+    """How many runs after ``run`` end where it does, by which docx-studio
+    tells ``run`` from them (``run.laterRuns``) where the offset cannot: an
+    empty run ``add_run()`` made after it, or one of breaks alone, ends there
+    too.
+
+    For a run ``add_run`` created, the runs it created after it; for a run a
+    read gave (``Paragraph.runs``), the later runs of that read and the runs
+    ``add_run`` created since. Each where it ends now, not where it ended at
+    the read: a write through a run moves the live proxies (:func:`track_run`),
+    as clearing a run of text after a run of a break leaves an empty run that
+    ends where the break's run does. A read run holds the next run of its
+    read (``_next_read``), so the later ones stay live, and current, while it
+    is. None for a run proxy that is neither, which the SDK cannot tell from
+    the runs around it.
+    """
+    end = run._range[1]
+    records = _records_of(run)
+    own = getattr(run, "_run_record", None) or getattr(run, "_owner_record", None)
+    if own is not None and own in records:
+        return sum(1 for other in records[records.index(own) + 1 :] if other.range[1] == end)
+    read_seq = getattr(run, "_read_seq", None)
+    if read_seq is None:
+        return None
+    later = 0
+    following: Run | None = getattr(run, "_next_read", None)
+    while following is not None:
+        if following._range[1] == end:
+            later += 1
+        following = getattr(following, "_next_read", None)
+    return later + sum(1 for other in records if other.seq > read_seq and other.range[1] == end)
+
+
 def ends_last_at_its_end(run: "Run") -> bool:
     """True when no run ``add_run`` created after ``run`` ends where it does.
 

{athena_python_docx-0.31.0 → athena_python_docx-0.33.0}/docx/commands.py

@@ -223,6 +223,10 @@ class Replace(Command):
     # …``), whose own properties docx-studio keeps for the new text; an older
     # docx-studio ignores it.
     whole_run: bool | None = None
+    # An empty run's identity among the runs at its place (``{"laterRuns": n}``,
+    # as ``Insert.run``), sent to a docx-studio reporting
+    # ``capabilities.runIdentity``.
+    run: dict[str, Any] | None = None
 
 
 @dataclass
@@ -233,13 +237,17 @@ class InsertLineBreak(Command):
     # ``True`` gives the break the formatting of the run it ends
     # (``Run.add_break``); an older docx-studio ignores it.
     inherit_marks: bool | None = None
-    # ``"column"``: a column break (``Run.add_break(WD_BREAK.COLUMN)``), which
-    # docx-studio writes after the paragraph's content, outside its
-    # text-address space; an older docx-studio ignores it and inserts a line
-    # break.
+    # ``"column"``: a column break (``Run.add_break(WD_BREAK.COLUMN)``),
+    # outside the paragraph's text-address space: with ``inline``, at the end
+    # of the run, in it; otherwise after the paragraph's content. An older
+    # docx-studio ignores it and inserts a line break.
     break_type: str | None = None
     # As ``Insert.run_edge``.
     run_edge: str | None = None
+    # ``True`` with ``break_type="column"``: the break at the end of the run,
+    # in it, as python-docx writes it. Sent only to a docx-studio reporting
+    # ``capabilities.inlineColumnBreak``; an older one ignores it.
+    inline: bool | None = None
 
 
 @dataclass
@@ -261,6 +269,10 @@ class FormatApply(Command):
     # (``run.bold = True``), which docx-studio keeps apart with their new
     # formatting; an older docx-studio ignores it.
     whole_run: bool | None = None
+    # The identity of an empty run that holds a page or column break
+    # (``{"laterRuns": n}``, as ``Insert.run``): its breaks take the
+    # formatting. Sent to a docx-studio reporting ``capabilities.runIdentity``.
+    run: dict[str, Any] | None = None
 
 
 @dataclass
@@ -725,6 +737,10 @@ class Info(Command):
     # ``docProps/core.xml``. An older docx-studio ignores the field, which
     # tells the SDK it has no ``SetCoreProperties``.
     include_core_properties: bool | None = None
+    # ``True`` also returns ``settings``: ``evenAndOddHeaders``, the
+    # document's ``w:evenAndOddHeaders`` in ``word/settings.xml``. An older
+    # docx-studio ignores the field and sends none.
+    include_settings: bool | None = None
 
 
 @dataclass

{athena_python_docx-0.31.0 → athena_python_docx-0.33.0}/docx/drawing/__init__.py

@@ -29,9 +29,12 @@ class Drawing:
     def has_picture(self) -> bool:
         """True when `drawing` contains an embedded picture.
 
-        A drawing docx-studio reports in a run is always a picture.
+        As python-docx: False for a drawing whose graphic is not a picture (a
+        chart, a diagram, a group), which docx-studio reports with
+        ``hasPicture: false``. An older docx-studio reports none, and every
+        drawing it reports reads as a picture.
         """
-        return True
+        return self._info.get("hasPicture") is not False
 
     @property
     def image(self) -> "Image":
@@ -44,6 +47,8 @@ class Drawing:
         from docx.image.image import Image
         from docx.shape import _strip_data_uri
 
+        if not self.has_picture:
+            raise ValueError("drawing does not contain a picture")
         image_id = self._info.get("imageId")
         if not isinstance(image_id, str) or not image_id:
             raise ValueError("drawing image cannot be read: docx-studio reported no id for it")

{athena_python_docx-0.31.0 → athena_python_docx-0.33.0}/docx/settings.py

@@ -4,8 +4,9 @@ Most Word app settings are not surfaced by DOCX Studio, so this proxy is
 intentionally minimal. The fields that ARE exposed have one-to-one
 DOCX Studio semantics:
 
-  * ``odd_and_even_pages_header_footer`` — toggles the document-level
-    ``<w:evenAndOddHeaders/>`` flag via DOCX Studio 1.8.1's
+  * ``odd_and_even_pages_header_footer`` — reads the document-level
+    ``<w:evenAndOddHeaders/>`` flag from ``Info`` (``includeSettings``) and
+    toggles it via DOCX Studio 1.8.1's
     ``doc.sections.setOddEvenHeadersFooters`` (doc-level despite its
     namespace — see ``commands.SetSectionsOddEvenHeadersFooters``).
   * ``track_revisions`` — alias for :attr:`docx.document.Document.track_revisions`.
@@ -50,6 +51,15 @@ class Settings:
 
     @property
     def odd_and_even_pages_header_footer(self) -> bool:
+        """The document's ``w:evenAndOddHeaders`` in ``word/settings.xml``, as
+        python-docx reads it (False when absent or off). A docx-studio that
+        does not report it (``Info`` without ``settings``) gives the value this
+        proxy last set."""
+        info: object = run_sync(self._session.doc.info({"includeSettings": True}))
+        settings: object = info.get("settings") if isinstance(info, dict) else None
+        reported: object = settings.get("evenAndOddHeaders") if isinstance(settings, dict) else None
+        if isinstance(reported, bool):
+            return reported
         return self._odd_and_even_pages_header_footer
 
     @odd_and_even_pages_header_footer.setter

{athena_python_docx-0.31.0 → athena_python_docx-0.33.0}/docx/table.py

@@ -23,9 +23,11 @@ class PendingTableClearWarning(UserWarning):
     setter is asked to clear a property (``None`` assignment) that
     python-docx 1.x supports but DOCX Studio 1.8 has no clear-op for.
 
-    Covers: ``Table.alignment / direction / autofit``,
+    Covers: ``Table.alignment / autofit``,
     ``_Row.height / height_rule``, ``_Column.width``,
-    ``_Cell.width / vertical_alignment``. DOCX Studio's
+    ``_Cell.width / vertical_alignment``, and any ``Table.table_direction``
+    write to a docx-studio that does not report
+    ``capabilities.tableDirection`` (one that does writes None too). DOCX Studio's
     ``tables.set_layout`` / ``set_row_height`` / ``set_column_width``
     / ``set_cell_properties`` require explicit values — the wire
     can't represent the python-docx "revert to inherited" intent.
@@ -1241,36 +1243,48 @@ class Table:
         )
 
     @property
-    def direction(self) -> "WD_TABLE_DIRECTION | None":
-        from docx.enum.table import WD_TABLE_DIRECTION
-
+    def table_direction(self) -> "WD_TABLE_DIRECTION | None":
+        """The table's ``w:bidiVisual`` as python-docx 1.2.0 reads it: ``True``
+        (right to left), ``False`` (an explicit left to right) or None (none),
+        the ``bool`` python-docx returns behind its ``WD_TABLE_DIRECTION`` hint
+        (``True == WD_TABLE_DIRECTION.RTL``)."""
         info: object = run_sync(
             self._session.doc.tables.get_properties({"nodeId": self._fresh_node_id()}),
         )
-        if isinstance(info, dict):
-            return WD_TABLE_DIRECTION.from_docx_studio(info.get("direction"))
+        direction: object = info.get("direction") if isinstance(info, dict) else None
+        if direction == "rtl":
+            return cast("WD_TABLE_DIRECTION", True)
+        if direction == "ltr":
+            return cast("WD_TABLE_DIRECTION", False)
         return None
 
-    @direction.setter
-    def direction(self, value: "WD_TABLE_DIRECTION | int | str | None") -> None:
+    @table_direction.setter
+    def table_direction(self, value: "WD_TABLE_DIRECTION | int | str | None") -> None:
+        """As python-docx 1.2.0: RTL writes ``w:bidiVisual``, LTR writes
+        ``w:bidiVisual w:val="0"`` and None removes it. A docx-studio that does
+        not report ``capabilities.tableDirection`` drops the write, so the SDK
+        sends none there and warns (``PendingTableClearWarning``)."""
+        from docx._capabilities import server_takes
+        from docx.commands import NULL
         from docx.enum.table import WD_TABLE_DIRECTION
 
-        if value is None:
-            _warn_table_clear("direction")
+        # None goes on the wire as JSON null (``NULL``): a ``None`` field is left off it.
+        wire: object = NULL if value is None else WD_TABLE_DIRECTION._wire(value, "Table.table_direction")
+        if not server_takes(self._session, "tableDirection"):
+            warnings.warn(
+                "Table.table_direction was IGNORED: this DOCX Studio does not write a table's "
+                "direction (w:bidiVisual); the table keeps its previous direction.",
+                PendingTableClearWarning,
+                stacklevel=2,
+            )
             return
-        v: str = WD_TABLE_DIRECTION._wire(value, "Table.direction")
-        # DOCX Studio's setLayout takes ``tableDirection`` (not
-        # ``direction``). Same diagnostic as alignment above —
-        # setTableOptions silently swallowed the field.
+        # DOCX Studio's setLayout takes ``tableDirection`` (not ``direction``).
         run_sync(
             self._session.doc.tables.set_layout(
-                {"nodeId": self._fresh_node_id(), "tableDirection": v},
+                {"nodeId": self._fresh_node_id(), "tableDirection": wire},
             ),
         )
 
-    # python-docx aliases
-    table_direction = direction
-
     @property
     def autofit(self) -> bool:
         info: object = run_sync(

{athena_python_docx-0.31.0 → athena_python_docx-0.33.0}/docx/text/hyperlink.py

@@ -171,13 +171,16 @@ class Hyperlink:
 
     @property
     def contains_page_break(self) -> bool:
-        """True when the text of this hyperlink contains a hard page break.
+        """True when a rendered page break (a page Word's last layout began)
+        occurs in one of the hyperlink's runs, as python-docx 1.x reads it.
 
-        Mirrors python-docx 1.x. Detection uses DOCX Studio's ``\\f`` form-
-        feed sentinel inside any wrapped run's text (matching
-        ``Run.contains_page_break`` / ``Paragraph.contains_page_break``).
+        docx-studio reads them in the runs (``renderedPageBreaks``); the
+        ``\\f`` sentinel is an older docx-studio's mark.
         """
         for run_data, _ in self._segments:
+            breaks = run_data.get("renderedPageBreaks")
+            if isinstance(breaks, list) and any(isinstance(brk, dict) for brk in breaks):
+                return True
             text = run_data.get("text", "")
             if isinstance(text, str) and "\f" in text:
                 return True

{athena_python_docx-0.31.0 → athena_python_docx-0.33.0}/docx/text/pagebreak.py

@@ -53,15 +53,45 @@ def _warn_pagebreak_fragment(prop: str) -> None:
     )
 
 
+class _ParagraphFragment:
+    """The part of a paragraph before or after one of its rendered page breaks.
+
+    python-docx returns a ``Paragraph`` divorced from the document body: a
+    copy of the paragraph cut at the break, whose changes the document never
+    sees. This one reads what text extraction asks of it, its ``text`` and
+    ``style``, and changes nothing.
+    """
+
+    __slots__ = ("_paragraph", "_text")
+
+    def __init__(self, *, paragraph: "Paragraph", text: str) -> None:
+        self._paragraph = paragraph
+        self._text = text
+
+    @property
+    def text(self) -> str:
+        """The fragment's text, as ``Paragraph.text`` reads it."""
+        return self._text
+
+    @property
+    def style(self):
+        """The paragraph's style: the fragment keeps the paragraph's properties."""
+        return self._paragraph.style
+
+    def __repr__(self) -> str:
+        return f"<_ParagraphFragment text={self._text!r}>"
+
+
 class RenderedPageBreak:
-    """A hard page break inside a paragraph, as Word would render it.
+    """A page break Word's last layout put in a paragraph (``w:lastRenderedPageBreak``).
 
-    Constructed by :meth:`Paragraph.rendered_page_breaks` and yielded
-    by :meth:`Paragraph.iter_inner_content`; not intended for direct
-    user instantiation.
+    Constructed by :meth:`Paragraph.rendered_page_breaks` and yielded by
+    :meth:`Run.iter_inner_content`; not intended for direct user
+    instantiation. ``info`` is the break as docx-studio reads it in its run
+    (``renderedPageBreaks``): its fragments' text, or no fragment.
     """
 
-    __slots__ = ("_paragraph", "_offset", "_preceding_text")
+    __slots__ = ("_paragraph", "_offset", "_preceding_text", "_info")
 
     def __init__(
         self,
@@ -69,30 +99,47 @@ class RenderedPageBreak:
         paragraph: "Paragraph",
         offset: int = 0,
         preceding_text: str = "",
+        info: "dict | None" = None,
     ) -> None:
         self._paragraph: "Paragraph" = paragraph
         self._offset: int = offset
         self._preceding_text: str = preceding_text
+        self._info: "dict | None" = info
+
+    def _fragment(self, side: str) -> "_ParagraphFragment | None":
+        """python-docx's fragment on `side` (``preceding``/``following``) of this break."""
+        info = self._info
+        if info is None:
+            _warn_pagebreak_fragment(f"{side}_paragraph_fragment")
+            return None
+        if side not in info:
+            raise ValueError("only defined on first rendered page-break in paragraph")
+        text = info[side]
+        return (
+            None if text is None else _ParagraphFragment(paragraph=self._paragraph, text=str(text))
+        )
 
     # ---- python-docx canonical surface ----
     @property
-    def preceding_paragraph_fragment(self) -> "Paragraph | None":
-        """The portion of the paragraph that flowed onto the page
-        *before* the break.
+    def preceding_paragraph_fragment(self) -> "_ParagraphFragment | None":
+        """The part of the paragraph before this break, as a paragraph.
 
-        DOCX Studio's flat model doesn't preserve mid-paragraph fragments;
-        returns ``None``. Use :attr:`preceding_paragraph_text` for the
-        plain-text equivalent or the parent paragraph for full text.
+        None when no content precedes it (the break precedes all of the
+        paragraph's content). A break in a hyperlink puts the whole hyperlink
+        in this fragment. Raises ``ValueError`` for a break that is not the
+        paragraph's first, as python-docx does.
         """
-        _warn_pagebreak_fragment("preceding_paragraph_fragment")
-        return None
+        return self._fragment("preceding")
 
     @property
-    def following_paragraph_fragment(self) -> "Paragraph | None":
-        """The portion of the paragraph that flowed onto the page
-        *after* the break. See :attr:`preceding_paragraph_fragment`."""
-        _warn_pagebreak_fragment("following_paragraph_fragment")
-        return None
+    def following_paragraph_fragment(self) -> "_ParagraphFragment | None":
+        """The part of the paragraph after this break, as a paragraph.
+
+        None when no content follows it. A break in a hyperlink leaves the
+        whole hyperlink out of this fragment. Raises ``ValueError`` for a
+        break that is not the paragraph's first, as python-docx does.
+        """
+        return self._fragment("following")
 
     # ---- athena-specific extensions (kept for compat) ----
     @property

{athena_python_docx-0.31.0 → athena_python_docx-0.33.0}/docx/text/paragraph.py

@@ -9,7 +9,7 @@ from typing import TYPE_CHECKING, Any
 from docx._athena_extension import athena_extension
 from docx._batching import run_sync
 from docx._buffer import writes_unapplied
-from docx._run_order import forget_paragraph, register_run
+from docx._run_order import forget_paragraph, read_stamp, register_run
 from docx._tracked import tracking
 
 #: The session attribute ``Paragraph.delete`` bumps, after which every
@@ -242,6 +242,30 @@ def _node_text(session: "Session", node_id: str, *, final: bool = False) -> str:
     return _extract_text(info, final=final)
 
 
+def _rendered_page_break_reads(info: object) -> "list[tuple[dict, int]]":
+    """Each rendered page break docx-studio reads in the runs of the paragraph
+    whose node info is `info` (``renderedPageBreaks``), its links' included, in
+    order, with its offset in the paragraph's text-address space."""
+    if not isinstance(info, dict):
+        return []
+    node: object = info.get("node")
+    block: object = (node.get("paragraph") or node.get("heading")) if isinstance(node, dict) else None
+    inlines: object = block.get("inlines") if isinstance(block, dict) else None
+    reads: list[tuple[dict, int]] = []
+    offset = 0
+    for inline in inlines if isinstance(inlines, list) else []:
+        run: object = inline.get("run") if isinstance(inline, dict) else None
+        if not isinstance(run, dict):
+            continue
+        breaks: object = run.get("renderedPageBreaks")
+        for brk in breaks if isinstance(breaks, list) else []:
+            if isinstance(brk, dict):
+                reads.append((brk, offset + int(brk.get("offset", 0) or 0)))
+        text: object = run.get("text")
+        offset += len(text) if isinstance(text, str) else 0
+    return reads
+
+
 def _extract_text(info: object, *, final: bool = False) -> str:
     """Concatenate the text content of a paragraph, mirroring
     python-docx ``Paragraph.text`` semantics:
@@ -818,6 +842,13 @@ class Paragraph:
         # cache for free (avoids a follow-up ``get_node_by_id`` if the
         # caller does ``p.runs[...]; p.add_run(...)``).
         self._text_len = offset
+        # Each run holds the next one of this read: docx-studio tells it from
+        # the later ones that end where it does when content goes to it, by
+        # where they end then (``docx._run_order.later_runs_at_end``).
+        stamp = read_stamp()
+        for index, run_obj in enumerate(runs):
+            run_obj._next_read = runs[index + 1] if index + 1 < len(runs) else None
+            run_obj._read_seq = stamp
         return runs
 
     @property
@@ -1122,22 +1153,28 @@ class Paragraph:
 
     @property
     def contains_page_break(self) -> bool:
-        """python-docx 1.x: True if the paragraph contains a hard page break."""
-        return "\f" in self.text
+        """python-docx 1.x: True when a rendered page break (a page Word's last
+        layout began) occurs in one of the paragraph's runs or its links' runs."""
+        info = self._node_info()
+        return bool(_rendered_page_break_reads(info)) or "\f" in _extract_text(info, final=True)
 
     @property
     def rendered_page_breaks(self) -> "list[RenderedPageBreak]":
-        """Return a list of :class:`RenderedPageBreak` proxies for each
-        hard page break in this paragraph.
-
-        python-docx 1.x exposes this for inspecting Word's rendered
-        page-break positions inside a paragraph. We surface a minimal
-        proxy with a ``preceding_paragraph_text`` property so the
-        common ``len(p.rendered_page_breaks)`` pattern works. The
-        underlying break is detected via the ``\\f`` sentinel in the
-        paragraph text.
+        """python-docx 1.x: a :class:`RenderedPageBreak` for each page Word's
+        last layout began in the paragraph's runs and its links' runs
+        (``w:lastRenderedPageBreak``), in document order.
+
+        Each reads python-docx's fragments: the part of the paragraph before
+        and after the break (``preceding_paragraph_fragment``,
+        ``following_paragraph_fragment``), defined on the first break only.
+        A paragraph from an older docx-studio marks its breaks with the
+        ``\\f`` sentinel in its text instead.
         """
-        text = _extract_text(self._node_info())
+        node_info = self._node_info()
+        reads = _rendered_page_break_reads(node_info)
+        if reads:
+            return [RenderedPageBreak(paragraph=self, offset=offset, info=info) for info, offset in reads]
+        text = _extract_text(node_info)
         if "\f" not in text:
             return []
         out: list[RenderedPageBreak] = []