Metadata-Version: 2.5
Name: athena-python-docx
Version: 0.46.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>
License-Expression: MIT
License-File: LICENSE-python-docx
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: athena-references>=0.1.0
Requires-Dist: lxml>=3.1.0
Requires-Dist: requests>=2.28
Requires-Dist: typing-extensions>=4.9.0
Requires-Dist: urllib3>=1.26.6
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: python-docx>=1.1; extra == 'dev'
Requires-Dist: responses>=0.24; extra == 'dev'
Requires-Dist: ruff>=0.3; extra == 'dev'
Description-Content-Type: text/markdown

# athena-python-docx

Drop-in replacement for [python-docx](https://python-docx.readthedocs.io/) that connects to Athena's Keryx-backed Word document stack.

## Quick start

```python
from docx import Document
from docx.shared import Inches, Pt, RGBColor

# Open an existing Word document asset by its Athena asset_id
with Document("asset_abc123") as doc:
    doc.add_heading("Market Analysis", level=1)

    p = doc.add_paragraph()
    r = p.add_run("Revenue grew ")
    highlight = p.add_run("12.3% year-over-year")
    highlight.bold = True
    highlight.font.color.rgb = RGBColor(0x00, 0x80, 0x00)
    p.add_run(".")

    t = doc.add_table(rows=2, cols=2, style="TableGrid")
    t.cell(0, 0).text = "Segment"
    t.cell(0, 1).text = "Revenue"
    t.cell(1, 0).text = "Enterprise"
    t.cell(1, 1).text = "$4.3M"

    doc.save()
```

## Local files

`Document()`, `Document(path)` and `Document(stream)` open a `.docx` file on this
machine with python-docx 1.2.0's own code, vendored in the package, as python-docx
does: no network, no Athena credentials, and `document.save(path_or_stream)`
writes python-docx's file. python-docx's own dependencies, lxml and
typing_extensions, install with the SDK.

```python
from docx import Document

document = Document("report.docx")           # a local file, python-docx's document
document.add_paragraph("Reviewed.")
document.save("report-reviewed.docx")

athena_doc = Document("asset_abc123")        # an Athena Word document, live
new_doc = Document.create(name="Q4 Report")  # a new one
```

## API parity rule

This SDK mirrors python-docx's public API **exactly**. See `CLAUDE.md` for the full contract.

## Development

```bash
uv venv
uv pip install -e ".[dev]"
uv run pytest tests/ -x
```

## DocX Execution Lab

For fast local repros against real Athena document assets, use the
headless runner in `scripts/docx_exec_lab.py`. It executes an arbitrary
Python snippet with this checkout of `athena-python-docx`, captures
stdout/stderr/errors/timings, and can export the resulting `.docx` for
text assertions. `scripts/docx_exec_lab_server.py` adds a local UI with
an Olympus Word document embed preview pane. See `DOCX_EXEC_LAB.md`.

## Environment variables

Required when connecting to DOCX Studio (set by the Athena backend in the `execute_word_document_code` executor sandbox):

- `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
