Skip to main content

oxml

Create and edit Word DOCX files from Python, including text, tables, comments and tracked changes. oxml uses a Rust XML editor and types derived from Microsoft's Open XML SDK. It requires neither .NET nor Office.

Edit a document

from oxml import Document

doc = Document.open('draft.docx')
doc.story.find('fourteen days').replace('twenty-one days')
doc.save('edited.docx')

Search works across text runs, so a phrase need not have uniform formatting. Replacement preserves surrounding formatting and uses the first affected run's format for the new text. Find the text again after each edit: ranges refer to a particular version of the XML.

doc.story is the main document text. doc.stories() also gives access to headers, footers, notes and comments. Story(element, view='original') reads the text before tracked changes without accepting or rejecting them.

Replacement can split and join adjacent paragraphs using \n, but cannot cross section or table-cell boundaries. Bookmarks and comment anchors survive text edits. Fields, content controls and existing revision payloads are protected from ordinary text replacement.

Build and edit XML

Use Document.new() to start a document, or Tree(xml_bytes) to work with standalone XML.

from oxml import Document, e, w

doc = Document.new()
body = next(doc.main.xml.elements(w.Body))
paragraph = body(e.p(e.r(e.t('New paragraph'))))
paragraph(e.pPr(e.jc(val='center')))
doc.save('new.docx')

e.p(...) builds a detached XML expression. Calling a live parent, such as body(...), attaches it and returns the new live element. Placement follows the schema: paragraph properties go before runs, and paragraphs go before final section properties. Existing content is never rearranged. Use parent(expression, index=n) when you need an exact XML child-node position or the schema order is unknown.

The e factory supplies the w namespace for elements and attributes. For example, e.tcW(type='dxa', w=2400) creates a table-cell width. Other attribute prefixes use double underscores, such as r__id and xml__space. Configure another namespace with E('a'), or custom bindings with E(ns=bindings).

You can also work directly with typed elements. For example, next(doc.main.xml.elements(w.Text)).value = 'Replacement' changes one text node. Typed attributes check values against SDK rules and refuse constraints they cannot fully check. Raw XML editing remains available for those cases.

The XML editor supports elements, attributes, text, comments and processing instructions, with namespace-aware copying and movement. It reads UTF-8 and UTF-16. Typed views and raw XML edits share the same live tree.

See Editing and preservation contracts for copying, namespaces and raw XML operations.

Comments and tracked changes

Add a comment to a text range:

doc = Document.open('draft.docx')
comment = doc.comments.add(doc.story.find('fourteen days'), 'Please extend this period.', 'Reviewer')
comment.reply('Agreed.', 'Drafter')
comment.resolve()
doc.save('commented.docx')

Comments support plain-text bodies, replies, resolution and deletion of individual reply subtrees or whole threads. Comment anchors are currently supported in the main document. Modern reply and resolution metadata is maintained alongside the comment text.

Record a replacement as a tracked change:

doc = Document.open('draft.docx')
doc.revisions.replace(doc.story.find('fourteen days'), 'twenty-one days', author='Drafter')
doc.save('redlined.docx')

Tracked changes cover text insertions and deletions, paragraph splits and joins, and direct run/paragraph formatting. Iterate over doc.revisions to accept or reject individual changes. accept_all() and reject_all() handle a whole story. Use doc.revisions.format(...) to track formatting changes.

Editing inside an existing revision requires accepting or rejecting it first. Table, move and nested revision histories are not supported. Bulk operations refuse unsupported revision types rather than silently skipping them. See Text/review scope for the detailed rules.

Styles, lists, tables and links

  • doc.styles finds, creates and applies paragraph, character and table styles without replacing direct formatting.
  • doc.numbering creates multilevel lists and controls continuation or restart.
  • Table.add(...) creates rectangular tables. Table(element) provides row and column edits. Structural edits do not support merged, offset or revised grids.
  • doc.bookmarks creates, finds and removes bookmarks and builds REF fields.
  • doc.hyperlinks adds and removes internal or external links while retaining the text's formatting. Linked text is protected from range edits until the link is removed.

These helpers edit the document's XML. They do not calculate layout, inherited formatting, displayed list numbers or field results. Usage details are in Document helpers.

doc.set_custom_xml(item_id, xml_bytes, schema_uri=...) creates or replaces a custom XML datastore by GUID and returns its Part. It manages the property part and relationships while preserving unrelated stores. Content controls can refer to the GUID through w:storeItemID.

