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

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

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

@@ -36,12 +36,21 @@ import os
 import re
 import urllib.parse
 import warnings
-from typing import Any, TypedDict
+from collections.abc import Callable
+from typing import Any, TypedDict, TypeVar
 
 import requests
 from requests.adapters import HTTPAdapter
 from urllib3.util.retry import Retry
 
+from docx._asset_token import (
+    EDIT,
+    STUDIO_KEY_ENV,
+    VIEW,
+    SigningUnavailable,
+    StudioToken,
+    TokenMinter,
+)
 from docx._batching import call_abandoned, note_progress
 from docx._buffer import CommandBuffer, keep_reported_message
 from docx._tracked import TRACKED_AUTHORING_CAPABILITY, TRACKED_MINIMAL_PARAGRAPH_TEXT_CAPABILITY
@@ -211,6 +220,8 @@ VERSION_CHECK_TIMEOUT_SECONDS: float = 10.0
 # (``CommandsRequestSchema`` in ``apps/api/src/commands/types.ts``).
 MAX_BATCH_COMMANDS: int = 500
 
+_T = TypeVar("_T")
+
 
 def _minted_ids(results: list[Any]) -> dict[str, str]:
     """The client → real ids that the Creates among a batch's ``results`` echo."""
@@ -720,6 +731,16 @@ def _parse_retry_after(value: str | None) -> float | None:
         return None
 
 
+def _rejected(status_code: int, err_body: str) -> AuthenticationError:
+    """docx-studio's 401 or 403, carrying its status (a 401 to a minted token
+    is minted again once, :meth:`HttpClient._with_token`)."""
+    error = AuthenticationError(
+        f"docx-studio rejected the request (HTTP {status_code}): {err_body}",
+    )
+    error.http_status = status_code  # type: ignore[attr-defined]
+    return error
+
+
 def _delegation_headers() -> dict[str, str]:
     """The user a service-key caller acts for, as ``X-Custom-Attributions``.
 
@@ -934,9 +955,7 @@ def _http_post_json(
 
     err_body: str = resp.text
     if resp.status_code in (401, 403):
-        raise AuthenticationError(
-            f"docx-studio rejected the request (HTTP {resp.status_code}): {err_body}",
-        )
+        raise _rejected(resp.status_code, err_body)
     if resp.status_code == 404:
         raise NotFoundError(
             f"docx-studio returned HTTP 404: {err_body}",
@@ -1009,9 +1028,7 @@ def _http_get(
         return resp
     err_body: str = resp.text
     if resp.status_code in (401, 403):
-        raise AuthenticationError(
-            f"docx-studio rejected the request (HTTP {resp.status_code}): {err_body}",
-        )
+        raise _rejected(resp.status_code, err_body)
     if resp.status_code == 404:
         try:
             parsed: object = resp.json()
@@ -1084,13 +1101,82 @@ class HttpClient:
         base_url: str,
         api_key: str,
         session: requests.Session | None = None,
+        asset_tokens: TokenMinter | None = None,
+        token_asset_id: str | None = None,
     ) -> None:
+        """``api_key`` authenticates every call, except that with ``asset_tokens``
+        the calls on ``token_asset_id`` carry a token minted for that document
+        alone (``docx._asset_token``): read-only for a read, read-write for a
+        command batch."""
         self._base_url: str = base_url.rstrip("/")
         self._api_key: str = api_key
         self._session: requests.Session = session or _build_retry_session()
+        self._asset_tokens: TokenMinter | None = asset_tokens
+        self._token_asset_id: str | None = token_asset_id
         # Header/footer paragraph ids, for the ``block not found`` hint.
         self.header_footer_block_ids: set[str] = set()
 
+    def _bearer(
+        self, *, asset_id: str, access: str
+    ) -> tuple[str, tuple[StudioToken, str] | None]:
+        """The credential for a call on ``asset_id``: its token, else the key."""
+        minter = self._asset_tokens
+        if minter is None or asset_id != self._token_asset_id:
+            return self._api_key, None
+        try:
+            token = minter.token(asset_id=asset_id, access=access)
+        except SigningUnavailable as exc:
+            return self._without_asset_tokens(asset_id=asset_id, reason=str(exc)), None
+        return token.token, (token, access)
+
+    def _without_asset_tokens(self, *, asset_id: str, reason: str) -> str:
+        """Athena signs no asset tokens here (its 503): use the studio key from
+        now on when one is set, else raise an error that says what to set."""
+        studio_key = os.environ.get(STUDIO_KEY_ENV)
+        if not studio_key:
+            raise AuthenticationError(
+                f"Athena could not mint a DOCX Studio token for {asset_id}: "
+                f"{reason.rstrip('.')} (HTTP 503). Set {STUDIO_KEY_ENV} (or pass api_key=) "
+                "to an Athena API key DOCX Studio accepts."
+            )
+        self._asset_tokens = None
+        self._api_key = studio_key
+        return studio_key
+
+    def _with_token(
+        self, *, asset_id: str, access: str, send: Callable[[str], _T]
+    ) -> _T:
+        """``send(bearer)`` with the call's credential. A 401 to a minted token
+        is sent once more with a newly minted one: docx-studio refused it before
+        acting on it, so nothing is applied twice."""
+        bearer, grant = self._bearer(asset_id=asset_id, access=access)
+        try:
+            return send(bearer)
+        except AuthenticationError as exc:
+            minter = self._asset_tokens
+            if grant is None or minter is None or getattr(exc, "http_status", None) != 401:
+                raise
+            refused, granted_access = grant
+            minter.invalidate(token=refused, access=granted_access)
+            try:
+                fresh = minter.token(asset_id=asset_id, access=granted_access)
+            except SigningUnavailable:
+                raise exc from None
+            if fresh.token == refused.token:
+                raise
+        try:
+            return send(fresh.token)
+        except AuthenticationError as again:
+            if getattr(again, "http_status", None) != 401:
+                raise
+            raise AuthenticationError(
+                f"docx-studio refused the token Athena minted for {asset_id}, and the one "
+                f"minted again after that refusal too ({again}). DOCX Studio at "
+                f"{self._base_url} may belong to another Athena deployment than "
+                "ATHENA_API_URL; check both URLs, or set ATHENA_DOCX_API_KEY to an Athena "
+                "API key the studio accepts."
+            ) from again
+
     def close(self) -> None:
         """Release the pooled HTTP connections held by ``requests.Session``.
 
