wordlive 0.8.0__tar.gz

wordlive-0.8.0/.github/workflows/docs.yml

@@ -0,0 +1,60 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'src/wordlive/**'
+      - 'pyproject.toml'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'src/wordlive/**'
+      - 'pyproject.toml'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+          cache: pip
+
+      - name: Install docs deps
+        run: pip install -e ".[docs]"
+
+      - name: Build site
+        run: mkdocs build --strict
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

wordlive-0.8.0/.github/workflows/release.yml

@@ -0,0 +1,81 @@
+name: release
+
+# Push a version tag to publish:  git tag v0.8.0 && git push origin v0.8.0
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Verify tag matches the package version
+        run: |
+          version=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          tag="${GITHUB_REF_NAME#v}"
+          echo "pyproject version: $version"
+          echo "release tag:       $GITHUB_REF_NAME -> $tag"
+          if [ "$version" != "$tag" ]; then
+            echo "::error::Tag '$GITHUB_REF_NAME' does not match pyproject version '$version'. Bump the version in pyproject.toml or retag."
+            exit 1
+          fi
+
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build
+          twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  pypi-publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # Must match the PyPI trusted-publisher "Environment name".
+    environment:
+      name: pypi
+      url: https://pypi.org/p/wordlive
+    permissions:
+      id-token: write   # OIDC token for trusted publishing — no API token needed
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: pypi-publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write   # to create the Release and upload assets
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create GitHub Release from the tag
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: >-
+          gh release create "$GITHUB_REF_NAME"
+          --repo "$GITHUB_REPOSITORY"
+          --title "$GITHUB_REF_NAME"
+          --generate-notes
+          dist/*

wordlive-0.8.0/.gitignore

@@ -0,0 +1,16 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# MkDocs build output
+site/
+
+# Personal notes
+notes.md

wordlive-0.8.0/.python-version

@@ -0,0 +1 @@
+3.13

wordlive-0.8.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: wordlive
+Version: 0.8.0
+Summary: Drive a running Microsoft Word instance from Python — xlwings, but for Word, and LLM-friendly.
+Author-email: "Thomas.Villani" <thomas.villani@gmail.com>
+Requires-Python: >=3.13
+Requires-Dist: click>=8.1
+Requires-Dist: pywin32>=306; sys_platform == 'win32'
+Provides-Extra: dev
+Requires-Dist: pytest-mock>=3.12; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-include-markdown-plugin>=6.2; extra == 'docs'
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# wordlive
+
+Drive a running Microsoft Word instance from Python — `xlwings`, but for Word.
+Built for both human scripting and LLM agents. Windows-only.
+
+## Install
+
+```
+pip install wordlive
+```
+
+(Requires Python 3.13+ and `pywin32` on Windows.)
+
+## Python
+
+```python
+import wordlive as wl
+
+with wl.attach() as word:
+    doc = word.documents.active
+
+    # Reads
+    outline = doc.outline()
+    bookmarks = doc.bookmarks.list()
+
+    # Polite writes — preserves the user's cursor and view, atomic Ctrl-Z.
+    with doc.edit("Update address block"):
+        doc.bookmarks["Address"].set_text("123 Main St")
+        doc.content_controls["Signatory"].set_text("Jane Doe")
+        doc.heading("Introduction").insert_paragraph_after("New context paragraph.")
+```
+
+## CLI
+
+JSON in, JSON out — designed to drop straight into an LLM tool-use loop:
+
+```
+wordlive status
+wordlive outline                  # heading structure (heading:N)
+wordlive outline --all            # every paragraph (para:N) — alias of `paragraphs`
+wordlive paragraphs               # same: para:N, level, offsets, text
+wordlive read bookmark Address
+wordlive write bookmark Address --text "123 Main St"
+
+# Insert a new paragraph relative to ANY anchor (heading, paragraph, bookmark, …):
+wordlive insert --anchor-id heading:1 --text "..."          # after (default)
+wordlive insert --anchor-id para:3 --text "..." --before
+
+# Address anchors by ID (the IDs `outline`/`paragraphs` emit — `heading:N`, `para:N`, `bookmark:NAME`, `cc:NAME`):
+wordlive replace --anchor-id heading:3 --text "Updated section text"
+wordlive go-to --anchor-id bookmark:Address
+
+# Explicit cursor surface (the non-preferred mode — deliberately moves the cursor):
+wordlive cursor read                              # where is the cursor? which para:N?
+wordlive cursor write --text "inserted here"      # type at the cursor
+
+# Styles + paragraph formatting (atomic-undo):
+wordlive style list
+wordlive style apply --anchor-id heading:3 --name "Heading 2"
+wordlive format-paragraph --anchor-id heading:3 --alignment center --space-before 6
+
+# Tables (cells are anchors: table:N:R:C):
+wordlive table list
+wordlive table read 1
+wordlive replace --anchor-id table:1:2:2 --text "$450"
+wordlive table add-row --table 1 --values '["Lodging", "$600"]'
+
+# Collaboration: comments + track changes (the polite, non-destructive surface):
+wordlive comment add --anchor-id heading:3 --text "Please expand this." --author Bot
+wordlive comment list
+wordlive comment resolve --index 1
+wordlive track on            # record edits as revisions; `track off` to stop
+
+# Lists & numbering (any anchor's paragraphs):
+wordlive list apply --anchor-id heading:6 --type numbered
+wordlive list restart --anchor-id heading:6
+
+# Sections, headers & footers (header:S:WHICH / footer:S:WHICH):
+wordlive section list
+wordlive header write --section 1 --text "ACME Corporation"
+wordlive footer read --section 1
+
+# Batch multiple ops in a single Ctrl-Z:
+wordlive exec --script ops.json
+```
+
+Where `ops.json` looks like:
+
+```json
+{
+  "label": "Update report",
+  "ops": [
+    {"op": "write_bookmark", "name": "Address", "text": "123 Main St"},
+    {"op": "write_cc", "name": "Signatory", "text": "Jane Doe"},
+    {"op": "insert_paragraph", "anchor_id": "heading:3", "text": "New risk paragraph."},
+    {"op": "replace", "anchor_id": "heading:3", "text": "Updated section text"},
+    {"op": "apply_style", "anchor_id": "heading:3", "name": "Heading 2"},
+    {"op": "format_paragraph", "anchor_id": "heading:3", "alignment": "center", "space_before": 6}
+  ]
+}
+```
+
+Exit codes: `0` ok, `2` anchor-not-found, `3` Word-busy, `4` Word-not-running, `1` other.
+
+## Design
+
+- **Politeness first** — operations preserve the user's `Selection`, view, and
+  scroll. The user keeps editing alongside you.
+- **Semantic anchors over `Selection`** — operations target bookmarks, content
+  controls, or headings — never the live cursor unless you ask.
+- **Atomic undo** — every `doc.edit()` opens a Word `UndoRecord`, so a single
+  Ctrl-Z reverts the whole block.
+- **Escape hatch** — every wrapper exposes `.com` for the raw COM object;
+  you're never blocked by missing coverage.
+
+See [`spec.md`](spec.md) for the full design.

wordlive-0.8.0/README.md

@@ -0,0 +1,116 @@
+# wordlive
+
+Drive a running Microsoft Word instance from Python — `xlwings`, but for Word.
+Built for both human scripting and LLM agents. Windows-only.
+
+## Install
+
+```
+pip install wordlive
+```
+
+(Requires Python 3.13+ and `pywin32` on Windows.)
+
+## Python
+
+```python
+import wordlive as wl
+
+with wl.attach() as word:
+    doc = word.documents.active
+
+    # Reads
+    outline = doc.outline()
+    bookmarks = doc.bookmarks.list()
+
+    # Polite writes — preserves the user's cursor and view, atomic Ctrl-Z.
+    with doc.edit("Update address block"):
+        doc.bookmarks["Address"].set_text("123 Main St")
+        doc.content_controls["Signatory"].set_text("Jane Doe")
+        doc.heading("Introduction").insert_paragraph_after("New context paragraph.")
+```
+
+## CLI
+
+JSON in, JSON out — designed to drop straight into an LLM tool-use loop:
+
+```
+wordlive status
+wordlive outline                  # heading structure (heading:N)
+wordlive outline --all            # every paragraph (para:N) — alias of `paragraphs`
+wordlive paragraphs               # same: para:N, level, offsets, text
+wordlive read bookmark Address
+wordlive write bookmark Address --text "123 Main St"
+
+# Insert a new paragraph relative to ANY anchor (heading, paragraph, bookmark, …):
+wordlive insert --anchor-id heading:1 --text "..."          # after (default)
+wordlive insert --anchor-id para:3 --text "..." --before
+
+# Address anchors by ID (the IDs `outline`/`paragraphs` emit — `heading:N`, `para:N`, `bookmark:NAME`, `cc:NAME`):
+wordlive replace --anchor-id heading:3 --text "Updated section text"
+wordlive go-to --anchor-id bookmark:Address
+
+# Explicit cursor surface (the non-preferred mode — deliberately moves the cursor):
+wordlive cursor read                              # where is the cursor? which para:N?
+wordlive cursor write --text "inserted here"      # type at the cursor
+
+# Styles + paragraph formatting (atomic-undo):
+wordlive style list
+wordlive style apply --anchor-id heading:3 --name "Heading 2"
+wordlive format-paragraph --anchor-id heading:3 --alignment center --space-before 6
+
+# Tables (cells are anchors: table:N:R:C):
+wordlive table list
+wordlive table read 1
+wordlive replace --anchor-id table:1:2:2 --text "$450"
+wordlive table add-row --table 1 --values '["Lodging", "$600"]'
+
+# Collaboration: comments + track changes (the polite, non-destructive surface):
+wordlive comment add --anchor-id heading:3 --text "Please expand this." --author Bot
+wordlive comment list
+wordlive comment resolve --index 1
+wordlive track on            # record edits as revisions; `track off` to stop
+
+# Lists & numbering (any anchor's paragraphs):
+wordlive list apply --anchor-id heading:6 --type numbered
+wordlive list restart --anchor-id heading:6
+
+# Sections, headers & footers (header:S:WHICH / footer:S:WHICH):
+wordlive section list
+wordlive header write --section 1 --text "ACME Corporation"
+wordlive footer read --section 1
+
+# Batch multiple ops in a single Ctrl-Z:
+wordlive exec --script ops.json
+```
+
+Where `ops.json` looks like:
+
+```json
+{
+  "label": "Update report",
+  "ops": [
+    {"op": "write_bookmark", "name": "Address", "text": "123 Main St"},
+    {"op": "write_cc", "name": "Signatory", "text": "Jane Doe"},
+    {"op": "insert_paragraph", "anchor_id": "heading:3", "text": "New risk paragraph."},
+    {"op": "replace", "anchor_id": "heading:3", "text": "Updated section text"},
+    {"op": "apply_style", "anchor_id": "heading:3", "name": "Heading 2"},
+    {"op": "format_paragraph", "anchor_id": "heading:3", "alignment": "center", "space_before": 6}
+  ]
+}
+```
+
+Exit codes: `0` ok, `2` anchor-not-found, `3` Word-busy, `4` Word-not-running, `1` other.
+
+## Design
+
+- **Politeness first** — operations preserve the user's `Selection`, view, and
+  scroll. The user keeps editing alongside you.
+- **Semantic anchors over `Selection`** — operations target bookmarks, content
+  controls, or headings — never the live cursor unless you ask.
+- **Atomic undo** — every `doc.edit()` opens a Word `UndoRecord`, so a single
+  Ctrl-Z reverts the whole block.
+- **Escape hatch** — every wrapper exposes `.com` for the raw COM object;
+  you're never blocked by missing coverage.
+
+See [`spec.md`](spec.md) for the full design.