Compare and import documents

Compare two documents to produce a new document with tracked text and direct-formatting changes:

from oxml import Document, compare

redline = compare(Document.open('original.docx'), Document.open('revised.docx'), author='Reviewer')
redline.save('comparison.docx')

The originals stay unchanged, and equal tables and other opaque blocks are retained. Comparison supports body-text and direct-formatting changes. It refuses changes to tables, sections or dependencies, and documents with unresolved revisions. Changes to paragraph counts require matching direct paragraph properties and a paragraph-only body apart from final section properties.

import_content(...) copies selected paragraphs and tables between documents, including their style, numbering, image and hyperlink dependencies. It preserves complete bookmark ranges and remaps conflicting IDs without overwriting destination definitions. Destination themes and document defaults still apply. Content with reviews, fields, sections or unsupported package dependencies is refused. See Import and compare for the detailed rules.

Preservation and limits

Saving an unchanged document returns the original bytes. Edited saves retain untouched package payloads. XML edits preserve namespace meaning and unknown content. Edited XML is serialized as UTF-8 without retaining its original formatting. doc.package gives access to parts, content types and relationships.

doc.validate() checks XML structure, attribute values, supported semantic rules and package relationships, including headers, footers and other reachable parts. Errors and unchecked regions are reported separately. Validation is incomplete: a report without errors does not establish that a document is valid.

Current document support focuses on DOCX. XLSX editing and conversion of Strict XML namespaces to the typed vocabulary are not implemented. Signed documents can pass through unchanged but cannot be edited. Encrypted, macro-enabled and template documents, ZIP64 and multidisk archives are refused. See DEV.md for resource limits, validation gaps and development commands.

License and acknowledgements

oxml's own code is Apache-2.0 licensed. Imported material retains its upstream notices and terms.

  • Open XML SDK — Microsoft, the .NET Foundation and contributors. Its schema metadata, validator behavior, implementation ideas and tests are the foundation for our typed model and validation. The SDK copyright and MIT notice ships with the Python package.
  • Open XML PowerTools — Microsoft, Eric White and contributors, for revision-processing and document-comparison reference behavior, tests and fixtures.
  • Pandoc — John MacFarlane, Jesse Rosenthal and contributors, for DOCX fixtures and independent reader/review expectations.
  • LibreOffice contributors and The Document Foundation, for regression documents and tests covering modern comments and cross-part content.
  • python-docx — Steve Canny and contributors, for the section fixture and API/test examples; Apache POI — the Apache Software Foundation and contributors, for the header-image fixture and relationship tests.

The fixture source table maps borrowed files to their upstream locations and retained licenses. Adapted tests identify their upstream cases in source comments. Thanks also to the developers of our runtime dependencies, especially PyO3 and quick-xml.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

