athena-python-pptx 0.1.80__tar.gz → 0.2.0__tar.gz

{athena_python_pptx-0.1.80 → athena_python_pptx-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-pptx
-Version: 0.1.80
+Version: 0.2.0
 Summary: Drop-in replacement for python-pptx that connects to PPTX Studio for real-time collaboration
 Project-URL: Homepage, https://github.com/pptx-studio/python-sdk
 Project-URL: Documentation, https://docs.pptx-studio.com/sdk/python

{athena_python_pptx-0.1.80 → athena_python_pptx-0.2.0}/docs/API_PARITY_EXCEPTIONS.md

@@ -324,6 +324,28 @@ prs.batch():` that fills it (see the skill prompt). When `add_slide()`
 runs outside the batch it flushes its own command, and a subsequent
 failed batch leaves the empty slide on the deck.
 
+### `<p:style><a:fontRef>` scheme is luminance-derived, not always `lt1`
+
+Upstream python-pptx hardcodes `<a:fontRef idx="minor"><a:schemeClr val="lt1"/></a:fontRef>`
+in the `<p:style>` block of every shape it creates. That fontRef is the
+default text color resolved by PowerPoint when a run carries no explicit
+`<a:rPr><a:solidFill>`, and `lt1` is white — so any shape that was filled
+with a light color (white, pale grey, pale red) rendered invisible text
+in PowerPoint. The bug surfaces on every cover-page logo box, agenda
+description, and disclaimer banner that LLM-authored code produces.
+
+Starting with the matching export-worker version, the SDK picks the
+fontRef scheme based on the shape's fill luminance: `dk1` (black) when
+the fill is light (sRGB luminance ≥ 0.55), `lt1` (white) otherwise. When
+no `fill_color_hex` is supplied the emitter still falls back to `lt1`
+for byte-stable parity with prior round-trips.
+
+This is an export-side behavior change, not an API change — callers who
+were already setting explicit run colors via `run.font.color.rgb` keep
+binary-identical output. The luminance-derived `<p:style>` only matters
+for shapes that rely on the shape preset style for their default text
+color, which is exactly the failure mode the change is intended to fix.
+
 ### Background `CommandBuffer._deferred_error` propagation
 
 Not a user-facing API; documented here because it changes the visible
@@ -746,3 +768,60 @@ slide.shapes.add_picture(
 The default `fit=None` preserves stock python-pptx behaviour. The only
 other accepted value is `"contain"`; passing anything else raises
 `ValueError` to fail loudly rather than silently no-op.
+
+---
+
+## `Shapes.add_linked_table()` — Athena studio-linking extension (added in Phase 3)
+
+Authors a **native PPT table** (`<a:tbl>`) whose cells are materialized
+from an Athena source asset's anchor range at insert time. Unlike
+``add_linked_ole_object``, which produces a frozen Excel preview /
+embedding pair, this produces a real PowerPoint table that's
+selectable, editable, and natively styled — but still carries a
+``SourceBinding`` so refresh can re-pull current values from the
+source spreadsheet.
+
+This method has no python-pptx counterpart — python-pptx has no
+concept of Athena asset references. Use ``add_table()`` (which IS in
+python-pptx) for unlinked tables.
+
+```python
+from pptx._references import (
+    AssetReference,
+    SheetTableAnchor,
+    VersionPolicyLatest,
+)
+from pptx.util import Inches
+
+slide.shapes.add_linked_table(
+    source=AssetReference(id='asset_xlsx_abc123'),
+    anchor=SheetTableAnchor(
+        sheet_id=0,
+        table_name='SalesQ4',
+        fallback_range='A1:F50',
+    ),
+    left=Inches(1),
+    top=Inches(1),
+    width=Inches(8),
+    height=Inches(4),
+    freshness_mode='athena_refreshable',  # default
+    version_policy=VersionPolicyLatest(),  # default
+)
+```
+
+Prefer ``SheetTableAnchor`` over ``SheetRangeAnchor`` whenever the
+source is an Excel named table — the table's ``displayName`` survives
+sorts, inserts, and row additions that would shift an A1 range.
+
+**Returns:** a ``GraphicFrame`` wrapping a ``Table`` proxy whose
+``rows`` / ``cols`` start at ``0`` on the client side. The materialized
+dimensions live on the server; fetch the deck snapshot if you need to
+iterate cells programmatically.
+
+**Refresh flow:** call the GraphQL ``refreshSourceBinding`` mutation
+(or the Olympus "Refresh from source" UI action). The server
+re-materializes the source range and writes the new cell values into
+the same table element on the Y.Doc.
+
+**`freshness_mode='office_live_link'` is reserved for Phase 5** and
+currently raises ``ValueError`` locally.

{athena_python_pptx-0.1.80 → athena_python_pptx-0.2.0}/pptx/__init__.py

@@ -132,7 +132,7 @@ def flush_all() -> None:
     _active_buffers[:] = alive
 
 
-__version__ = "0.1.80"
+__version__ = "0.2.0"
 
 __all__ = [
     # Main entry point

athena_python_pptx-0.2.0/pptx/_athena_extension.py

@@ -0,0 +1,374 @@
+"""Marker decorator + audit helpers for Athena extensions beyond
+upstream python-pptx.
+
+This SDK aims to be a 100% drop-in replacement for upstream
+[python-pptx](https://python-pptx.readthedocs.io/) — every public
+class, method, property, and parameter name mirrors the upstream API.
+Anything that exists in **athena-python-pptx** but NOT in upstream
+python-pptx is an **Athena extension** and must be:
+
+1. Documented in ``docs/API_PARITY_EXCEPTIONS.md`` for the human-readable
+   rationale (motivation, design notes).
+2. Marked at runtime with :func:`athena_extension` — so introspection
+   tooling (parity audits, docs generation, IDE plugins) can identify
+   the addition without grepping prose, and so the
+   :func:`iter_athena_extensions` walker can enumerate every addition
+   in one place.
+
+The decorator stamps the wrapped object with introspectable attributes:
+
+* ``__athena_extension__`` — always ``True``
+* ``__athena_extension_issue__`` — upstream issue ref, e.g.
+  ``"python-pptx#123"`` or ``"Athena"`` for SDK-native additions
+* ``__athena_extension_description__`` — one-line summary
+* ``__athena_extension_since__`` — athena-python-pptx SDK version that
+  introduced the surface
+
+A pre-existing :func:`pptx.decorators.athena_only` decorator exists for
+back-compat — that decorator is now a thin compat shim around
+:func:`athena_extension` so every call site stays valid.
+
+Apply at every Athena-extension layer:
+
+* **Class** — decorator on the ``class`` statement::
+
+    @athena_extension(description="HTTP command buffer (REST-SDK only)")
+    class CommandBuffer: ...
+
+* **Method / function** — decorator on the ``def`` statement::
+
+    @athena_extension(description="Presentation.render_slide — PNG render")
+    def render_slide(self, slide_index, scale=1.0): ...
+
+* **Classmethod** — decorator goes inside ``@classmethod``::
+
+    @classmethod
+    @athena_extension(description="Asset-backed Presentation factory")
+    def create(cls, name, ...): ...
+
+* **Property** — decorator on the **getter** (before ``@property``)::
+
+    @property
+    @athena_extension(description="Athena asset id alias for deck_id")
+    def asset_id(self): ...
+
+* **Module-level constant** — for whole modules that are entirely
+  Athena extensions, set at top of file::
+
+    __athena_extension_module__ = True
+    __athena_extension_description__ = "HTTP wire layer (REST-SDK only)"
+
+  The walker picks these up alongside per-member markers.
+
+The decorator is import-time-cheap, has no runtime overhead at call
+sites (it returns the original object after stamping), and never
+modifies docstrings or signatures.
+
+Mirror of ``docx-studio/python-sdk/docx/_athena_extension.py`` (kept
+in sync across docx-studio / xlsx-studio / pptx-studio SDKs so tooling
+can walk all three the same way).
+"""
+
+from __future__ import annotations
+
+import importlib
+import pkgutil
+from typing import Any, Callable, Iterator, TypeVar
+
+
+# Attribute names — kept as module constants so audits and tests can
+# reference them without re-typing the string everywhere.
+ATHENA_EXTENSION_ATTR: str = "__athena_extension__"
+ATHENA_EXTENSION_ISSUE_ATTR: str = "__athena_extension_issue__"
+ATHENA_EXTENSION_DESCRIPTION_ATTR: str = "__athena_extension_description__"
+ATHENA_EXTENSION_SINCE_ATTR: str = "__athena_extension_since__"
+
+ATHENA_EXTENSION_MODULE_ATTR: str = "__athena_extension_module__"
+
+# Default ``since`` value for new additions. Pre-existing extensions
+# carry their original since values explicitly.
+_DEFAULT_SINCE: str = "0.1.80"
+
+
+T = TypeVar("T")
+
+
+def athena_extension(
+    *,
+    issue: int | str | None = None,
+    description: str = "",
+    since: str = _DEFAULT_SINCE,
+) -> Callable[[T], T]:
+    """Decorator that marks a class / function / method as an Athena
+    extension beyond upstream python-pptx.
+
+    Stamps four introspectable attributes on the wrapped object:
+
+    - ``__athena_extension__`` — always ``True``
+    - ``__athena_extension_issue__`` — ``"python-pptx#<n>"`` when ``issue``
+      is an int; passed through verbatim when a string; ``None`` when
+      omitted
+    - ``__athena_extension_description__`` — ``description``
+    - ``__athena_extension_since__`` — ``since``
+
+    Returns the original object unchanged (apart from the new
+    attributes), so call sites pay zero runtime cost.
+
+    For properties, decorate the underlying getter (and setter) BEFORE
+    ``@property`` so the markers stick to ``prop.fget`` / ``prop.fset``::
+
+        @property
+        @athena_extension(description="Athena asset id alias")
+        def asset_id(self): ...
+    """
+    issue_value: str | None
+    if issue is None:
+        issue_value = None
+    elif isinstance(issue, int):
+        issue_value = f"python-pptx#{issue}"
+    else:
+        issue_value = str(issue)
+
+    def decorator(obj: T) -> T:
+        try:
+            setattr(obj, ATHENA_EXTENSION_ATTR, True)
+            if issue_value is not None:
+                setattr(obj, ATHENA_EXTENSION_ISSUE_ATTR, issue_value)
+            if description:
+                setattr(obj, ATHENA_EXTENSION_DESCRIPTION_ATTR, description)
+            setattr(obj, ATHENA_EXTENSION_SINCE_ATTR, since)
+        except (AttributeError, TypeError) as exc:
+            raise TypeError(
+                f"@athena_extension cannot be applied to "
+                f"{type(obj).__name__} — built-in descriptor rejects "
+                f"setattr. For properties, decorate the underlying "
+                f"getter/setter function BEFORE @property:\n\n"
+                f"    @property\n"
+                f"    @athena_extension(...)\n"
+                f"    def my_prop(self): ...\n",
+            ) from exc
+        return obj
+
+    return decorator
+
+
+def is_athena_extension(obj: Any) -> bool:
+    """Return ``True`` if ``obj`` is marked as an Athena extension.
+
+    Handles the property-wrapping case: a ``property`` descriptor
+    proxies to its ``fget`` (and ``fset``) — either marker counts.
+
+    Also recognises the legacy ``@athena_only`` marker
+    (``_athena_only`` attribute set by :mod:`pptx.decorators`) so
+    surfaces decorated before the migration still show up.
+    """
+    if getattr(obj, ATHENA_EXTENSION_ATTR, False):
+        return True
+    if getattr(obj, "_athena_only", False):
+        return True
+    if isinstance(obj, property):
+        if obj.fget is not None and (
+            getattr(obj.fget, ATHENA_EXTENSION_ATTR, False)
+            or getattr(obj.fget, "_athena_only", False)
+        ):
+            return True
+        if obj.fset is not None and (
+            getattr(obj.fset, ATHENA_EXTENSION_ATTR, False)
+            or getattr(obj.fset, "_athena_only", False)
+        ):
+            return True
+    return False
+
+
+def athena_extension_metadata(obj: Any) -> dict[str, Any] | None:
+    """Return a dict of marker attributes for ``obj``, or ``None`` if
+    it isn't an Athena extension.
+
+    Surfaces decorated with the legacy ``@athena_only`` marker that
+    haven't been migrated to ``@athena_extension`` yet are recognised
+    via their ``_athena_only`` / ``_athena_description`` /
+    ``_athena_since`` attributes.
+    """
+    target: Any = obj
+    if isinstance(obj, property):
+        for candidate in (obj.fget, obj.fset):
+            if candidate is None:
+                continue
+            if (
+                getattr(candidate, ATHENA_EXTENSION_ATTR, False)
+                or getattr(candidate, "_athena_only", False)
+            ):
+                target = candidate
+                break
+        else:
+            return None
+
+    if getattr(target, ATHENA_EXTENSION_ATTR, False):
+        return {
+            "issue": getattr(target, ATHENA_EXTENSION_ISSUE_ATTR, None),
+            "description": getattr(target, ATHENA_EXTENSION_DESCRIPTION_ATTR, ""),
+            "since": getattr(target, ATHENA_EXTENSION_SINCE_ATTR, None),
+        }
+    if getattr(target, "_athena_only", False):
+        # Legacy marker from pptx.decorators.athena_only — translate.
+        return {
+            "issue": None,
+            "description": getattr(target, "_athena_description", "") or "",
+            "since": getattr(target, "_athena_since", None),
+        }
+    return None
+
+
+def iter_athena_extensions(package: str = "pptx") -> Iterator[dict[str, Any]]:
+    """Walk every submodule of ``package`` and yield one record per
+    Athena extension found.
+
+    Records have shape::
+
+        {
+            "kind": "module" | "class" | "function" | "method" |
+                    "property" | "classmethod" | "staticmethod",
+            "location": "pptx.presentation.Presentation.create",
+            "issue": "python-pptx#123" | "Athena" | None,
+            "description": "Asset-backed factory",
+            "since": "0.1.80",
+        }
+
+    Recognises both the new ``@athena_extension`` marker AND the
+    pre-existing ``@athena_only`` marker so surfaces decorated before
+    the migration still surface in the registry.
+    """
+    try:
+        root = importlib.import_module(package)
+    except ImportError:
+        return
+
+    if getattr(root, ATHENA_EXTENSION_MODULE_ATTR, False):
+        yield {
+            "kind": "module",
+            "location": package,
+            "issue": getattr(root, ATHENA_EXTENSION_ISSUE_ATTR, None),
+            "description": getattr(root, ATHENA_EXTENSION_DESCRIPTION_ATTR, ""),
+            "since": getattr(root, ATHENA_EXTENSION_SINCE_ATTR, None),
+        }
+    yield from _iter_module_members(root, package)
+
+    if not hasattr(root, "__path__"):
+        return
+
+    for _finder, sub_name, _ispkg in pkgutil.walk_packages(
+        root.__path__, prefix=f"{package}.",
+    ):
+        try:
+            sub = importlib.import_module(sub_name)
+        except Exception:  # noqa: BLE001 — broken submodule, skip.
+            continue
+        if getattr(sub, ATHENA_EXTENSION_MODULE_ATTR, False):
+            yield {
+                "kind": "module",
+                "location": sub_name,
+                "issue": getattr(sub, ATHENA_EXTENSION_ISSUE_ATTR, None),
+                "description": getattr(sub, ATHENA_EXTENSION_DESCRIPTION_ATTR, ""),
+                "since": getattr(sub, ATHENA_EXTENSION_SINCE_ATTR, None),
+            }
+        yield from _iter_module_members(sub, sub_name)
+
+
+def _is_marked(obj: Any) -> bool:
+    return (
+        getattr(obj, ATHENA_EXTENSION_ATTR, False)
+        or getattr(obj, "_athena_only", False)
+    )
+
+
+def _iter_module_members(
+    module: Any, module_name: str,
+) -> Iterator[dict[str, Any]]:
+    """Walk ``vars(module)`` and yield extension records for top-level
+    callables / classes. For each class, recurse into its members.
+
+    Underscore-prefixed *classes* ARE walked — python-pptx uses
+    leading-underscore class names for collection types that are part
+    of the public API. Underscore-prefixed *functions* / module attrs
+    are treated as private and skipped.
+    """
+    seen_classes: set[int] = set()
+    for attr_name, attr in vars(module).items():
+        is_class = isinstance(attr, type)
+        if attr_name.startswith("_") and not is_class:
+            continue
+        if not is_class and _is_marked(attr):
+            kind = "command" if attr_name[0:1].isupper() else "function"
+            meta = athena_extension_metadata(attr) or {}
+            yield {
+                "kind": kind,
+                "location": f"{module_name}.{attr_name}",
+                **meta,
+            }
+        if is_class:
+            qual = getattr(attr, "__qualname__", attr_name)
+            mod_of_class = getattr(attr, "__module__", "")
+            if mod_of_class and mod_of_class != module_name:
+                continue
+            if id(attr) in seen_classes:
+                continue
+            seen_classes.add(id(attr))
+            if _is_marked(attr):
+                meta = athena_extension_metadata(attr) or {}
+                yield {
+                    "kind": "class",
+                    "location": f"{module_name}.{qual}",
+                    **meta,
+                }
+            yield from _iter_class_members(attr, module_name, qual)
+
+
+def _iter_class_members(
+    cls: type, module_name: str, class_qualname: str,
+) -> Iterator[dict[str, Any]]:
+    """Yield records for marked methods / properties on ``cls``.
+
+    Handles three wrapped-callable cases the bare attribute lookup
+    would miss:
+
+    * ``property`` — read marker from ``fget`` / ``fset``.
+    * ``classmethod`` — marker lives on ``__func__``.
+    * ``staticmethod`` — marker lives on ``__func__``.
+    """
+    for member_name, member in vars(cls).items():
+        if member_name.startswith("_"):
+            continue
+        probe: Any = member
+        if isinstance(member, (classmethod, staticmethod)):
+            probe = member.__func__
+        meta = athena_extension_metadata(probe)
+        if meta is None and probe is not member:
+            meta = athena_extension_metadata(member)
+        if meta is None:
+            continue
+        if isinstance(member, property):
+            kind = "property"
+        elif isinstance(member, classmethod):
+            kind = "classmethod"
+        elif isinstance(member, staticmethod):
+            kind = "staticmethod"
+        else:
+            kind = "method"
+        yield {
+            "kind": kind,
+            "location": f"{module_name}.{class_qualname}.{member_name}",
+            **meta,
+        }
+
+
+__all__ = [
+    "athena_extension",
+    "is_athena_extension",
+    "athena_extension_metadata",
+    "iter_athena_extensions",
+    "ATHENA_EXTENSION_ATTR",
+    "ATHENA_EXTENSION_ISSUE_ATTR",
+    "ATHENA_EXTENSION_DESCRIPTION_ATTR",
+    "ATHENA_EXTENSION_SINCE_ATTR",
+    "ATHENA_EXTENSION_MODULE_ATTR",
+]

{athena_python_pptx-0.1.80 → athena_python_pptx-0.2.0}/pptx/_ptc.py

@@ -31,6 +31,12 @@ of stdlib code is cheaper than spinning up a 4th release pipeline.
 
 from __future__ import annotations
 
+__athena_extension_module__: bool = True
+__athena_extension_description__: str = (
+    "Programmatic Tool Calling (Daytona sandbox event emission)."
+)
+__athena_extension_since__: str = "0.1.0"
+
 import json
 import os
 import time

{athena_python_pptx-0.1.80 → athena_python_pptx-0.2.0}/pptx/_references.py

@@ -16,6 +16,12 @@ Note (Athena extension):
 
 from __future__ import annotations
 
+__athena_extension_module__: bool = True
+__athena_extension_description__: str = (
+    "Cross-studio asset reference types (Athena studio-linking, no upstream)."
+)
+__athena_extension_since__: str = "0.1.71"
+
 from dataclasses import dataclass, field
 from typing import Any, Literal, Optional
 

{athena_python_pptx-0.1.80 → athena_python_pptx-0.2.0}/pptx/batching.py

@@ -6,6 +6,13 @@ context manager interface for batch operations.
 """
 
 from __future__ import annotations
+
+__athena_extension_module__: bool = True
+__athena_extension_description__: str = (
+    "Command buffer + batching helpers (REST-SDK only)."
+)
+__athena_extension_since__: str = "0.1.0"
+
 import threading
 from contextlib import contextmanager
 from threading import local