athena-python-docx 0.5.0__tar.gz → 0.5.2__tar.gz

{athena_python_docx-0.5.0 → athena_python_docx-0.5.2}/CLAUDE.md

@@ -76,6 +76,44 @@ not file-backed. Each is documented in the relevant docstring.
   hits `POST {base_url}/docs/empty`. The constructor positional-arg
   shape (`Document(asset_id)`) is preserved for parity.
 
+- **`Document.save(path_or_stream=None)`** — argument is optional.
+  Stock python-docx requires it and `TypeError`s on no-arg, but in an
+  asset-backed SDK there is no local file to write — writes are always
+  in-place against the Y.Doc. Forcing the upstream signature broke
+  every agent invocation that reflexively called `doc.save()` (a
+  near-universal Python pattern), so we accept it for parity-friendly
+  call sites and ignore the value at runtime.
+
+- **`Document.track_revisions: bool`** — when `True`, all subsequent
+  mutations are recorded as tracked revisions instead of direct edits.
+  python-docx upstream has no top-level toggle (the closest is
+  hand-edited `<w:trackChanges/>` on `Document.settings.element`).
+  We expose this as a Document-level property because every SuperDoc
+  mutation accepts a per-call `changeMode` envelope field. The
+  python-docx-parity alias `Document.settings.track_revisions` reads
+  and writes the same flag so call sites that walk `doc.settings`
+  see consistent state.
+
+- **`Document.tracked_revisions()` context manager** — scope
+  `track_revisions=True` to a `with` block; restores the previous
+  value on exit (even on exception). Block-scoped track-changes is a
+  Pythonic ergonomic that doesn't exist in upstream python-docx
+  because the upstream package has no track-changes API at all.
+
+- **`Document.user_name: str | None` / `Document.user_email: str |
+  None`** — author identity threaded through to SuperDoc on session-
+  open for tracked-change attribution. python-docx's
+  `Document.core_properties.last_modified_by` is the closest upstream
+  surface; we use the SuperDoc-native fields directly because SuperDoc
+  bakes them into the change records.
+
+- **`Document.revisions: Revisions`** — collection of tracked changes
+  with iteration, `get(id)`, `accept_all()`, `reject_all()`,
+  `accept(id)`, `reject(id)`. Per-revision `Revision.accept()` /
+  `Revision.reject()` resolve a single change. python-docx upstream
+  has zero track-changes API, so this entire surface is an Athena
+  extension wired to SuperDoc's `doc.trackChanges.{list,get,decide}`.
+
 ### If you need a deviation
 
 If there is a genuine technical reason why a deviation from python-docx is necessary:

