athena-python-docx 0.9.0__tar.gz → 0.10.1__tar.gz

{athena_python_docx-0.9.0 → athena_python_docx-0.10.1}/CLAUDE.md

@@ -81,20 +81,69 @@ remaining work* for the exact wire-op shape needed to unblock each.
 These differ from stock python-docx because the SDK is asset-backed,
 not file-backed. Each is documented in the relevant docstring.
 
-- **`Document.create(name=, base_url=, api_key=, parent_folder_id=, workspace_id=)`**
+- **Built-in table style friendly names resolve to OOXML styleIds.**
+  Word's ``styles.xml`` ships built-in table styles whose styleIds
+  (``LightGrid-Accent1``, ``MediumShading1-Accent2``, …) differ from
+  their display names (``"Light Grid Accent 1"``, …). Stock
+  python-docx resolves the friendly form against the loaded
+  document's styles collection at write time. We can't read
+  ``styles.xml`` over HTTP, so ``Document.add_table(style=...)`` /
+  ``Table.style`` setter consult an in-process map
+  (``docx._table_styles.BUILTIN_TABLE_STYLE_IDS``) covering every
+  Word 2007 and Word 2013+ built-in table style (204 entries) before
+  the value reaches ``<w:tblStyle w:val="..."/>``. Without this
+  mapping Word can't resolve the friendly name in ``styles.xml``
+  and silently falls back to ``Normal Table`` (no borders, no
+  header fill, no banding). Custom user-defined style names pass
+  through unchanged. Whether Word actually renders a Word 2013+
+  style after resolution also depends on SuperDoc's exported
+  ``styles.xml`` containing the matching ``<w:style w:type="table">``
+  definition — at SuperDoc 1.8.1 the exported ``styles.xml`` only
+  carries the Word 2007 set, so Word 2013+ styleIds resolve in the
+  ``<w:tblStyle>`` element but still fall back to ``Normal Table``
+  until SuperDoc upstream ships an expanded ``styles.xml``.
+
+- **`Document.create(name=, base_url=, api_key=, parent_folder_id=, workspace_id=, docx=, agora_base_url=)`**
   classmethod. Stock python-docx returns a blank in-memory document
   for `Document(None)`; we can't fabricate a SuperDocument asset
   client-side, so net-new asset creation is a separate factory that
   hits `POST {base_url}/docs/empty`. The constructor positional-arg
   shape (`Document(asset_id)`) is preserved for parity.
+  - **`docx=path`** mirrors the upstream `Document(docx="template.docx")`
+    constructor kwarg: when provided, the local `.docx` is uploaded to
+    agora's `/api/super-docs/create-from-upload` and used as the seed
+    for the new SuperDocument. The bytes are mirrored to S3 server-side
+    so subsequent template-asset reuse is fast. Without `docx=`, the
+    default Athena template is applied as today.
+  - **`agora_base_url=`** is a transport-detail kwarg only required when
+    the SDK can't derive the agora host from `base_url` (or from
+    `$ATHENA_AGORA_BASE_URL`). The default substitution rule replaces
+    `docx-studio` with `agora` in the docx-studio host; explicit
+    `agora_base_url` is required for local development or unusual
+    deployment topologies.
+
+- **`Document.asset_id: str`** read-only property — the Athena asset
+  id this Document is bound to (`asset_<uuid>`). Agent-callable so
+  the typical pattern `doc = Document.create(...); print(doc.asset_id)`
+  works without reaching into `doc._session._asset_id`. Stock
+  python-docx has no analogue (it operates on local files), so this
+  is an Athena-only addition. Mirrors the parallel public accessors
+  on the other studios: `Workbook.workbook_id` (xlsx) and
+  `Presentation.deck_id` (pptx).
 