@@ -1285,13 +1371,18 @@ class HttpClient:
             body["changeMode"] = change_mode
         if user is not None:
             body["user"] = user
-        resp: dict = _http_post_json(
-            session=self._session,
-            url=url,
-            api_key=self._api_key,
-            body=body,
-            timeout=timeout_for_commands(commands=commands),
-            header_footer_block_ids=self.header_footer_block_ids,
+        # docx-studio's /commands needs edit access, for a batch of queries too.
+        resp: dict = self._with_token(
+            asset_id=asset_id,
+            access=EDIT,
+            send=lambda bearer: _http_post_json(
+                session=self._session,
+                url=url,
+                api_key=bearer,
+                body=body,
+                timeout=timeout_for_commands(commands=commands),
+                header_footer_block_ids=self.header_footer_block_ids,
+            ),
         )
         applied = resp.get("applied")
         # Commands the engine doesn't implement yet are reported in
@@ -1353,10 +1444,9 @@ class HttpClient:
         kind): a held read is then read again, so the read's own request
         reports what went wrong."""
         try:
-            resp = _http_get(
-                session=self._session,
-                url=self._doc_url(asset_id, "version"),
-                api_key=self._api_key,
+            resp = self._get(
+                asset_id,
+                "version",
                 params={"since": token},
                 timeout=VERSION_CHECK_TIMEOUT_SECONDS,
             )
@@ -1369,14 +1459,31 @@ class HttpClient:
     def _doc_url(self, asset_id: str, path: str) -> str:
         return f"{self._base_url}/docs/{urllib.parse.quote(asset_id, safe='')}/{path}"
 
+    def _get(
+        self,
+        asset_id: str,
+        path: str,
+        *,
+        params: dict[str, str] | None = None,
+        timeout: float = DEFAULT_OP_TIMEOUT_SECONDS,
+    ) -> requests.Response:
+        """``GET /docs/:id/<path>``, one of docx-studio's read-only routes (VIEW gate)."""
+        return self._with_token(
+            asset_id=asset_id,
+            access=VIEW,
+            send=lambda bearer: _http_get(
+                session=self._session,
+                url=self._doc_url(asset_id, path),
+                api_key=bearer,
+                params=params,
+                timeout=timeout,
+            ),
+        )
+
     def get_layout(self, asset_id: str) -> dict[str, Any]:
         """``GET /docs/:id/layout.json`` — the page count and page sizes as
         DOCX Studio's layout engine paginates the document (VIEW gate)."""
-        resp = _http_get(
-            session=self._session,
-            url=self._doc_url(asset_id, "layout.json"),
-            api_key=self._api_key,
-        )
+        resp = self._get(asset_id, "layout.json")
         try:
             data: object = resp.json()
         except ValueError as e:
@@ -1388,12 +1495,7 @@ class HttpClient:
     def render_page_png(self, asset_id: str, page_number: int, *, scale: float) -> RenderedPagePng:
         """``GET /docs/:id/pages/:n.png?scale=`` — one page (1-indexed) as PNG,
         from the same layout engine the editor paginates with (VIEW gate)."""
-        resp = _http_get(
-            session=self._session,
-            url=self._doc_url(asset_id, f"pages/{page_number}.png"),
-            api_key=self._api_key,
-            params={"scale": f"{scale:g}"},
-        )
+        resp = self._get(asset_id, f"pages/{page_number}.png", params={"scale": f"{scale:g}"})
         page_count_header = resp.headers.get("X-Page-Count", "")
         page_count = int(page_count_header) if page_count_header.isdigit() else 0
         return RenderedPagePng(png=resp.content, page_count=page_count)
@@ -1405,10 +1507,9 @@ class HttpClient:
         the plain export without ``X-Docx-Clean-Copy``: that is refused here,
         so an unclean copy never reaches the caller.
         """
-        resp = _http_get(
-            session=self._session,
-            url=self._doc_url(asset_id, "export.docx"),
-            api_key=self._api_key,
+        resp = self._get(
+            asset_id,
+            "export.docx",
             params={"clean": "1", **({"clearTitle": "1"} if clear_title else {})},
             timeout=LONG_RUNNING_COMMAND_TIMEOUT_SECONDS,
         )