athena-python-docx 0.1.8__tar.gz → 0.2.1__tar.gz

{athena_python_docx-0.1.8 → athena_python_docx-0.2.1}/.gitignore

@@ -9,6 +9,7 @@ __pycache__/
 *.py[cod]
 *$py.class
 .venv/
+.venv-*/
 venv/
 env/
 *.egg-info/

{athena_python_docx-0.1.8 → athena_python_docx-0.2.1}/PKG-INFO

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

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

{athena_python_docx-0.1.8 → athena_python_docx-0.2.1}/docx/document.py

@@ -98,8 +98,66 @@ class Document:
             for item in items
         ]
 
+    @property
+    def sections(self):
+        """Return the document's sections collection."""
+        from docx.section import Sections
+
+        self._ensure_open()
+        return Sections(session=self._session)
+
+    @property
+    def inline_shapes(self):
+        """Return the document's inline-shape collection."""
+        from docx.shape import InlineShapes
+
+        self._ensure_open()
+        return InlineShapes(session=self._session)
+
+    @property
+    def styles(self):
+        """Return the document's styles collection."""
+        from docx.styles.styles import Styles
+
+        self._ensure_open()
+        return Styles(session=self._session)
+
+    @property
+    def core_properties(self):
+        """Return a minimal CoreProperties proxy.
+
+        Most python-docx fields aren't surfaced by Superdoc; accessing an
+        unsupported field returns None rather than raising.
+        """
+        from docx.opc.coreprops import CoreProperties
+
+        return CoreProperties(session=self._session)
+
+    @property
+    def settings(self):
+        """Return a minimal Settings proxy (stubbed; Superdoc doesn't surface app settings)."""
+        from docx.settings import Settings
+
+        return Settings(session=self._session)
+
+    @property
+    def element(self):
+        """python-docx returns the underlying lxml element. We return a best-effort proxy."""
+        return None
+
+    part = element
+
     # ---- Append operations ----
 
