athena-python-docx 0.42.1__tar.gz → 0.43.0__tar.gz

{athena_python_docx-0.42.1 → athena_python_docx-0.43.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: athena-python-docx
-Version: 0.42.1
+Version: 0.43.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.42.1 → athena_python_docx-0.43.0}/docx/__init__.py

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

{athena_python_docx-0.42.1 → athena_python_docx-0.43.0}/docx/_http.py

@@ -38,6 +38,20 @@ _API_KEY_ENV = "ATHENA_DOCX_API_KEY"  # noqa: S105
 _AGORA_BASE_URL_ENV = "ATHENA_AGORA_BASE_URL"
 
 
+def _resolve_api_key(api_key: str | None) -> str | None:
+    """The key a create or upload sends: ``api_key``, else the studio key.
+
+    ``ATHENA_DOCX_API_KEY`` comes first, as on every other call this SDK
+    makes. Both create paths land outside Athena's public API (docx-studio's
+    ``/docs/empty``, agora's ``/api/docx-studio/assets``), and inside an Athena
+    session VM or computer ``ATHENA_API_KEY`` is a credential only that public
+    API (``/api/v0``) accepts. ``ATHENA_API_KEY`` stays the fallback for an
+    environment that sets no studio key (local use with one personal key).
+    The new document is owned by the user the key belongs to.
+    """
+    return api_key or os.environ.get(_API_KEY_ENV) or os.environ.get("ATHENA_API_KEY")
+
+
 def _derive_agora_base_url(docx_base_url: str) -> str | None:
     """Best-effort derive an Agora base URL from a docx-studio base URL.
 
@@ -99,11 +113,11 @@ def create_empty_document(
             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``.
+            Falls back to ``$ATHENA_DOCX_API_KEY``, then ``$ATHENA_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.
+        workspace_id: Optional workspace UUID; defaults to the sandbox run's
+            ATHENA_WORKSPACE_ID, then the caller's current workspace.
         timeout: Request timeout in seconds.
 
     Returns:
@@ -115,17 +129,7 @@ def create_empty_document(
         DocxError: any other 4xx/5xx from the server.
     """
     resolved_base: str | None = base_url or os.environ.get(_BASE_URL_ENV)