oxml-0.1.1.tar.gz (809.3 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

oxml-0.1.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.9 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ x86-64

oxml-0.1.1-cp313-cp313-macosx_11_0_arm64.whl (1.8 MB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

oxml-0.1.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.9 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64

oxml-0.1.1-cp312-cp312-macosx_11_0_arm64.whl (1.8 MB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

oxml-0.1.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.9 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ x86-64

oxml-0.1.1-cp311-cp311-macosx_11_0_arm64.whl (1.8 MB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

oxml-0.1.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.9 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.17+ x86-64

oxml-0.1.1-cp310-cp310-macosx_11_0_arm64.whl (1.8 MB view details)

Uploaded CPython 3.10macOS 11.0+ ARM64

File details

Details for the file oxml-0.1.1.tar.gz.

File metadata

  • Download URL: oxml-0.1.1.tar.gz
  • Upload date:
  • Size: 809.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for oxml-0.1.1.tar.gz
Algorithm Hash digest
SHA256 ca14bfbc3280d2024735e3391c84392436f4751725f5ee006cf7432a7424c675
MD5 7457e2c6f7e75afaa9faedc4189da82e
BLAKE2b-256 a36f94a90bf37fcf4b9a4b9eba9c0def62772a8db17655e96e3c6b004a52b786

See more details on using hashes here.

Provenance

The following attestation bundles were made for oxml-0.1.1.tar.gz:

Publisher: ci.yml on AnswerDotAI/oxml

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file oxml-0.1.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for oxml-0.1.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 579028b788d4c6504f907ab88698c2dee449115dc1855264f439176f6b31dc1c
MD5 62c238076915d2de0e0e8e081391ea0b
BLAKE2b-256 560d86ca7882ced91843d5bcba3c8493c922b385d1b9a3584d837d83735c8c6f

See more details on using hashes here.

Provenance

The following attestation bundles were made for oxml-0.1.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: ci.yml on AnswerDotAI/oxml

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file oxml-0.1.1-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for oxml-0.1.1-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 e3a4fd882533bdefbaea2cd405fc3b6b03a526183a1b2b98074547f967e10736
MD5 9225afadabb188df0287e4a9f790ee10
BLAKE2b-256 aa62a502895d72045f2359f2684b0fbc70ff2d1439cdc8aa77db6cb104411800

See more details on using hashes here.

Provenance

The following attestation bundles were made for oxml-0.1.1-cp313-cp313-macosx_11_0_arm64.whl:

Publisher: ci.yml on AnswerDotAI/oxml

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file oxml-0.1.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for oxml-0.1.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 6b1c8dbb6b35196fdbeed8d5e90360dae8e5256799d92b7a73324fd2a470830c
MD5 a47360acfac1be0e6f1894be5d2ed73f
BLAKE2b-256 2e14166eca256b280ad7cf70a6fb05d2ac969683d709fa5495dc7385f1913756

See more details on using hashes here.

Provenance

The following attestation bundles were made for oxml-0.1.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: ci.yml on AnswerDotAI/oxml

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file oxml-0.1.1-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for oxml-0.1.1-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 6833a2b0ab832fdaf11a4aff55b72207e1bf93d39ce2d8e19749905102f4201d
MD5 46612a381dfd1d8367c4e0b100547cce
BLAKE2b-256 9aef506f1036b57e41fd81f6145ddc710c61e0f47f128446f183b24c92f5d38c

See more details on using hashes here.

Provenance

The following attestation bundles were made for oxml-0.1.1-cp312-cp312-macosx_11_0_arm64.whl:

Publisher: ci.yml on AnswerDotAI/oxml

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file oxml-0.1.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for oxml-0.1.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 591d02d4d7098921251b779fe1520cfc262b8b8494b91041ced4e05931742661
MD5 97a2cd107d24b32b0f027a0d2f655f3e
BLAKE2b-256 645bb92bc9dc892be3a36ef9328201e137854ee01e1e07995a1e62ffab6c4e7a

See more details on using hashes here.

Provenance

The following attestation bundles were made for oxml-0.1.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: ci.yml on AnswerDotAI/oxml

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file oxml-0.1.1-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for oxml-0.1.1-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 71e106c81c4a609f3eac9738bc5ba8baec79e6a60992e73926801824a19d93eb
MD5 1642d5037e02680ddbf414e784dae3d3
BLAKE2b-256 0be4ec5e8a95077382ae4b9d8e8dd685d9342ce8a1f573dc0a4aa1b0b8487d41

See more details on using hashes here.

Provenance

The following attestation bundles were made for oxml-0.1.1-cp311-cp311-macosx_11_0_arm64.whl:

Publisher: ci.yml on AnswerDotAI/oxml

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file oxml-0.1.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for oxml-0.1.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 f15773769f60c18235f9751228bcaf14508f2f41a8c108984e75254bac133431
MD5 6155bbe237712545e116ac9921caf236
BLAKE2b-256 b3e9ed718d8d67b8bb21144d851ecfd134989c59b433c2759e57027c9479ca62

See more details on using hashes here.

Provenance

The following attestation bundles were made for oxml-0.1.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: ci.yml on AnswerDotAI/oxml

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file oxml-0.1.1-cp310-cp310-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for oxml-0.1.1-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 9df07d8cc3ad976e36617714da54474668acaecadb928aee62923bf440cfde97
MD5 d72b767cf521150cbfe25526389ef39b
BLAKE2b-256 ed837c4d53a8ffeafffb74dca5f8ce386d34dfd2dc17842fa5a2111a749bf2ff

See more details on using hashes here.

Provenance

The following attestation bundles were made for oxml-0.1.1-cp310-cp310-macosx_11_0_arm64.whl:

Publisher: ci.yml on AnswerDotAI/oxml

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.1.3

9 files

0.1.2

9 files

This release

0.1.1 This release

9 files

0.1.0

9 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page