-- **`Document.save(path_or_stream=None)`** — argument is optional.
-  Stock python-docx requires it and `TypeError`s on no-arg, but in an
+- **`Document.save(path_or_stream=None)`** — argument is optional and,
+  when supplied, raises
+  :class:`docx.errors.LocalSaveTargetNotSupportedError`. Stock
+  python-docx requires it and `TypeError`s on no-arg, but in an
   asset-backed SDK there is no local file to write — writes are always
   in-place against the Y.Doc. Forcing the upstream signature broke
   every agent invocation that reflexively called `doc.save()` (a
-  near-universal Python pattern), so we accept it for parity-friendly
-  call sites and ignore the value at runtime.
+  near-universal Python pattern), so the no-arg form is supported.
+  When a path or stream IS supplied, the SDK cannot fulfill the
+  implied "write bytes to this target" contract, so the call raises
+  loudly rather than silently flushing — agents must use Olympus's
+  Export DOCX (which goes through the SuperDoc session that already
+  has the bytes) instead of expecting a local file.
 
 - **`Document.track_revisions: bool`** — when `True`, all subsequent
   mutations are recorded as tracked revisions instead of direct edits.

{athena_python_docx-0.9.0 → athena_python_docx-0.10.1}/PKG-INFO

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

{athena_python_docx-0.9.0 → athena_python_docx-0.10.1}/docx/__init__.py

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

athena_python_docx-0.10.1/docx/_http.py