+    @staticmethod
+    def _normalize_text(text: str) -> str:
+        """Normalize line endings like python-docx: \\r\\n → \\n\\n, lone \\r → \\n."""
+        # python-docx's text IO strips \r and converts \r to \n.
+        if not text:
+            return text
+        # \r\n → \n\n (preserves paragraph-break semantics)
+        return text.replace("\r\n", "\n\n").replace("\r", "\n")
+
     def add_paragraph(
         self,
         text: str = "",
@@ -135,7 +193,7 @@ class Document:
             return self.add_heading(text=text, level=0)
 
         params: dict = {
-            "text": text,
+            "text": self._normalize_text(text),
             "at": {"kind": "documentEnd"},
         }
         result: dict = run_sync(
@@ -162,19 +220,38 @@ class Document:
                 f"level must be in 0..9; got {level}",
             )
 
-        # Map level 0 → Title, 1..9 → Heading N. create.heading understands
-        # level directly (level=0 means Title in python-docx semantics; Superdoc
-        # accepts levels 1..9 for HeadingN and may interpret 0 as Title depending
-        # on version — we pass level as-is).
+        # python-docx semantics: level=0 is Title, 1..9 are Heading N.
+        # Superdoc's doc.create.heading only accepts integer levels 1..6,
+        # so Title (level=0) routes through create.paragraph followed by a
+        # style change to "Title". Levels 7..9 fall through to create.heading
+        # and will raise a SuperDocError if the runtime rejects them — that
+        # mirrors python-docx's tolerance without silently degrading.
+        if level == 0:
+            result: dict = run_sync(
+                self._session.doc.create.paragraph(
+                    {"text": text, "at": {"kind": "documentEnd"}},
+                ),
+            )
+            node_id: str = _extract_inserted_node_id(
+                result, expected_type="paragraph",
+            )
+            if not node_id:
+                raise RuntimeError(
+                    f"Superdoc did not return a nodeId for add_heading(level=0): {result!r}",
+                )
+            paragraph = Paragraph(session=self._session, node_id=node_id)
+            paragraph.style = "Title"
+            return paragraph
+
         params: dict = {
             "text": text,
-            "level": level if level >= 1 else 1,
+            "level": level,
             "at": {"kind": "documentEnd"},
         }
-        result: dict = run_sync(
+        result = run_sync(
             self._session.doc.create.heading(params),
         )
-        node_id: str = _extract_inserted_node_id(result, expected_type="paragraph")
+        node_id = _extract_inserted_node_id(result, expected_type="paragraph")
         if not node_id:
             raise RuntimeError(
                 f"Superdoc did not return a nodeId for add_heading: {result!r}",
@@ -289,14 +366,53 @@ class Document:
             ),
         )
 
+    def add_section(self, start_type: object = None):
+        """Append a new section and return its Section proxy.
+
+        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
+        self.add_paragraph("")
+        break_type: str = "nextPage"
+        if start_type is not None:
+            if isinstance(start_type, WD_SECTION_START):
+                break_type = start_type.to_superdoc()
+            elif isinstance(start_type, str):
+                break_type = start_type
+        run_sync(
+            self._session.doc.create.section_break(
+                {"at": {"kind": "documentEnd"}, "breakType": break_type},
+            ),
+        )
+        info: object = run_sync(self._session.doc.sections.list({}))
+        items: list = []
+        if isinstance(info, dict):
+            items_obj = info.get("items", [])
+            if isinstance(items_obj, list):
+                items = items_obj
+        if not items:
+            raise RuntimeError(
+                "Superdoc did not return any sections after add_section",
+            )
+        last = items[-1]
+        addr = last.get("address", {}) if isinstance(last, dict) else {}
+        return Section(session=self._session, address=addr if isinstance(addr, dict) else {})
+
     def add_page_break(self) -> None:
         """Append a page break at the end of the document.
 
-        Uses `doc.create.section_break` with OOXML `breakType="nextPage"`,
-        which is the canonical hard page break (what python-docx's
-        ``add_page_break()`` produces).
+        python-docx appends an empty paragraph with a page-break run inside;
+        `doc.paragraphs` includes that new paragraph. We mirror by adding
+        an anchor paragraph first, then the section break.
         """
         self._ensure_open()
+        # Anchor paragraph so doc.paragraphs reflects the break visually.
+        self.add_paragraph("")
         run_sync(
             self._session.doc.create.section_break(
                 {"at": {"kind": "documentEnd"}, "breakType": "nextPage"},

athena_python_docx-0.2.1/docx/enum/section.py

@@ -0,0 +1,37 @@
+"""Section-related enums — python-docx parity (docx.enum.section)."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class WD_ORIENTATION(Enum):
+    PORTRAIT = "portrait"
+    LANDSCAPE = "landscape"
+
+    def to_superdoc(self) -> str:
+        return self.value
+
+
+# python-docx also exposes a short alias
+WD_ORIENT = WD_ORIENTATION
+
+
+class WD_SECTION_START(Enum):
+    CONTINUOUS = "continuous"
+    NEW_COLUMN = "nextColumn"
+    NEW_PAGE = "nextPage"
+    EVEN_PAGE = "evenPage"
+    ODD_PAGE = "oddPage"
+
+    def to_superdoc(self) -> str:
+        if self == WD_SECTION_START.CONTINUOUS:
+            return "continuous"
+        if self == WD_SECTION_START.EVEN_PAGE:
+            return "evenPage"
+        if self == WD_SECTION_START.ODD_PAGE:
+            return "oddPage"
+        return "nextPage"
+
+
+WD_SECTION = WD_SECTION_START

athena_python_docx-0.2.1/docx/enum/style.py

@@ -0,0 +1,64 @@
+"""Style-related enums — python-docx parity (docx.enum.style)."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class WD_STYLE_TYPE(Enum):
+    PARAGRAPH = "paragraph"
+    CHARACTER = "character"
+    LIST = "list"
+    TABLE = "table"
+
+
+WD_STYLE = WD_STYLE_TYPE
+
+
+class WD_BUILTIN_STYLE(Enum):
+    """Common built-in Word style names. Names match python-docx exactly."""
+
+    BLOCK_QUOTATION = "Quote"
+    BODY_TEXT = "Body Text"
+    BODY_TEXT_2 = "Body Text 2"
+    BODY_TEXT_3 = "Body Text 3"
+    BODY_TEXT_FIRST_INDENT = "Body Text First Indent"
+    BODY_TEXT_FIRST_INDENT_2 = "Body Text First Indent 2"
+    BODY_TEXT_IND = "Body Text Indent"
+    BODY_TEXT_IND_2 = "Body Text Indent 2"
+    BODY_TEXT_IND_3 = "Body Text Indent 3"
+    CAPTION = "Caption"
+    DEFAULT_PARAGRAPH_FONT = "Default Paragraph Font"
+    EMPHASIS = "Emphasis"
+    HEADING_1 = "Heading 1"
+    HEADING_2 = "Heading 2"
+    HEADING_3 = "Heading 3"
+    HEADING_4 = "Heading 4"
+    HEADING_5 = "Heading 5"
+    HEADING_6 = "Heading 6"
+    HEADING_7 = "Heading 7"
+    HEADING_8 = "Heading 8"
+    HEADING_9 = "Heading 9"
+    INTENSE_EMPHASIS = "Intense Emphasis"
+    INTENSE_QUOTE = "Intense Quote"
+    INTENSE_REFERENCE = "Intense Reference"
+    LIST_BULLET = "List Bullet"
+    LIST_BULLET_2 = "List Bullet 2"
+    LIST_BULLET_3 = "List Bullet 3"
+    LIST_NUMBER = "List Number"
+    LIST_NUMBER_2 = "List Number 2"
+    LIST_NUMBER_3 = "List Number 3"
+    MACRO_TEXT = "Macro Text"
+    NAV_PANE = "Nav Pane"
+    NORMAL = "Normal"
+    NORMAL_INDENT = "Normal Indent"
+    NORMAL_TABLE = "Normal Table"
+    NO_SPACING = "No Spacing"
+    QUOTE = "Quote"
+    SUBTITLE = "Subtitle"
+    STRONG = "Strong"
+    TABLE_GRID = "Table Grid"
+    TITLE = "Title"
+    TOC_1 = "TOC 1"
+    TOC_2 = "TOC 2"
+    TOC_3 = "TOC 3"

athena_python_docx-0.2.1/docx/enum/table.py

@@ -0,0 +1,52 @@
+"""Table-related enums — python-docx parity (docx.enum.table)."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class WD_ROW_HEIGHT_RULE(Enum):
+    AUTO = "auto"
+    AT_LEAST = "atLeast"
+    EXACTLY = "exact"
+
+    def to_superdoc(self) -> str:
+        return self.value
+
+
+# Short alias used by python-docx
+WD_ROW_HEIGHT = WD_ROW_HEIGHT_RULE
+
+
+class WD_TABLE_ALIGNMENT(Enum):
+    LEFT = "left"
+    CENTER = "center"
+    RIGHT = "right"
+
+    def to_superdoc(self) -> str:
+        return self.value
+
+
+class WD_TABLE_DIRECTION(Enum):
+    LTR = "ltr"
+    RTL = "rtl"
+
+    def to_superdoc(self) -> str:
+        return self.value
+
+
+class WD_ALIGN_VERTICAL(Enum):
+    TOP = "top"
+    CENTER = "center"
+    BOTTOM = "bottom"
+    BOTH = "both"
+
+    def to_superdoc(self) -> str:
+        # Superdoc enum: top | center | bottom
+        if self == WD_ALIGN_VERTICAL.BOTH:
+            return "center"
+        return self.value
+
+
+# python-docx exposes WD_CELL_VERTICAL_ALIGNMENT as an alias for cells
+WD_CELL_VERTICAL_ALIGNMENT = WD_ALIGN_VERTICAL

athena_python_docx-0.2.1/docx/enum/text.py

@@ -0,0 +1,160 @@
+"""Text-related enums — python-docx parity (docx.enum.text).
+
+Values map to Superdoc primitives where supported; unmapped values
+(e.g. Thai/Arabic justification variants) still parse but serialize to
+their best Superdoc equivalent.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class WD_ALIGN_PARAGRAPH(Enum):
+    """Paragraph alignment (justification)."""
+
+    LEFT = "left"
+    CENTER = "center"
+    RIGHT = "right"
+    JUSTIFY = "justify"
+    DISTRIBUTE = "distribute"
+    JUSTIFY_MED = "justifyMed"
+    JUSTIFY_HI = "justifyHi"
+    JUSTIFY_LOW = "justifyLow"
+    THAI_JUSTIFY = "thaiJustify"
+
+    def to_superdoc(self) -> str:
+        # Superdoc only supports left/center/right/justify; coerce the
+        # distributed/thai variants to "justify" so set_alignment doesn't
+        # reject them.
+        if self in (
+            WD_ALIGN_PARAGRAPH.DISTRIBUTE,
+            WD_ALIGN_PARAGRAPH.JUSTIFY_MED,
+            WD_ALIGN_PARAGRAPH.JUSTIFY_HI,
+            WD_ALIGN_PARAGRAPH.JUSTIFY_LOW,
+            WD_ALIGN_PARAGRAPH.THAI_JUSTIFY,
+        ):
+            return "justify"
+        return self.value
+
+    @classmethod
+    def from_superdoc(cls, s: str) -> "WD_ALIGN_PARAGRAPH | None":
+        try:
+            return cls(s)
+        except ValueError:
+            pass
+        try:
+            return cls(s.lower())
+        except ValueError:
+            return None
+
+
+class WD_LINE_SPACING(Enum):
+    """Line-spacing rule."""
+
+    SINGLE = "single"
+    ONE_POINT_FIVE = "onePointFive"
+    DOUBLE = "double"
+    AT_LEAST = "atLeast"
+    EXACTLY = "exactly"
+    MULTIPLE = "multiple"
+
+    def to_superdoc(self) -> str:
+        # Superdoc's lineRule enum: "auto" | "exact" | "atLeast"
+        if self == WD_LINE_SPACING.EXACTLY:
+            return "exact"
+        if self == WD_LINE_SPACING.AT_LEAST:
+            return "atLeast"
+        # SINGLE/1.5/DOUBLE/MULTIPLE all map to "auto" with a line value
+        return "auto"
+
+
+class WD_TAB_ALIGNMENT(Enum):
+    LEFT = "left"
+    CENTER = "center"
+    RIGHT = "right"
+    DECIMAL = "decimal"
+    BAR = "bar"
+    LIST = "list"
+    CLEAR = "clear"
+    END = "end"
+    NUM = "num"
+    START = "start"
+
+    def to_superdoc(self) -> str:
+        if self in (
+            WD_TAB_ALIGNMENT.LIST,
+            WD_TAB_ALIGNMENT.CLEAR,
+            WD_TAB_ALIGNMENT.END,
+            WD_TAB_ALIGNMENT.NUM,
+            WD_TAB_ALIGNMENT.START,
+        ):
+            return "left"
+        return self.value
+
+
+class WD_TAB_LEADER(Enum):
+    SPACES = "none"
+    DOTS = "dot"
+    DASHES = "hyphen"
+    LINES = "underscore"
+    HEAVY = "heavy"
+    MIDDLE_DOT = "middleDot"
+
+    def to_superdoc(self) -> str:
+        return self.value
+
+
+class WD_BREAK(Enum):
+    LINE = "line"
+    PAGE = "page"
+    COLUMN = "column"
+    LINE_CLEAR_LEFT = "lineClearLeft"
+    LINE_CLEAR_RIGHT = "lineClearRight"
+    LINE_CLEAR_ALL = "lineClearAll"
+    TEXT_WRAPPING = "textWrapping"
+
+
+class WD_UNDERLINE(Enum):
+    NONE = "none"
+    SINGLE = "single"
+    WORDS = "words"
+    DOUBLE = "double"
+    DOTTED = "dotted"
+    THICK = "thick"
+    DASH = "dash"
+    DOT_DASH = "dotDash"
+    DOT_DOT_DASH = "dotDotDash"
+    WAVY = "wavy"
+    DOTTED_HEAVY = "dottedHeavy"
+    DASH_HEAVY = "dashHeavy"
+    DOT_DASH_HEAVY = "dotDashHeavy"
+    DOT_DOT_DASH_HEAVY = "dotDotDashHeavy"
+    WAVY_HEAVY = "wavyHeavy"
+    DASH_LONG = "dashLong"
+    DASH_LONG_HEAVY = "dashLongHeavy"
+    WAVY_DOUBLE = "wavyDouble"
+
+
+class WD_COLOR_INDEX(Enum):
+    AUTO = "default"
+    BLACK = "black"
+    BLUE = "blue"
+    BRIGHT_GREEN = "green"
+    DARK_BLUE = "darkBlue"
+    DARK_RED = "darkRed"
+    DARK_YELLOW = "darkYellow"
+    GRAY_25 = "lightGray"
+    GRAY_50 = "darkGray"
+    GREEN = "darkGreen"
+    PINK = "magenta"
+    RED = "red"
+    TEAL = "darkCyan"
+    TURQUOISE = "cyan"
+    VIOLET = "darkMagenta"
+    WHITE = "white"
+    YELLOW = "yellow"
+
+
+# Alias used by python-docx as well
+WD_COLOR = WD_COLOR_INDEX

athena_python_docx-0.2.1/docx/opc/__init__.py

@@ -0,0 +1 @@
+"""docx.opc — Open Packaging Convention bindings (stubbed)."""

athena_python_docx-0.2.1/docx/opc/coreprops.py

@@ -0,0 +1,145 @@
+"""CoreProperties — python-docx docx.opc.coreprops.CoreProperties parity.
+
+Superdoc doesn't surface most core document properties (author, title,
+modified, etc.). We expose the attributes with defaults so code that
+reads them doesn't raise.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from docx.client import Session
+
+
+class CoreProperties:
+    def __init__(self, *, session: "Session") -> None:
+        self._session: "Session" = session
+        self._cache: dict[str, object] = {}
+
+    @property
+    def author(self) -> str:
+        return str(self._cache.get("author", ""))
+
+    @author.setter
+    def author(self, value: str) -> None:
+        self._cache["author"] = value
+
+    @property
+    def category(self) -> str:
+        return str(self._cache.get("category", ""))
+
+    @category.setter
+    def category(self, value: str) -> None:
+        self._cache["category"] = value
+
+    @property
+    def comments(self) -> str:
+        return str(self._cache.get("comments", ""))
+
+    @comments.setter
+    def comments(self, value: str) -> None:
+        self._cache["comments"] = value
+
+    @property
+    def content_status(self) -> str:
+        return str(self._cache.get("content_status", ""))
+
+    @content_status.setter
+    def content_status(self, value: str) -> None:
+        self._cache["content_status"] = value
+
+    @property
+    def created(self) -> datetime | None:
+        v = self._cache.get("created")
+        return v if isinstance(v, datetime) else None
+
+    @created.setter
+    def created(self, value: datetime | None) -> None:
+        self._cache["created"] = value
+
+    @property
+    def identifier(self) -> str:
+        return str(self._cache.get("identifier", ""))
+
+    @identifier.setter
+    def identifier(self, value: str) -> None:
+        self._cache["identifier"] = value
+
+    @property
+    def keywords(self) -> str:
+        return str(self._cache.get("keywords", ""))
+
+    @keywords.setter
+    def keywords(self, value: str) -> None:
+        self._cache["keywords"] = value
+
+    @property
+    def language(self) -> str:
+        return str(self._cache.get("language", ""))
+
+    @language.setter
+    def language(self, value: str) -> None:
+        self._cache["language"] = value
+
+    @property
+    def last_modified_by(self) -> str:
+        # Intentionally returns empty — attribution is Keryx-owned.
+        return str(self._cache.get("last_modified_by", ""))
+
+    @last_modified_by.setter
+    def last_modified_by(self, value: str) -> None:
+        self._cache["last_modified_by"] = value
+
+    @property
+    def last_printed(self) -> datetime | None:
+        v = self._cache.get("last_printed")
+        return v if isinstance(v, datetime) else None
+
+    @last_printed.setter
+    def last_printed(self, value: datetime | None) -> None:
+        self._cache["last_printed"] = value
+
+    @property
+    def modified(self) -> datetime | None:
+        v = self._cache.get("modified")
+        return v if isinstance(v, datetime) else None
+
+    @modified.setter
+    def modified(self, value: datetime | None) -> None:
+        self._cache["modified"] = value
+
+    @property
+    def revision(self) -> int:
+        v = self._cache.get("revision", 0)
+        return int(v) if isinstance(v, (int, float, str)) else 0
+
+    @revision.setter
+    def revision(self, value: int) -> None:
+        self._cache["revision"] = value
+
+    @property
+    def subject(self) -> str:
+        return str(self._cache.get("subject", ""))
+
+    @subject.setter
+    def subject(self, value: str) -> None:
+        self._cache["subject"] = value
+
+    @property
+    def title(self) -> str:
+        return str(self._cache.get("title", ""))
+
+    @title.setter
+    def title(self, value: str) -> None:
+        self._cache["title"] = value
+
+    @property
+    def version(self) -> str:
+        return str(self._cache.get("version", ""))
+
+    @version.setter
+    def version(self, value: str) -> None:
+        self._cache["version"] = value