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

{athena_python_docx-0.22.0 → athena_python_docx-0.23.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.23.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: athena-python-docx
-Version: 0.22.0
+Version: 0.23.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.23.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.23.0"
 
 from docx.api import Document
 from docx._buffer import discard_all, flush_all

{athena_python_docx-0.22.0 → athena_python_docx-0.23.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.22.0 → athena_python_docx-0.23.0}/docx/text/paragraph.py

@@ -1501,7 +1501,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

{athena_python_docx-0.22.0 → athena_python_docx-0.23.0}/pyproject.toml

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

{athena_python_docx-0.22.0 → athena_python_docx-0.23.0}/tests/test_citations.py

@@ -435,3 +435,186 @@ def test_cell_add_citation_validates_the_source_before_sending() -> None:
     with pytest.raises(ValueError, match="source or citation_string"):
         cell.add_citation()
     assert session.commands == []
+
+
+# ---------------------------------------------------------------------------
+# Image region citations
+# ---------------------------------------------------------------------------
+
+_IMAGE_REGION_URL = (
+    "/dashboard/spaces/?asset_ids=asset_chart&type=image"
+    "&anchor=pixel_range&x=355&y=120&width=100&height=565"
+)
+
+
+def test_paragraph_add_citation_cites_an_image_region_with_pixel_range_anchor() -> None:
+    from docx._references import AssetReference, PixelRangeAnchor
+    from docx.text.paragraph import Paragraph
+
+    session = _FakeSession()
+    paragraph = Paragraph(session=session, node_id="para_1", text_len=48)
+
+    citation_id = paragraph.add_citation(
+        AssetReference(id="asset_chart"),
+        anchor=PixelRangeAnchor(x=355, y=120, width=100, height=565),
+        display_value="57.8",
+    )
+
+    [cmd] = session.commands
+    assert isinstance(cmd, AddCitation)
+    assert cmd.to_dict() == {
+        "type": "AddCitation",
+        "destinationAnchor": {"type": "pm_node", "nodeId": "para_1"},
+        "sourceRef": {"referenced": "asset", "id": "asset_chart"},
+        "sourceAnchor": {"type": "pixel_range", "x": 355, "y": 120, "width": 100, "height": 565},
+        "citationId": citation_id,
+        "displayValue": "57.8",
+    }
+
+
+def test_image_region_citation_keeps_an_excerpt_for_the_cited_paragraph() -> None:
+    # Chat and Sheets accept an excerpt next to a region anchor; DOCX Studio
+    # keeps it on the record (the span to highlight) and out of the URL.
+    from docx._references import AssetReference, PixelRangeAnchor
+    from docx.text.paragraph import Paragraph
+
+    session = _FakeSession()
+    paragraph = Paragraph(session=session, node_id="para_1")
+
+    paragraph.add_citation(
+        AssetReference(id="asset_chart"),
+        anchor=PixelRangeAnchor(x=355, y=120, width=100, height=565),
+        excerpt="57.8",
+    )
+
+    [cmd] = session.commands
+    assert cmd.excerpt == "57.8"
+    assert cmd.source_anchor == {"type": "pixel_range", "x": 355, "y": 120, "width": 100, "height": 565}
+
+
+def test_paragraph_add_citation_accepts_an_image_region_citation_string() -> None:
+    from docx.text.paragraph import Paragraph
+
+    session = _FakeSession()
+    paragraph = Paragraph(session=session, node_id="para_1")
+
+    paragraph.add_citation(_IMAGE_REGION_URL, display_value="East bar")
+    paragraph.add_citation(citation_string=f"https://app.athenaintel.com{_IMAGE_REGION_URL}")
+
+    assert [cmd.citation_string for cmd in session.commands] == [
+        _IMAGE_REGION_URL,
+        f"https://app.athenaintel.com{_IMAGE_REGION_URL}",
+    ]
+    assert all(cmd.source_ref is None and cmd.source_anchor is None for cmd in session.commands)
+
+
+def test_cell_add_citation_cites_an_image_region() -> None:
+    from docx._references import AssetReference, PixelRangeAnchor
+    from docx.table import _Cell
+
+    session = _FakeSession()
+    cell = _Cell(table=_CellTableStub(session), row=1, col=1)  # type: ignore[arg-type]
+
+    cell.add_citation(
+        AssetReference(id="asset_chart"),
+        anchor=PixelRangeAnchor(x=700, y=332, width=460, height=64),
+    )
+
+    [cmd] = session.commands
+    assert cmd.destination_anchor == {"type": "pm_node", "nodeId": "tc:2:1:1"}
+    assert cmd.source_anchor == {"type": "pixel_range", "x": 700, "y": 332, "width": 460, "height": 64}
+
+
+@pytest.mark.parametrize(
+    ("citation_string", "message"),
+    [
+        (
+            "/dashboard/spaces/?asset_ids=asset_chart&type=image&excerpt=57.8",
+            "cannot use an excerpt",
+        ),
+        (
+            "https://app.athenaintel.com/dashboard/spaces/?asset_ids=asset_chart&type=image#:~:text=57.8",
+            "cannot use an excerpt",
+        ),
+        (
+            "/dashboard/spaces/?asset_ids=asset_chart&type=image&anchor=page&page=1",
+            "cannot use anchor=page",
+        ),
+        (
+            "/dashboard/spaces/?asset_ids=asset_chart&type=image&anchor=pixel_range&x=355&y=120&width=100",
+            "Missing: height",
+        ),
+        (
+            # A blank value is missing, as agora parses the query.
+            "/dashboard/spaces/?asset_ids=asset_chart&type=image&anchor=pixel_range&x=&y=120&width=100&height=565",
+            "Missing: x",
+        ),
+        (
+            "/dashboard/spaces/?asset_ids=asset_chart&type=image&anchor=pixel_range&x=oops&y=120&width=100&height=565",
+            "Not a number: x",
+        ),
+        (
+            "https://app.athenaintel.com/dashboard/spaces/?asset_ids=asset_chart&type=image"
+            "&anchor=rect&x=0.1&y=0.2&width=wide&height=0.4",
+            "Not a number: width",
+        ),
+    ],
+)
+def test_add_citation_rejects_the_image_citation_urls_chat_rejects(
+    citation_string: str, message: str
+) -> None:
+    from docx.text.paragraph import Paragraph
+
+    session = _FakeSession()
+    paragraph = Paragraph(session=session, node_id="para_1")
+
+    with pytest.raises(ValueError, match=message):
+        paragraph.add_citation(citation_string)
+    assert session.commands == []
+
+
+def test_add_citation_accepts_an_image_reference_without_a_region() -> None:
+    # The whole image, with no excerpt: chat accepts it too.
+    from docx.text.paragraph import Paragraph
+
+    session = _FakeSession()
+    paragraph = Paragraph(session=session, node_id="para_1")
+
+    paragraph.add_citation("/dashboard/spaces/?asset_ids=asset_chart&type=image")
+    # A blank excerpt is no excerpt, as agora parses the query.
+    paragraph.add_citation("/dashboard/spaces/?asset_ids=asset_chart&type=image&excerpt=")
+
+    assert [cmd.citation_string for cmd in session.commands] == [
+        "/dashboard/spaces/?asset_ids=asset_chart&type=image",
+        "/dashboard/spaces/?asset_ids=asset_chart&type=image&excerpt=",
+    ]
+
+
+def test_add_citation_rejects_a_typed_region_with_a_non_numeric_coordinate() -> None:
+    from docx._references import AssetReference, PixelRangeAnchor
+    from docx.text.paragraph import Paragraph
+
+    session = _FakeSession()
+    paragraph = Paragraph(session=session, node_id="para_1")
+
+    with pytest.raises(ValueError, match="Not a number: y"):
+        paragraph.add_citation(
+            AssetReference(id="asset_chart"),
+            anchor=PixelRangeAnchor(x=355, y="top", width=100, height=565),  # type: ignore[arg-type]
+        )
+    assert session.commands == []
+
+
+def test_add_citation_rejects_a_typed_image_source_without_a_region_anchor() -> None:
+    from docx._references import AssetMeta, AssetReference, PageAnchor
+    from docx.text.paragraph import Paragraph
+
+    session = _FakeSession()
+    paragraph = Paragraph(session=session, node_id="para_1")
+    image = AssetReference(id="asset_chart", meta=AssetMeta(asset_type="image"))
+
+    with pytest.raises(ValueError, match="cannot use anchor=page"):
+        paragraph.add_citation(image, anchor=PageAnchor(page=1))
+    with pytest.raises(ValueError, match="cannot use an excerpt"):
+        paragraph.add_citation(image, excerpt="57.8")
+    assert session.commands == []