-    # Create must authenticate as the REAL user so the new asset's ``created_by``
-    # is the user, not a service identity. ``ATHENA_API_KEY`` is the canonical
-    # per-user Athena key (a local API key in BYO/SSO mode that agora resolves to
-    # the real user); the docx-studio studio key (``ATHENA_DOCX_API_KEY``) is a
-    # deployment service credential used only for studio access-checks on
-    # EXISTING assets, and agora's create gate rejects it (no backing user). So
-    # prefer the user key here; only fall back to the studio key for callers that
-    # set just that.
-    resolved_key: str | None = (
-        api_key or os.environ.get("ATHENA_API_KEY") or os.environ.get(_API_KEY_ENV)
-    )
+    resolved_key: str | None = _resolve_api_key(api_key)
 
     if not resolved_base:
         raise SessionError(
@@ -149,8 +153,9 @@ def create_empty_document(
         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
+    resolved_workspace = workspace_id or os.environ.get("ATHENA_WORKSPACE_ID")
+    if resolved_workspace:
+        body["workspaceId"] = resolved_workspace
 
     # Lazy import — _http is loaded lazily by Document.create(), so the
     # package is fully initialized by the time we reach this code.
@@ -232,6 +237,7 @@ def upload_document(
     name: str | None = None,
     parent_folder_id: str | None = None,
     workspace_id: str | None = None,
+    source_asset_id: str | None = None,
     timeout: float = 120.0,
 ) -> UploadAssetResult:
     """Upload a local ``.docx`` to agora and create a new Word document asset.
@@ -247,11 +253,12 @@ def upload_document(
         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``.
+        api_key: Athena API key. Falls back to ``$ATHENA_DOCX_API_KEY``, then
+            ``$ATHENA_API_KEY``.
         name: Optional asset title (defaults to the file's stem).
         parent_folder_id: Optional parent folder for the new asset.
-        workspace_id: Optional workspace UUID; defaults to the caller's
-            current workspace as resolved by Agora.
+        workspace_id: Optional workspace UUID; defaults to the sandbox run's
+            ATHENA_WORKSPACE_ID, then the caller's current workspace in Agora.
         timeout: Request timeout in seconds (uploads can be slow for big
             decks/templates).
 
@@ -267,17 +274,7 @@ def upload_document(
     import os
 
     resolved_docx_base: str | None = docx_base_url or os.environ.get(_BASE_URL_ENV)
-    # Create must authenticate as the REAL user so the new asset's ``created_by``
-    # is the user, not a service identity. ``ATHENA_API_KEY`` is the canonical
-    # per-user Athena key (a local API key in BYO/SSO mode that agora resolves to
-    # the real user); the docx-studio studio key (``ATHENA_DOCX_API_KEY``) is a
-    # deployment service credential used only for studio access-checks on
-    # EXISTING assets, and agora's create gate rejects it (no backing user). So
-    # prefer the user key here; only fall back to the studio key for callers that
-    # set just that.
-    resolved_key: str | None = (
-        api_key or os.environ.get("ATHENA_API_KEY") or os.environ.get(_API_KEY_ENV)
-    )
+    resolved_key: str | None = _resolve_api_key(api_key)
     resolved_agora_base: str | None = (
         agora_base_url
         or os.environ.get(_AGORA_BASE_URL_ENV)
@@ -323,10 +320,13 @@ def upload_document(
         "seed_author": "requester",
         "seed_template": False,
     }
+    if source_asset_id is not None:
+        create_body["source_asset_id"] = source_asset_id
     if parent_folder_id is not None:
         create_body["parent_folder_id"] = parent_folder_id
-    if workspace_id is not None:
-        create_body["workspace_id"] = workspace_id
+    resolved_workspace = workspace_id or os.environ.get("ATHENA_WORKSPACE_ID")
+    if resolved_workspace:
+        create_body["workspace_id"] = resolved_workspace
 
     create_url: str = resolved_agora_base.rstrip("/") + "/api/docx-studio/assets"
 

{athena_python_docx-0.42.1 → athena_python_docx-0.43.0}/docx/document.py

@@ -259,6 +259,7 @@ class Document:
         track_revisions: bool = False,
         docx: str | None = None,
         agora_base_url: str | None = None,
+        source_asset_id: str | None = None,
     ) -> "Document":
         """Create a new Word document asset and return an opened Document.
 
@@ -279,9 +280,14 @@ class Document:
             base_url: docx-studio API base URL. Falls back to
                 ``$ATHENA_DOCX_BASE_URL``.
             api_key: Athena API key (PropelAuth user API key) or
-                access token. Falls back to ``$ATHENA_DOCX_API_KEY``.
+                access token. Falls back to ``$ATHENA_DOCX_API_KEY``, then
+                ``$ATHENA_API_KEY``, as every other call does; the upload path
+                (``docx=``) sends the same key to agora.
             parent_folder_id: Optional parent folder; defaults to
-                workspace root.
+                the source document's folder when source_asset_id is set,
+                otherwise workspace root.
+            source_asset_id: Original asset when creating a copy from an export.
+                Agora checks source access and destination edit permission.
             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,
@@ -325,6 +331,7 @@ class Document:
                     name=name,
                     parent_folder_id=parent_folder_id,
                     workspace_id=workspace_id,
+                    source_asset_id=source_asset_id,
                 )
                 asset_id = upload_result["asset_id"]
             else:

{athena_python_docx-0.42.1 → athena_python_docx-0.43.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "athena-python-docx"
-version = "0.42.1"
+version = "0.43.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.43.0/tests/test_create_workspace.py

@@ -0,0 +1,82 @@
+"""A sandbox create carries its run's workspace through both HTTP paths."""
+
+from __future__ import annotations
+
+import io
+import json
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from docx._http import create_empty_document, upload_document
+
+
+@pytest.mark.parametrize("upload", [False, True])
+@pytest.mark.parametrize(
+    ("run_workspace", "explicit_workspace", "expected_workspace"),
+    [
+        ("workspace_A", None, "workspace_A"),
+        ("workspace_A", "", "workspace_A"),
+        ("workspace_A", "workspace_explicit", "workspace_explicit"),
+        (None, None, None),
+        ("", None, None),
+    ],
+)
+def test_create_workspace(
+    *,
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    upload: bool,
+    run_workspace: str | None,
+    explicit_workspace: str | None,
+    expected_workspace: str | None,
+) -> None:
+    if run_workspace is None:
+        monkeypatch.delenv("ATHENA_WORKSPACE_ID", raising=False)
+    else:
+        monkeypatch.setenv("ATHENA_WORKSPACE_ID", run_workspace)
+    created = json.dumps(
+        {
+            "assetId": "asset_new",
+            "asset_id": "asset_new",
+            "name": "Memo",
+            "workspaceId": "workspace_B",
+        }
+    ).encode()
+    with patch(
+        "docx._http.urllib.request.urlopen",
+        side_effect=[
+            io.BytesIO(created),
+            io.BytesIO(b'{"asset_id": "asset_new", "seeded": true}'),
+        ],
+    ) as urlopen:
+        if upload:
+            source = tmp_path / "memo.docx"
+            source.write_bytes(b"PK\x03\x04template")
+            upload_document(
+                docx_path=str(source),
+                docx_base_url="https://docx.example",
+                agora_base_url="https://api.example",
+                api_key="user-key",
+                workspace_id=explicit_workspace,
+                parent_folder_id="asset_folder_A",
+            )
+        else:
+            create_empty_document(
+                base_url="https://docx.example",
+                api_key="user-key",
+                workspace_id=explicit_workspace,
+                parent_folder_id="asset_folder_A",
+            )
+
+    request = urlopen.call_args_list[0].args[0]
+    body = json.loads(request.data)
+    workspace_key = "workspace_id" if upload else "workspaceId"
+    folder_key = "parent_folder_id" if upload else "parentFolderId"
+    if expected_workspace is None:
+        assert workspace_key not in body
+    else:
+        assert body[workspace_key] == expected_workspace
+    assert body[folder_key] == "asset_folder_A"
+    assert request.get_header("Authorization") == "Bearer user-key"

{athena_python_docx-0.42.1 → athena_python_docx-0.43.0}/tests/test_document_create.py

@@ -201,45 +201,45 @@ def test_create_outside_a_run_sends_no_attributions(
     assert "x-custom-attributions" not in captured["headers"]
 
 
-def test_create_prefers_user_key_over_studio_key(
+def test_create_sends_the_studio_key_not_athena_api_key(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
-    """create() authenticates as the user, not the static studio key.
+    """create() sends docx-studio its own key, ``ATHENA_DOCX_API_KEY``.
 
-    In self-hosted SSO the executor injects BOTH the static studio key
-    (``ATHENA_DOCX_API_KEY``) and the per-user key (``ATHENA_API_KEY``). create
-    must use the per-user key so the new asset's ``created_by`` is the real
-    user — the studio key is a deployment service credential that agora's
-    create gate rejects (no backing user).
+    Inside an Athena session VM or computer ``ATHENA_API_KEY`` is a credential
+    only Athena's public API (``/api/v0``) accepts; docx-studio would refuse
+    it. Both keys are set there, and the studio key is the person's own.
     """
     monkeypatch.setenv(
         "ATHENA_DOCX_BASE_URL",
         "https://docx-studio.stg.athenaintel.com",
     )
-    monkeypatch.setenv("ATHENA_DOCX_API_KEY", "studio-static-key")
-    monkeypatch.setenv("ATHENA_API_KEY", "user-local-key")
+    monkeypatch.setenv("ATHENA_DOCX_API_KEY", "studio-key")
+    monkeypatch.setenv("ATHENA_API_KEY", "athsvm_public-api-only")
     captured: dict[str, Any] = {}
 
     def _capture(req: Any, **_kwargs: Any) -> _FakeResponse:
+        captured["url"] = req.full_url
         captured["headers"] = dict(req.headers)
         return _FakeResponse(json.dumps(_FAKE_RESPONSE).encode("utf-8"))
 
     with patch("docx._http.urllib.request.urlopen", side_effect=_capture):
         Document.create(name="X")
 
-    assert captured["headers"]["Authorization"] == "Bearer user-local-key"
+    assert captured["url"] == "https://docx-studio.stg.athenaintel.com/docs/empty"
+    assert captured["headers"]["Authorization"] == "Bearer studio-key"
 
 
-def test_create_falls_back_to_studio_key_without_user_key(
+def test_create_falls_back_to_athena_api_key_without_a_studio_key(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
-    """With only the studio key configured, create still authenticates with it."""
+    """With only ``ATHENA_API_KEY`` set (local use), create authenticates with it."""
     monkeypatch.setenv(
         "ATHENA_DOCX_BASE_URL",
         "https://docx-studio.stg.athenaintel.com",
     )
-    monkeypatch.setenv("ATHENA_DOCX_API_KEY", "studio-static-key")
-    monkeypatch.delenv("ATHENA_API_KEY", raising=False)
+    monkeypatch.delenv("ATHENA_DOCX_API_KEY", raising=False)
+    monkeypatch.setenv("ATHENA_API_KEY", "personal-key")
     captured: dict[str, Any] = {}
 
     def _capture(req: Any, **_kwargs: Any) -> _FakeResponse:
@@ -249,4 +249,21 @@ def test_create_falls_back_to_studio_key_without_user_key(
     with patch("docx._http.urllib.request.urlopen", side_effect=_capture):
         Document.create(name="X")
 
-    assert captured["headers"]["Authorization"] == "Bearer studio-static-key"
+    assert captured["headers"]["Authorization"] == "Bearer personal-key"
+
+
+def test_create_with_an_explicit_api_key_sends_it(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("ATHENA_DOCX_API_KEY", "studio-key")
+    monkeypatch.setenv("ATHENA_API_KEY", "athsvm_public-api-only")
+    captured: dict[str, Any] = {}
+
+    def _capture(req: Any, **_kwargs: Any) -> _FakeResponse:
+        captured["headers"] = dict(req.headers)
+        return _FakeResponse(json.dumps(_FAKE_RESPONSE).encode("utf-8"))
+
+    with patch("docx._http.urllib.request.urlopen", side_effect=_capture):
+        Document.create(name="X", base_url="https://example.com", api_key="explicit")
+
+    assert captured["headers"]["Authorization"] == "Bearer explicit"

{athena_python_docx-0.42.1 → athena_python_docx-0.43.0}/tests/test_document_create_from_template.py

@@ -83,8 +83,10 @@ def test_derive_agora_base_url_returns_none_for_unrelated_hosts() -> None:
     assert _derive_agora_base_url("https://unrelated.example.com") is None
 
 
+@pytest.mark.parametrize("parent", [None, "folder_override"])
 def test_upload_document_creates_asset_then_imports_docx(
     monkeypatch: pytest.MonkeyPatch,
+    parent: str | None,
 ) -> None:
     """upload_document() should create the asset, then import the .docx bytes."""
     monkeypatch.setenv("ATHENA_DOCX_API_KEY", "bg_test_key")
@@ -115,6 +117,8 @@ def test_upload_document_creates_asset_then_imports_docx(
                 docx_path=path,
                 name="My Template Seeded Doc",
                 workspace_id="ws_explicit",
+                source_asset_id="asset_source",
+                parent_folder_id=parent,
             )
     finally:
         os.unlink(path)
@@ -134,6 +138,8 @@ def test_upload_document_creates_asset_then_imports_docx(
         "seed_author": "requester",
         "seed_template": False,
         "workspace_id": "ws_explicit",
+        "source_asset_id": "asset_source",
+        **({"parent_folder_id": parent} if parent is not None else {}),
     }
     assert create_req["attributions"] == "session_id:thread_1"
     assert (
@@ -198,6 +204,80 @@ def test_upload_document_deletes_created_asset_when_import_fails(
     assert captured[-1]["auth"] == "Bearer bg_test_key"
 
 
+def test_upload_document_sends_the_studio_key_not_athena_api_key(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """The create, the import and the rollback all send ``ATHENA_DOCX_API_KEY``.
+
+    They go to agora's ``/api/docx-studio/assets``, outside the public API
+    (``/api/v0``) that a session VM's or computer's ``ATHENA_API_KEY`` is
+    limited to.
+    """
+    monkeypatch.setenv("ATHENA_DOCX_API_KEY", "studio-key")
+    monkeypatch.setenv("ATHENA_API_KEY", "athsvm_public-api-only")
+    monkeypatch.setenv("ATHENA_AGORA_BASE_URL", "https://api.example.com")
+
+    captured: list[tuple[str, str, str | None]] = []
+
+    def _fake_urlopen(req, timeout):  # noqa: ANN001, ARG001
+        captured.append((req.get_method(), req.full_url, req.get_header("Authorization")))
+        if req.get_method() == "DELETE":
+            return _FakeResponse(b"")
+        if req.full_url.endswith("/api/docx-studio/assets"):
+            return _FakeResponse(json.dumps(_FAKE_CREATE_RESPONSE).encode("utf-8"))
+        raise urllib.error.HTTPError(
+            url=req.full_url,
+            code=500,
+            msg="Import Failed",
+            hdrs=None,  # type: ignore[arg-type]
+            fp=io.BytesIO(b'{"error":"boom"}'),
+        )
+
+    path = _make_docx_tmpfile()
+    try:
+        with patch("docx._http.urllib.request.urlopen", side_effect=_fake_urlopen):
+            with pytest.raises(DocxError, match="HTTP 500"):
+                upload_document(docx_path=path, name="Memo")
+    finally:
+        os.unlink(path)
+
+    asset_url = (
+        "https://api.example.com/api/docx-studio/assets/"
+        "asset_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
+    )
+    assert captured == [
+        ("POST", "https://api.example.com/api/docx-studio/assets", "Bearer studio-key"),
+        ("POST", f"{asset_url}/import", "Bearer studio-key"),
+        ("DELETE", asset_url, "Bearer studio-key"),
+    ]
+
+
+def test_upload_document_falls_back_to_athena_api_key_without_a_studio_key(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """With only ``ATHENA_API_KEY`` set (local use), the upload authenticates with it."""
+    monkeypatch.delenv("ATHENA_DOCX_API_KEY", raising=False)
+    monkeypatch.setenv("ATHENA_API_KEY", "personal-key")
+    monkeypatch.setenv("ATHENA_AGORA_BASE_URL", "https://api.example.com")
+
+    auths: list[str | None] = []
+
+    def _fake_urlopen(req, timeout):  # noqa: ANN001, ARG001
+        auths.append(req.get_header("Authorization"))
+        if req.full_url.endswith("/api/docx-studio/assets"):
+            return _FakeResponse(json.dumps(_FAKE_CREATE_RESPONSE).encode("utf-8"))
+        return _FakeResponse(json.dumps(_FAKE_IMPORT_RESPONSE).encode("utf-8"))
+
+    path = _make_docx_tmpfile()
+    try:
+        with patch("docx._http.urllib.request.urlopen", side_effect=_fake_urlopen):
+            upload_document(docx_path=path, name="Memo")
+    finally:
+        os.unlink(path)
+
+    assert auths == ["Bearer personal-key", "Bearer personal-key"]
+
+
 def test_upload_document_rejects_unseeded_import_response(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
@@ -400,12 +480,16 @@ def test_document_create_with_docx_passes_workspace_id(
             api_key="bg_test_key",
             docx=path,
             workspace_id="ws_other",
+            source_asset_id="asset_original",
+            parent_folder_id="folder_override",
         )
     finally:
         os.unlink(path)
 
     assert doc.asset_id == "asset_new_from_template"
     assert captured["workspace_id"] == "ws_other"
+    assert captured["source_asset_id"] == "asset_original"
+    assert captured["parent_folder_id"] == "folder_override"
 
 
 def test_document_create_without_docx_uses_empty_endpoint(

{athena_python_docx-0.42.1 → athena_python_docx-0.43.0}/uv.lock

@@ -8,7 +8,7 @@ resolution-markers = [
 
 [[package]]
 name = "athena-python-docx"
-version = "0.42.1"
+version = "0.43.0"
 source = { editable = "." }
 dependencies = [
     { name = "athena-references" },