{athena_python_docx-0.5.0 → athena_python_docx-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.5.0
+Version: 0.5.2
 Summary: Drop-in replacement for python-docx that connects to Athena's Superdoc/Keryx collaborative document stack
 Project-URL: Homepage, https://athenaintelligence.ai
 Author-email: Athena Intelligence <engineering@athenaintelligence.ai>

{athena_python_docx-0.5.0 → athena_python_docx-0.5.2}/docx/__init__.py

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

{athena_python_docx-0.5.0 → athena_python_docx-0.5.2}/docx/_buffer.py

@@ -123,6 +123,13 @@ class CommandBuffer:
         self._timer: threading.Timer | None = None
         self._auto_flush_seconds: float = auto_flush_seconds
         self._closed: bool = False
+        # Track-changes envelope state — propagated as request-level
+        # ``changeMode`` and ``user`` on every batch. ``Document``
+        # mutates these via :meth:`set_change_mode` / :meth:`set_user`,
+        # which flush before changing so prior buffered ops keep their
+        # original semantics.
+        self._change_mode: str | None = None
+        self._user: dict[str, str] | None = None
         _register(self)
 
     @property
@@ -134,6 +141,55 @@ class CommandBuffer:
         with self._lock:
             return len(self._pending)
 
+    @property
+    def change_mode(self) -> str | None:
+        return self._change_mode
+
+    @property
+    def user(self) -> "dict[str, str] | None":
+        return None if self._user is None else dict(self._user)
+
+    def set_change_mode(self, mode: str | None) -> None:
+        """Set the batch-level change mode and flush prior pending ops.
+
+        Flushing first means commands queued under the previous mode
+        retain those semantics — switching modes mid-stream doesn't
+        retro-actively re-tag earlier mutations. ``mode`` is one of
+        ``"direct"``, ``"tracked"``, or ``None`` to clear.
+        """
+        if mode is not None and mode not in ("direct", "tracked"):
+            raise ValueError(
+                f"change_mode must be 'direct', 'tracked', or None; got {mode!r}"
+            )
+        with self._lock:
+            current = self._change_mode
+        if current == mode:
+            return
+        # Drain any queued commands with the *previous* mode before
+        # adopting the new one.
+        self.flush()
+        with self._lock:
+            self._change_mode = mode
+
+    def set_user(self, name: str | None, email: str | None = None) -> None:
+        """Set the batch-level user identity.
+
+        Sent on every commands request envelope. SuperDoc honors the
+        identity at session-open time only — subsequent batches against
+        a pooled session ignore the value, but the payload is still
+        included so a fresh session picks it up.
+        """
+        if name is None:
+            with self._lock:
+                self._user = None
+            return
+        if not name:
+            raise ValueError("user name must be a non-empty string")
+        with self._lock:
+            self._user = {"name": name}
+            if email:
+                self._user["email"] = email
+
     def call(self, cmd: Command) -> Any:
         """Execute or buffer ``cmd``.
 
@@ -167,9 +223,16 @@ class CommandBuffer:
             self._cancel_timer_locked()
             pending = self._pending
             self._pending = []
+            change_mode = self._change_mode
+            user = None if self._user is None else dict(self._user)
         if not pending:
             return []
-        return self._client.execute_batch(self._asset_id, pending)
+        return self._client.execute_batch(
+            self._asset_id,
+            pending,
+            change_mode=change_mode,
+            user=user,
+        )
 
     @contextmanager
     def batch(self) -> Generator[None, None, None]:
@@ -212,8 +275,15 @@ class CommandBuffer:
             self._cancel_timer_locked()
             pending = self._pending
             self._pending = []
+            change_mode = self._change_mode
+            user = None if self._user is None else dict(self._user)
         all_cmds: list[Command] = [*pending, cmd]
-        results: list[Any] = self._client.execute_batch(self._asset_id, all_cmds)
+        results: list[Any] = self._client.execute_batch(
+            self._asset_id,
+            all_cmds,
+            change_mode=change_mode,
+            user=user,
+        )
         if not results:
             return {}
         return results[-1]

{athena_python_docx-0.5.0 → athena_python_docx-0.5.2}/docx/_http_doc.py

@@ -103,6 +103,9 @@ from docx.commands import (
     TablesSetRowHeight,
     TablesSetStyle,
     TablesSetTableOptions,
+    TrackChangesDecide,
+    TrackChangesGet,
+    TrackChangesList,
 )
 from docx.errors import (
     AuthenticationError,
@@ -260,9 +263,23 @@ class HttpClient:
         self,
         asset_id: str,
         commands: list[Command],
+        *,
+        change_mode: str | None = None,
+        user: dict[str, str] | None = None,
     ) -> list[Any]:
         """POST a batch of typed commands, return per-command result dicts.
 
+        Envelope fields:
+            change_mode: ``"direct"`` | ``"tracked"`` | ``None``. When
+                set, the server injects this into every mutation
+                forwarded to SuperDoc — tracked edits land as
+                ``<w:ins>`` / ``<w:del>`` revisions instead of replacing
+                the underlying text.
+            user: ``{"name": ..., "email": ...}`` identity for
+                tracked-change attribution. Honored only when SuperDoc
+                opens the per-asset session for the first time; ignored
+                on subsequent batches against the same pooled session.
+
         On success, length matches len(commands). On 207 partial-failure,
         the server returns 207 with `applied` (the successful prefix) plus
         an `error` for the failing command — :func:`_http_post_json`
@@ -278,6 +295,10 @@ class HttpClient:
             "commands": [c.to_dict() for c in commands],
             "return": {"snapshot": False},
         }
