docxium 0.1.0__tar.gz

docxium-0.1.0/.github/workflows/CI.yml

@@ -0,0 +1,79 @@
+# Builds the wheels and the sdist and tests every wheel on the oldest and a recent Python.
+# release.yml calls this workflow and publishes the artifacts.
+#
+# Every wheel is built and tested on a runner of its own architecture. Linux arm64 has no
+# "latest" runner label, so a versioned one is used.
+
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - master
+  pull_request:
+  workflow_dispatch:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  wheels:
+    name: wheel (${{ matrix.name }})
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: linux-x86_64
+            runner: ubuntu-latest
+          - name: linux-aarch64
+            runner: ubuntu-24.04-arm
+          - name: windows-x64
+            runner: windows-latest
+          - name: macos-aarch64
+            runner: macos-latest
+          - name: macos-x86_64
+            runner: macos-15-intel
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.x"
+      - name: Build the wheel
+        uses: PyO3/maturin-action@v1
+        with:
+          args: --release --out dist
+          manylinux: auto
+          sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
+      - name: Upload the wheel
+        uses: actions/upload-artifact@v7
+        with:
+          name: wheels-${{ matrix.name }}
+          path: dist
+      - uses: astral-sh/setup-uv@v10.2.0
+      - name: Test the wheel
+        shell: bash
+        run: |
+          set -e
+          for version in 3.9 3.14; do
+            uv venv --python "$version" ".venv-$version"
+            uv pip install --python ".venv-$version" dist/*.whl
+            uv run --no-project --python ".venv-$version" python -m unittest discover tests
+          done
+
+  sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Build the sdist
+        uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+      - name: Upload the sdist
+        uses: actions/upload-artifact@v7
+        with:
+          name: wheels-sdist
+          path: dist

docxium-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,49 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+      - master
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Install docxium and the documentation tools
+        run: |
+          pip install maturin
+          pip install .
+          pip install -r docs/requirements.txt
+      - name: Build the documentation
+        run: sphinx-build -b html docs docs/_build/html
+      - uses: actions/configure-pages@v6
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: docs/_build/html
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5

docxium-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,57 @@
+# Publishes to PyPI with Trusted Publishing (OIDC); no API token is stored in the repository.
+#
+# PyPI setup: add a trusted publisher for the project "docxium" with
+#   owner: cmostw, repository: docxium, workflow: release.yml, environment: pypi.
+#
+# Trigger: push a tag named v<version>, for example v0.1.0.
+
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    uses: ./.github/workflows/CI.yml
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/docxium
+    permissions:
+      # OIDC token for PyPI and for the attestation
+      id-token: write
+      attestations: write
+    steps:
+      - uses: actions/checkout@v7
+      - name: Check that the tag matches the package version
+        run: |
+          python3 - <<'PY'
+          import os
+          import tomllib
+
+          tag = os.environ["GITHUB_REF_NAME"].removeprefix("v")
+          versions = {
+              "pyproject.toml": tomllib.load(open("pyproject.toml", "rb"))["project"]["version"],
+              "Cargo.toml": tomllib.load(open("Cargo.toml", "rb"))["package"]["version"],
+          }
+          mismatched = {name: v for name, v in versions.items() if v != tag}
+          if mismatched:
+              raise SystemExit(f"tag {tag} does not match {mismatched}")
+          PY
+      - uses: actions/download-artifact@v8
+      - name: Generate artifact attestation
+        uses: actions/attest@v4
+        with:
+          subject-path: 'wheels-*/*'
+      - uses: astral-sh/setup-uv@v10.2.0
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always 'wheels-*/*'

docxium-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Python / uv
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+
+# Python build artifacts
+build/
+dist/
+docs/_build/
+
+# Compiled extension and debug symbols produced by maturin
+*.so
+*.pdb
+
+# Rust
+target/
+
+# Test / lint / type-check caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# IDE / editor
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db

docxium-0.1.0/Cargo.lock

