docxdriver 0.3.3__tar.gz → 0.4.0__tar.gz

{docxdriver-0.3.3 → docxdriver-0.4.0}/Cargo.lock

@@ -416,7 +416,7 @@ dependencies = [
 
 [[package]]
 name = "docxdriver-cli"
-version = "0.3.3"
+version = "0.4.0"
 dependencies = [
  "clap",
  "docxdriver-core",
@@ -427,7 +427,7 @@ dependencies = [
 
 [[package]]
 name = "docxdriver-core"
-version = "0.3.3"
+version = "0.4.0"
 dependencies = [
  "hex",
  "latex2mathml",
@@ -444,7 +444,7 @@ dependencies = [
 
 [[package]]
 name = "docxdriver-mcp"
-version = "0.3.3"
+version = "0.4.0"
 dependencies = [
  "axum",
  "cap-std",
@@ -460,18 +460,26 @@ dependencies = [
  "tokio-util",
 ]
 
+[[package]]
+name = "docxdriver-monty-repl"
+version = "0.4.0"
+dependencies = [
+ "docxdriver-core",
+]
+
 [[package]]
 name = "docxdriver-python"
-version = "0.3.3"
+version = "0.4.0"
 dependencies = [
  "docxdriver-core",
  "pyo3",
+ "serde",
  "serde_json",
 ]
 
 [[package]]
 name = "docxdriver-wasm"
-version = "0.3.3"
+version = "0.4.0"
 dependencies = [
  "docxdriver-core",
  "js-sys",

{docxdriver-0.3.3 → docxdriver-0.4.0}/Cargo.toml

@@ -3,7 +3,7 @@ resolver = "2"
 members = ["crates/docxdriver-python"]
 
 [workspace.package]
-version = "0.3.3"
+version = "0.4.0"
 edition = "2021"
 license = "MIT"
 repository = "https://github.com/jhnoel/docxdriver"

{docxdriver-0.3.3 → docxdriver-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docxdriver
-Version: 0.3.3
+Version: 0.4.0
 Summary: Python SDK for the native Rust DOCX engine
 License-Expression: MIT
 Requires-Python: >=3.10
@@ -18,38 +18,44 @@ Install from PyPI:
 python -m pip install docxdriver
 ```
 
-The core API exposes `execute_request`, `canonical_plan_json`, and the convenience
-functions `run_command`, `run_plan`, and `run_request`. Results preserve document
-contents as Python `bytes`.
-
-The optional sandbox REPL harness is available as a subpackage in the same
-distribution:
+`Document` works on `.docx` bytes; typed plan builders live in
+`docxdriver.plan`:
 
 ```python
-from docxdriver.repl import NativeBridge, PRELUDE, REFERENCE
+from pathlib import Path
+from docxdriver import Document, create
+from docxdriver.plan import Plan, ReplaceText
+
+doc = Document(Path("contract.docx").read_bytes())
+doc.markup()                      # body with the ids plans address
+doc.comments(); doc.revisions(); doc.styles(); doc.assets()
+doc.find("thirty")
+review = doc.review(Plan(author="Reviewer", ops=[
+    ReplaceText(at="0F537164", select="thirty", with_="sixty"),
+]))
+review.report                     # preview: each op's outcome
+Path("contract.docx").write_bytes(doc.commit(review.key).data)
+
+new = create(paragraphs=["Hello"])  # or create(html="<p>Hello</p>")
 ```
 
-`NativeBridge` provides async `init`, `call`, and `reset` requests for a host
-running a Python sandbox. The sandbox receives authoring classes and async
-wrappers from `PRELUDE`; `REFERENCE` provides their API documentation. The
-sandbox itself does not import the native extension. Native work runs through
-host callbacks outside the server event loop.
-
-The host confines reads and writes to the provided workspace, verifies source
-hashes and candidate output before commit, and performs atomic file replacement
-with read-back verification. Commit keys are bounded and single-use. Cancellation
-is drained before another host call so a write callback cannot be abandoned.
+Commit keys are single-use. Natively `review.key` carries the key; in a
+sandbox it is `None` and the host shows the key only to the model, so a
+commit proves the review was read. Sandbox hosts written in Python build on
+the stateless `review_plan(data, plan_json)` and
+`commit_plan(data, plan_json, key)`, keeping each plan under a key they issue.
 
-Set `DOCXDRIVER_QUOTE_AUDIT_COMMENTS=1` to enable structured Quote/Term/Inline plan
-values and protected quotation audit comments. The provenance policy defaults to
-`permissive`; `controlled` and `authoritative` fail closed.
+Engine diagnostics raise `ValueError`. The lower-level `execute_request`,
+`canonical_plan_json`, `run_command`, `run_plan` and `run_request` remain.
 
-The prelude and API reference are generated from shared Pi templates. After
-changing those templates, regenerate them from the repository root:
+`plan.py` and `document.py` stay within Monty's Python subset. Rust hosts get
+the same text as `docxdriver_monty_repl::PLAN` and `DOCUMENT`, so sandbox code
+and native code are interchangeable. The op dataclasses are generated from the
+core schema; regenerate from the repository root with
+`python scripts/generate-python-plan.py`.
 
-```sh
-python scripts/generate-docxdriver-repl-prelude.py
-```
+Version 0.4.0 removed the `docxdriver.repl` sandbox host from this package. Its
+source remains in `experimental/python-repl-host` for hosts to vendor.
 
 Build and install a wheel from the repository root:
 

docxdriver-0.4.0/README.md

@@ -0,0 +1,87 @@
+# docxdriver
+
+Python SDK for the Rust DOCX engine. It supports Python 3.10 and later and has no
+Python runtime dependencies.
+
+Install from PyPI:
+
+```sh
+python -m pip install docxdriver
+```
+
+`Document` works on `.docx` bytes; typed plan builders live in
+`docxdriver.plan`:
+
+```python
+from pathlib import Path
+from docxdriver import Document, create
+from docxdriver.plan import Plan, ReplaceText
+
+doc = Document(Path("contract.docx").read_bytes())
+doc.markup()                      # body with the ids plans address
+doc.comments(); doc.revisions(); doc.styles(); doc.assets()
+doc.find("thirty")
+review = doc.review(Plan(author="Reviewer", ops=[
+    ReplaceText(at="0F537164", select="thirty", with_="sixty"),
+]))
+review.report                     # preview: each op's outcome
+Path("contract.docx").write_bytes(doc.commit(review.key).data)
+
+new = create(paragraphs=["Hello"])  # or create(html="<p>Hello</p>")
+```
+
+Commit keys are single-use. Natively `review.key` carries the key; in a
+sandbox it is `None` and the host shows the key only to the model, so a
+commit proves the review was read. Sandbox hosts written in Python build on
+the stateless `review_plan(data, plan_json)` and
+`commit_plan(data, plan_json, key)`, keeping each plan under a key they issue.
+
+Engine diagnostics raise `ValueError`. The lower-level `execute_request`,
+`canonical_plan_json`, `run_command`, `run_plan` and `run_request` remain.
+
+`plan.py` and `document.py` stay within Monty's Python subset. Rust hosts get
+the same text as `docxdriver_monty_repl::PLAN` and `DOCUMENT`, so sandbox code
+and native code are interchangeable. The op dataclasses are generated from the
+core schema; regenerate from the repository root with
+`python scripts/generate-python-plan.py`.
+
+Version 0.4.0 removed the `docxdriver.repl` sandbox host from this package. Its
+source remains in `experimental/python-repl-host` for hosts to vendor.
+
+Build and install a wheel from the repository root:
+
+```sh
+python -m pip install "maturin>=1.9,<2"
+maturin build --profile python --locked --manifest-path crates/docxdriver-python/Cargo.toml --out /tmp/docxdriver-wheels
+python -m pip install /tmp/docxdriver-wheels/*.whl
+```
+
+## Publish to PyPI
+
+The `Publish Python SDK` GitHub Actions workflow builds a source distribution
+and wheels for Linux x86_64 and aarch64, macOS universal2, and Windows x86_64
+when a `v*` tag is pushed. The tag must match the version in the root
+`Cargo.toml` workspace package.
+
+Before the first release, configure a PyPI trusted publisher for the
+`docxdriver` project with these values:
+
+- Owner: `jhnoel`
+- Repository: `docxdriver`
+- Workflow filename: `pypi.yml`
+- GitHub environment: `pypi`
+
+Create the `pypi` GitHub environment under the repository settings if you want
+to add release approvals. Then update the workspace version, commit the change,
+and push the matching tag (for example, `v0.2.7`). GitHub Actions publishes the
+built distributions using PyPI's trusted publishing; no long-lived PyPI token is
+needed.
+
+The `python` Cargo profile keeps release optimizations and enables panic unwinding
+so PyO3 can turn Rust panics into Python exceptions. ABI3 wheels support Python
+3.10 and later on the built operating system and architecture. To run the Python
+SDK and host tests after installing the wheel:
+
+```sh
+python -m unittest discover -s crates/docxdriver-python/tests
+```

{docxdriver-0.3.3 → docxdriver-0.4.0}/crates/docxdriver-core/Cargo.toml

@@ -4,7 +4,13 @@ description = "Artifact-first DOCX engine: (bytes, DocxCommand JSON) -> (bytes,
 version.workspace = true
 edition.workspace = true
 license.workspace = true
+repository.workspace = true
 readme = "README.md"
+keywords = ["docx", "ooxml", "word", "document", "track-changes"]
+categories = ["text-processing", "parser-implementations"]
+# Library sources and the runtime template only; tests, examples and the
+# schema generator stay in the repository.
+include = ["/src/**/*.rs", "!/src/bin/**", "/assets/blank.docx", "/README.md", "/LICENSE"]
 
 [dependencies]
 xmloxide = { version = "0.4.3", default-features = false }

docxdriver-0.4.0/crates/docxdriver-core/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 docxdriver contributors
+
+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.

docxdriver-0.4.0/crates/docxdriver-core/src/facade.rs

@@ -0,0 +1,200 @@
+//! Typed document API over the Request engine: one `.docx` in memory,
+//! read, searched, reviewed and committed without JSON envelopes.
+//!
+//! ```text
+//! let doc = Document::open(&bytes);
+//! doc.markup(View::Markup)?            body with the ids plans address
+//! doc.comments()? / revisions()? / styles()? / assets()?
+//! doc.find("thirty", Case::Sensitive)?
+//! let plan = doc.plan(json)?           bound to these bytes
+//! let review = doc.review(&plan)?      key + report, nothing written
+//! let bytes = doc.commit(&plan, &review.key)?
+//! ```
+//!
+//! The preview key binds bytes and plan, so commit refuses anything that
+//! was not reviewed against these exact bytes. No state lives between calls.
+
+use serde_json::Value;
+
+use crate::api::{
+    execute_command, execute_plan, parse_plan_json, Command, CommandRequest, CommandResult,
+    CreateCommand, Diagnostic, FindCommand, Plan, PlanReport, PlanRequest, PlanResult,
+    PreviewKey, ReadCommand, SourceHash,
+};
+
+/// Which text of the body to project.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum View {
+    /// Tracked changes shown as `<ins>`/`<del>`.
+    Markup,
+    /// As if every change were accepted.
+    Final,
+    /// As if every change were rejected.
+    Original,
+}
+
+/// Case handling for [`Document::find`].
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Case {
+    Sensitive,
+    Insensitive,
+}
+
+/// What [`create`] builds a new document from.
+#[derive(Debug, Clone, PartialEq)]
+pub enum Source {
+    Paragraphs(Vec<String>),
+    Html(String),
+}
+
+/// A previewed plan: commit it with `key`; `report` says what each op did.
+#[derive(Debug, Clone, PartialEq)]
+pub struct Review {
+    pub key: PreviewKey,
+    pub report: PlanReport,
+}
+
+/// A `.docx` held as bytes.
+#[derive(Debug, Clone, Copy)]
+pub struct Document<'a> {
+    bytes: &'a [u8],
+}
+
+/// Builds a new `.docx`.
+pub fn create(source: Source) -> Result<Vec<u8>, Diagnostic> {
+    let command = match source {
+        Source::Paragraphs(paragraphs) => CreateCommand { paragraphs, html: None },
+        Source::Html(html) => CreateCommand { paragraphs: Vec::new(), html: Some(html) },
+    };
+    match run(None, Command::Create(command)) {
+        CommandResult::Completed { bytes: Some(bytes), .. } => Ok(bytes),
+        CommandResult::Completed { .. } => Err(engine("create returned no document")),
+        CommandResult::Rejected { diagnostic, .. } => Err(diagnostic),
+    }
+}
+
+impl<'a> Document<'a> {
+    pub fn open(bytes: &'a [u8]) -> Self {
+        Self { bytes }
+    }
+
+    /// The body as HTML-like markup with stable paragraph ids.
+    pub fn markup(&self, view: View) -> Result<String, Diagnostic> {
+        let view = match view {
+            View::Markup => "markup",
+            View::Final => "final",
+            View::Original => "original",
+        };
+        let result = self.read("document", Some(view))?;
+        match result.get("markup") {
+            Some(Value::String(markup)) => Ok(markup.clone()),
+            _ => Err(engine("document read returned no markup")),
+        }
+    }
+
+    /// Equations by paragraph, e.g. `{"at": "0F537164", "equation": 1, ...}`,
+    /// the addresses `replace_equation`/`delete_equation` take.
+    pub fn equations(&self) -> Result<Vec<Value>, Diagnostic> {
+        Ok(array(self.read("document", None)?, "equations"))
+    }
+
+    /// Comment threads with anchors and replies.
+    pub fn comments(&self) -> Result<Vec<Value>, Diagnostic> {
+        self.list("comments")
+    }
+
+    /// Tracked changes; their ids feed `AcceptRevision`/`RejectRevision`.
+    pub fn revisions(&self) -> Result<Vec<Value>, Diagnostic> {
+        self.list("revisions")
+    }
+
+    /// Style definitions.
+    pub fn styles(&self) -> Result<Vec<Value>, Diagnostic> {
+        self.list("styles")
+    }
+
+    /// Embedded images and media.
+    pub fn assets(&self) -> Result<Vec<Value>, Diagnostic> {
+        self.list("assets")
+    }
+
+    /// Paragraphs containing `query`, with their ids.
+    pub fn find(&self, query: &str, case: Case) -> Result<Vec<Value>, Diagnostic> {
+        let command = FindCommand {
+            query: query.into(),
+            ignore_case: case == Case::Insensitive,
+            view: None,
+        };
+        let result = completed(run(Some(self.bytes), Command::Find(command)))?;
+        Ok(array(result, "matches"))
+    }
+
+    /// Parses a plan's JSON and binds it to these bytes; any `base` given
+    /// is replaced. E.g. `{"author":"A","change_mode":"track","ops":[...]}`.
+    pub fn plan(&self, json: &str) -> Result<Plan, Diagnostic> {
+        let mut value: Value = serde_json::from_str(json).map_err(|error| invalid(error.to_string()))?;
+        let Some(object) = value.as_object_mut() else {
+            return Err(invalid("a plan is a JSON object".into()));
+        };
+        object.insert("base".into(), Value::String(SourceHash::from_bytes(self.bytes).as_str()));
+        parse_plan_json(&value.to_string())
+    }
+
+    /// Previews `plan`; writes nothing.
+    pub fn review(&self, plan: &Plan) -> Result<Review, Diagnostic> {
+        match self.execute(plan, None) {
+            PlanResult::Previewed { preview_key, report, .. } => Ok(Review { key: preview_key, report }),
+            PlanResult::Committed { .. } => Err(engine("preview committed")),
+            PlanResult::Rejected { diagnostic, .. } => Err(diagnostic),
+        }
+    }
+
+    /// Applies a reviewed plan, returning the new document's bytes.
+    pub fn commit(&self, plan: &Plan, key: &PreviewKey) -> Result<Vec<u8>, Diagnostic> {
+        match self.execute(plan, Some(key.clone())) {
+            PlanResult::Committed { bytes, .. } => Ok(bytes),
+            PlanResult::Previewed { .. } => Err(engine("commit only previewed")),
+            PlanResult::Rejected { diagnostic, .. } => Err(diagnostic),
+        }
+    }
+
+    fn execute(&self, plan: &Plan, preview_key: Option<PreviewKey>) -> PlanResult {
+        execute_plan(self.bytes, &PlanRequest { plan: plan.clone(), preview_key })
+    }
+
+    // One listing read, e.g. "comments" → result["comments"].
+    fn list(&self, part: &str) -> Result<Vec<Value>, Diagnostic> {
+        Ok(array(self.read(part, None)?, part))
+    }
+
+    fn read(&self, part: &str, view: Option<&str>) -> Result<Value, Diagnostic> {
+        let command = ReadCommand { read_kind: Some(part.into()), view: view.map(Into::into) };
+        completed(run(Some(self.bytes), Command::Read(command)))
+    }
+}
+
+fn run(input: Option<&[u8]>, command: Command) -> CommandResult {
+    execute_command(input, &CommandRequest { command, expected_source: None })
+}
+
+fn completed(result: CommandResult) -> Result<Value, Diagnostic> {
+    match result {
+        CommandResult::Completed { result, .. } => Ok(result.unwrap_or(Value::Null)),
+        CommandResult::Rejected { diagnostic, .. } => Err(diagnostic),
+    }
+}
+
+fn array(mut result: Value, field: &str) -> Vec<Value> {
+    match result.get_mut(field).map(Value::take) {
+        Some(Value::Array(items)) => items,
+        _ => Vec::new(),
+    }
+}
+
+fn invalid(message: String) -> Diagnostic {
+    Diagnostic { code: "invalid_plan".into(), message, path: None, span: None }
+}
+
+fn engine(message: &str) -> Diagnostic {
+    Diagnostic { code: "engine".into(), message: message.into(), path: None, span: None }
+}

{docxdriver-0.3.3 → docxdriver-0.4.0}/crates/docxdriver-core/src/lib.rs

@@ -3,11 +3,13 @@
 //! The stable contract is the source-bound typed [`Request`] and [`RequestResult`]
 //! API. Requests are either a typed one-command envelope or a validated Plan;
 //! plans support canonical JSON/TOML, deterministic preview keys, atomic folds,
-//! typed diagnostics, and complete output metadata.
+//! typed diagnostics, and complete output metadata. [`Document`] is the same
+//! engine as plain methods on one document's bytes.
 
 mod api;
 mod commands;
 mod document;
+mod facade;
 mod html;
 mod media;
 mod outcome;
@@ -15,3 +17,4 @@ mod package;
 mod segments;
 
 pub use api::*;
+pub use facade::{create, Case, Document, Review, Source, View};

{docxdriver-0.3.3 → docxdriver-0.4.0}/crates/docxdriver-python/Cargo.toml

@@ -4,6 +4,7 @@ description = "Native Python bindings for docxdriver-core"
 version.workspace = true
 edition.workspace = true
 license.workspace = true
+publish = false
 readme = "README.md"
 
 [lib]
@@ -13,4 +14,5 @@ crate-type = ["cdylib", "rlib"]
 [dependencies]
 docxdriver-core = { path = "../docxdriver-core" }
 pyo3 = { version = "0.27.2", features = ["abi3-py310"] }
+serde = "1"
 serde_json = "1"

docxdriver-0.4.0/crates/docxdriver-python/README.md

@@ -0,0 +1,87 @@
+# docxdriver
+
+Python SDK for the Rust DOCX engine. It supports Python 3.10 and later and has no
+Python runtime dependencies.
+
+Install from PyPI:
+
+```sh
+python -m pip install docxdriver
+```
+
+`Document` works on `.docx` bytes; typed plan builders live in
+`docxdriver.plan`:
+
+```python
+from pathlib import Path
+from docxdriver import Document, create
+from docxdriver.plan import Plan, ReplaceText
+
+doc = Document(Path("contract.docx").read_bytes())
+doc.markup()                      # body with the ids plans address
+doc.comments(); doc.revisions(); doc.styles(); doc.assets()
+doc.find("thirty")
+review = doc.review(Plan(author="Reviewer", ops=[
+    ReplaceText(at="0F537164", select="thirty", with_="sixty"),
+]))
+review.report                     # preview: each op's outcome
+Path("contract.docx").write_bytes(doc.commit(review.key).data)
+
+new = create(paragraphs=["Hello"])  # or create(html="<p>Hello</p>")
+```
+
+Commit keys are single-use. Natively `review.key` carries the key; in a
+sandbox it is `None` and the host shows the key only to the model, so a
+commit proves the review was read. Sandbox hosts written in Python build on
+the stateless `review_plan(data, plan_json)` and
+`commit_plan(data, plan_json, key)`, keeping each plan under a key they issue.
+
+Engine diagnostics raise `ValueError`. The lower-level `execute_request`,
+`canonical_plan_json`, `run_command`, `run_plan` and `run_request` remain.
+
+`plan.py` and `document.py` stay within Monty's Python subset. Rust hosts get
+the same text as `docxdriver_monty_repl::PLAN` and `DOCUMENT`, so sandbox code
+and native code are interchangeable. The op dataclasses are generated from the
+core schema; regenerate from the repository root with
+`python scripts/generate-python-plan.py`.
+
+Version 0.4.0 removed the `docxdriver.repl` sandbox host from this package. Its
+source remains in `experimental/python-repl-host` for hosts to vendor.
+
+Build and install a wheel from the repository root:
+
+```sh
+python -m pip install "maturin>=1.9,<2"
+maturin build --profile python --locked --manifest-path crates/docxdriver-python/Cargo.toml --out /tmp/docxdriver-wheels
+python -m pip install /tmp/docxdriver-wheels/*.whl
+```
+
+## Publish to PyPI
+
+The `Publish Python SDK` GitHub Actions workflow builds a source distribution
+and wheels for Linux x86_64 and aarch64, macOS universal2, and Windows x86_64
+when a `v*` tag is pushed. The tag must match the version in the root
+`Cargo.toml` workspace package.
+
+Before the first release, configure a PyPI trusted publisher for the
+`docxdriver` project with these values:
+
+- Owner: `jhnoel`
+- Repository: `docxdriver`
+- Workflow filename: `pypi.yml`
+- GitHub environment: `pypi`
+
+Create the `pypi` GitHub environment under the repository settings if you want
+to add release approvals. Then update the workspace version, commit the change,
+and push the matching tag (for example, `v0.2.7`). GitHub Actions publishes the
+built distributions using PyPI's trusted publishing; no long-lived PyPI token is
+needed.
+
+The `python` Cargo profile keeps release optimizations and enables panic unwinding
+so PyO3 can turn Rust panics into Python exceptions. ABI3 wheels support Python
+3.10 and later on the built operating system and architecture. To run the Python
+SDK and host tests after installing the wheel:
+
+```sh
+python -m unittest discover -s crates/docxdriver-python/tests
+```

{docxdriver-0.3.3 → docxdriver-0.4.0/crates/docxdriver-python}/python/docxdriver/__init__.py

@@ -1,6 +1,7 @@
 """Python SDK for the docxdriver document engine."""
 import json
-from ._core import __version__, canonical_plan_json, execute_request
+from ._core import __version__, canonical_plan_json, commit_plan, execute_request, review_plan
+from .document import Document, Review, create
 
 
 def run_request(data, request):