+        if change_mode is not None:
+            body["changeMode"] = change_mode
+        if user is not None:
+            body["user"] = user
         resp: dict = _http_post_json(
             session=self._session,
             url=url,
@@ -396,6 +417,12 @@ _OP_TO_COMMAND: dict[str, type[Command]] = {
     "lists.merge": ListsMerge,
     "lists.split": ListsSplit,
     "selection.current": SelectionCurrent,
+    # Track Changes (Athena extension — see docx.revisions.Revisions).
+    # python-docx upstream has no track-changes API; the SDK exposes
+    # this as Document.revisions and Document.track_revisions.
+    "track_changes.list": TrackChangesList,
+    "track_changes.get": TrackChangesGet,
+    "track_changes.decide": TrackChangesDecide,
 }
 
 
@@ -423,6 +450,11 @@ _FIELD_RENAMES: dict[str, dict[str, str]] = {
     "create.paragraph": {"in": "in_"},
     "create.heading": {"in": "in_"},
     "create.table": {"in": "in_"},
+    # SuperDoc's track-changes-list filter is named `type:` on the wire
+    # (matching the rest of its API), but `type` is our Command
+    # discriminator. Rename to `change_type` on the Python side; the
+    # server applier renames back when calling SuperDoc.
+    "track_changes.list": {"type": "change_type", "in": "in_"},
 }
 
 

{athena_python_docx-0.5.0 → athena_python_docx-0.5.2}/docx/api.py

@@ -26,6 +26,9 @@ def Document(
     *,
     base_url: str | None = None,
     api_key: str | None = None,
+    user_name: str | None = None,
+    user_email: str | None = None,
+    track_revisions: bool = False,
 ) -> _Document:
     """Open a Word document for editing.
 
@@ -39,6 +42,15 @@ def Document(
               ``$ATHENA_DOCX_BASE_URL``.
         api_key: Athena API key / PropelAuth bearer. Falls back to
               ``$ATHENA_DOCX_API_KEY``.
+        user_name: (Athena extension) author identity for tracked
+              changes. Threaded through to SuperDoc on session-open;
+              ignored on subsequent requests against a pooled session.
+        user_email: (Athena extension) optional email for the
+              tracked-change author tooltip.
+        track_revisions: (Athena extension) start the document with
+              track-changes mode enabled. Equivalent to setting
+              :attr:`Document.track_revisions` to ``True`` after
+              construction.
 
     Returns:
         A Document instance bound to the asset.
@@ -59,6 +71,9 @@ def Document(
         asset_id=docx,
         http_base_url=base_url,
         http_api_key=api_key,
+        user_name=user_name,
+        user_email=user_email,
+        track_revisions=track_revisions,
     )
 
 

{athena_python_docx-0.5.0 → athena_python_docx-0.5.2}/docx/commands.py

@@ -622,6 +622,70 @@ class SelectionCurrent(Command):
     include_text: bool | None = None
 
 
+# ---------------------------------------------------------------------------
+# Track Changes
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class TrackChangesList(Command):
+    """List tracked changes (insertions, deletions, formatting marks).
+
+    Mirrors SuperDoc's ``doc.trackChanges.list``. The wire field for
+    "filter by change type" is ``type`` on SuperDoc's side; we send
+    ``changeType`` instead and the server applier renames in transit so
+    it doesn't collide with our top-level Command discriminator
+    (``type: "TrackChangesList"``).
+
+    ``in_`` accepts either the literal string ``"all"`` (apply across
+    every story — body, headers, footnotes, ...) or a story locator
+    dict ``{kind: "story", storyType, ...}``. Trailing-underscore on
+    the field name avoids the Python keyword collision; the
+    ``_snake_to_camel`` helper strips it for the wire.
+    """
+
+    change_type: str | None = None  # "insert" | "delete" | "format"
+    limit: int | None = None
+    offset: int | None = None
+    in_: dict[str, Any] | str | None = None
+
+
+@dataclass
+class TrackChangesGet(Command):
+    """Read a single tracked change by id.
+
+    Returns ``{address, id, type, author, authorEmail, date, excerpt,
+    wordRevisionIds?}``. ``story`` narrows the lookup to a specific
+    body/header/footnote scope when the change id might collide across
+    stories (rare, but supported).
+    """
+
+    id: str = ""
+    story: dict[str, Any] | None = None
+
+
+@dataclass
+class TrackChangesDecide(Command):
+    """Accept or reject one or all tracked changes.
+
+    Mirrors SuperDoc's ``doc.trackChanges.decide``. ``decision`` is
+    ``"accept"`` or ``"reject"``. ``target`` is either a single change
+    address (``{id, story?}``) or the bulk sentinel
+    (``{scope: "all"}``).
+
+    ``change_mode`` overrides the batch-level mode for *this one
+    decide* — useful when you want to decide a change that itself was
+    made under tracked mode without recursively producing more
+    changes. Default behaviour: omit and let SuperDoc apply ``direct``.
+    """
+
+    decision: str = "accept"  # "accept" | "reject"
+    target: dict[str, Any] = dataclasses.field(default_factory=dict)
+    force: bool | None = None
+    expected_revision: int | None = None
+    change_mode: str | None = None
+
+
 # ---------------------------------------------------------------------------
 # Helpers
 # ---------------------------------------------------------------------------
@@ -649,6 +713,9 @@ _QUERY_TYPES: frozenset[str] = frozenset(
         "HeaderFootersGet",
         "HeaderFootersResolve",
         "SelectionCurrent",
+        # Track-changes reads — never mutate, always flush.
+        "TrackChangesList",
+        "TrackChangesGet",
     }
 )
 
@@ -671,6 +738,10 @@ _RESPONSE_BEARING_TYPES: frozenset[str] = frozenset(
         # it in a Comment proxy.
         "CommentsCreate",
         "CommentsPatch",
+        # TrackChangesDecide returns {success, inserted, updated, removed}
+        # describing the entities affected by accept/reject — callers
+        # need that synchronously to invalidate their Revision proxies.
+        "TrackChangesDecide",
     }
 )
 
@@ -745,6 +816,10 @@ __all__ = [
     "TablesGetCells",
     "TablesGetProperties",
     "MarkdownToFragment",
+    # Track Changes
+    "TrackChangesList",
+    "TrackChangesGet",
+    "TrackChangesDecide",
     # Helpers
     "is_query",
     "is_response_bearing",

{athena_python_docx-0.5.0 → athena_python_docx-0.5.2}/docx/document.py

@@ -17,7 +17,8 @@ from __future__ import annotations
 import base64
 import io
 import sys
-from typing import TYPE_CHECKING, BinaryIO, Iterator
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, BinaryIO, Generator, Iterator
 
 from docx._batching import run_sync
 from docx.client import Session
@@ -34,6 +35,7 @@ if TYPE_CHECKING:
     from collections.abc import Sequence
 
     from docx.comments import Comment, Comments
+    from docx.revisions import Revisions
     from docx.shape import InlineShape
     from docx.styles.style import ParagraphStyle, TableStyle
     from docx.table import Table
@@ -57,6 +59,9 @@ class Document:
         asset_id: str,
         http_base_url: str | None = None,
         http_api_key: str | None = None,
+        user_name: str | None = None,
+        user_email: str | None = None,
+        track_revisions: bool = False,
     ) -> None:
         self._session: Session = Session(
             asset_id=asset_id,
@@ -65,6 +70,12 @@ class Document:
         )
         self._saved: bool = False
         self._closed: bool = False
+        # Track-changes state. Defaults are deferred to the buffer (set
+        # only when non-default) so existing callers retain the
+        # baseline "no envelope changeMode/user" behavior.
+        self._pending_user_name: str | None = user_name
+        self._pending_user_email: str | None = user_email
+        self._pending_track_revisions: bool = bool(track_revisions)
 
     @classmethod
     def create(
@@ -75,6 +86,9 @@ class Document:
         api_key: str | None = None,
         parent_folder_id: str | None = None,
         workspace_id: str | None = None,
+        user_name: str | None = None,
+        user_email: str | None = None,
+        track_revisions: bool = False,
     ) -> "Document":
         """Create a new SuperDocument asset and return an opened Document.
 
@@ -120,6 +134,9 @@ class Document:
             asset_id=result["asset_id"],
             http_base_url=base_url,
             http_api_key=api_key,
+            user_name=user_name,
+            user_email=user_email,
+            track_revisions=track_revisions,
         )
 
     # ---- Public properties ----
