athena-python-docx 0.2.2__tar.gz → 0.2.3__tar.gz

{athena_python_docx-0.2.2 → athena_python_docx-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: athena-python-docx
-Version: 0.2.2
+Version: 0.2.3
 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.2.2 → athena_python_docx-0.2.3}/docx/__init__.py

@@ -6,7 +6,7 @@ See CLAUDE.md for the API parity contract.
 
 from __future__ import annotations
 
-__version__ = "0.2.2"
+__version__ = "0.2.3"
 
 from docx.api import Document
 # Re-exports python-docx ships at docx top-level for convenience.

{athena_python_docx-0.2.2 → athena_python_docx-0.2.3}/docx/document.py

@@ -115,7 +115,6 @@ class Document:
     @property
     def sections(self):
         """Return the document's sections collection."""
-        from docx.section import Sections
 
         self._ensure_open()
         return Sections(session=self._session)
@@ -397,8 +396,6 @@ class Document:
         Mirrors python-docx: creating a section adds a trailing empty
         paragraph that marks the section boundary.
         """
-        from docx.enum.section import WD_SECTION_START
-        from docx.section import Section
 
         self._ensure_open()
         # python-docx always inserts an anchor paragraph at the section break

{athena_python_docx-0.2.2 → athena_python_docx-0.2.3}/docx/section.py

@@ -14,7 +14,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 from docx._batching import run_sync
-from docx.shared import Emu, Length, Pt
+from docx.shared import Length, Pt
 
 if TYPE_CHECKING:
     from docx.client import Session

{athena_python_docx-0.2.2 → athena_python_docx-0.2.3}/docx/shape.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 from docx._batching import run_sync
-from docx.shared import Emu, Length, Pt
+from docx.shared import Length, Pt
 
 if TYPE_CHECKING:
     from docx.client import Session

{athena_python_docx-0.2.2 → athena_python_docx-0.2.3}/docx/text/parfmt.py

@@ -14,7 +14,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 from docx._batching import run_sync
-from docx.shared import Length, Pt, Twips
+from docx.shared import Length, Twips
 
 if TYPE_CHECKING:
     from docx.enum.text import WD_ALIGN_PARAGRAPH, WD_LINE_SPACING

{athena_python_docx-0.2.2 → athena_python_docx-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "athena-python-docx"
-version = "0.2.2"
+version = "0.2.3"
 description = "Drop-in replacement for python-docx that connects to Athena's Superdoc/Keryx collaborative document stack"
 readme = "README.md"
 license = "MIT"

athena_python_docx-0.2.3/scripts/release.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# Tag + push a new athena-python-docx release. CI handles the rest:
+# PyPI publish, Docker image rebuild, Daytona snapshot creation, Doppler
+# flip in agora dev + stg. See
+# .github/workflows/athena-python-docx-release.yml for the full flow.
+#
+# Usage:
+#   ./scripts/release.sh <version>
+#
+# e.g. ./scripts/release.sh 0.2.3 — releases athena-python-docx==0.2.3
+# by:
+#   1. Updating pyproject.toml + docx/__init__.py
+#   2. Committing the version bump
+#   3. Tagging athena-python-docx-v<version>
+#   4. Pushing the commit + tag to origin
+#
+# CI trigger fires on the tag push and runs the full release pipeline.
+
+set -euo pipefail
+
+if [ $# -ne 1 ]; then
+  echo "Usage: $0 <version> (e.g., 0.2.3)" >&2
+  exit 1
+fi
+
+VERSION="$1"
+if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(\.(dev|rc|a|b)[0-9]+)?$ ]]; then
+  echo "ERROR: version '$VERSION' is not a valid semver-ish" >&2
+  exit 1
+fi
+
+SDK_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+REPO_ROOT="$(git -C "$SDK_DIR" rev-parse --show-toplevel)"
+
+# Require clean working tree so the commit captures only the version bump.
+if ! git -C "$REPO_ROOT" diff --quiet || ! git -C "$REPO_ROOT" diff --cached --quiet; then
+  echo "ERROR: working tree is dirty. Commit or stash first." >&2
+  git -C "$REPO_ROOT" status --short >&2
+  exit 1
+fi
+
+# Bump pyproject.toml
+sed -i.bak "s/^version = \".*\"/version = \"$VERSION\"/" "$SDK_DIR/pyproject.toml"
+rm -f "$SDK_DIR/pyproject.toml.bak"
+
+# Bump docx/__init__.py
+sed -i.bak "s/^__version__ = \".*\"/__version__ = \"$VERSION\"/" "$SDK_DIR/docx/__init__.py"
+rm -f "$SDK_DIR/docx/__init__.py.bak"
+
+# Show the diff so the operator sees what will be committed.
+echo "=== Version bump diff ==="
+git -C "$REPO_ROOT" diff "$SDK_DIR/pyproject.toml" "$SDK_DIR/docx/__init__.py"
+echo "========================="
+
+TAG="athena-python-docx-v$VERSION"
+
+# Commit + tag + push.
+git -C "$REPO_ROOT" add "$SDK_DIR/pyproject.toml" "$SDK_DIR/docx/__init__.py"
+git -C "$REPO_ROOT" commit -m "chore(docx-sdk): bump version to $VERSION"
+git -C "$REPO_ROOT" tag "$TAG"
+git -C "$REPO_ROOT" push
+git -C "$REPO_ROOT" push origin "$TAG"
+
+cat <<EOF
+
+Tagged $TAG and pushed. CI is now running the full release pipeline:
+
+  1. PyPI publish        → https://pypi.org/project/athena-python-docx/$VERSION/
+  2. Docker image rebuild → athenaintel/daytona-document:$VERSION
+  3. Daytona snapshot    → document-exec:$VERSION
+  4. Doppler flip        → agora/dev + agora/stg
+
+Watch the run:
+  https://github.com/Athena-Intel/demo-app-monorepo/actions/workflows/athena-python-docx-release.yml
+
+For prd rollout, after canary verification:
+  doppler secrets set --project agora --config prd \\
+    DAYTONA_DOCUMENT_EXEC_SNAPSHOT=document-exec:$VERSION
+
+EOF

athena_python_docx-0.2.3/tests/fidelity/auto_gen_cases.py

@@ -0,0 +1,260 @@
+"""Auto-generate test cases from python-docx's public API surface.
+
+For every `(ClassName, method_or_property)` pair python-docx exposes that
+our SDK claims to support, emit a minimum-viable test case that:
+  - constructs the relevant object (via a small set of hand-written fixtures)
+  - invokes the method / sets the property
+  - asserts no exception is raised
+
+The generated cases live in memory; run via `auto_gen_cases.run_all`.
+Complements hand-written cases by guaranteeing every surface has at least
+one exercise path.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import traceback
+from pathlib import Path
+from typing import Any, Callable
+
+_SDK_ROOT = Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(_SDK_ROOT))
+
+from tests.fidelity.fake_session import install_fake_session  # noqa: E402
+
+
+# ── Representative values per type ───────────────────────────────────
+
+
+def _rep_value(param_name: str, param_type: str, obj_context: str) -> Any:
+    """Pick a representative value for a parameter name+type hint."""
+    from docx.enum.table import (
+        WD_ROW_HEIGHT_RULE,
+    )
+    from docx.enum.text import (
+        WD_ALIGN_PARAGRAPH,
+        WD_COLOR_INDEX,
+    )
+    from docx.enum.section import WD_ORIENTATION, WD_SECTION_START
+    from docx.shared import Inches, Pt, RGBColor
+
+    name = param_name.lower()
+    type_str = param_type.lower()
+    # Booleans
+    if "bool" in type_str or name in ("bold", "italic", "underline", "active"):
+        return True
+    # String literals
+    if "str" in type_str or name in ("text", "name", "style", "id", "label"):
+        return "sample"
+    # Lengths
+    if "length" in type_str or "emu" in type_str or "inches" in type_str or "pt " in type_str:
+        return Inches(1)
+    if name in ("width", "height", "size") and "int" in type_str:
+        return Pt(12)
+    if "rgb" in type_str or "color" in name:
+        return RGBColor(0, 0, 0)
+    if "int" in type_str or "number" in type_str:
+        if "level" in name:
+            return 1
+        if name in ("rows", "cols", "rowindex", "columnindex"):
+            return 2
+        return 1
+    # Enums
+    if "alignment" in name:
+        return WD_ALIGN_PARAGRAPH.CENTER
+    if "orientation" in name:
+        return WD_ORIENTATION.PORTRAIT
+    if "start_type" in name or "break_type" in name:
+        return WD_SECTION_START.NEW_PAGE
+    if "highlight" in name:
+        return WD_COLOR_INDEX.YELLOW
+    if "rule" in name:
+        return WD_ROW_HEIGHT_RULE.AT_LEAST
+    return None
+
+
+# ── Fixtures ──────────────────────────────────────────────────────────
+
+
+def _fixture_new_doc() -> Any:
+    install_fake_session()
+    from docx import Document
+    return Document("asset_fake")
+
+
+_FIXTURES: dict[str, Callable[[Any], Any]] = {
+    "Document": lambda doc: doc,
+    "Paragraph": lambda doc: doc.add_paragraph("auto-gen"),
+    "Run": lambda doc: doc.add_paragraph().add_run("auto-gen"),
+    "Font": lambda doc: doc.add_paragraph().add_run("auto-gen").font,
+    "ParagraphFormat": lambda doc: doc.add_paragraph("auto-gen").paragraph_format,
+    "Table": lambda doc: doc.add_table(rows=2, cols=2),
+    "_Cell": lambda doc: doc.add_table(rows=1, cols=1).cell(0, 0),
+    "_Row": lambda doc: doc.add_table(rows=1, cols=1).rows[0],
+    "_Column": lambda doc: doc.add_table(rows=1, cols=1).columns[0],
+    "Section": lambda doc: doc.sections[0],
+    "Styles": lambda doc: doc.styles,
+    "CoreProperties": lambda doc: doc.core_properties,
+    "InlineShapes": lambda doc: doc.inline_shapes,
+    "Sections": lambda doc: doc.sections,
+}
+
+
+_PROPERTY_VALUES: dict[tuple[str, str], Any] = {}  # populated lazily
+
+
+def _property_value(cls_name: str, prop: str) -> Any:
+    from docx.enum.table import WD_ALIGN_VERTICAL, WD_ROW_HEIGHT_RULE, WD_TABLE_ALIGNMENT
+    from docx.enum.text import WD_ALIGN_PARAGRAPH, WD_COLOR_INDEX
+    from docx.enum.section import WD_ORIENTATION
+    from docx.shared import Inches, Pt
+
+    # Hand-tuned per (class, property) — most important ones.
+    mapping = {
+        ("Paragraph", "text"): "text",
+        ("Paragraph", "style"): "Normal",
+        ("Paragraph", "alignment"): WD_ALIGN_PARAGRAPH.CENTER,
+        ("Run", "text"): "text",
+        ("Run", "bold"): True,
+        ("Run", "italic"): True,
+        ("Run", "underline"): True,
+        ("Run", "style"): "Emphasis",
+        ("Font", "name"): "Arial",
+        ("Font", "size"): Pt(12),
+        ("Font", "bold"): True,
+        ("Font", "italic"): True,
+        ("Font", "strike"): True,
+        ("Font", "double_strike"): True,
+        ("Font", "all_caps"): True,
+        ("Font", "small_caps"): True,
+        ("Font", "shadow"): True,
+        ("Font", "outline"): True,
+        ("Font", "emboss"): True,
+        ("Font", "imprint"): True,
+        ("Font", "hidden"): True,
+        ("Font", "subscript"): True,
+        ("Font", "superscript"): True,
+        ("Font", "highlight_color"): WD_COLOR_INDEX.YELLOW,
+        ("ParagraphFormat", "alignment"): WD_ALIGN_PARAGRAPH.CENTER,
+        ("ParagraphFormat", "left_indent"): Inches(0.5),
+        ("ParagraphFormat", "right_indent"): Inches(0.25),
+        ("ParagraphFormat", "first_line_indent"): Inches(0.25),
+        ("ParagraphFormat", "space_before"): Pt(12),
+        ("ParagraphFormat", "space_after"): Pt(6),
+        ("ParagraphFormat", "line_spacing"): 1.5,
+        ("ParagraphFormat", "keep_together"): True,
+        ("ParagraphFormat", "keep_with_next"): True,
+        ("ParagraphFormat", "widow_control"): True,
+        ("ParagraphFormat", "page_break_before"): True,
+        ("Table", "style"): "TableGrid",
+        ("Table", "alignment"): WD_TABLE_ALIGNMENT.CENTER,
+        ("Table", "autofit"): True,
+        ("_Cell", "text"): "cell body",
+        ("_Cell", "vertical_alignment"): WD_ALIGN_VERTICAL.CENTER,
+        ("_Cell", "width"): Inches(1),
+        ("_Row", "height"): Pt(20),
+        ("_Row", "height_rule"): WD_ROW_HEIGHT_RULE.AT_LEAST,
+        ("_Column", "width"): Inches(1),
+        ("Section", "page_width"): Inches(8.5),
+        ("Section", "page_height"): Inches(11),
+        ("Section", "orientation"): WD_ORIENTATION.PORTRAIT,
+        ("Section", "left_margin"): Inches(1),
+        ("Section", "right_margin"): Inches(1),
+        ("Section", "top_margin"): Inches(1),
+        ("Section", "bottom_margin"): Inches(1),
+    }
+    return mapping.get((cls_name, prop))
+
+
+# ── Test runner ───────────────────────────────────────────────────────
+
+
+def run_all() -> tuple[int, int, list[tuple[str, str]]]:
+    """Run auto-generated tests; return (passed, total, failures)."""
+    failures: list[tuple[str, str]] = []
+    total = 0
+    passed = 0
+    for cls_name, fix in _FIXTURES.items():
+        # Per-class: iterate known (class, property) pairs
+        for (cname, prop), val in list(_PROPERTY_VALUES.items()):
+            if cname != cls_name:
+                continue
+        # Use _property_value mapping: iterate all keys matching this class
+        from docx.enum.table import WD_ALIGN_VERTICAL  # noqa: F401 — keeps import list alive
+        mapping_keys = _collect_property_keys(cls_name)
+        for prop in mapping_keys:
+            val = _property_value(cls_name, prop)
+            if val is None:
+                continue
+            total += 1
+            doc = _fixture_new_doc()
+            try:
+                target = fix(doc)
+                _set_nested(target, prop, val)
+                # Round-trip read (best effort; skip if getter raises)
+                try:
+                    _ = _get_nested(target, prop)
+                except Exception:
+                    pass
+                passed += 1
+            except Exception as e:  # noqa: BLE001
+                failures.append((f"{cls_name}.{prop}", f"{type(e).__name__}: {e}"))
+            finally:
+                try:
+                    doc.close()
+                except Exception:
+                    pass
+    return passed, total, failures
+
+
+def _collect_property_keys(cls_name: str) -> list[str]:
+    """Pull properties we have values for."""
+    # Use introspection on the _property_value mapping: easiest way
+    # without duplicating data is to call it with each key and filter.
+    all_keys = [
+        "text", "style", "alignment", "bold", "italic", "underline",
+        "name", "size", "strike", "double_strike", "all_caps", "small_caps",
+        "shadow", "outline", "emboss", "imprint", "hidden", "subscript",
+        "superscript", "highlight_color", "left_indent", "right_indent",
+        "first_line_indent", "space_before", "space_after", "line_spacing",
+        "keep_together", "keep_with_next", "widow_control", "page_break_before",
+        "autofit", "vertical_alignment", "width", "height", "height_rule",
+        "page_width", "page_height", "orientation", "left_margin",
+        "right_margin", "top_margin", "bottom_margin",
+    ]
+    return [k for k in all_keys if _property_value(cls_name, k) is not None]
+
+
+def _set_nested(obj: Any, path: str, value: Any) -> None:
+    parts = path.split(".")
+    for p in parts[:-1]:
+        obj = getattr(obj, p)
+    setattr(obj, parts[-1], value)
+
+
+def _get_nested(obj: Any, path: str) -> Any:
+    for p in path.split("."):
+        obj = getattr(obj, p)
+    return obj
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--verbose", action="store_true")
+    args = parser.parse_args()
+    passed, total, failures = run_all()
+    for name, err in failures:
+        print(f"  ❌ {name:45} — {err}")
+        if args.verbose:
+            traceback.print_exc()
+    print()
+    print(f"Auto-generated fidelity: {passed}/{total} passed")
+    if failures:
+        print(f"Failures: {len(failures)}")
+    return 0 if not failures else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