@@ -0,0 +1,148 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "docxium"
+version = "0.1.0"
+dependencies = [
+ "pyo3",
+ "quick-xml",
+]
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "libc"
+version = "0.2.190"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ce5d3ddc6d3fa000eb1536d85e147bfe31aacaba692ed6a876f95cb7c855be78"
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "portable-atomic"
+version = "1.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05c8b63e8d9609db387f0324918f81d68fe27748f084ef092fb35954d0539a85"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.29.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "700d18fa267b73b9b521fd7e13580e2f446916f176cacee1ab63fcc8191f1655"
+dependencies = [
+ "libc",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.29.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7b3fc0c4d08f6bb10e71fe39dfb9e2f59c6eb6854e22ec8092f50c69a4499adb"
+dependencies = [
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.29.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dfc0b8e19df29aad7086cf977bb0c2a2f143e30567eb113e9cf72b62ca698330"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.29.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6100e8a4b5eba53afaa5ed078364851a0b2499c553a44c31026b929049b49dc6"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.29.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6143877a16e82b5a727b7127ff4cd86858a24a28d745d72f43e6f227c7b1bdb3"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "quick-xml"
+version = "0.42.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41b1177fdf999d2321d3fb46ff47159d9c1fb9ad66a4879f8c50a0b504615e9b"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "target-lexicon"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.26"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d245f478577f809a851594d02313b640fb437e0bb33866753cff937863096954"

docxium-0.1.0/Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "docxium"
+version = "0.1.0"
+edition = "2024"
+description = "Batch operations for python-docx implemented in Rust"
+license = "MIT"
+readme = "README.md"
+
+[lib]
+name = "_core"
+crate-type = ["cdylib"]
+
+[dependencies]
+pyo3 = { version = "0.29.3", features = ["abi3-py39"] }
+quick-xml = "0.42.0"
+
+[profile.release]
+lto = true
+codegen-units = 1

docxium-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CMOS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docxium-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: docxium
+Version: 0.1.0
+Requires-Dist: python-docx>=1.2,<2
+License-File: LICENSE
+Summary: python-docx extended with batch operations implemented in Rust
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+<a id="readme-top"></a>
+
+<!-- PROJECT HEADER -->
+<br />
+<div align="center">
+  <h3 align="center">docxium</h3>
+
+  <p align="center">
+    python-docx extended with batch operations implemented in Rust.
+  </p>
+
+[![MIT License][license-shield]][license-url] [![Rust][Rust-badge]][Rust-url] [![Python][Python-badge]][Python-url]
+
+  <p align="center">
+    <a href="https://cmostw.github.io/docxium/"><strong>Documentation »</strong></a>
+    &middot;
+    <a href="#benchmarks">Benchmarks</a>
+    &middot;
+    <a href="https://github.com/cmostw/docxium/issues/new?labels=bug">Report Bug</a>
+    &middot;
+    <a href="https://github.com/cmostw/docxium/issues/new?labels=enhancement">Request Feature</a>
+  </p>
+</div>
+
+<!-- TABLE OF CONTENTS -->
+<details>
+  <summary>Table of Contents</summary>
+  <ol>
+    <li><a href="#about-the-project">About The Project</a></li>
+    <li><a href="#usage">Usage</a></li>
+    <li><a href="#benchmarks">Benchmarks</a></li>
+    <li><a href="#license">License</a></li>
+  </ol>
+</details>
+
+<!-- ABOUT THE PROJECT -->
+## About The Project
+
+[python-docx](https://github.com/python-openxml/python-docx) adds content to a document one call
+at a time. With 50,000 paragraphs of three runs each, building the document takes 39.5 s and
+reading all paragraph text back takes 3.5 s (see [Benchmarks](#benchmarks)).
+
+docxium keeps python-docx as the document model and adds batch methods. A batch method receives a
+whole list of paragraphs or table rows in one call. Rust generates the WordprocessingML for the
+list, and python-docx's own parser inserts it into the document, so the result is an ordinary
+python-docx `Document`.
+
+* `import docxium as docx` exposes the batch methods. Names and submodules that docxium does not
+  define (`docxium.shared`, `docxium.enum.text`, ...) are forwarded to python-docx.
+* Methods that python-docx already provides are python-docx's and are not changed.
+* Opening and saving are performed by python-docx and are not changed.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+<!-- USAGE EXAMPLES -->
+## Usage
+
+Everything python-docx provides is used as python-docx documents it. Only the additions below
+are specific to docxium. They are available on the document returned by `docxium.Document()`,
+or on an existing `docx.Document` after `docxium.accelerate(doc)`.
+
+```python
+import docxium as docx
+
+doc = docx.Document()
+doc.add_headings(["Introduction", "Methods"], level=1, alignment="center")
+doc.add_paragraphs(
+    [
+        "plain",
+        ["mixed ", ("bold", True, None), ("red", {"size": 18, "color": "FF0000"})],
+    ],
+    alignment="justify",
+)
+doc.add_table_from_rows(rows, header=True, col_widths=[docx.shared.Inches(1)] * 3)
+texts = doc.extract_paragraph_texts()
+```
+
+| method | behavior |
+|---|---|
+| `add_paragraphs(paragraphs, style=None, alignment=None)` | Appends one paragraph per item. `style` is a style name or object; `alignment` is a `WD_ALIGN_PARAGRAPH` member or its name; both apply to every item. Equivalent to `add_paragraph` and `add_run` calls. |
+| `add_headings(texts, level=1, alignment=None)` | Same as `add_paragraphs` with the `Title` style for level 0 and `Heading N` for levels 1-9, as `add_heading` selects. |
+| `add_table_from_rows(rows, style=None, *, header=False, col_widths=None)` | Appends a table and returns it. Cells that are not `str` are converted with `str()`. `header=True` writes the first row in bold. `col_widths` holds one width per column (a `docx.shared.Length` or an EMU integer); without it the text width is divided evenly, as `add_table` does. |
+| `extract_paragraph_texts()` | Returns the text of every paragraph in document order, including paragraphs inside tables. `Document.paragraphs` lists body-level paragraphs only. |
+
+A paragraph is a `str` or an iterable of runs. A run is a `str`, `(text, bold, italic)`, or
+`(text, {...})` where the dict may contain:
+
+| key | value |
+|---|---|
+| `bold`, `italic`, `underline`, `strike`, `all_caps`, `small_caps` | bool |
+| `superscript`, `subscript` | bool (not both) |
+| `size` | points, e.g. `10.5` |
+| `color` | `"RRGGBB"` (a leading `#` is accepted) |
+| `font` | font name |
+| `highlight` | color name (`"yellow"`, `"darkBlue"`, `"dark_blue"`) or a `WD_COLOR_INDEX` member |
+
+Invalid input raises `TypeError` or `ValueError`.
+
+The written XML equals python-docx's for the equivalent calls, with one difference: an empty table
+cell is written as `<w:p/>`, while python-docx writes `<w:p><w:r/></w:p>`.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+<!-- BENCHMARKS -->
+## Benchmarks
+
+Speed-up is the python-docx time divided by the docxium time. Each workload runs on one thread;
+the value reported is the median of 7 rounds.
+
+* **Workloads:** paragraphs of three runs each (one plain, one bold, one italic), and tables of
+  five columns.
+* **Build** creates the document from in-memory data, including the time to prepare that data.
+* **Extract text** reads the text of all paragraphs.
+* **Total** is build + save + open + extract.
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/_static/benchmarks-dark.svg">
+    <img alt="Bar charts of the docxium speed-up over python-docx for build, text extraction and total, with the measured times beside each bar." src="docs/_static/benchmarks-light.svg" width="880">
+  </picture>
+</p>
+
+Save and open are performed by python-docx in both cases; their ratios lie between 0.93× and
+1.05×. Timings for every phase are listed in [docs/benchmarks.rst](docs/benchmarks.rst).
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+<!-- LICENSE -->
+## License
+
+Distributed under the MIT License. See [`LICENSE`](LICENSE) for more information. docxium
+depends on python-docx, which is also MIT licensed.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+<!-- MARKDOWN LINKS & IMAGES -->
+[license-shield]: https://img.shields.io/github/license/cmostw/docxium.svg?style=for-the-badge
+[license-url]: https://github.com/cmostw/docxium/blob/master/LICENSE
+[Rust-badge]: https://img.shields.io/badge/Rust-000000?style=for-the-badge&logo=rust&logoColor=white
+[Rust-url]: https://www.rust-lang.org/
+[Python-badge]: https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&logoColor=white
+[Python-url]: https://www.python.org/
+