@@ -262,10 +279,16 @@ class Document:
 
     @property
     def settings(self):
-        """Return a minimal Settings proxy (stubbed; Superdoc doesn't surface app settings)."""
+        """Return a minimal Settings proxy.
+
+        Most Word app settings aren't surfaced by Superdoc.
+        ``Settings.track_revisions`` is wired through to
+        :attr:`Document.track_revisions` so python-docx-style call sites
+        (``doc.settings.track_revisions = True``) work end-to-end.
+        """
         from docx.settings import Settings
 
-        return Settings(session=self._session)
+        return Settings(session=self._session, document=self)
 
     @property
     def element(self):
@@ -274,6 +297,121 @@ class Document:
 
     part = element
 
+    # ---- Track changes (Athena extension — see docx.revisions) ----
+
+    @property
+    def track_revisions(self) -> bool:
+        """Whether subsequent mutations are recorded as tracked
+        revisions instead of direct edits.
+
+        Setting this to ``True`` flushes any pending buffered commands
+        (so they retain their previous semantics) before switching the
+        mode for new commands. Toggling repeatedly is safe — a no-op
+        when the value doesn't change.
+
+        DEVIATION FROM python-docx: upstream has no top-level
+        ``track_revisions`` property. The closest thing is
+        ``Document.settings.element`` carrying ``<w:trackChanges/>``.
+        We expose this as a Document-level toggle for ergonomics; the
+        ``Document.settings.track_revisions`` alias gives parity-
+        friendly call sites the same surface.
+        """
+        return self._pending_track_revisions
+
+    @track_revisions.setter
+    def track_revisions(self, value: bool) -> None:
+        new_value = bool(value)
+        if new_value == self._pending_track_revisions:
+            return
+        self._pending_track_revisions = new_value
+        # If the session is open, push immediately so subsequent
+        # mutations land under the new mode. Otherwise the value is
+        # captured and synced at session-open time.
+        buffer = self._buffer()
+        if buffer is not None:
+            buffer.set_change_mode("tracked" if new_value else None)
+
+    @contextmanager
+    def tracked_revisions(self) -> "Generator[None, None, None]":
+        """Scope ``track_revisions=True`` to a ``with`` block.
+
+        Restores the previous value (typically ``False``) on exit, even
+        if the body raises. Useful for "make these specific edits as
+        tracked changes" without leaking the mode to surrounding code::
+
+            with doc.tracked_revisions():
+                doc.add_paragraph("Reviewer note: please verify.")
+                # ...
+
+        The mode change forces a buffer flush at entry and exit, so
+        prior buffered ops keep their original mode.
+        """
+        previous: bool = self._pending_track_revisions
+        self.track_revisions = True
+        try:
+            yield
+        finally:
+            self.track_revisions = previous
+
+    @property
+    def user_name(self) -> "str | None":
+        """The author identity threaded through to SuperDoc on
+        session-open, used for tracked-change attribution.
+
+        ``None`` means "fall back to the docx-studio service account".
+        Setting after the session is open does not retro-actively
+        rename existing changes — SuperDoc honors the value at session
+        creation.
+        """
+        return self._pending_user_name
+
+    @user_name.setter
+    def user_name(self, value: "str | None") -> None:
+        if value is not None and not isinstance(value, str):
+            raise ValidationError(
+                f"user_name must be a string or None; got {type(value)!r}"
+            )
+        self._pending_user_name = value or None
+        buffer = self._buffer()
+        if buffer is not None:
+            buffer.set_user(self._pending_user_name, self._pending_user_email)
+
+    @property
+    def user_email(self) -> "str | None":
+        """Optional email displayed alongside the author name in
+        tracked-change tooltips. Same lifecycle caveats as
+        :attr:`user_name`."""
+        return self._pending_user_email
+
+    @user_email.setter
+    def user_email(self, value: "str | None") -> None:
+        if value is not None and not isinstance(value, str):
+            raise ValidationError(
+                f"user_email must be a string or None; got {type(value)!r}"
+            )
+        self._pending_user_email = value or None
+        buffer = self._buffer()
+        if buffer is not None:
+            buffer.set_user(self._pending_user_name, self._pending_user_email)
+
+    @property
+    def revisions(self) -> "Revisions":
+        """Return the document's tracked-changes collection.
+
+        Iterating yields :class:`docx.revisions.Revision` proxies.
+        Bulk-resolve via :meth:`Revisions.accept_all` /
+        :meth:`Revisions.reject_all`; per-change resolve via
+        :meth:`Revision.accept` / :meth:`Revision.reject`.
+
+        DEVIATION FROM python-docx: upstream has no track-changes API
+        whatsoever. This is an Athena extension wired to SuperDoc's
+        ``doc.trackChanges.{list,get,decide}``.
+        """
+        from docx.revisions import Revisions
+
+        self._ensure_open()
+        return Revisions(session=self._session)
+
     # ---- Comments (stubbed — see docx-studio/PYTHON_DOCX_PARITY_GAPS.md § 3.1) ----
 
     @property