athena_python_docx-0.2.3/tests/fidelity/coverage_report.py

@@ -0,0 +1,117 @@
+"""Parity coverage scorecard.
+
+Combines layers L1-L6 into a single `coverage.json` + human scorecard:
+
+  - L1 (import parity)      — from parity_crawl --ours output
+  - L2 (signature match)    — from parity_diff
+  - L3 (enum value parity)  — from parity_diff
+  - L6 (property round-trip)— from round_trip_tests
+
+The output looks like:
+
+  python-docx coverage scorecard (0.2.2)
+  =====================================
+   Classes     27/30  (90%)    ✅
+   Properties  210/225 (93%)   ✅
+   Methods     122/142 (86%)   ⚠️
+   Enum values 68/73   (93%)   ✅
+
+Intended as a CI gate: any decrease fails the job.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+_SDK_ROOT = Path(__file__).resolve().parents[2]
+
+
+def _load(path: Path) -> dict:
+    if not path.exists():
+        return {}
+    return json.loads(path.read_text())
+
+
+def _count_in_stock(stock: dict) -> dict[str, int]:
+    classes = 0
+    properties = 0
+    methods = 0
+    enum_values = 0
+    for mod_path, entries in stock.items():
+        for qual, entry in entries.items():
+            if not isinstance(entry, dict):
+                continue
+            if entry.get("kind") == "class":
+                classes += 1
+                # Enum detection: a class whose bases include Enum-ish
+                is_enum = any(
+                    b in ("Enum", "IntEnum", "BaseXmlEnum") for b in entry.get("bases", [])
+                )
+                for m_name, m_entry in entry.get("members", {}).items():
+                    if not isinstance(m_entry, dict):
+                        continue
+                    kind = m_entry.get("kind")
+                    if kind == "property":
+                        properties += 1
+                    elif kind == "method":
+                        methods += 1
+                    elif kind == "attribute" and is_enum:
+                        enum_values += 1
+    return {"classes": classes, "properties": properties, "methods": methods, "enum_values": enum_values}
+
+
+def _count_diff_missing(diff: dict) -> dict[str, int]:
+    missing = {"classes": len(diff.get("missing_classes", [])), "properties": 0, "methods": 0, "enum_values": 0}
+    # missing_members are a flat list; we can't tell property/method from there
+    # without cross-ref to stock. For now, lump them under "methods" as a rough
+    # signal — the scorecard will be approximate but still useful.
+    missing["methods"] += len(diff.get("missing_members", []))
+    return missing
+
+
+def main() -> int:
+    stock = _load(_SDK_ROOT / "tests/fidelity/stock_spec.json")
+    diff = _load(_SDK_ROOT / "tests/fidelity/parity_diff.json")
+    if not stock or not diff:
+        print("run parity_crawl.py --stock / --ours / --diff first")
+        return 1
+    totals = _count_in_stock(stock)
+    missing = _count_diff_missing(diff)
+
+    implemented = {
+        k: max(totals[k] - missing.get(k, 0), 0)
+        for k in totals
+    }
+
+    version = _get_sdk_version()
+
+    print()
+    print(f"python-docx coverage scorecard (athena-python-docx {version})")
+    print("=" * 60)
+    for key, label in [("classes", "Classes"), ("properties", "Properties"), ("methods", "Methods"), ("enum_values", "Enum values")]:
+        t = totals[key]
+        i = implemented[key]
+        pct = (i * 100 // t) if t else 100
+        icon = "✅" if pct >= 90 else ("⚠️" if pct >= 75 else "❌")
+        print(f"  {label:14} {i:4}/{t:<4} ({pct:>3}%) {icon}")
+    print()
+
+    # Round-trip scorecard (L6)
+    rt_path = _SDK_ROOT / "tests/fidelity/round_trip_tests.py"
+    if rt_path.exists():
+        print("Property round-trips:  run `.venv/bin/python tests/fidelity/round_trip_tests.py` for details")
+
+    return 0
+
+
+def _get_sdk_version() -> str:
+    init = (_SDK_ROOT / "docx/__init__.py").read_text()
+    import re
+    m = re.search(r'__version__ = "([^"]+)"', init)
+    return m.group(1) if m else "?"
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{athena_python_docx-0.2.2 → athena_python_docx-0.2.3}/tests/fidelity/fake_session.py

@@ -364,16 +364,31 @@ class FakeDocState:
             if target.get("kind") == "block" and target.get("nodeType") == "tableCell":
                 cell_nid = target.get("nodeId")
                 content = params.get("content") or {}
-                # Extract text from prosemirror paragraph fragment.
+                # Extract text from either a prosemirror `{type:"paragraph",
+                # content:[{type:"text",text:"…"}]}` fragment OR a Superdoc
+                # native `{kind:"paragraph", paragraph:{inlines:[{run:...}]}}`
+                # fragment.
                 appended: str = ""
                 if isinstance(content, dict):
-                    inline_list = content.get("content") or []
+                    inline_list = content.get("content")
                     if isinstance(inline_list, list):
                         for inl in inline_list:
                             if isinstance(inl, dict) and inl.get("type") == "text":
                                 t = inl.get("text")
                                 if isinstance(t, str):
                                     appended += t
+                    # Superdoc native shape
+                    para = content.get("paragraph")
+                    if isinstance(para, dict):
+                        inlines = para.get("inlines") or []
+                        if isinstance(inlines, list):
+                            for inl in inlines:
+                                if isinstance(inl, dict):
+                                    run = inl.get("run")
+                                    if isinstance(run, dict):
+                                        t = run.get("text")
+                                        if isinstance(t, str):
+                                            appended += t
                 # Find cell and append to its first paragraph.
                 for t in self.tables:
                     for r_idx, row in enumerate(t.cells):
@@ -391,6 +406,23 @@ class FakeDocState:
                                 )
             return {"ok": True}
 
+        # markdown_to_fragment: return a minimal-valid Superdoc fragment.
+        if op == "markdownToFragment":
+            md = params.get("markdown", "")
+            return {
+                "fragment": {
+                    "kind": "paragraph",
+                    "paragraph": {
+                        "inlines": (
+                            [{"kind": "run", "run": {"text": md}}]
+                            if md else []
+                        ),
+                    },
+                },
+                "lossy": False,
+                "diagnostics": [],
+            }
+
         if op == "insertLineBreak":
             blk_id = params.get("blockId")
             if blk_id: