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

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

@@ -1,5 +1,32 @@
 ## Release History
 
+**0.5.0 (2026-11-02)**
+
+- Rejected DTDs and entity expansion in XML tree serialization.
+- Distinguished complete scans from clean inspection reports.
+- Kept complex-field detection within its paragraph, including text boxes.
+- Ignored indentation in schema-derived Word and DrawingML structures (fingerprint v3).
+- Added a callback to exclude package parts or XML subtrees from fingerprints.
+- Added a per-part normalization callback and a reusable XML tree serializer.
+- Preserved following text when excluding elements with the XML tree serializer.
+- Preserved XML namespace declarations when fingerprinting, including namespace
+  references in attribute values.
+- Ignored formatting whitespace in known Word structural XML elements by default
+  when fingerprinting, preserving text and allowing exact structural whitespace comparison.
+- Fixed hyperlink field conversion when proofing markers appear in the result.
+- Added streaming story queries with caller-defined predicates and optional early exit.
+- Replaced the fixed hyperlink feature fields with general-purpose scan events.
+
+**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.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-docx-oss
-Version: 0.3.3
+Version: 0.5.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.5.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.5.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, ScanEvent
+
+See :ref:`package_inspection` for finding codes, exclusions, scan scope, and
+resource guarantees.

python_docx_oss-0.5.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.5.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.5.0/docs/user/inspection.rst

@@ -0,0 +1,242 @@
+.. _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)
+
+The report contains an immutable package inventory and structured findings.
+
+To search Word story XML, provide a predicate that receives read-only events::
+
+    def find_bookmark(event):
+        return event.kind == "start" and event.tag.endswith("}bookmarkStart")
+
+    report = inspect("input.docx", predicate=find_bookmark, stop_on_match=True)
+    if report.findings:
+        print("The scanned package is damaged")
+    elif report.matched:
+        print("Bookmark found")
+
+A predicate selects query scope: the main document and reachable headers,
+footers, footnotes, endnotes, and comments. Query reports have empty inventory
+and ``scope == "query"``. Without a predicate, inspection retains full scope
+and inventory. The predicate runs on immutable ``ScanEvent`` objects with
+``partname``, ``kind`` (start/end/text), expanded ``tag``, ``attributes`` on
+start events, and ``text`` on text events. Text may be delivered in multiple
+chunks. A stateful callable may track element nesting and split text.
+
+The default scans the full query scope even after a match; ``stop_on_match=True``
+stops at the first match and sets ``scan_complete=False``. Findings report only
+scanned content; neither an early match nor a query with no findings proves the
+whole package is valid. Predicate exceptions propagate. The source stream is
+never handed to the predicate.
+
+``scan_complete`` describes whether the selected scope was scanned successfully,
+not whether the package is clean. Findings such as a missing relationship target
+can coexist with a complete scan. Empty XML parts cannot be parsed as XML and,
+like unreadable or unparseable parts, make the scan incomplete. Early stops also
+make the scan incomplete. A query is incomplete if a reachable story is missing.
+
+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
+--------------------------------------
+
+The query scans all reachable Word story parts, including Transitional and Strict
+Word namespaces. No built-in hyperlink-specific feature is assumed.
+
+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. By default, whitespace-only text directly inside known
+element-only Word, DrawingML, MCE, and WordprocessingShape structures is ignored.
+This includes whitespace between extension children of a known structure. Text
+elements, unknown or unverified extension elements, generic Custom XML parts, and
+elements under ``xml:space="preserve"`` retain whitespace. An explicit
+``xml:space="default"`` resets inherited preservation. Elements with an
+``xsi:type`` override are preserved conservatively. Set ``ignore_structural_whitespace=False`` on the policy
+to retain structural whitespace. Namespace prefixes and declarations are preserved,
+including declarations referenced only from attribute values. This rule applies
+only to parts declared with a known WordprocessingML or DrawingML theme content
+type, and to specific structural elements within them. The generated name list
+comes from ECMA-376 fifth-edition Transitional and Strict schemas, ECMA-376 Part 3
+MCE structures, and Microsoft's MS-ODRAWXML WordprocessingShape schema. It excludes
+ambiguous element names, VML, and unverified extensions. The document is not schema
+validated; this rule assumes the known elements follow their element-only or empty
+content model. Use ``normalize`` for broader application-specific comparison.
+Raw XML hashing with
+``canonicalize_xml=False`` always preserves the original bytes.
+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 expanded structural-whitespace rules use fingerprint algorithm version 3, so
+digest strings differ from earlier versions even when whitespace handling is disabled.
+
+The optional ``normalize`` callback can replace the bytes hashed for a part::
+
+    from docx import FingerprintItem, FingerprintPolicy, serialize_xml
+    from lxml import etree
+
+    def normalize(item: FingerprintItem, read_bytes):
+        if not item.part_name.endswith(".xml"):
+            return "raw"
+        content = read_bytes()
+        try:
+            return serialize_xml(content, part_name=item.part_name)
+        except etree.XMLSyntaxError:
+            return content
+
+    policy = FingerprintPolicy(normalize=normalize)
+
+The callback receives a part item and an on-demand reader. Return bytes to hash
+those bytes directly, ``"raw"`` to hash the original part incrementally, or
+``None`` to use the default processing. ``read_bytes()`` returns the original
+bytes, can be called repeatedly, and materializes that part in memory only when
+called. Errors propagate. The callback must produce deterministic results.
+Part exclusions run first. For bytes or raw results, the callback is responsible
+for any element-level exclusions; default XML canonicalization and element
+exclusion callbacks are bypassed. When every included part is handled by the
+callback, Content Types need not be read for classification. Otherwise the
+Content Types member is still read to classify parts using default processing.
+
+``serialize_xml()`` is a tree-based helper: it removes blank text using lxml,
+optionally excludes XML elements with the same predicate as ``exclude``, and
+returns serialized bytes. It preserves attribute order, requires memory
+proportional to the XML part, and preserves text following an excluded element
+that remains after lxml's blank-text removal.
+Its blank-text treatment is broader
+than the default structural-whitespace rule; use it only when appropriate.
+
+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.
+* ``exclude``: a predicate for package parts and XML elements.
+
+The predicate receives a read-only ``FingerprintItem``. Its ``kind`` is ``part``
+or ``xml_element``; ``part_name`` is the package-relative member name. XML
+elements also expose expanded-name ``tag`` and ``attributes``, ``ancestors``
+(root first), and ``parent_tag`` (or ``None`` for a root). For example::
+
+    from docx import FingerprintItem, FingerprintPolicy
+
+    def exclude(item: FingerprintItem) -> bool:
+        if item.kind == "part":
+            return item.part_name.startswith("docProps/")
+        return item.tag == "{urn:example}color" and item.parent_tag == "{urn:example}properties"
+
+    policy = FingerprintPolicy(exclude=exclude)
+
+Returning true excludes the part or the element and its entire subtree; excluded
+subtrees are not visited. Exclusions combine with the other policy settings: any
+matching rule excludes the item. XML element callbacks run only when XML
+canonicalization is enabled. Part callbacks run even with raw XML hashing.
+Content Types are read for default XML classification even when excluded. The
+predicate must be deterministic and equivalent for both fingerprints being
+compared; its exceptions propagate to the caller.
+
+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 default XML processing is used, ``[Content_Types].xml`` is 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.5.0/docs/user/transformations.rst

@@ -0,0 +1,150 @@
+.. _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; proofing
+markers within the result remain in their original order.
+
+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.5.0}/src/docx/__init__.py

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

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

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