python-docx-oss 0.3.3__tar.gz → 0.4.0__tar.gz

{python_docx_oss-0.3.3 → python_docx_oss-0.4.0}/HISTORY.md

@@ -1,5 +1,15 @@
 ## Release History
 
+**0.4.0 (2026-10-29)**
+
+- Added explicit, transactional empty Custom XML repair and conservative hyperlink
+  field conversion and run merging, with immutable change reports and selection callbacks.
+- Added read-only package inspection with immutable inventories, structured findings,
+  empty and whitespace-only XML detection, and streaming hyperlink feature detection
+  across Word story parts.
+- Added configurable SHA-256 package fingerprints with incremental payload processing,
+  XML canonicalization, and explicit part, relationship, and XML exclusions.
+
 **0.3.3 (2026-09-10)**
 
 - Switched PyPI distribution to GitHub Actions automated releases using PyPI Trusted Publishing (OIDC).

{python_docx_oss-0.3.3/src/python_docx_oss.egg-info → python_docx_oss-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-docx-oss
-Version: 0.3.3
+Version: 0.4.0
 Summary: Create, read, and update Microsoft Word .docx files.
 Author: Ethan St Lee
 License-Expression: MIT
@@ -66,7 +66,10 @@ or low-level package and relationship access.
 | Low-level OPC parts and relationships | Stable | `document.part.package`, `part.rels` |
 | In-memory read, export, and independent copies | Stable | `Document()`, `to_bytes()`, `copy()` |
 | Document sanitization | Development | `document.sanitize()` |
-| Package inspection and diff | Planned | — |
+| Read-only package inspection and story feature scanning | Development | `inspect()` |
+| Configurable package-content fingerprints | Development | `fingerprint()`, `FingerprintPolicy` |
+| Explicit empty Custom XML repair and hyperlink normalization | Development | `repair()`, `normalize()` |
+| Package and semantic diff | Planned | — |
 
 ## Installation
 
@@ -116,6 +119,42 @@ document.save("output.docx")
 
 ## Advanced Capabilities
 
+### Package inspection and fingerprints
+
+Inspect damaged documents before opening them, without loading media payloads:
+
+```python
+from docx import FingerprintPolicy, fingerprint, inspect
+
+report = inspect("input.docx")
+for finding in report.findings:
+    print(finding.code, finding.partname)
+
+digest = fingerprint("input.docx", policy=FingerprintPolicy(exclude_parts=("docProps/*",)))
+```
+
+These APIs leave inputs unchanged and restore seekable stream positions. Fingerprints
+ignore ZIP metadata and member ordering; all content is included unless explicitly
+excluded. See [Package inspection and fingerprints](docs/user/inspection.rst) for
+finding codes, XML comparison semantics, and policy rules.
+
+### Explicit repair and normalization
+
+```python
+from docx import normalize, repair
+
+repaired = repair(source_bytes, empty_custom_xml=True)
+if repaired.report.succeeded:
+    normalized = normalize(repaired.content, hyperlink_fields=True, hyperlink_runs=True)
+    if normalized.report.succeeded:
+        output_bytes = normalized.content
+```
+
+Operations are disabled by default. Results include committed changes, skipped cases,
+and errors; validation failures return the original bytes. See
+[Repair and normalization](docs/user/transformations.rst) for supported structures,
+selection callbacks, and preservation rules.
+
 ### Custom properties
 
 ```python
@@ -200,8 +239,8 @@ uv run pyright
 ## Project Status
 
 The current focus is stabilizing the independent SDK baseline, its in-memory workflows,
-and its advanced OOXML capabilities before expanding document inspection, comparison,
-sanitization, composition, and validation APIs.
+sanitization, and read-only package analysis before expanding document comparison,
+composition, and validation APIs.
 
 ## Credits
 

{python_docx_oss-0.3.3 → python_docx_oss-0.4.0}/README.md

@@ -37,7 +37,10 @@ or low-level package and relationship access.
 | Low-level OPC parts and relationships | Stable | `document.part.package`, `part.rels` |
 | In-memory read, export, and independent copies | Stable | `Document()`, `to_bytes()`, `copy()` |
 | Document sanitization | Development | `document.sanitize()` |
-| Package inspection and diff | Planned | — |
+| Read-only package inspection and story feature scanning | Development | `inspect()` |
+| Configurable package-content fingerprints | Development | `fingerprint()`, `FingerprintPolicy` |
+| Explicit empty Custom XML repair and hyperlink normalization | Development | `repair()`, `normalize()` |
+| Package and semantic diff | Planned | — |
 
 ## Installation
 
@@ -87,6 +90,42 @@ document.save("output.docx")
 
 ## Advanced Capabilities
 
+### Package inspection and fingerprints
+
+Inspect damaged documents before opening them, without loading media payloads:
+
+```python
+from docx import FingerprintPolicy, fingerprint, inspect
+
+report = inspect("input.docx")
+for finding in report.findings:
+    print(finding.code, finding.partname)
+
+digest = fingerprint("input.docx", policy=FingerprintPolicy(exclude_parts=("docProps/*",)))
+```
+
+These APIs leave inputs unchanged and restore seekable stream positions. Fingerprints
+ignore ZIP metadata and member ordering; all content is included unless explicitly
+excluded. See [Package inspection and fingerprints](docs/user/inspection.rst) for
+finding codes, XML comparison semantics, and policy rules.
+
+### Explicit repair and normalization
+
+```python
+from docx import normalize, repair
+
+repaired = repair(source_bytes, empty_custom_xml=True)
+if repaired.report.succeeded:
+    normalized = normalize(repaired.content, hyperlink_fields=True, hyperlink_runs=True)
+    if normalized.report.succeeded:
+        output_bytes = normalized.content
+```
+
+Operations are disabled by default. Results include committed changes, skipped cases,
+and errors; validation failures return the original bytes. See
+[Repair and normalization](docs/user/transformations.rst) for supported structures,
+selection callbacks, and preservation rules.
+
 ### Custom properties
 
 ```python
@@ -171,8 +210,8 @@ uv run pyright
 ## Project Status
 
 The current focus is stabilizing the independent SDK baseline, its in-memory workflows,
-and its advanced OOXML capabilities before expanding document inspection, comparison,
-sanitization, composition, and validation APIs.
+sanitization, and read-only package analysis before expanding document comparison,
+composition, and validation APIs.
 
 ## Credits
 

python_docx_oss-0.4.0/docs/api/inspection.rst

@@ -0,0 +1,11 @@
+.. _inspection_api:
+
+Package inspection and fingerprinting
+============================================
+
+.. automodule:: docx.inspection
+   :members: inspect, fingerprint, FingerprintPolicy, PackageInspection,
+             PackageInventory, PartInventory, RelationshipInventory, Finding, Features
+
+See :ref:`package_inspection` for finding codes, exclusions, scan scope, and
+resource guarantees.

python_docx_oss-0.4.0/docs/api/transforms.rst

@@ -0,0 +1,9 @@
+Package transformation APIs
+============================================
+
+.. automodule:: docx.transforms
+   :members: repair, normalize, TransformationResult, TransformationReport, Change,
+             HyperlinkTarget
+
+See :ref:`package_transformations` for repair eligibility, supported hyperlink
+structures, transactional errors, and preservation guarantees.

{python_docx_oss-0.3.3 → python_docx_oss-0.4.0}/docs/index.rst

@@ -97,6 +97,8 @@ User Guide
    user/styles-using
    user/comments
    user/sanitization
+   user/inspection
+   user/transformations
    user/shapes
    user/custom-properties
    user/custom-xml
@@ -117,6 +119,8 @@ API Documentation
    api/section
    api/comments
    api/sanitize
+   api/inspection
+   api/transforms
    api/shape
    api/dml
    api/shared

python_docx_oss-0.4.0/docs/user/inspection.rst

@@ -0,0 +1,151 @@
+.. _package_inspection:
+
+Inspecting packages and comparing content
+================================================
+
+``inspect()`` observes a DOCX before it can be opened as a ``Document``. It does
+not repair or rewrite the input. Both inspection and fingerprinting accept a
+filesystem path (including ``pathlib.Path``), raw bytes, or a binary stream::
+
+    from docx import inspect
+
+    report = inspect("input.docx")
+    for finding in report.findings:
+        print(finding.code, finding.partname, finding.target)
+
+    if report.features.field_hyperlink or report.features.split_hyperlink_runs:
+        print("Hyperlink shapes requiring application review were found")
+
+The report consists of three immutable values:
+
+* ``inventory.parts`` lists ZIP members, uncompressed sizes, Content-Types, and
+  whether each member is reachable from package relationships.
+* ``inventory.relationships`` lists source names, IDs, Type URIs, resolved
+  internal targets, and external URIs. External targets are never fetched.
+* ``findings`` identifies damaged or suspicious structures. ``features`` records
+  Word story facts; it does not decide whether an application should normalize
+  or reject a document.
+
+Names are package-relative without a leading slash. The relationship source
+``/`` denotes the package root. Internal target paths are resolved relative to
+their source, with URI percent escapes decoded. Reachability does not imply
+that a part is well-formed or safe to open.
+
+Findings
+--------
+
+Use ``report.has_finding(code)`` or ``report.findings_by_code(code)`` rather than
+matching human-readable exception messages. Findings carry the affected member
+name when one is available, and missing-target findings carry ``target``.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 65
+
+   * - Code
+     - Meaning
+   * - ``not_a_package``
+     - An opened source cannot be read as a ZIP package.
+   * - ``missing_content_types``
+     - The package has no ``[Content_Types].xml`` member.
+   * - ``missing_main_document``
+     - No package-root officeDocument relationship resolves to an existing part.
+   * - ``invalid_content_types``
+     - The Content-Types member has an unexpected root element.
+   * - ``invalid_relationships``
+     - A relationship member has an unexpected root, missing required attributes,
+       duplicate IDs, or an invalid target URI.
+   * - ``empty_xml_part``
+     - An XML member has zero bytes or contains only XML whitespace.
+   * - ``unparseable_xml_part``
+     - XML is malformed or uses a DTD, which this API rejects.
+   * - ``missing_relationship_target``
+     - An internal relationship points to an absent member.
+   * - ``unreadable_part``
+     - An XML member cannot be decompressed or fails its ZIP integrity check.
+   * - ``duplicate_member``
+     - The ZIP contains the same member name more than once; inventory uses the first.
+   * - ``unsafe_member_name``
+     - A ZIP member has an absolute name, backslash, or parent-directory component.
+
+All recognizable XML parts are checked, including unreachable XML. A broken
+relationship part does not prevent other parts from being inventoried. Findings
+are observations, not a complete OPC/schema/security validation; an empty list
+does not guarantee that ``Document()`` or Microsoft Word can open the input.
+Invalid source argument types raise ``TypeError``. Source opening failures, such
+as ``FileNotFoundError`` or ``PermissionError``, propagate to the caller rather
+than being classified as package damage. This matches ``repair()`` and ``normalize()``.
+
+Story scanning and resource use
+--------------------------------------
+
+``field_hyperlink`` detects a first instruction token of ``HYPERLINK``, including
+simple fields (``w:fldSimple/@w:instr``) and complex field instructions split across
+runs. Other commands containing the word, such as ``REF HYPERLINK_ref``, do not
+match. ``split_hyperlink_runs`` detects ``w:hyperlink``
+elements with more than one direct ``w:r`` child. The scanner covers the main
+document and reachable header, footer, footnote, endnote, and comment story parts;
+configuration XML such as styles and settings does not contribute features.
+Transitional and Strict Word namespaces are supported.
+
+Inspection reads XML incrementally without building an element tree. Media,
+embedded objects, and other binary member payloads are never opened. Memory use
+scales with package inventory and XML/field nesting depth, rather than story text or
+media size. Metadata lists still scale with the number of parts and relationships.
+Binary payload checksums are therefore not validated by inspection.
+
+Seekable streams are read from the beginning, then restored to their original
+position on success or failure. Caller-owned streams are never closed. A
+forward-only stream is consumed and spooled, spilling to a temporary file beyond
+1 MiB. Paths and temporary handles are closed internally.
+
+Content fingerprints
+--------------------
+
+``fingerprint()`` computes a versioned SHA-256 package-content fingerprint::
+
+    from docx import FingerprintPolicy, fingerprint
+
+    unchanged = fingerprint(before_bytes) == fingerprint(after_bytes)
+
+    policy = FingerprintPolicy(exclude_parts=("docProps/*",))
+    unchanged_except_properties = (
+        fingerprint(before_bytes, policy=policy)
+        == fingerprint(after_bytes, policy=policy)
+    )
+
+Member ordering, compression, ZIP timestamps, directory entries, and other ZIP
+metadata do not affect the fingerprint. Member names and contents do. XML uses
+C14N 2.0 with comments, which normalizes attribute ordering, quote style, and
+empty-element spelling. Text whitespace and namespace prefixes are preserved.
+This is not a semantic Word comparison: equivalent rendering can produce
+different fingerprints. Compare fingerprints with the same policy and API
+algorithm version; the digest is not compatible with arbitrary existing hashes.
+
+The default includes document properties, Custom XML, relationships, and binary
+content. ``FingerprintPolicy`` can explicitly exclude:
+
+* ``exclude_parts``: shell-style patterns against member names; ``*`` also
+  matches ``/``;
+* ``exclude_relationship_types``: complete relationship Type URIs;
+* ``exclude_xml_tags``: expanded XML names, removing entire subtrees;
+* ``exclude_xml_attributes``: expanded XML attribute names.
+
+For example, ``exclude_xml_tags=("{namespace-uri}element",)`` applies to that
+element throughout the package. Excluding a member does not automatically
+exclude relationships or Content-Type declarations that reference it.
+Relationship exclusions do not remove their target parts. Applications must
+choose the complete policy appropriate to their comparison.
+
+When XML canonicalization is enabled, ``[Content_Types].xml`` is always read for
+XML classification, even if excluded from the digest. XML parts with nonstandard
+extensions therefore retain the same comparison rules. A malformed or empty
+Content-Types member raises a member-specific ``ValueError`` even when excluded.
+
+Set ``canonicalize_xml=False`` to hash XML bytes exactly. XML exclusions cannot
+be combined with that mode. Unlike ``inspect()``, fingerprinting raises on
+unreadable packages or malformed included XML rather than returning a partial
+digest. Duplicate member names are rejected. DTDs are rejected when XML is
+canonicalized. Binary and XML contents are processed incrementally; the function
+does not collect all member payloads in memory. Stream guarantees match
+``inspect()``.

python_docx_oss-0.4.0/docs/user/transformations.rst

@@ -0,0 +1,149 @@
+.. _package_transformations:
+
+Repairing and normalizing packages
+============================================
+
+``repair()`` and ``normalize()`` perform explicit package edits. Every operation
+is disabled by default. They accept the same path, bytes, and binary stream
+inputs as :ref:`package_inspection`, and return a ``TransformationResult`` with
+``content`` bytes and an immutable ``report``::
+
+    from docx import normalize, repair
+
+    repaired = repair(source_bytes, empty_custom_xml=True)
+    if repaired.report.succeeded:
+        normalized = normalize(
+            repaired.content,
+            hyperlink_fields=True,
+            hyperlink_runs=True,
+        )
+        if normalized.report.succeeded:
+            output_bytes = normalized.content
+
+Inputs are never overwritten. Seekable streams are read from the beginning and
+their positions restored; borrowed streams stay open. Forward-only streams are
+consumed. Source access failures and invalid argument types raise because original
+bytes cannot be obtained. Application selector exceptions also propagate.
+
+Reports and transactional behavior
+--------------------------------------------
+
+The report exposes:
+
+* ``before`` and ``after``: package inspection reports for the original and
+  returned content;
+* ``changes``: committed operations with member name, count, and, where relevant,
+  relationship ID and target;
+* ``skipped``: unsupported or unselected hyperlink operations, with member context;
+* ``errors``: conditions that prevented the operation;
+* ``succeeded``: whether the operation completed without errors;
+* ``changed``: whether any changes were committed.
+
+When all options are disabled, the original bytes are returned with an inspection
+report, without attempting repair or document-open validation. Existing findings
+remain visible in ``before``; ``succeeded`` does not imply those findings were fixed.
+
+With an operation enabled, input inspection runs first. Unsupported damage blocks
+the operation. A candidate is inspected again and opened as a ``Document``; its
+main part must be a supported Word document with a body. On failure, the original
+bytes are returned, ``errors`` explains why, and ``changes`` is empty. Thus
+``after`` always describes the bytes actually returned. Successful operations may
+still contain ``skipped`` entries; inspect those before assuming every hyperlink
+was normalized.
+
+This validates package relationships and library readability, not full OOXML
+schema conformance or Microsoft Word rendering. Operations currently target the
+Transitional Word namespace supported by ``Document()``.
+
+Empty Custom XML repair
+--------------------------------------------
+
+``repair(source, empty_custom_xml=True)`` replaces empty Custom XML data with
+``<root/>``. Eligibility requires both:
+
+* all incoming internal relationships to the part are ``customXml``; and
+* the Content-Type is generic ``application/xml`` or ``text/xml``.
+
+Zero-byte and XML-whitespace-only parts qualify as empty. The original schema,
+business tags, or lost data cannot be reconstructed: the replacement is a neutral
+well-formed placeholder. The report records ``filled_empty_custom_xml`` for each
+part. Relationships, Custom XML properties, and other package members are retained.
+
+The API does not fill empty main documents, headers, Custom XML properties, or
+unidentified orphan XML. Malformed nonempty XML and other inspection findings
+cause the whole repair to fail, preserving the original bytes. Run normalization
+separately after a successful repair. Repeating repair on its output is a byte
+identical no-op.
+
+Hyperlink normalization
+--------------------------------------------
+
+``hyperlink_fields=True`` converts supported ``HYPERLINK`` fields into standard
+``w:hyperlink`` elements. It handles simple fields and paragraph-local complex
+fields with separate begin, instruction, separator, result, and end runs. Field
+instructions may span runs. Result runs retain their text and formatting.
+
+Supported targets include quoted or unquoted addresses, bookmark-only links,
+and address plus bookmark. Supported switches are ``\l`` (anchor), ``\o``
+(tooltip), ``\t`` (target frame), and ``\* MERGEFORMAT``. Unknown switches,
+locked or nested fields, revision markup, mixed delimiter/content runs, and
+bookmark or comment range boundaries are left unchanged and reported. Other
+field types, such as TOC and REF, are untouched.
+
+Quoted field arguments decode escaped backslashes and escaped double quotes.
+Unknown or malformed escapes, unclosed strings, and doubled-quote notation are
+preserved and reported as skipped rather than converted into potentially wrong targets.
+
+External hyperlink relationships are reused when possible. New IDs avoid existing
+IDs in that story part. Missing relationship members and their Content-Type
+declarations are added when needed. Main document, headers, footers, footnotes,
+endnotes, and comments are processed through their reachable story relationships.
+
+``hyperlink_runs=True`` merges adjacent text-only runs inside a hyperlink only
+when explicit run properties and attributes other than ``w:rsidR`` and
+``w:rsidRPr`` match. The surviving run retains its original session identifiers;
+per-run session provenance is coalesced. Text and spaces are preserved.
+Different formatting, other attributes (including ``w:rsidDel``), drawings,
+tabs, breaks, revision containers,
+and intervening markup prevent merging across that boundary. Safe adjacent groups
+can still be merged while unsupported groups are reported as skipped.
+
+Application-owned selection
+--------------------------------------------
+
+The optional ``select_hyperlink`` callback receives an immutable
+``HyperlinkTarget(partname, address, anchor)``. Return ``True`` to select a
+supported field conversion or existing-link run merge::
+
+    def select_link(target):
+        return target.address is not None and target.address.startswith(
+            "https://example.test/documents/"
+        )
+
+    result = normalize(
+        source_bytes,
+        hyperlink_fields=True,
+        hyperlink_runs=True,
+        select_hyperlink=select_link,
+    )
+
+Without a callback all supported hyperlinks are selected. The SDK contains no
+application URL or tag rules. For existing hyperlinks ``address`` comes from the
+story relationship target; bookmark-only links have ``address=None``. The callback
+must be deterministic: it may be called for conversion and then again for merging
+the resulting link. Returning ``False`` is reported as skipped.
+
+Preservation and resource use
+--------------------------------------------
+
+Only edited XML members are serialized. Other member contents, including opaque
+media, embedded objects, macros, unknown XML, and unreachable parts, are copied
+unchanged. ZIP member metadata and archive comments are retained where supported
+by Python's ZIP writer; compressed bytes and ZIP offsets may change. The package
+is not saved through ``Document`` during transformation.
+
+These editing APIs retain input and output bytes, build a tree for the story
+currently being edited, and open the result for validation. They do not have the
+streaming memory profile of ``inspect()``. No-op results retain the original bytes
+exactly. Repeated normalization with the same deterministic selection is a byte
+identical no-op once supported changes have been applied.

{python_docx_oss-0.3.3 → python_docx_oss-0.4.0}/src/docx/__init__.py

@@ -9,14 +9,16 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Type
 
 from docx.api import Document
+from docx.inspection import FingerprintPolicy, fingerprint, inspect
+from docx.transforms import normalize, repair
 
 if TYPE_CHECKING:
     from docx.opc.part import Part
 
-__version__ = "0.3.3"
+__version__ = "0.4.0"
 
 
-__all__ = ["Document"]
+__all__ = ["Document", "FingerprintPolicy", "fingerprint", "inspect", "normalize", "repair"]
 
 
 # -- register custom Part classes with opc package reader --

python_docx_oss-0.4.0/src/docx/inspection/__init__.py

@@ -0,0 +1,24 @@
+"""Read-only package inspection and configurable content fingerprints."""
+
+from docx.inspection.fingerprint import FingerprintPolicy, fingerprint
+from docx.inspection.reader import inspect
+from docx.inspection.result import (
+    Features,
+    Finding,
+    PackageInspection,
+    PackageInventory,
+    PartInventory,
+    RelationshipInventory,
+)
+
+__all__ = [
+    "Features",
+    "Finding",
+    "FingerprintPolicy",
+    "PackageInspection",
+    "PackageInventory",
+    "PartInventory",
+    "RelationshipInventory",
+    "fingerprint",
+    "inspect",
+]