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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: athena-python-docx
-Version: 0.42.1
+Version: 0.44.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>
@@ -81,6 +81,13 @@ Required when connecting to DOCX Studio (set by the Athena backend in the `execu
 - `ATHENA_DOCX_BASE_URL` — DOCX Studio API base URL
 - `ATHENA_DOCX_API_KEY` — Athena API key or service-issued DOCX Studio token
 
+Without `ATHENA_DOCX_API_KEY` (and without `api_key=`), the SDK uses
+`ATHENA_API_KEY`. When `ATHENA_API_URL` is set too (the bare Athena URL or one
+ending in `/api/v0`), an opened document's calls carry a 15-minute token Athena
+mints for that document alone (`POST /api/v0/assets/{asset_id}/studio-token`),
+read-only for reads; `Document.create()` and its upload still send the key
+(`docx/_asset_token.py`).
+
 ## License
 
 MIT

{athena_python_docx-0.42.1 → athena_python_docx-0.44.0}/README.md

@@ -56,6 +56,13 @@ Required when connecting to DOCX Studio (set by the Athena backend in the `execu
 - `ATHENA_DOCX_BASE_URL` — DOCX Studio API base URL
 - `ATHENA_DOCX_API_KEY` — Athena API key or service-issued DOCX Studio token
 
+Without `ATHENA_DOCX_API_KEY` (and without `api_key=`), the SDK uses
+`ATHENA_API_KEY`. When `ATHENA_API_URL` is set too (the bare Athena URL or one
+ending in `/api/v0`), an opened document's calls carry a 15-minute token Athena
+mints for that document alone (`POST /api/v0/assets/{asset_id}/studio-token`),
+read-only for reads; `Document.create()` and its upload still send the key
+(`docx/_asset_token.py`).
+
 ## License
 
 MIT

{athena_python_docx-0.42.1 → athena_python_docx-0.44.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.44.0"
 
 from docx.api import Document
 from docx._buffer import discard_all, flush_all

athena_python_docx-0.44.0/docx/_asset_token.py

@@ -0,0 +1,354 @@
+"""Per-document DOCX Studio tokens, minted from Athena's public API.
+
+A call on an existing Word document reaches DOCX Studio with, in this order:
+
+1. the ``api_key`` the caller passed;
+2. the studio's own key, ``ATHENA_DOCX_API_KEY``;
+3. when ``ATHENA_API_KEY`` and ``ATHENA_API_URL`` are both set, a token for that
+   document alone, minted by
+   ``POST {ATHENA_API_URL}/api/v0/assets/{asset_id}/studio-token`` with
+   ``X-API-KEY: $ATHENA_API_KEY`` and sent as ``Authorization: Bearer``. It names
+   the caller, the document, one access level and DOCX Studio, and lasts 15
+   minutes;
+4. otherwise ``ATHENA_API_KEY`` itself, as before.
+
+Creating a document (``Document.create``, its upload) keeps the key of 1, 2 or
+4: a document that does not exist yet has no token. A token goes only to its
+own document's routes.
+
+A token is minted once per (agora, key, asset, access) for the whole process,
+again 90 seconds before it expires, and once more when the studio answers 401.
+A read mints a read-only token (``{"access": "view"}``: the version check, the
+layout, page renders, the clean export), a write a read-write one
+(``{"access": "edit"}``, which Athena grants only to a caller who may edit).
+Every command batch is a write to DOCX Studio, whose ``/commands`` route needs
+edit access even for a batch that only queries. ``ATHENA_API_URL`` ends in
+``/api/v0`` inside an Athena computer and is the bare agora URL in a session VM
+or locally; both work.
+
+Athena's refusals (400, 401, 403, 404, 422) raise at once, without a retry. A
+deployment that signs no asset tokens answers 503: the client then uses the
+studio key when one is set, and otherwise raises an error that names it.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import inspect
+import os
+import threading
+import time
+from collections import OrderedDict
+from dataclasses import dataclass, field
+from typing import Any
+from urllib.parse import quote
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+from docx.errors import (
+    AuthenticationError,
+    DocxError,
+    DocxStudioTemporarilyUnavailable,
+    NotFoundError,
+    SessionError,
+)
+
+API_KEY_ENV = "ATHENA_API_KEY"
+API_URL_ENV = "ATHENA_API_URL"
+STUDIO_KEY_ENV = "ATHENA_DOCX_API_KEY"
+#: The token audience DOCX Studio verifies.
+AUDIENCE = "docx-studio"
+TOKEN_PREFIX = "aat_"
+PUBLIC_API_PREFIX = "/api/v0"
+
+#: The access a token is minted for.
+VIEW = "view"
+EDIT = "edit"
+
+#: Minted again this long before Athena's ``expires_at_ms``.
+REFRESH_BEFORE_EXPIRY_SECONDS = 90.0
+#: The longest a token is held, whatever the local clock says (Athena's lifetime).
+MAX_LIFETIME_SECONDS = 15 * 60.0
+#: The shortest, so a clock running ahead of Athena's cannot mint per call.
+MIN_LIFETIME_SECONDS = 30.0
+MINT_TIMEOUT_SECONDS = 30.0
+_MAX_CACHED_TOKENS = 256
+_LOCK_STRIPES = 16
+
+_KIND_BY_AUDIENCE = {
+    AUDIENCE: "a Word document",
+    "pptx-studio": "a presentation",
+    "xlsx-studio": "a spreadsheet",
+}
+
+
+def public_api_base(url: str) -> str:
+    """The public API base for ``url``, whether or not it already ends in it."""
+    base = url.strip().rstrip("/")
+    if base.endswith(PUBLIC_API_PREFIX):
+        return base
+    return base + PUBLIC_API_PREFIX
+
+
+@dataclass(frozen=True)
+class StudioToken:
+    """One minted token and what Athena said about it."""
+
+    token: str = field(repr=False)
+    asset_id: str
+    audience: str
+    #: ``"r"`` (reads only) or ``"rw"``.
+    access_type: str
+    #: ``time.monotonic()`` after which the token is minted again.
+    refresh_at: float
+
+    def is_fresh(self) -> bool:
+        return time.monotonic() < self.refresh_at
+
+
+class SigningUnavailable(Exception):
+    """Athena's 503: this deployment signs no asset tokens."""
+
+
+class _TokenCache:
+    """Process-wide tokens by (agora, key, asset, access), least recently used first."""
+
+    def __init__(self, max_entries: int) -> None:
+        self._entries: OrderedDict[tuple[str, str, str, str], StudioToken] = OrderedDict()
+        self._max_entries = max_entries
+        self._lock = threading.Lock()
+        # Minting holds one stripe, so threads wanting the same token wait for
+        # one mint instead of each minting their own.
+        self._mint_locks = tuple(threading.Lock() for _ in range(_LOCK_STRIPES))
+
+    def get(self, key: tuple[str, str, str, str]) -> StudioToken | None:
+        with self._lock:
+            token = self._entries.get(key)
+            if token is not None:
+                self._entries.move_to_end(key)
+            return token
+
+    def put(self, key: tuple[str, str, str, str], token: StudioToken) -> None:
+        with self._lock:
+            self._entries[key] = token
+            self._entries.move_to_end(key)
+            while len(self._entries) > self._max_entries:
+                self._entries.popitem(last=False)
+
+    def discard(self, key: tuple[str, str, str, str], token: StudioToken) -> None:
+        """Forget ``token`` unless another thread already replaced it."""
+        with self._lock:
+            if self._entries.get(key) is token:
+                del self._entries[key]
+
+    def mint_lock(self, key: tuple[str, str, str, str]) -> threading.Lock:
+        return self._mint_locks[hash(key) % _LOCK_STRIPES]
+
+    def clear(self) -> None:
+        with self._lock:
+            self._entries.clear()
+
+
+_CACHE = _TokenCache(_MAX_CACHED_TOKENS)
+
+_SESSION: requests.Session | None = None
+_SESSION_LOCK = threading.Lock()
+
+
+def _mint_session() -> requests.Session:
+    """One session for every mint: connection retries, and status retries for
+    429/502/504. A 503 is Athena's answer, not a transient fault, so it is not
+    retried; minting is safe to resend (each mint only signs a new token)."""
+    global _SESSION
+    with _SESSION_LOCK:
+        if _SESSION is None:
+            retry_kwargs: dict[str, Any] = {
+                "total": None,
+                "status": 2,
+                "connect": 2,
+                "read": 0,
+                "other": 0,
+                "backoff_factor": 0.5,
+                "status_forcelist": (429, 502, 504),
+                "allowed_methods": frozenset(["POST"]),
+                "raise_on_status": False,
+                "respect_retry_after_header": True,
+            }
+            if "backoff_max" in inspect.signature(Retry).parameters:
+                retry_kwargs["backoff_max"] = 5.0
+            session = requests.Session()
+            adapter = HTTPAdapter(max_retries=Retry(**retry_kwargs))
+            session.mount("http://", adapter)
+            session.mount("https://", adapter)
+            _SESSION = session
+        return _SESSION
+
+
+def _detail(response: requests.Response) -> str:
+    """Athena's reason (``{"detail": ...}``), else a short excerpt of the body."""
+    try:
+        body = response.json()
+    except ValueError:
+        return " ".join((response.text or "").split())[:200]
+    detail = body.get("detail") if isinstance(body, dict) else None
+    if isinstance(detail, dict):
+        detail = detail.get("message")
+    if isinstance(detail, str):
+        return detail.strip()
+    return ""
+
+
+def _lifetime_seconds(expires_at_ms: int) -> float:
+    """How long to hold a token, from Athena's expiry and the local clock."""
+    remaining = expires_at_ms / 1000.0 - time.time()
+    return min(max(remaining, MIN_LIFETIME_SECONDS), MAX_LIFETIME_SECONDS)
+
+
+class TokenMinter:
+    """Mints the studio tokens one ``ATHENA_API_KEY`` holds, through the cache."""
+
+    def __init__(self, *, api_url: str, api_key: str) -> None:
+        self.base = public_api_base(api_url)
+        self._api_key = api_key
+        self._fingerprint = hashlib.sha256(api_key.encode("utf-8")).hexdigest()
+
+    @classmethod
+    def from_environment(cls) -> TokenMinter | None:
+        """The minter for ``ATHENA_API_KEY`` at ``ATHENA_API_URL``; None when either is unset."""
+        api_key = os.environ.get(API_KEY_ENV)
+        api_url = os.environ.get(API_URL_ENV)
+        if not api_key or not api_url or not api_url.strip():
+            return None
+        return cls(api_url=api_url, api_key=api_key)
+
+    def _key(self, *, asset_id: str, access: str) -> tuple[str, str, str, str]:
+        return (self.base, self._fingerprint, asset_id, access)
+
+    def token(self, *, asset_id: str, access: str) -> StudioToken:
+        """The token for ``asset_id`` at ``access``: the cached one while fresh,
+        else a new one. Raises when Athena refuses it, when it is for another
+        studio, and :class:`SigningUnavailable` on a 503."""
+        key = self._key(asset_id=asset_id, access=access)
+        token = _CACHE.get(key)
+        if token is None or not token.is_fresh():
+            with _CACHE.mint_lock(key):
+                token = _CACHE.get(key)
+                if token is None or not token.is_fresh():
+                    token = self._mint(asset_id=asset_id, access=access)
+                    _CACHE.put(key, token)
+        if token.audience != AUDIENCE:
+            raise DocxError(
+                f"Asset {asset_id} is not a Word document: Athena edits it through "
+                f"{token.audience}. Open it with the Athena SDK for "
+                f"{_KIND_BY_AUDIENCE.get(token.audience, 'that kind of asset')}."
+            )
+        return token
+
+    def invalidate(self, *, token: StudioToken, access: str) -> None:
+        """Forget ``token`` (the studio answered 401 to it), so the next call mints."""
+        _CACHE.discard(self._key(asset_id=token.asset_id, access=access), token)
+
+    def _mint(self, *, asset_id: str, access: str) -> StudioToken:
+        url = f"{self.base}/assets/{quote(asset_id, safe='')}/studio-token"
+        try:
+            response = _mint_session().post(
+                url,
+                json={"access": access},
+                headers={"X-API-KEY": self._api_key, "Accept": "application/json"},
+                timeout=MINT_TIMEOUT_SECONDS,
+            )
+        except requests.RequestException as exc:
+            raise SessionError(
+                f"Unable to reach Athena at {url} to mint a DOCX Studio token for "
+                f"{asset_id}: {exc}"
+            ) from exc
+        try:
+            return self._read(response, asset_id=asset_id)
+        finally:
+            response.close()
+
+    @staticmethod
+    def _read(response: requests.Response, *, asset_id: str) -> StudioToken:
+        status = response.status_code
+        if status == 503:
+            raise SigningUnavailable(_detail(response) or "This deployment signs no asset tokens.")
+        detail = _detail(response)
+        reason = f"(HTTP {status}{': ' + detail if detail else ''})"
+        if status == 401:
+            raise AuthenticationError(
+                f"Athena refused ATHENA_API_KEY when asked for a DOCX Studio token for "
+                f"{asset_id} {reason}. The key is invalid, expired or revoked; retrying "
+                "with it will not help."
+            )
+        if status == 403:
+            raise AuthenticationError(f"Athena refused a DOCX Studio token for {asset_id} {reason}.")
+        if status == 404:
+            raise NotFoundError(
+                f"Athena refused a DOCX Studio token for {asset_id} {reason}: the document "
+                "does not exist, or this key may not read it.",
+                payload={"status": 404, "body": detail},
+            )
+        if status in (400, 422):
+            raise DocxError(f"Athena refused a DOCX Studio token for {asset_id} {reason}.")
+        if not response.ok:
+            raise DocxStudioTemporarilyUnavailable(
+                f"Athena could not mint a DOCX Studio token for {asset_id} {reason}.",
+                http_status=status,
+            )
+        try:
+            body = response.json()
+        except ValueError:
+            body = None
+        if not isinstance(body, dict):
+            body = {}
+        token = body.get("token")
+        audience = body.get("audience")
+        access_type = body.get("access_type")
+        expires_at_ms = body.get("expires_at_ms")
+        if (
+            not isinstance(token, str)
+            or not token.startswith(TOKEN_PREFIX)
+            or not isinstance(audience, str)
+            or access_type not in ("r", "rw")
+            or not isinstance(expires_at_ms, int)
+            or isinstance(expires_at_ms, bool)
+            or body.get("asset_id") != asset_id
+        ):
+            raise SessionError(
+                f"Athena's studio token answer for {asset_id} is not one this SDK can use "
+                "(expected token, audience, access_type, expires_at_ms and this asset id)."
+            )
+        return StudioToken(
+            token=token,
+            asset_id=asset_id,
+            audience=audience,
+            access_type=access_type,
+            refresh_at=time.monotonic()
+            + max(
+                _lifetime_seconds(expires_at_ms) - REFRESH_BEFORE_EXPIRY_SECONDS,
+                MIN_LIFETIME_SECONDS,
+            ),
+        )
+
+
+def studio_credentials(*, api_key: str | None) -> tuple[str | None, TokenMinter | None]:
+    """What a client authenticates with: ``(key, minter)``.
+
+    ``key`` serves every route the minter does not: ``api_key`` when the caller
+    passed one, else ``ATHENA_DOCX_API_KEY``, else ``ATHENA_API_KEY``. ``minter``
+    mints per-document tokens when neither of the first two is set and
+    ``ATHENA_API_KEY`` and ``ATHENA_API_URL`` are.
+    """
+    if api_key:
+        return api_key, None
+    studio_key = os.environ.get(STUDIO_KEY_ENV)
+    if studio_key:
+        return studio_key, None
+    return os.environ.get(API_KEY_ENV), TokenMinter.from_environment()
+
+
+def _clear_cache() -> None:
+    """Forget every cached token (tests)."""
+    _CACHE.clear()

{athena_python_docx-0.42.1 → athena_python_docx-0.44.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"