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

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

@@ -81,12 +81,46 @@ 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.10.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.10.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.10.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.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.10.0 → athena_python_docx-0.10.1}/docx/document.py

@@ -174,12 +174,21 @@ class Document:
         user_name: str | None = None,
         user_email: str | None = None,
         track_revisions: bool = False,
+        docx: str | None = None,
+        agora_base_url: str | None = None,
     ) -> "Document":
         """Create a new SuperDocument asset and return an opened Document.
 
-        Hits ``POST {base_url}/docs/empty`` on docx-studio with the
-        provided Athena API key, then returns a Document bound to the
-        new asset.
+        By default this hits ``POST {base_url}/docs/empty`` on docx-studio
+        with the provided Athena API key, then returns a Document bound to
+        the new asset.
+
+        When ``docx`` is provided, the local ``.docx`` file is uploaded as
+        the seed instead of starting from the bundled default template.
+        The upload goes through agora's ``/api/super-docs/create-from-upload``
+        endpoint (which seeds the new SuperDoc Y.Doc via SuperDoc SDK).
+        Mirrors stock python-docx's ``Document(docx=...)`` constructor
+        kwarg.
 
         Args:
             name: Display title for the new document. Defaults to the
@@ -192,6 +201,14 @@ class Document:
                 workspace root.
             workspace_id: Optional workspace UUID; defaults to the
                 caller's current workspace as resolved by Agora.
+            docx: Optional path to a local ``.docx`` file. When provided,
+                the file is uploaded and used as the seed for the new
+                document. Mirrors python-docx's
+                ``Document(docx="template.docx")`` pattern.
+            agora_base_url: Agora base URL used by the upload path. Falls
+                back to ``$ATHENA_AGORA_BASE_URL`` and finally to a
+                ``docx-studio`` → ``agora`` substitution against
+                ``base_url``. Ignored when ``docx`` is not set.
 
         Returns:
             A Document bound to the newly-created asset.
@@ -204,10 +221,12 @@ class Document:
         DEVIATION FROM python-docx: stock python-docx returns a blank
         in-memory document for ``Document(None)``. Our SDK is backed by
         an Athena asset, so we expose a separate ``create()`` factory
-        rather than overloading the constructor.
+        rather than overloading the constructor. The ``docx=`` kwarg
+        mirrors the upstream constructor kwarg on this factory instead.
         """
         from docx import _ptc
-        from docx._http import create_empty_document
+        from docx._http import create_empty_document, upload_document
+        from docx.errors import DocxError
 
         # PTC: surface asset creation as its own top-level sub-tool-card.
         # The asset_id isn't known until create_empty_document returns,
@@ -215,13 +234,37 @@ class Document:
         # asset_id into the end event's result.
         call_id = _ptc.emit_begin("CreateDocument", {"name": name})
         try:
-            result = create_empty_document(
-                base_url=base_url,
-                api_key=api_key,
-                name=name,
-                parent_folder_id=parent_folder_id,
-                workspace_id=workspace_id,
-            )
+            if docx is not None:
+                # Fail-fast: the agora upload endpoint that backs the
+                # ``docx=`` path doesn't accept a workspace_id parameter
+                # (it always lands in the caller's current workspace).
+                # Silently dropping it would be a contract violation
+                # vs. the non-``docx`` path which honors workspace_id.
+                if workspace_id is not None:
+                    raise DocxError(
+                        "workspace_id is not supported when docx= is provided. "
+                        "Omit workspace_id (the uploaded template lands in the "
+                        "caller's current workspace), or use Document.create() "
+                        "without docx= and add content via the SDK afterwards.",
+                    )
+                upload_result = upload_document(
+                    docx_path=docx,
+                    docx_base_url=base_url,
+                    agora_base_url=agora_base_url,
+                    api_key=api_key,
+                    name=name,
+                    parent_folder_id=parent_folder_id,
+                )
+                asset_id = upload_result["asset_id"]
+            else:
+                result = create_empty_document(
+                    base_url=base_url,
+                    api_key=api_key,
+                    name=name,
+                    parent_folder_id=parent_folder_id,
+                    workspace_id=workspace_id,
+                )
+                asset_id = result["asset_id"]
         except Exception as exc:
             _ptc.emit_end(
                 call_id=call_id,
@@ -233,11 +276,11 @@ class Document:
         _ptc.emit_end(
             call_id=call_id,
             tool_name="CreateDocument",
-            result={"ok": True, "assetId": result["asset_id"]},
+            result={"ok": True, "assetId": asset_id},
             is_error=False,
         )
         return cls(
-            asset_id=result["asset_id"],
+            asset_id=asset_id,
             http_base_url=base_url,
             http_api_key=api_key,
             user_name=user_name,
@@ -933,12 +976,13 @@ class Document:
         node_id: str = client_node_id
 
         if style:
+            from docx._table_styles import resolve_table_style_id
             from docx.styles.style import BaseStyle
 
             style_id = style.style_id if isinstance(style, BaseStyle) else str(style)
             run_sync(
                 self._session.doc.tables.set_style(
-                    {"nodeId": node_id, "styleId": style_id},
+                    {"nodeId": node_id, "styleId": resolve_table_style_id(style_id)},
                 ),
             )
 

{athena_python_docx-0.10.0 → athena_python_docx-0.10.1}/docx/table.py

@@ -487,10 +487,13 @@ class Table:
 
     @style.setter
     def style(self, value: str | None) -> None:
+        from docx._table_styles import resolve_table_style_id
+
         nid: str = self._fresh_node_id()
+        style_id = resolve_table_style_id(value) if value else "TableGrid"
         run_sync(
             self._session.doc.tables.set_style(
-                {"nodeId": nid, "styleId": value or "TableGrid"},
+                {"nodeId": nid, "styleId": style_id},
             ),
         )