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

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

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

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

athena_python_docx-0.45.0/docx/_asset_token.py

@@ -0,0 +1,379 @@
+"""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. In case 3 Athena's public
+API creates it instead (``docx._public_create``). 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. An
+Athena older than the route answers FastAPI's bare 404 (``{"detail": "Not
+Found"}``): the client then sends ``ATHENA_API_KEY``, as before the route.
+"""
+
+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 MintRouteMissing(Exception):
+    """A 404 with FastAPI's bare route-not-found body: the Athena at
+    ``ATHENA_API_URL`` predates the studio-token route (a self-hosted release
+    older than the SDK). The client then sends ``ATHENA_API_KEY``, as before."""
+
+
+#: What FastAPI answers for a path no route matches. Athena's own 404 from the
+#: studio-token route names the asset ("Asset not found."), so the two never mix.
+_ROUTE_NOT_FOUND_BODY = {"detail": "Not Found"}
+
+
+def _is_route_missing(response: requests.Response) -> bool:
+    if response.status_code != 404:
+        return False
+    try:
+        return bool(response.json() == _ROUTE_NOT_FOUND_BODY)
+    except ValueError:
+        return False
+
+
+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.")
+        if _is_route_missing(response):
+            raise MintRouteMissing(f"no studio-token route at {response.url}")
+        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.43.0 → athena_python_docx-0.45.0}/docx/_http.py

@@ -45,8 +45,10 @@ def _resolve_api_key(api_key: str | None) -> str | None:
     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).
+    API (``/api/v0``) accepts: there (neither key set, ``ATHENA_API_URL`` set)
+    Athena's public API creates the document instead (``docx._public_create``).
+    ``ATHENA_API_KEY`` stays the fallback for an environment that sets no
+    studio key and no ``ATHENA_API_URL`` (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")
@@ -137,6 +139,14 @@ def create_empty_document(
             "Pass base_url= to Document.create() or set the env var "
             '(e.g. ATHENA_DOCX_BASE_URL="https://docx-studio.prd.athenaintel.com").',
         )
+    created = _create_through_athena(
+        api_key=api_key,
+        name=name,
+        parent_folder_id=parent_folder_id,
+        workspace_id=workspace_id,
+    )
+    if created is not None:
+        return created
     if not resolved_key:
         raise AuthenticationError(
             f"Missing api_key and {_API_KEY_ENV} env var. "
@@ -221,6 +231,44 @@ def create_empty_document(
     )
 
 
+def _create_through_athena(
+    *,
+    api_key: str | None,
+    name: str | None,
+    parent_folder_id: str | None,
+    workspace_id: str | None,
+) -> CreateAssetResult | None:
+    """A new document Athena's public API made, or None for docx-studio's path.
+
+    Athena creates it when no ``api_key`` and no ``ATHENA_DOCX_API_KEY`` are set
+    and ``ATHENA_API_KEY`` and ``ATHENA_API_URL`` are (``docx._public_create``).
+    None otherwise, and when that Athena predates the public create.
+    """
+    from docx._public_create import (
+        PublicApi,
+        PublicCreateUnavailable,
+        create_word_document,
+    )
+
+    api = PublicApi.for_creation(api_key=api_key)
+    if api is None:
+        return None
+    try:
+        created = create_word_document(
+            api=api,
+            name=name,
+            parent_folder_id=parent_folder_id,
+            workspace_id=workspace_id or os.environ.get("ATHENA_WORKSPACE_ID"),
+        )
+    except PublicCreateUnavailable:
+        return None
+    return CreateAssetResult(
+        asset_id=created["asset_id"],
+        name=created["title"],
+        workspace_id=created["workspace_id"] or "",
+    )
+
+
 class UploadAssetResult(TypedDict):
     """Parsed response from the create-and-import upload flow."""
 
@@ -228,6 +276,58 @@ class UploadAssetResult(TypedDict):
     name: str
 
 
+def _upload_through_athena(
+    *,
+    docx_path: str,
+    api_key: str | None,
+    name: str | None,
+    parent_folder_id: str | None,
+    workspace_id: str | None,
+    source_asset_id: str | None,
+    timeout: float,
+) -> UploadAssetResult | None:
+    """A document Athena made from the ``.docx`` at ``docx_path``, or None.
+
+    Athena's ``POST /api/v0/assets/create-from-file`` makes it in one request
+    when no ``api_key`` and no ``ATHENA_DOCX_API_KEY`` are set and
+    ``ATHENA_API_KEY`` and ``ATHENA_API_URL`` are (``docx._public_create``).
+    None otherwise, and when that Athena predates the route: the upload then
+    goes through agora's docx-studio bridge, as before.
+    """
+    from docx._public_create import (
+        PublicApi,
+        PublicCreateUnavailable,
+        create_word_document_from_file,
+    )
+
+    api = PublicApi.for_creation(api_key=api_key)
+    if api is None:
+        return None
+    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
+    try:
+        created = create_word_document_from_file(
+            api=api,
+            docx_path=docx_path,
+            title=title,
+            parent_folder_id=parent_folder_id,
+            workspace_id=workspace_id or os.environ.get("ATHENA_WORKSPACE_ID"),
+            source_asset_id=source_asset_id,
+            timeout=timeout,
+        )
+    except PublicCreateUnavailable:
+        return None
+    return UploadAssetResult(asset_id=created["asset_id"], name=created["title"])
+
+
 def upload_document(
     *,
     docx_path: str,
@@ -273,6 +373,18 @@ def upload_document(
     import base64
     import os
 
+    uploaded = _upload_through_athena(
+        docx_path=docx_path,
+        api_key=api_key,
+        name=name,
+        parent_folder_id=parent_folder_id,
+        workspace_id=workspace_id,
+        source_asset_id=source_asset_id,
+        timeout=timeout,
+    )
+    if uploaded is not None:
+        return uploaded
+
     resolved_docx_base: str | None = docx_base_url or os.environ.get(_BASE_URL_ENV)
     resolved_key: str | None = _resolve_api_key(api_key)
     resolved_agora_base: str | None = (