@@ -661,15 +799,20 @@ class Document:
         run_sync(self._session.save(in_place=True))
         self._saved = True
 
-    def save(self, path_or_stream: "str | BinaryIO") -> None:  # noqa: ARG002
+    def save(self, path_or_stream: "str | BinaryIO | None" = None) -> None:  # noqa: ARG002
         """Flush pending edits to Keryx.
 
-        ``path_or_stream`` matches python-docx's ``Document.save`` signature
-        and is required to match the upstream contract — calling
-        ``save()`` with no argument is a TypeError, just like python-docx.
-        The argument is accepted but ignored at runtime: writes are always
-        in-place against the Y.Doc. To export to a local file, use the
-        Olympus UI's Export DOCX.
+        Intentional deviation from python-docx: ``path_or_stream`` is
+        optional. Stock python-docx requires it and raises ``TypeError``
+        on ``save()`` no-arg, but in this asset-backed SDK there is no
+        local file to write to — writes are always in-place against the
+        Y.Doc. Agent-generated code reflexively calls ``doc.save()`` and
+        forcing the upstream signature broke every such invocation
+        (`Untitled Word Document` session
+        ``thread_3f6b59e0-ae25-4f6e-8391-c286b17a3334``). The argument
+        is accepted for parity-friendly call sites but ignored at
+        runtime. To export to a local file, use the Olympus UI's
+        Export DOCX.
         """
         self._flush()
 
@@ -688,9 +831,9 @@ class Document:
     def __exit__(self, exc_type, exc_val, exc_tb) -> None:  # noqa: ANN001
         if exc_type is None and not self._saved and self._session.is_open:
             try:
-                # Use _flush(), not save() — python-docx requires
-                # save(path_or_stream); the context-manager path has no
-                # path to forward, so it drains internally.
+                # Drain via _flush() directly — save() works no-arg as
+                # an intentional deviation, but skipping it avoids the
+                # public-API hop on the autosave path.
                 self._flush()
             except Exception as e:
                 _log_warn(f"autosave failed for {self._session.asset_id}: {e}")
@@ -705,6 +848,36 @@ class Document:
             )
         if not self._session.is_open:
             run_sync(self._session.open())
+            # Propagate pending track-changes state to the freshly-built
+            # buffer. Done here (and not at construction) because the
+            # buffer doesn't exist until session.open() runs.
+            self._sync_track_changes_state()
+
+    def _buffer(self):
+        """Return the live :class:`CommandBuffer`, or ``None`` if the
+        session hasn't been opened yet."""
+        handle = getattr(self._session, "_doc_handle", None)
+        return getattr(handle, "buffer", None) if handle is not None else None
+
+    def _sync_track_changes_state(self) -> None:
+        """Push pending track-changes state into the buffer.
+
+        Called when the session is opened (deferred init) and on
+        subsequent property setters. Idempotent — applying twice with
+        the same values is cheap (the buffer skips the flush when the
+        value didn't change).
+        """
+        buffer = self._buffer()
+        if buffer is None:
+            return
+        if self._pending_user_name is not None or self._pending_user_email is not None:
+            buffer.set_user(
+                self._pending_user_name,
+                self._pending_user_email,
+            )
+        buffer.set_change_mode(
+            "tracked" if self._pending_track_revisions else None
+        )
 
 
 # ---- Module-level helpers ----