docx-editor 0.2.2__tar.gz → 0.2.4__tar.gz

{docx_editor-0.2.2 → docx_editor-0.2.4}/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "docx-editor",
   "description": "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "author": {
     "name": "pablospe"
   },

docx_editor-0.2.4/.github/workflows/on-release-main.yml

@@ -0,0 +1,109 @@
+name: release-main
+
+on:
+  release:
+    types: [published]
+
+jobs:
+
+  set-version:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Export tag
+        id: vars
+        run: |
+          release_version="${GITHUB_REF_NAME}"
+          if [[ ! "$release_version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "Release tag must be a plain X.Y.Z version, for example 0.3.0. Do not use a v prefix." >&2
+            exit 1
+          fi
+          echo "version=$release_version" >> "$GITHUB_OUTPUT"
+        if: ${{ github.event_name == 'release' }}
+
+      - name: Validate checked-in versions
+        run: |
+          python - <<'PY'
+          import json
+          import os
+          import sys
+          import tomllib
+          from pathlib import Path
+
+          expected = os.environ["RELEASE_VERSION"]
+          pyproject = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
+          plugin = json.loads(Path(".claude-plugin/plugin.json").read_text())["version"]
+          lock = tomllib.loads(Path("uv.lock").read_text())
+          locked = next(
+              package["version"]
+              for package in lock["package"]
+              if package["name"] == "docx-editor"
+          )
+
+          versions = {
+              "release tag": expected,
+              "pyproject.toml": pyproject,
+              "uv.lock": locked,
+              ".claude-plugin/plugin.json": plugin,
+          }
+          mismatches = {name: version for name, version in versions.items() if version != expected}
+          if mismatches:
+              for name, version in versions.items():
+                  print(f"{name}: {version}", file=sys.stderr)
+              raise SystemExit("Release versions must all match before publishing.")
+          PY
+        env:
+          RELEASE_VERSION: ${{ steps.vars.outputs.version }}
+        if: ${{ github.event_name == 'release' }}
+
+      - name: Update project version
+        run: |
+          sed -i "s/^version = \".*\"/version = \"$RELEASE_VERSION\"/" pyproject.toml
+        env:
+          RELEASE_VERSION: ${{ steps.vars.outputs.version }}
+        if: ${{ github.event_name == 'release' }}
+
+      - name: Upload updated pyproject.toml
+        uses: actions/upload-artifact@v4
+        with:
+          name: pyproject-toml
+          path: pyproject.toml
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: [set-version]
+    permissions:
+      id-token: write  # Required for trusted publishing
+    steps:
+      - name: Check out
+        uses: actions/checkout@v4
+
+      - name: Set up the environment
+        uses: ./.github/actions/setup-python-env
+
+      - name: Download updated pyproject.toml
+        uses: actions/download-artifact@v4
+        with:
+          name: pyproject-toml
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish package
+        run: uv publish
+
+  deploy-docs:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # Required for gh-pages push
+    steps:
+      - name: Check out
+        uses: actions/checkout@v4
+
+      - name: Set up the environment
+        uses: ./.github/actions/setup-python-env
+
+      - name: Deploy documentation
+        run: uv run mkdocs gh-deploy --force

{docx_editor-0.2.2 → docx_editor-0.2.4}/.gitignore

@@ -211,4 +211,5 @@ marimo/_static/
 marimo/_lsp/
 __marimo__/
 
-.worktree
+.worktree/
+.worktrees/

{docx_editor-0.2.2 → docx_editor-0.2.4}/CONTRIBUTING.md

@@ -96,7 +96,7 @@ Now, validate that all unit tests are passing:
 make test
 ```
 
-9. Before raising a pull request you should also run tox.
+8. Before raising a pull request you should also run tox.
    This will run the tests across different versions of Python:
 
 ```bash
@@ -106,15 +106,15 @@ tox
 This requires you to have multiple versions of python installed.
 This step is also triggered in the CI/CD pipeline, so you could also choose to skip this step locally.
 
-10. Commit your changes and push your branch to GitHub:
+9. Commit your changes and push your branch to GitHub:
 
 ```bash
-git add .
+git add <changed-files>
 git commit -m "Your detailed description of your changes."
 git push origin name-of-your-bugfix-or-feature
 ```
 
-11. Submit a pull request through the GitHub website.
+10. Submit a pull request through the GitHub website.
 
 # Pull Request Guidelines
 
@@ -136,31 +136,58 @@ This project uses GitHub Releases to trigger automated publishing to PyPI and do
    - `pyproject.toml` → `version = "X.Y.Z"`
    - `.claude-plugin/plugin.json` → `"version": "X.Y.Z"`
 
-2. **Commit and push** the version bump:
+   The release workflow also re-stamps `pyproject.toml` from the release
+   tag before building. The manual bump is still required so `main`,
+   `uv.lock`, and plugin metadata are consistent before the release starts.
+
+2. **Refresh `uv.lock`** so its pinned project version matches:
+
+   ```bash
+   uv lock
+   ```
+
+   Skipping this makes `make check` and release validation fail with
+   `The lockfile at 'uv.lock' needs to be updated, but '--locked' was provided.`
+
+3. **Run the local checks**:
 
    ```bash
-   git add pyproject.toml .claude-plugin/plugin.json
+   make check
+   make test
+   ```
+
+4. **Commit and push** the version bump:
+
+   ```bash
+   git add pyproject.toml .claude-plugin/plugin.json uv.lock
    git commit -m "bump version to X.Y.Z"
    git push origin main
    ```
 
-3. **Create a GitHub Release**:
+5. **Create a GitHub Release**:
 
    - Go to [Releases](https://github.com/pablospe/docx-editor/releases/new)
-   - Create a new tag matching the version: `X.Y.Z` (e.g., `0.3.0`)
+   - **Create a new tag matching the version: `X.Y.Z` (e.g., `0.3.0`). Do not use a `v` prefix.**
    - Set the target branch to `main`
    - Add release notes (use "Generate release notes" for a changelog)
    - Click **Publish release**
 
-4. **Automated CI** (`.github/workflows/on-release-main.yml`) will:
+6. **Automated CI** (`.github/workflows/on-release-main.yml`) will:
 
-   - Update `pyproject.toml` version from the release tag
+   - Validate that the release tag, `pyproject.toml`, `uv.lock`, and `.claude-plugin/plugin.json` versions match
+   - Update `pyproject.toml` version from the release tag before packaging
    - Build the package with `uv build`
    - Publish to [PyPI](https://pypi.org/project/docx-editor/) via trusted publishing
    - Deploy documentation to GitHub Pages with `mkdocs gh-deploy`
 
+7. **Verify the release**:
+
+   - Check that the release workflow completed successfully in GitHub Actions
+   - Confirm the new version appears on [PyPI](https://pypi.org/project/docx-editor/)
+   - Confirm the documentation was deployed to GitHub Pages
+
 ## Notes
 
-- The release tag **must** match the version format (e.g., `0.3.0`, no `v` prefix)
+- The release tag **must** match the version format exactly (e.g., `0.3.0`, no `v` prefix)
 - PyPI publishing uses [trusted publishing](https://docs.pypi.org/trusted-publishers/) (no API tokens needed)
 - If you need to build and publish manually, you can use `make build-and-publish`

{docx_editor-0.2.2 → docx_editor-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docx-editor
-Version: 0.2.2
+Version: 0.2.4
 Summary: Edit docx with python
 Project-URL: Homepage, https://pablospe.github.io/docx-editor/
 Project-URL: Repository, https://github.com/pablospe/docx-editor

{docx_editor-0.2.2 → docx_editor-0.2.4}/docs/api.md

@@ -18,10 +18,14 @@ Open a Word document for editing.
 
 - `path` (str | Path): Path to the .docx file
 - `author` (str, optional): Author name for tracked changes. Defaults to system username.
-- `force_recreate` (bool): If True, delete existing workspace and create fresh. Defaults to False.
+- `force_recreate` (bool): If True, delete any existing workspace (stale or in-sync) before opening — any unsaved edits in the workspace are discarded. Use this to recover from `WorkspaceSyncError`. Defaults to False.
 
 **Returns:** Document instance ready for editing
 
+**Raises:**
+
+- `WorkspaceSyncError`: If the source `.docx` was modified since the workspace was created. Pass `force_recreate=True` to discard the stale workspace and re-unpack from the current source. The workspace is never deleted silently.
+
 **Example:**
 
 ```python
@@ -49,7 +53,73 @@ print(doc.source_path)  # Path("/path/to/contract.docx")
 
 ### Track Changes Methods
 
-#### `replace(find, replace_with)`
+#### `list_paragraphs(max_chars=80)`
+
+List paragraphs with hash-anchored references.
+
+**Parameters:**
+
+- `max_chars` (int): Maximum preview length. Use 0 for refs only.
+
+**Returns:** List of strings in the form `P{index}#{hash}| preview text`
+
+**Example:**
+
+```python
+refs = doc.list_paragraphs()
+for ref in refs:
+    print(ref)
+```
+
+#### `get_visible_text()`
+
+Get flattened visible document text. Inserted text is included and deleted text is excluded.
+
+**Returns:** Visible text with paragraphs separated by newlines (str)
+
+**Example:**
+
+```python
+text = doc.get_visible_text()
+```
+
+#### `find_text(text, occurrence=0)`
+
+Find text in the document, including text spanning XML element boundaries.
+
+**Parameters:**
+
+- `text` (str): Text to search for
+- `occurrence` (int): Which occurrence to return. Defaults to 0.
+
+**Returns:** Match information, or None if not found
+
+**Example:**
+
+```python
+match = doc.find_text("Aim: To")
+if match and match.spans_boundary:
+    print("Text spans multiple XML contexts")
+```
+
+#### `count_matches(text)`
+
+Count visible text matches across the document.
+
+**Parameters:**
+
+- `text` (str): Text to search for
+
+**Returns:** Number of occurrences found (int)
+
+**Example:**
+
+```python
+if doc.count_matches("Section 5") > 1:
+    print("Use paragraph refs and occurrence to target the intended match")
+```
+
+#### `replace(find, replace_with, *, paragraph, occurrence=0)`
 
 Replace text with tracked changes.
 
@@ -57,32 +127,37 @@ Replace text with tracked changes.
 
 - `find` (str): Text to find and replace
 - `replace_with` (str): Replacement text
+- `paragraph` (str): Paragraph reference from `list_paragraphs()`, such as `P2#f3c1`
+- `occurrence` (int): Which occurrence within the paragraph. Defaults to 0.
 
-**Returns:** The change ID of the insertion (int)
+**Returns:** Updated paragraph reference (str)
 
 **Example:**
 
 ```python
-doc.replace("30 days", "60 days")
+ref = doc.replace("30 days", "60 days", paragraph="P2#f3c1")
+doc.replace("net", "gross", paragraph=ref)
 ```
 
-#### `delete(text)`
+#### `delete(text, *, paragraph, occurrence=0)`
 
 Mark text as deleted with tracked changes.
 
 **Parameters:**
 
 - `text` (str): Text to mark as deleted
+- `paragraph` (str): Paragraph reference from `list_paragraphs()`, such as `P2#f3c1`
+- `occurrence` (int): Which occurrence within the paragraph. Defaults to 0.
 
-**Returns:** The change ID of the deletion (int)
+**Returns:** Updated paragraph reference (str)
 
 **Example:**
 
 ```python
-doc.delete("obsolete clause")
+ref = doc.delete("obsolete clause", paragraph="P5#d4e5")
 ```
 
-#### `insert_after(anchor, text)`
+#### `insert_after(anchor, text, *, paragraph, occurrence=0)`
 
 Insert text after anchor with tracked changes.
 
@@ -90,16 +165,18 @@ Insert text after anchor with tracked changes.
 
 - `anchor` (str): Text to find as insertion point
 - `text` (str): Text to insert after the anchor
+- `paragraph` (str): Paragraph reference from `list_paragraphs()`, such as `P2#f3c1`
+- `occurrence` (int): Which occurrence within the paragraph. Defaults to 0.
 
-**Returns:** The change ID of the insertion (int)
+**Returns:** Updated paragraph reference (str)
 
 **Example:**
 
 ```python
-doc.insert_after("Section 5", " (as amended)")
+ref = doc.insert_after("Section 5", " (as amended)", paragraph="P3#b2c4")
 ```
 
-#### `insert_before(anchor, text)`
+#### `insert_before(anchor, text, *, paragraph, occurrence=0)`
 
 Insert text before anchor with tracked changes.
 
@@ -107,13 +184,72 @@ Insert text before anchor with tracked changes.
 
 - `anchor` (str): Text to find as insertion point
 - `text` (str): Text to insert before the anchor
+- `paragraph` (str): Paragraph reference from `list_paragraphs()`, such as `P2#f3c1`
+- `occurrence` (int): Which occurrence within the paragraph. Defaults to 0.
+
+**Returns:** Updated paragraph reference (str)
+
+**Example:**
+
+```python
+ref = doc.insert_before("Section 6", "New clause: ", paragraph="P4#a7b2")
+```
+
+#### `rewrite_paragraph(ref, new_text)`
+
+Rewrite a paragraph using tracked changes generated from a word-level diff.
+
+**Parameters:**
+
+- `ref` (str): Paragraph reference from `list_paragraphs()`
+- `new_text` (str): Desired paragraph text
+
+**Returns:** Updated paragraph reference (str)
+
+**Example:**
+
+```python
+ref = doc.rewrite_paragraph("P2#f3c1", "Payment is due within 60 days after invoice receipt.")
+```
+
+#### `batch_edit(operations)`
+
+Apply multiple edits after validating paragraph hashes up front.
+
+**Parameters:**
+
+- `operations` (list[EditOperation]): Edit operations to apply
+
+**Returns:** Updated paragraph references in input order (list[str])
+
+**Example:**
+
+```python
+from docx_editor import EditOperation
+
+new_refs = doc.batch_edit([
+    EditOperation(action="replace", find="old", replace_with="new", paragraph="P2#f3c1"),
+    EditOperation(action="delete", text="remove this", paragraph="P5#d4e5"),
+])
+```
+
+#### `batch_rewrite(rewrites)`
+
+Rewrite multiple paragraphs after validating paragraph hashes up front.
+
+**Parameters:**
+
+- `rewrites` (list[tuple[str, str]]): Pairs of paragraph ref and desired text
 
-**Returns:** The change ID of the insertion (int)
+**Returns:** Updated paragraph references in input order (list[str])
 
 **Example:**
 
 ```python
-doc.insert_before("Section 6", "New clause: ")
+new_refs = doc.batch_rewrite([
+    ("P1#a7b2", "Updated first paragraph."),
+    ("P3#c3d4", "Updated third paragraph."),
+])
 ```
 
 ### Comment Methods
@@ -403,7 +539,7 @@ Raised when the specified text is not found in the document.
 from docx_editor.exceptions import TextNotFoundError
 
 try:
-    doc.replace("nonexistent text", "new text")
+    doc.replace("nonexistent text", "new text", paragraph="P2#f3c1")
 except TextNotFoundError as e:
     print(f"Text not found: {e}")
 ```

docx_editor-0.2.4/docs/index.md

@@ -0,0 +1,62 @@
+# docx-editor
+
+Pure Python library for Word document track changes and comments, without requiring Microsoft Word.
+
+> **Note:** The PyPI package is named `docx-editor` because `docx-edit` was too similar to an existing package.
+
+## Features
+
+- **Hash-Anchored Paragraph References**: target edits with paragraph refs like `P2#f3c1`
+- **Batch Editing**: apply multiple paragraph-scoped edits with upfront hash validation
+- **Paragraph Rewrite**: rewrite a paragraph and generate tracked changes from the diff
+- **Track Changes**: Replace, delete, and insert text with revision tracking
+- **Comments**: Add, reply, resolve, and delete comments
+- **Revision Management**: List, accept, and reject tracked changes
+- **Cross-Boundary Editing**: Find and replace text spanning multiple XML elements
+- **Cross-Platform**: Works on Linux, macOS, and Windows
+- **No Dependencies**: Only requires `defusedxml` for secure XML parsing
+
+## Installation
+
+```bash
+pip install docx-editor
+```
+
+## Quick Start
+
+```python
+from docx_editor import Document
+
+with Document.open("contract.docx", author="Legal Team") as doc:
+    # List paragraphs to get hash-anchored references.
+    for paragraph in doc.list_paragraphs():
+        print(paragraph)
+    # Example output:
+    # P1#a7b2| Introduction to the contract...
+    # P2#f3c1| Payment is due within 30 days...
+
+    # Edit methods require a paragraph ref and return the updated ref.
+    ref = doc.replace("30 days", "60 days", paragraph="P2#f3c1")
+    ref = doc.insert_after("Payment", " terms", paragraph=ref)
+    doc.delete("obsolete text", paragraph="P5#d4e5")
+
+    # Comments and revision management.
+    doc.add_comment("Section 5", "Please review")
+    revisions = doc.list_revisions()
+    if revisions:
+        doc.accept_revision(revisions[0].id)
+
+    doc.save()
+```
+
+## Context Manager
+
+```python
+from docx_editor import Document
+
+with Document.open("contract.docx") as doc:
+    ref = doc.list_paragraphs()[0].split("|", 1)[0]
+    doc.replace("old term", "new term", paragraph=ref)
+    doc.save()
+# Automatically closes and cleans up workspace
+```