@@ -0,0 +1,379 @@
+"""HTTP bootstrap for Document.create().
+
+The SDK's primary transport is y-websocket via Superdoc; this module is
+the *only* HTTP client in the package. It exists solely so that
+``Document.create()`` can hit ``POST /docs/empty`` on docx-studio to
+provision a new SuperDocument asset and receive a collab bundle to open
+the document with.
+
+We use ``urllib`` from stdlib to avoid pulling ``httpx`` / ``requests``
+into the runtime — this code runs in Daytona sandboxes where every MB
+matters, and the existing SDK already keeps its dep tree tight.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+from typing import TypedDict
+
+from docx.errors import (
+    AuthenticationError,
+    DocxError,
+    SessionError,
+)
+
+
+class _CollabBundle(TypedDict):
+    """The collab credentials returned alongside a freshly-created asset.
+
+    Note: env-var-shape (matches what ``Session`` reads), even though
+    the wire format from docx-studio uses different key names. The
+    keys are renamed at parse time.
+    """
+
+    SUPERDOC_COLLAB_TOKEN: str
+    KERYX_WS_URL: str
+    ATHENA_WORKSPACE_ID: str
+
+
+class CreateAssetResult(TypedDict):
+    """Parsed response from ``POST /docs/empty``."""
+
+    asset_id: str
+    name: str
+    workspace_id: str
+    collab: _CollabBundle
+
+
+_BASE_URL_ENV = "ATHENA_DOCX_BASE_URL"
+_API_KEY_ENV = "ATHENA_DOCX_API_KEY"  # noqa: S105
+_AGORA_BASE_URL_ENV = "ATHENA_AGORA_BASE_URL"
+
+
+def _derive_agora_base_url(docx_base_url: str) -> str | None:
+    """Best-effort derive an Agora base URL from a docx-studio base URL.
+
+    The Athena hosts follow a parallel ``<service>.<env>.athenaintel.com``
+    convention, so substituting ``docx-studio`` → ``agora`` lands on the
+    matching Agora service. Returns ``None`` when the substitution
+    doesn't apply (e.g. ``http://localhost:4100``), in which case the
+    caller must provide ``agora_base_url`` explicitly.
+    """
+    if "docx-studio" not in docx_base_url:
+        return None
+    return docx_base_url.replace("docx-studio", "agora")
+
+
+def create_empty_document(
+    *,
+    base_url: str | None = None,
+    api_key: str | None = None,
+    name: str | None = None,
+    parent_folder_id: str | None = None,
+    workspace_id: str | None = None,
+    timeout: float = 30.0,
+) -> CreateAssetResult:
+    """Call ``POST {base_url}/docs/empty`` and parse the response.
+
+    Args:
+        base_url: docx-studio API base, e.g. ``https://docx-studio.stg.athenaintel.com``.
+            Falls back to ``$ATHENA_DOCX_BASE_URL``.
+        api_key: Athena API key (PropelAuth user API key) or PropelAuth
+            access token. Sent as ``Authorization: Bearer <api_key>``.
+            Falls back to ``$ATHENA_DOCX_API_KEY``.
+        name: Optional display title.
+        parent_folder_id: Optional parent folder; defaults to workspace root.
+        workspace_id: Optional workspace UUID; defaults to caller's
+            current workspace.
+        timeout: Request timeout in seconds.
+
+    Returns:
+        Parsed response dict with the new asset_id and a collab bundle
+        ready to feed into ``Session(..., bundle=...)``.
+
+    Raises:
+        SessionError: missing base_url or unparseable response.
+        AuthenticationError: missing api_key, or the server returned 401/403.
+        DocxError: any other 4xx/5xx from the server.
+    """
+    resolved_base: str | None = base_url or os.environ.get(_BASE_URL_ENV)
+    resolved_key: str | None = api_key or os.environ.get(_API_KEY_ENV)
+
+    if not resolved_base:
+        raise SessionError(
+            f"Missing base_url and {_BASE_URL_ENV} env var. "
+            "Pass base_url= to Document.create() or set the env var.",
+        )
+    if not resolved_key:
+        raise AuthenticationError(
+            f"Missing api_key and {_API_KEY_ENV} env var. "
+            "Pass api_key= to Document.create() or set the env var.",
+        )
+
+    url: str = resolved_base.rstrip("/") + "/docs/empty"
+    body: dict[str, str] = {}
+    if name is not None:
+        body["name"] = name
+    if parent_folder_id is not None:
+        body["parentFolderId"] = parent_folder_id
+    if workspace_id is not None:
+        body["workspaceId"] = workspace_id
+
+    # Lazy import — _http is loaded lazily by Document.create(), so the
+    # package is fully initialized by the time we reach this code.
+    from docx import __version__
+
+    payload: bytes = json.dumps(body).encode("utf-8")
+    req = urllib.request.Request(  # noqa: S310
+        url,
+        data=payload,
+        method="POST",
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {resolved_key}",
+            "Accept": "application/json",
+            "User-Agent": f"athena-python-docx/{__version__}",
+        },
+    )
+
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310
+            raw: bytes = resp.read()
+    except urllib.error.HTTPError as e:
+        err_body: str = ""
+        try:
+            err_body = e.read().decode("utf-8", errors="replace")
+        except Exception:  # noqa: BLE001
+            pass
+        if e.code in (401, 403):
+            raise AuthenticationError(
+                f"docx-studio rejected the API key (HTTP {e.code}): {err_body}",
+            ) from e
+        raise DocxError(
+            f"docx-studio /docs/empty returned HTTP {e.code}: {err_body}",
+        ) from e
+    except urllib.error.URLError as e:
+        raise SessionError(
+            f"Unable to reach docx-studio at {url}: {e.reason}",
+        ) from e
+
+    try:
+        parsed: dict = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as e:
+        raise SessionError(
+            f"docx-studio returned non-JSON response: {raw[:200]!r}",
+        ) from e
+
+    asset_id_obj = parsed.get("assetId")
+    name_obj = parsed.get("name")
+    ws_obj = parsed.get("workspaceId")
+    collab_obj = parsed.get("collab")
+    if not (
+        isinstance(asset_id_obj, str)
+        and isinstance(name_obj, str)
+        and isinstance(ws_obj, str)
+        and isinstance(collab_obj, dict)
+    ):
+        raise SessionError(
+            f"docx-studio response is missing required fields: {parsed!r}",
+        )
+    token_obj = collab_obj.get("token")
+    ws_url_obj = collab_obj.get("wsUrl")
+    bundle_ws_obj = collab_obj.get("workspaceId")
+    if not (
+        isinstance(token_obj, str)
+        and isinstance(ws_url_obj, str)
+        and isinstance(bundle_ws_obj, str)
+    ):
+        raise SessionError(
+            f"docx-studio collab bundle is malformed: {collab_obj!r}",
+        )
+
+    return CreateAssetResult(
+        asset_id=asset_id_obj,
+        name=name_obj,
+        workspace_id=ws_obj,
+        collab=_CollabBundle(
+            SUPERDOC_COLLAB_TOKEN=token_obj,
+            KERYX_WS_URL=ws_url_obj,
+            ATHENA_WORKSPACE_ID=bundle_ws_obj,
+        ),
+    )
+
+
+class UploadAssetResult(TypedDict):
+    """Parsed response from agora's ``POST /api/super-docs/create-from-upload``."""
+
+    asset_id: str
+    name: str
+
+
+def upload_document(
+    *,
+    docx_path: str,
+    docx_base_url: str | None = None,
+    agora_base_url: str | None = None,
+    api_key: str | None = None,
+    name: str | None = None,
+    parent_folder_id: str | None = None,
+    timeout: float = 120.0,
+) -> UploadAssetResult:
+    """Upload a local ``.docx`` to agora and create a new SuperDocument asset.
+
+    The endpoint lives on agora (``POST /api/super-docs/create-from-upload``),
+    not docx-studio, because the upload + Y.Doc-seed path is implemented
+    server-side in agora. The SDK still talks to docx-studio for command
+    application; this function only handles the initial create.
+
+    Args:
+        docx_path: Filesystem path to the ``.docx`` to upload.
+        docx_base_url: docx-studio base URL — used as a fallback to derive
+            the agora URL when ``agora_base_url`` is not supplied. Falls
+            back to ``$ATHENA_DOCX_BASE_URL``.
+        agora_base_url: Explicit Agora base URL. Falls back to
+            ``$ATHENA_AGORA_BASE_URL`` and finally to a host substitution
+            of ``docx-studio`` → ``agora`` against ``docx_base_url``.
+        api_key: Athena API key. Falls back to ``$ATHENA_DOCX_API_KEY``.
+        name: Optional asset title (defaults to the file's stem).
+        parent_folder_id: Optional parent folder for the new asset.
+        timeout: Request timeout in seconds (uploads can be slow for big
+            decks/templates).
+
+    Returns:
+        Dict with the new asset_id and the resolved title.
+
+    Raises:
+        SessionError: missing base URLs / unreachable agora.
+        AuthenticationError: missing api_key, or 401/403 from server.
+        DocxError: any other 4xx/5xx, or a malformed response.
+    """
+    import io
+    import mimetypes
+    import os
+    import uuid
+
+    resolved_docx_base: str | None = docx_base_url or os.environ.get(_BASE_URL_ENV)
+    resolved_key: str | None = api_key or os.environ.get(_API_KEY_ENV)
+    resolved_agora_base: str | None = (
+        agora_base_url
+        or os.environ.get(_AGORA_BASE_URL_ENV)
+        or (_derive_agora_base_url(resolved_docx_base) if resolved_docx_base else None)
+    )
+
+    if not resolved_agora_base:
+        raise SessionError(
+            f"Missing agora_base_url, {_AGORA_BASE_URL_ENV}, and {_BASE_URL_ENV} "
+            "(or the docx-studio URL doesn't follow the docx-studio↔agora "
+            "host pattern). Pass agora_base_url= to Document.create() or set "
+            f"the {_AGORA_BASE_URL_ENV} env var.",
+        )
+    if not resolved_key:
+        raise AuthenticationError(
+            f"Missing api_key and {_API_KEY_ENV} env var. "
+            "Pass api_key= to Document.create() or set the env var.",
+        )
+
+    if not os.path.exists(docx_path):
+        raise SessionError(f"DOCX file not found: {docx_path}")
+    if not docx_path.lower().endswith(".docx"):
+        raise SessionError(
+            f"Only .docx files are accepted by the upload endpoint (got {docx_path})",
+        )
+
+    title = name
+    if title is None:
+        base = os.path.basename(docx_path)
+        title = base[:-5] if base.lower().endswith(".docx") else base
+
+    # Build the agora URL with query-string params (FastAPI binds non-body
+    # args from the query string for multipart routes).
+    from urllib.parse import urlencode
+
+    qs: dict[str, str] = {"is_template": "false", "title": title}
+    if parent_folder_id is not None:
+        qs["parent_folder_id"] = parent_folder_id
+
+    url: str = (
+        resolved_agora_base.rstrip("/")
+        + "/api/super-docs/create-from-upload?"
+        + urlencode(qs)
+    )
+
+    # Build a minimal multipart/form-data body without pulling in
+    # `requests` — keep the urllib-only dep profile.
+    with open(docx_path, "rb") as f:
+        file_bytes: bytes = f.read()
+    content_type: str = (
+        mimetypes.guess_type(docx_path)[0]
+        or "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+    )
+    boundary: str = f"----athenaDocxBoundary{uuid.uuid4().hex}"
+    filename = os.path.basename(docx_path)
+    body_parts: list[bytes] = []
+    body_parts.append(f"--{boundary}\r\n".encode("utf-8"))
+    body_parts.append(
+        (
+            'Content-Disposition: form-data; name="file"; '
+            f'filename="{filename}"\r\n'
+            f"Content-Type: {content_type}\r\n\r\n"
+        ).encode("utf-8"),
+    )
+    body_parts.append(file_bytes)
+    body_parts.append(f"\r\n--{boundary}--\r\n".encode("utf-8"))
+    body: bytes = b"".join(body_parts)
+
+    from docx import __version__
+
+    req = urllib.request.Request(  # noqa: S310
+        url,
+        data=body,
+        method="POST",
+        headers={
+            "Content-Type": f"multipart/form-data; boundary={boundary}",
+            "Authorization": f"Bearer {resolved_key}",
+            "Accept": "application/json",
+            "User-Agent": f"athena-python-docx/{__version__}",
+        },
+    )
+
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310
+            raw: bytes = resp.read()
+    except urllib.error.HTTPError as e:
+        err_body: str = ""
+        try:
+            err_body = e.read().decode("utf-8", errors="replace")
+        except Exception:  # noqa: BLE001
+            pass
+        if e.code in (401, 403):
+            raise AuthenticationError(
+                f"agora rejected the API key (HTTP {e.code}): {err_body}",
+            ) from e
+        raise DocxError(
+            f"agora /api/super-docs/create-from-upload returned HTTP {e.code}: {err_body}",
+        ) from e
+    except urllib.error.URLError as e:
+        raise SessionError(
+            f"Unable to reach agora at {url}: {e.reason}",
+        ) from e
+
+    # Avoid unused import warning when io isn't otherwise referenced.
+    _ = io
+    try:
+        parsed: dict = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as e:
+        raise SessionError(
+            f"agora returned non-JSON response: {raw[:200]!r}",
+        ) from e
+
+    asset_id_obj = parsed.get("id")
+    name_obj = parsed.get("title")
+    if not (isinstance(asset_id_obj, str) and isinstance(name_obj, str)):
+        raise SessionError(
+            f"agora response is missing required fields: {parsed!r}",
+        )
+
+    return UploadAssetResult(asset_id=asset_id_obj, name=name_obj)

{athena_python_docx-0.9.0 → athena_python_docx-0.10.1}/docx/_http_doc.py

@@ -30,6 +30,7 @@ format is now typed end-to-end either way.
 from __future__ import annotations
 
 import json
+import os
 from typing import Any
 
 import requests
@@ -106,6 +107,7 @@ from docx.commands import (
     TablesSetRowHeight,
     TablesSetStyle,
     TablesSetTableOptions,
+    TableSetCell,
     TrackChangesDecide,
     TrackChangesGet,
     TrackChangesList,
@@ -372,6 +374,9 @@ def _http_post_json(
         "Accept": "application/json",
         "User-Agent": _user_agent(),
     }
+    custom_attr = os.environ.get("ATHENA_DOCX_CUSTOM_ATTRIBUTIONS")
+    if custom_attr:
+        headers["X-Custom-Attributions"] = custom_attr
     try:
         resp = session.post(
             url,
@@ -647,6 +652,7 @@ _OP_TO_COMMAND: dict[str, type[Command]] = {
     "tables.set_cell_properties": TablesSetCellProperties,
     "tables.set_column_width": TablesSetColumnWidth,
     "tables.set_row_height": TablesSetRowHeight,
+    "tables.set_cell": TableSetCell,
     # Images (mutations)
     "images.set_size": SetImageSize,
     "images.set_alt_text": SetImageAltText,

athena_python_docx-0.10.1/docx/_table_styles.py

@@ -0,0 +1,92 @@
+"""Friendly-name → OOXML styleId resolution for Word's built-in table styles.
+
+Word stores built-in table styles in ``word/styles.xml`` with internal
+styleIds like ``LightGrid-Accent1`` and friendly display names like
+``"Light Grid Accent 1"``. python-docx accepts the friendly name and
+resolves it against the loaded document's styles collection at write
+time. Our SDK ships commands over HTTP and never sees ``styles.xml``,
+so we keep an in-process map and resolve the friendly form to the
+canonical styleId before the value reaches the
+``<w:tblStyle w:val="..."/>`` element in the exported ``.docx``.
+
+Without this resolution Word can't find the style definition in
+``styles.xml`` and silently falls back to ``Normal Table`` — i.e.
+no borders, no header fill, no banding.
+"""
+
+from __future__ import annotations
+
+
+def _build_builtin_table_style_map() -> dict[str, str]:
+    """Build the friendly-name → styleId map for all Word built-in table styles.
+
+    Mirrors every ``<w:lsdException w:name="...">`` table-style
+    declaration in Word's default ``styles.xml`` for Word 2007 and
+    Word 2013+. Pattern: friendly names use spaces; styleIds collapse
+    spaces in the base and join the optional ``Accent N`` suffix with
+    a hyphen.
+    """
+    table: dict[str, str] = {
+        "Normal Table": "TableNormal",
+        "Table Grid": "TableGrid",
+        # Word 2013+ added a single un-numbered "Grid Table Light"
+        # alongside the numbered 1–7 series.
+        "Grid Table Light": "GridTableLight",
+    }
+    # Word 2007 era — 14 bases × (base + 6 accents) = 98 entries.
+    bases_2007: tuple[tuple[str, str], ...] = (
+        ("Light Shading", "LightShading"),
+        ("Light List", "LightList"),
+        ("Light Grid", "LightGrid"),
+        ("Medium Shading 1", "MediumShading1"),
+        ("Medium Shading 2", "MediumShading2"),
+        ("Medium List 1", "MediumList1"),
+        ("Medium List 2", "MediumList2"),
+        ("Medium Grid 1", "MediumGrid1"),
+        ("Medium Grid 2", "MediumGrid2"),
+        ("Medium Grid 3", "MediumGrid3"),
+        ("Dark List", "DarkList"),
+        ("Colorful Shading", "ColorfulShading"),
+        ("Colorful List", "ColorfulList"),
+        ("Colorful Grid", "ColorfulGrid"),
+    )
+    # Word 2013+ Plain Table — 5 entries, no accents.
+    for n in range(1, 6):
+        table[f"Plain Table {n}"] = f"PlainTable{n}"
+    # Word 2013+ Grid Table / List Table — 7 bases × (base + 6 accents) = 49
+    # entries per series. The "Light"/"Dark"/"Colorful" suffix on some
+    # bases is part of the styleId, not a separate "Accent N" axis.
+    bases_2013: tuple[tuple[str, str], ...] = (
+        ("Grid Table 1 Light", "GridTable1Light"),
+        ("Grid Table 2", "GridTable2"),
+        ("Grid Table 3", "GridTable3"),
+        ("Grid Table 4", "GridTable4"),
+        ("Grid Table 5 Dark", "GridTable5Dark"),
+        ("Grid Table 6 Colorful", "GridTable6Colorful"),
+        ("Grid Table 7 Colorful", "GridTable7Colorful"),
+        ("List Table 1 Light", "ListTable1Light"),
+        ("List Table 2", "ListTable2"),
+        ("List Table 3", "ListTable3"),
+        ("List Table 4", "ListTable4"),
+        ("List Table 5 Dark", "ListTable5Dark"),
+        ("List Table 6 Colorful", "ListTable6Colorful"),
+        ("List Table 7 Colorful", "ListTable7Colorful"),
+    )
+    for friendly, style_id in (*bases_2007, *bases_2013):
+        table[friendly] = style_id
+        for n in range(1, 7):
+            table[f"{friendly} Accent {n}"] = f"{style_id}-Accent{n}"
+    return table
+
+
+BUILTIN_TABLE_STYLE_IDS: dict[str, str] = _build_builtin_table_style_map()
+
+
+def resolve_table_style_id(style: str) -> str:
+    """Return the OOXML styleId for a Word built-in table style friendly name.
+
+    Custom user-defined style names pass through unchanged so that
+    callers that already supply canonical styleIds (or non-built-in
+    style names defined elsewhere) keep working.
+    """
+    return BUILTIN_TABLE_STYLE_IDS.get(style, style)

{athena_python_docx-0.9.0 → athena_python_docx-0.10.1}/docx/api.py

@@ -6,7 +6,10 @@ python-docx signature:
 Our signature deviates from the path-based one because we don't open
 .docx files from disk — we open Y.Doc assets from Keryx. The parameter
 is reused: pass an asset_id string where python-docx would take a file
-path.
+path. The id MUST be ``asset_<uuid>``; anything else (a title, a file
+path, etc.) raises ``ValueError`` before any HTTP request. To mint a
+new asset, call ``Document.create(name=...)`` and reuse the returned
+``doc.asset_id`` on subsequent ``Document(...)`` opens.
 
 For net-new asset creation, use the classmethod ``Document.create()``
 (see ``docx.document``). Stock python-docx returns a blank document
@@ -18,8 +21,18 @@ write that has to happen first. ``Document.create()`` handles that via
 
 from __future__ import annotations
 
+import re
+
 from docx.document import Document as _Document
 
+# Asset-id shape validation. Athena SuperDocument assets are
+# ``asset_<uuid>``. Rejecting anything else up front prevents the
+# common agent failure mode of passing a document TITLE
+# (``Document("Q4 Report Draft")``) instead of its id, which would
+# otherwise round-trip through the docx-studio session and fail with
+# an opaque server error.
+_ASSET_ID_PATTERN = re.compile(r"^asset_[A-Za-z0-9_-]+$")
+
 
 def Document(
     docx: str | None = None,
@@ -67,14 +80,49 @@ def Document(
             "To create a brand-new document, call "
             "Document.create(name=..., base_url=..., api_key=...).",
         )
-    return _Document(
-        asset_id=docx,
-        http_base_url=base_url,
-        http_api_key=api_key,
-        user_name=user_name,
-        user_email=user_email,
-        track_revisions=track_revisions,
+    if not _ASSET_ID_PATTERN.match(docx):
+        raise ValueError(
+            f"Document({docx!r}) is not a valid SuperDocument asset id. "
+            f"Asset ids look like 'asset_<uuid>' "
+            f"(e.g., 'asset_3a9328bc-9c1c-4498-be8f-bda3883276f5'). To "
+            f"open an existing document, pass its asset id — NOT its "
+            f"title. To create a new document titled {docx!r}, call "
+            f"Document.create(name={docx!r}) and reuse the returned "
+            f"document's asset id on subsequent calls in the same "
+            f"conversation."
+        )
+
+    # PTC: surface document open as its own sub-tool-card so the
+    # frontend can react (e.g., auto-open the asset tab). The paired
+    # ``Document.create()`` path emits ``CreateDocument``; this open
+    # path emits ``OpenDocument`` with the asset id.
+    from docx import _ptc
+
+    call_id = _ptc.emit_begin("OpenDocument", {"assetId": docx})
+    try:
+        doc = _Document(
+            asset_id=docx,
+            http_base_url=base_url,
+            http_api_key=api_key,
+            user_name=user_name,
+            user_email=user_email,
+            track_revisions=track_revisions,
+        )
+    except Exception as exc:
+        _ptc.emit_end(
+            call_id=call_id,
+            tool_name="OpenDocument",
+            result={"ok": False, "error": str(exc)},
+            is_error=True,
+        )
+        raise
+    _ptc.emit_end(
+        call_id=call_id,
+        tool_name="OpenDocument",
+        result={"ok": True, "assetId": docx},
+        is_error=False,
     )
+    return doc
 
 
 # Re-export the classmethod factories at module level so callers can