python-docx-oss 0.2.0__tar.gz → 0.3.0__tar.gz

{python_docx_oss-0.2.0 → python_docx_oss-0.3.0}/HISTORY.md

@@ -1,5 +1,13 @@
 ## Release History
 
+**Unreleased**
+
+**0.3.0 (2026-08-29)**
+
+- Added opt-in package-level document sanitization for personal metadata,
+  comments, web extensions, and formatting revision history.
+- Added structured sanitization reports and real Word comment round-trip coverage.
+
 **0.2.0 (2026-08-24)**
 
 - Added direct loading from raw DOCX bytes with ``Document(bytes)``.

{python_docx_oss-0.2.0/src/python_docx_oss.egg-info → python_docx_oss-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-docx-oss
-Version: 0.2.0
+Version: 0.3.0
 Summary: Create, read, and update Microsoft Word .docx files.
 Author: Ethan St Lee
 License-Expression: MIT
@@ -23,7 +23,7 @@ Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: lxml>=3.1.0
+Requires-Dist: lxml>=6.1.0
 Requires-Dist: typing_extensions>=4.9.0
 Dynamic: license-file
 
@@ -65,7 +65,8 @@ or low-level package and relationship access.
 | Latin and East Asian font controls | Stable | `run.font.name`, `run.font.hAnsi`, `run.font.eastAsia` |
 | Low-level OPC parts and relationships | Stable | `document.part.package`, `part.rels` |
 | In-memory read, export, and independent copies | Stable | `Document()`, `to_bytes()`, `copy()` |
-| Package inspection, diff, and sanitization | Planned | — |
+| Document sanitization | Development | `document.sanitize()` |
+| Package inspection and diff | Planned | — |
 
 ## Installation
 

{python_docx_oss-0.2.0 → python_docx_oss-0.3.0}/README.md

@@ -36,7 +36,8 @@ or low-level package and relationship access.
 | Latin and East Asian font controls | Stable | `run.font.name`, `run.font.hAnsi`, `run.font.eastAsia` |
 | Low-level OPC parts and relationships | Stable | `document.part.package`, `part.rels` |
 | In-memory read, export, and independent copies | Stable | `Document()`, `to_bytes()`, `copy()` |
-| Package inspection, diff, and sanitization | Planned | — |
+| Document sanitization | Development | `document.sanitize()` |
+| Package inspection and diff | Planned | — |
 
 ## Installation
 

python_docx_oss-0.3.0/docs/api/sanitize.rst

@@ -0,0 +1,60 @@
+.. _sanitize_api:
+
+Sanitization objects
+====================
+
+.. currentmodule:: docx.sanitize
+
+
+SanitizationReport objects
+--------------------------
+
+.. autoclass:: SanitizationReport
+   :members: changed
+
+   .. attribute:: scrubbed_properties
+
+      Names of core properties normalized during sanitization.
+
+   .. attribute:: removed_comment_markers
+
+      Number of outermost comment marker elements removed from Word story XML.
+
+   .. attribute:: removed_formatting_revisions
+
+      Number of outermost formatting revision elements removed.
+
+   .. attribute:: removed_parts
+
+      Package part names made unreachable by removed relationships.
+
+   .. attribute:: removed_relationships
+
+      :class:`RemovedRelationship` records for relationships removed from the
+      package graph.
+
+   .. attribute:: warnings
+
+      Non-fatal conditions encountered while sanitizing the package.
+
+
+RemovedRelationship objects
+---------------------------
+
+.. autoclass:: RemovedRelationship
+
+   .. attribute:: source
+
+      Part name of the relationship source, or ``/`` for the package itself.
+
+   .. attribute:: relationship_id
+
+      Relationship identifier used by the source.
+
+   .. attribute:: relationship_type
+
+      Full relationship type URI.
+
+   .. attribute:: target
+
+      Target part name or external target reference.

{python_docx_oss-0.2.0 → python_docx_oss-0.3.0}/docs/index.rst

@@ -22,7 +22,9 @@ supports capabilities needed by more demanding document workflows:
 * SVG and EMF vector images;
 * separate Latin and East Asian font settings;
 * document custom properties; and
-* multiple Custom XML parts that survive a load/save round trip.
+* multiple Custom XML parts that survive a load/save round trip; and
+* explicit package-level sanitization of metadata, comments, web extensions,
+  and formatting revision history.
 
 Here is a small example:
 
@@ -94,6 +96,7 @@ User Guide
    user/styles-understanding
    user/styles-using
    user/comments
+   user/sanitization
    user/shapes
    user/custom-properties
    user/custom-xml
@@ -113,6 +116,7 @@ API Documentation
    api/table
    api/section
    api/comments
+   api/sanitize
    api/shape
    api/dml
    api/shared

python_docx_oss-0.3.0/docs/user/sanitization.rst

@@ -0,0 +1,56 @@
+.. _sanitization:
+
+Document sanitization
+=====================
+
+Sanitization removes selected package-level information before a document is
+shared. Every operation is disabled by default because removal is destructive.
+
+Use :meth:`Document.sanitize() <docx.document.Document.sanitize>` with explicit
+options and inspect its report before saving::
+
+    from docx import Document
+
+    document = Document("input.docx")
+    report = document.sanitize(
+        personal_metadata=True,
+        comments=True,
+        web_extensions=True,
+        formatting_revisions=True,
+    )
+
+    if report.changed:
+        document.save("sanitized.docx")
+
+The returned :class:`~docx.sanitize.SanitizationReport` identifies scrubbed
+properties, removed XML markers, parts, and relationships, plus any warnings.
+Each removed relationship is represented by
+:class:`~docx.sanitize.RemovedRelationship`. Repeating the same sanitization is
+idempotent: the second report has ``changed == False`` when nothing new was
+added.
+
+Options
+-------
+
+``personal_metadata``
+    Clears author and last-modified-by values and canonicalizes the revision
+    number. Duplicate property elements are removed.
+
+``comments``
+    Removes comment markers from all reachable Word XML story parts and removes
+    the complete comments relationship tree, including modern comments extension
+    parts when present.
+
+``web_extensions``
+    Removes web-extension task panes and their related package parts.
+
+``formatting_revisions``
+    Removes property-change history such as ``rPrChange`` and ``pPrChange`` while
+    retaining the currently effective formatting.
+
+Scope boundary
+--------------
+
+This API does not accept or reject tracked content revisions. It also does not
+remove Custom XML, macros, OLE objects, external links, or application-specific
+business metadata. Those operations require separate policy decisions.

{python_docx_oss-0.2.0 → python_docx_oss-0.3.0}/pyproject.toml

@@ -18,7 +18,7 @@ classifiers = [
   "Topic :: Office/Business :: Office Suites",
   "Topic :: Software Development :: Libraries",
 ]
-dependencies = ["lxml>=3.1.0", "typing_extensions>=4.9.0"]
+dependencies = ["lxml>=6.1.0", "typing_extensions>=4.9.0"]
 description = "Create, read, and update Microsoft Word .docx files."
 dynamic = ["version"]
 keywords = ["docx", "office", "openxml", "word"]
@@ -41,7 +41,7 @@ dev = [
   "behave>=1.2.6",
   "pyparsing>=3.2.3",
   "pyright>=1.1.401",
-  "pytest>=8.4.0",
+  "pytest>=9.0.3",
   "ruff>=0.11.13",
   "sphinx-book-theme",
   "tox>=4.26.0",

{python_docx_oss-0.2.0 → python_docx_oss-0.3.0}/src/docx/__init__.py

@@ -13,7 +13,7 @@ from docx.api import Document
 if TYPE_CHECKING:
     from docx.opc.part import Part
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 
 __all__ = ["Document"]

{python_docx_oss-0.2.0 → python_docx_oss-0.3.0}/src/docx/document.py

@@ -12,6 +12,7 @@ from docx.api import Document as open_document
 from docx.blkcntnr import BlockItemContainer
 from docx.enum.section import WD_SECTION
 from docx.enum.text import WD_BREAK
+from docx.sanitize import SanitizationReport, sanitize_document
 from docx.section import Section, Sections
 from docx.shared import ElementProxy, Emu, Inches, Length
 from docx.text.run import Run
@@ -229,6 +230,27 @@ class Document(ElementProxy):
         """
         self._part.save(path_or_stream)
 
+    def sanitize(
+        self,
+        *,
+        personal_metadata: bool = False,
+        comments: bool = False,
+        web_extensions: bool = False,
+        formatting_revisions: bool = False,
+    ) -> SanitizationReport:
+        """Apply the explicitly selected package-level cleanup operations.
+
+        Every option defaults to |False| because sanitization is destructive. The
+        returned report describes all package and XML changes made to this document.
+        """
+        return sanitize_document(
+            self,
+            personal_metadata=personal_metadata,
+            comments=comments,
+            web_extensions=web_extensions,
+            formatting_revisions=formatting_revisions,
+        )
+
     @property
     def sections(self) -> Sections:
         """|Sections| object providing access to each section in this document."""

{python_docx_oss-0.2.0 → python_docx_oss-0.3.0}/src/docx/opc/coreprops.py

@@ -9,6 +9,7 @@ import datetime as dt
 from typing import TYPE_CHECKING
 
 from docx.oxml.coreprops import CT_CoreProperties
+from docx.oxml.ns import qn
 
 if TYPE_CHECKING:
     from docx.oxml.coreprops import CT_CoreProperties
@@ -21,6 +22,40 @@ class CoreProperties:
     def __init__(self, element: CT_CoreProperties):
         self._element = element
 
+    def deduplicate(self, *property_names: str) -> set[str]:
+        """Remove duplicate XML elements for the named core properties.
+
+        The first occurrence is retained so callers can subsequently normalize its
+        value through the regular property setter.
+        """
+        element_tags = {
+            "author": qn("dc:creator"),
+            "category": qn("cp:category"),
+            "comments": qn("dc:description"),
+            "content_status": qn("cp:contentStatus"),
+            "created": qn("dcterms:created"),
+            "identifier": qn("dc:identifier"),
+            "keywords": qn("cp:keywords"),
+            "language": qn("dc:language"),
+            "last_modified_by": qn("cp:lastModifiedBy"),
+            "last_printed": qn("cp:lastPrinted"),
+            "modified": qn("dcterms:modified"),
+            "revision": qn("cp:revision"),
+            "subject": qn("dc:subject"),
+            "title": qn("dc:title"),
+            "version": qn("cp:version"),
+        }
+        changed: set[str] = set()
+        for property_name in property_names:
+            try:
+                tag = element_tags[property_name]
+            except KeyError as exc:
+                raise ValueError(f"Unsupported core property: {property_name}") from exc
+            for duplicate in self._element.findall(tag)[1:]:
+                self._element.remove(duplicate)
+                changed.add(property_name)
+        return changed
+
     @property
     def author(self):
         return self._element.author_text

{python_docx_oss-0.2.0 → python_docx_oss-0.3.0}/src/docx/opc/part.py

@@ -144,6 +144,10 @@ class Part:
             rel = self.rels.get_or_add(reltype, cast(Part, target))
             return rel.rId
 
+    def replace_blob(self, blob: bytes) -> None:
+        """Replace the serialized payload of this non-XML part."""
+        self._blob = blob
+
     @property
     def related_parts(self):
         """Dictionary mapping related parts by rId, so child objects can resolve
@@ -235,6 +239,10 @@ class XmlPart(Part):
         """The root XML element of this XML part."""
         return self._element
 
+    def replace_blob(self, blob: bytes) -> None:
+        """Reject raw replacement because this part serializes from ``element``."""
+        raise TypeError("cannot replace the blob of an XmlPart; replace its element instead")
+
     @element.setter
     def element(self, e: BaseOxmlElement):
         self._element = e

python_docx_oss-0.3.0/src/docx/sanitize/__init__.py

@@ -0,0 +1,10 @@
+"""Package-level DOCX sanitization.
+
+Callers use :meth:`docx.document.Document.sanitize`; this package keeps OPC graph
+mutation and XML cleanup details behind that single method.
+"""
+
+from docx.sanitize.cleaner import sanitize_document
+from docx.sanitize.result import RemovedRelationship, SanitizationReport
+
+__all__ = ["RemovedRelationship", "SanitizationReport", "sanitize_document"]

python_docx_oss-0.3.0/src/docx/sanitize/cleaner.py

@@ -0,0 +1,221 @@
+"""Implementation of the package-level sanitization boundary."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Iterator
+
+from lxml import etree
+
+from docx.opc.oxml import serialize_part_xml
+from docx.opc.part import Part, XmlPart
+from docx.oxml.ns import qn
+from docx.oxml.parser import parse_xml
+from docx.sanitize.result import RemovedRelationship, SanitizationReport
+
+if TYPE_CHECKING:
+    from lxml.etree import _Element as etree_Element  # pyright: ignore[reportPrivateUsage]
+
+    from docx.document import Document
+    from docx.opc.package import OpcPackage
+    from docx.oxml.xmlchemy import BaseOxmlElement
+
+
+_COMMENT_MARKER_TAGS = (
+    qn("w:commentRangeStart"),
+    qn("w:commentRangeEnd"),
+    qn("w:commentReference"),
+)
+_COMMENT_RELATIONSHIP_NAMES = frozenset(
+    {
+        "commentauthors",
+        "comments",
+        "commentsextended",
+        "commentsextensible",
+        "commentsids",
+        "people",
+    }
+)
+_FORMATTING_REVISION_TAGS = tuple(
+    qn(tag)
+    for tag in (
+        "w:rPrChange",
+        "w:pPrChange",
+        "w:tblPrChange",
+        "w:trPrChange",
+        "w:tcPrChange",
+        "w:sectPrChange",
+    )
+)
+_WEB_EXTENSION_RELATIONSHIP_NAMES = frozenset({"webextension", "webextensiontaskpanes"})
+
+
+def sanitize_document(
+    document: Document,
+    *,
+    personal_metadata: bool,
+    comments: bool,
+    web_extensions: bool,
+    formatting_revisions: bool,
+) -> SanitizationReport:
+    """Apply selected sanitizers while keeping all graph mechanics internal."""
+    package = document.part.package
+    assert package is not None
+
+    if not any((personal_metadata, comments, web_extensions, formatting_revisions)):
+        return SanitizationReport()
+
+    parts_before = _reachable_part_names(package)
+    scrubbed_properties: list[str] = []
+    removed_relationships: list[RemovedRelationship] = []
+    warnings: list[str] = []
+    removed_comment_markers = 0
+    removed_formatting_revisions = 0
+
+    if personal_metadata:
+        scrubbed_properties.extend(_scrub_personal_metadata(package))
+
+    if comments or formatting_revisions:
+        for part, root in _iter_word_xml(package, warnings):
+            part_changed = False
+            if comments:
+                count = _remove_elements(root, _COMMENT_MARKER_TAGS)
+                removed_comment_markers += count
+                part_changed = part_changed or count > 0
+            if formatting_revisions:
+                count = _remove_elements(root, _FORMATTING_REVISION_TAGS)
+                removed_formatting_revisions += count
+                part_changed = part_changed or count > 0
+            if part_changed and not isinstance(part, XmlPart):
+                part.replace_blob(serialize_part_xml(root))
+
+    if comments:
+        removed_relationships.extend(_drop_relationships(package, _COMMENT_RELATIONSHIP_NAMES))
+    if web_extensions:
+        removed_relationships.extend(
+            _drop_relationships(package, _WEB_EXTENSION_RELATIONSHIP_NAMES)
+        )
+
+    parts_after = _reachable_part_names(package)
+    return SanitizationReport(
+        scrubbed_properties=tuple(scrubbed_properties),
+        removed_comment_markers=removed_comment_markers,
+        removed_formatting_revisions=removed_formatting_revisions,
+        removed_parts=tuple(sorted(parts_before - parts_after)),
+        removed_relationships=tuple(removed_relationships),
+        warnings=tuple(warnings),
+    )
+
+
+def _drop_relationships(
+    package: OpcPackage, relationship_names: frozenset[str]
+) -> list[RemovedRelationship]:
+    removed: list[RemovedRelationship] = []
+    for source_name, source in _relationship_sources(package):
+        for rId, rel in list(source.rels.items()):
+            if _relationship_name(rel.reltype) not in relationship_names:
+                continue
+            target = rel.target_ref if rel.is_external else str(rel.target_part.partname)
+            removed.append(RemovedRelationship(source_name, rId, rel.reltype, target))
+            del source.rels[rId]
+    return removed
+
+
+def _iter_word_xml(
+    package: OpcPackage, warnings: list[str]
+) -> Iterator[tuple[Part, BaseOxmlElement]]:
+    for part in _reachable_parts(package):
+        if not str(part.partname).startswith("/word/"):
+            continue
+        if isinstance(part, XmlPart):
+            yield part, part.element
+            continue
+        if not part.content_type.endswith("+xml") and part.content_type != "application/xml":
+            continue
+        try:
+            yield part, parse_xml(part.blob)
+        except etree.XMLSyntaxError as exc:
+            warnings.append(f"Could not sanitize XML part {part.partname}: {exc}")
+
+
+def _reachable_parts(package: OpcPackage) -> list[Part]:
+    parts: list[Part] = []
+    visited: set[int] = set()
+
+    def walk(source: OpcPackage | Part) -> None:
+        for rel in source.rels.values():
+            if rel.is_external:
+                continue
+            part = rel.target_part
+            identity = id(part)
+            if identity in visited:
+                continue
+            visited.add(identity)
+            parts.append(part)
+            walk(part)
+
+    walk(package)
+    return parts
+
+
+def _reachable_part_names(package: OpcPackage) -> set[str]:
+    return {str(part.partname) for part in _reachable_parts(package)}
+
+
+def _relationship_name(relationship_type: str) -> str:
+    return relationship_type.rstrip("/").rsplit("/", 1)[-1].lower()
+
+
+def _relationship_sources(package: OpcPackage) -> list[tuple[str, OpcPackage | Part]]:
+    return [("/", package), *[(str(part.partname), part) for part in _reachable_parts(package)]]
+
+
+def _remove_elements(root: BaseOxmlElement, tags: tuple[str, ...]) -> int:
+    tag_set = set(tags)
+    elements = [
+        element
+        for tag in tags
+        for element in root.iter(tag)
+        if not any(ancestor.tag in tag_set for ancestor in element.iterancestors())
+    ]
+    for element in elements:
+        parent = element.getparent()
+        if parent is not None:
+            comment_run = _empty_comment_reference_run(element)
+            parent.remove(element)
+            if comment_run is not None:
+                comment_run_parent = comment_run.getparent()
+                if comment_run_parent is not None:
+                    comment_run_parent.remove(comment_run)
+    return len(elements)
+
+
+def _scrub_personal_metadata(package: OpcPackage) -> list[str]:
+    core_properties = package.core_properties
+    changed = core_properties.deduplicate("author", "last_modified_by", "revision")
+    if core_properties.author:
+        changed.add("author")
+    if core_properties.last_modified_by:
+        changed.add("last_modified_by")
+    if core_properties.revision != 1:
+        changed.add("revision")
+    core_properties.author = ""
+    core_properties.last_modified_by = ""
+    core_properties.revision = 1
+    return [name for name in ("author", "last_modified_by", "revision") if name in changed]
+
+
+def _empty_comment_reference_run(element: etree_Element) -> etree_Element | None:
+    if element.tag != qn("w:commentReference"):
+        return None
+    run = element.getparent()
+    if run is None or run.tag != qn("w:r"):
+        return None
+    remaining = [child for child in run if child is not element]
+    if not remaining:
+        return run
+    if len(remaining) != 1 or remaining[0].tag != qn("w:rPr"):
+        return None
+    run_properties = remaining[0]
+    if len(run_properties) != 1 or run_properties[0].tag != qn("w:rStyle"):
+        return None
+    return run if run_properties[0].get(qn("w:val")) == "CommentReference" else None

python_docx_oss-0.3.0/src/docx/sanitize/result.py

@@ -0,0 +1,38 @@
+"""Value objects returned by document sanitization."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class RemovedRelationship:
+    """A package relationship removed during sanitization."""
+
+    source: str
+    relationship_id: str
+    relationship_type: str
+    target: str
+
+
+@dataclass(frozen=True)
+class SanitizationReport:
+    """Immutable summary of changes made by ``Document.sanitize()``."""
+
+    scrubbed_properties: tuple[str, ...] = ()
+    removed_comment_markers: int = 0
+    removed_formatting_revisions: int = 0
+    removed_parts: tuple[str, ...] = ()
+    removed_relationships: tuple[RemovedRelationship, ...] = ()
+    warnings: tuple[str, ...] = ()
+
+    @property
+    def changed(self) -> bool:
+        """Whether the document package was modified."""
+        return bool(
+            self.scrubbed_properties
+            or self.removed_comment_markers
+            or self.removed_formatting_revisions
+            or self.removed_parts
+            or self.removed_relationships
+        )

{python_docx_oss-0.2.0 → python_docx_oss-0.3.0/src/python_docx_oss.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-docx-oss
-Version: 0.2.0
+Version: 0.3.0
 Summary: Create, read, and update Microsoft Word .docx files.
 Author: Ethan St Lee
 License-Expression: MIT
@@ -23,7 +23,7 @@ Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: lxml>=3.1.0
+Requires-Dist: lxml>=6.1.0
 Requires-Dist: typing_extensions>=4.9.0
 Dynamic: license-file
 
@@ -65,7 +65,8 @@ or low-level package and relationship access.
 | Latin and East Asian font controls | Stable | `run.font.name`, `run.font.hAnsi`, `run.font.eastAsia` |
 | Low-level OPC parts and relationships | Stable | `document.part.package`, `part.rels` |
 | In-memory read, export, and independent copies | Stable | `Document()`, `to_bytes()`, `copy()` |
-| Package inspection, diff, and sanitization | Planned | — |
+| Document sanitization | Development | `document.sanitize()` |
+| Package inspection and diff | Planned | — |
 
 ## Installation
 

{python_docx_oss-0.2.0 → python_docx_oss-0.3.0}/src/python_docx_oss.egg-info/SOURCES.txt

@@ -29,6 +29,7 @@ docs/_themes/armstrong/static/rtd.css_t
 docs/api/comments.rst
 docs/api/dml.rst
 docs/api/document.rst
+docs/api/sanitize.rst
 docs/api/section.rst
 docs/api/settings.rst
 docs/api/shape.rst
@@ -98,6 +99,7 @@ docs/user/documents.rst
 docs/user/hdrftr.rst
 docs/user/install.rst
 docs/user/quickstart.rst
+docs/user/sanitization.rst
 docs/user/sections.rst
 docs/user/shapes.rst
 docs/user/styles-understanding.rst
@@ -343,6 +345,9 @@ src/docx/parts/numbering.py
 src/docx/parts/settings.py
 src/docx/parts/story.py
 src/docx/parts/styles.py
+src/docx/sanitize/__init__.py
+src/docx/sanitize/cleaner.py
+src/docx/sanitize/result.py
 src/docx/styles/__init__.py
 src/docx/styles/latent.py
 src/docx/styles/style.py
@@ -393,6 +398,7 @@ tests/test_document.py
 tests/test_drawing.py
 tests/test_enum.py
 tests/test_package.py
+tests/test_sanitize.py
 tests/test_section.py
 tests/test_settings.py
 tests/test_shape.py
@@ -402,6 +408,7 @@ tests/unitdata.py
 tests/dml/__init__.py
 tests/dml/test_color.py
 tests/fixtures/README.md
+tests/fixtures/comments/word-comments-rich.docx
 tests/fixtures/customxml/generate_fixture.py
 tests/fixtures/customxml/multiple-custom-xml-parts.docx
 tests/fixtures/documents/word-blank.docx

{python_docx_oss-0.2.0 → python_docx_oss-0.3.0}/src/python_docx_oss.egg-info/requires.txt

@@ -1,2 +1,2 @@
-lxml>=3.1.0
+lxml>=6.1.0
 typing_extensions>=4.9.0