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

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

@@ -2,6 +2,19 @@
 
 **Unreleased**
 
+**0.3.2 (2026-09-08)**
+
+- Restored the 0.0.12 architecture where OXML elements (`CT_R`, `CT_P`, `CT_Hyperlink`)
+  do not override lxml's Cython `_Element.text` descriptor, resolving text duplication
+  when calling `itertext()` on bare `lxml.etree._Element` parent nodes (such as revision
+  tags `w:ins`, `w:del`, and container tags like `w:txbxContent`).
+- Standardized OXML rich-text extraction and assignment on `.texts`, while maintaining full
+  compatibility for public proxy APIs (`Paragraph.text`, `Run.text`, `Hyperlink.text`, `_Cell.text`).
+- Documented the intentional upstream difference in the compatibility guide.
+
+- Fixed an issue where calling `itertext()` on oxml elements produced duplicated
+  text due to overridden `.text` properties.
+
 **0.3.0 (2026-08-29)**
 
 - Added opt-in package-level document sanitization for personal metadata,

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-docx-oss
-Version: 0.3.0
+Version: 0.3.2
 Summary: Create, read, and update Microsoft Word .docx files.
 Author: Ethan St Lee
 License-Expression: MIT
@@ -155,6 +155,11 @@ available through `Document.add_float_picture()` and `Run.add_float_picture()`.
 
 - The project maintains broad compatibility with the public `python-docx` API while
   following its own versioning and product roadmap.
+- Clean lxml integration: Low-level OXML elements avoid shadowing lxml's Cython
+  `_Element.text` descriptor (using `.texts` internally). This guarantees that standard
+  `element.itertext()` on parent elements and untyped revision nodes (`w:ins`, `w:del`,
+  `w:txbxContent`) never duplicates text, while high-level proxy APIs (`paragraph.text`,
+  `run.text`) remain fully compatible with `python-docx`.
 - Compatibility does not extend to every private or internal `python-docx` API. Test
   those integrations before migrating production systems.
 - The SDK focuses exclusively on DOCX. It is not a general XLSX/PPTX Office suite.

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

@@ -126,6 +126,11 @@ available through `Document.add_float_picture()` and `Run.add_float_picture()`.
 
 - The project maintains broad compatibility with the public `python-docx` API while
   following its own versioning and product roadmap.
+- Clean lxml integration: Low-level OXML elements avoid shadowing lxml's Cython
+  `_Element.text` descriptor (using `.texts` internally). This guarantees that standard
+  `element.itertext()` on parent elements and untyped revision nodes (`w:ins`, `w:del`,
+  `w:txbxContent`) never duplicates text, while high-level proxy APIs (`paragraph.text`,
+  `run.text`) remain fully compatible with `python-docx`.
 - Compatibility does not extend to every private or internal `python-docx` API. Test
   those integrations before migrating production systems.
 - The SDK focuses exclusively on DOCX. It is not a general XLSX/PPTX Office suite.

{python_docx_oss-0.3.0 → python_docx_oss-0.3.2}/docs/conf.py

@@ -13,7 +13,7 @@ import sys
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-sys.path.insert(0, os.path.abspath(".."))
+sys.path.insert(0, os.path.abspath("../src"))
 
 from docx import __version__  # noqa
 

{python_docx_oss-0.3.0 → python_docx_oss-0.3.2}/docs/user/compatibility.rst

@@ -43,6 +43,14 @@ public inherited API or its observable behavior. Each record must identify:
 * the ``python-docx-oss`` behavior and rationale; and
 * any migration action required by callers.
 
+Preservation of lxml ``_Element.text`` and ``itertext()`` semantics
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* **Affected API**: Low-level OXML element classes (``CT_P``, ``CT_R``, ``CT_Hyperlink`` in ``docx.oxml``) and observable ``element.itertext()`` / ``element.text`` behavior on XML elements.
+* **Upstream baseline (v1.2.0)**: Upstream defined ``@property def text`` on ``CT_P``, ``CT_R``, and ``CT_Hyperlink`` to return concatenated run/paragraph text. Overriding the Cython descriptor ``_Element.text`` on ``ElementBase`` subclasses causes standard ``lxml`` C-level tree iteration (``itertext()``) to invoke the Python property. As a consequence, calling ``itertext()`` on parent elements or on bare ``lxml.etree._Element`` nodes (such as revision tags ``w:ins``, ``w:del``, or container tags like ``w:txbxContent``) visits both the container node and child ``<w:t>`` nodes, causing text to be duplicated (e.g., ``"Beta"`` becomes ``"BetaBeta"``).
+* **python-docx-oss behavior and rationale**: ``python-docx-oss`` intentionally does not override the ``.text`` property on any ``BaseOxmlElement`` subclass. Rich-text extraction and assignment at the OXML element level is named ``.texts`` (e.g., ``_r.texts``, ``_p.texts``, ``_hyperlink.texts``). Public proxy classes (|Paragraph|, |Run|, |Hyperlink|, and |_Cell|) continue to expose their standard ``.text`` property, delegating internally to ``.texts``. This design preserves standard ``lxml`` descriptor semantics, ensuring that ``itertext()`` produces clean, single-occurrence text across all XML elements.
+* **Migration action**: Callers using public proxy objects (such as ``paragraph.text`` or ``run.text``) require no changes. Callers interacting directly with low-level OXML element instances (e.g., ``run._r``) should use ``.texts`` instead of ``.text`` for rich-text assembly, or standard ``lxml`` methods like ``element.itertext()``.
+
 Additive APIs and capabilities do not require individual divergence records;
 they belong in the API documentation and Capability Matrix. Upstream baseline
 changes follow the :doc:`../dev/upstream-maintenance` policy.

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

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

{python_docx_oss-0.3.0 → python_docx_oss-0.3.2}/src/docx/oxml/text/hyperlink.py

@@ -37,9 +37,9 @@ class CT_Hyperlink(BaseOxmlElement):
         return self.xpath("./w:r/w:lastRenderedPageBreak")
 
     @property
-    def text(self) -> str:  # pyright: ignore[reportIncompatibleMethodOverride]
+    def texts(self) -> str:
         """The textual content of this hyperlink.
 
         `CT_Hyperlink` stores the hyperlink-text as one or more `w:r` children.
         """
-        return "".join(r.text for r in self.xpath("w:r"))
+        return "".join(r.texts for r in self.xpath("w:r"))

{python_docx_oss-0.3.0 → python_docx_oss-0.3.2}/src/docx/oxml/text/paragraph.py

@@ -93,13 +93,13 @@ class CT_P(BaseOxmlElement):
         pPr.style = style
 
     @property
-    def text(self):  # pyright: ignore[reportIncompatibleMethodOverride]
+    def texts(self) -> str:
         """The textual content of this paragraph.
 
         Inner-content child elements like `w:r` and `w:hyperlink` are translated to
         their text equivalent.
         """
-        return "".join(e.text for e in self.xpath("w:r | w:hyperlink"))
+        return "".join(e.texts for e in self.xpath("w:r | w:hyperlink"))
 
     def _insert_pPr(self, pPr: CT_PPr) -> CT_PPr:
         self.insert(0, pPr)

{python_docx_oss-0.3.0 → python_docx_oss-0.3.2}/src/docx/oxml/text/run.py

@@ -127,29 +127,25 @@ class CT_R(BaseOxmlElement):
         rPr.style = style
 
     @property
-    def text(self) -> str:
+    def texts(self) -> str:
         """The textual content of this run.
 
         Inner-content child elements like `w:tab` are translated to their text
         equivalent.
+
+        Note: We intentionally do NOT define `@property def text` on CT_R or any
+        other oxml element, because doing so overrides lxml's Cython descriptor
+        `_Element.text`, which corrupts lxml `itertext()` on parent elements (such
+        as bare `_Element` revision tags `w:ins`, `w:del`, etc.).
         """
         return "".join(
             str(e) for e in self.xpath("w:br | w:cr | w:noBreakHyphen | w:ptab | w:t | w:tab")
         )
 
-    @text.setter
-    def text(self, text: str):  # pyright: ignore[reportIncompatibleMethodOverride]
-        self.clear_content()
-        _RunContentAppender.append_to_run_from_text(self, text)
-
-    @property
-    def texts(self) -> str:
-        """Alias for `text` property for compatibility with python-docx-oss."""
-        return self.text
-
     @texts.setter
     def texts(self, text: str):
-        self.text = text
+        self.clear_content()
+        _RunContentAppender.append_to_run_from_text(self, text)
 
     def _insert_rPr(self, rPr: CT_RPr) -> CT_RPr:
         self.insert(0, rPr)

{python_docx_oss-0.3.0 → python_docx_oss-0.3.2}/src/docx/table.py

@@ -281,7 +281,7 @@ class _Cell(BlockItemContainer):
         tc.clear_content()
         p = tc.add_p()
         r = p.add_r()
-        r.text = text
+        r.texts = text
 
     @property
     def vertical_alignment(self):

{python_docx_oss-0.3.0 → python_docx_oss-0.3.2}/src/docx/text/hyperlink.py

@@ -98,7 +98,7 @@ class Hyperlink(Parented):
         respectively. Note that rendered page-breaks can occur within a hyperlink but
         they are not reflected in this text.
         """
-        return self._hyperlink.text
+        return self._hyperlink.texts
 
     @property
     def url(self) -> str:

{python_docx_oss-0.3.0 → python_docx_oss-0.3.2}/src/docx/text/paragraph.py

@@ -160,7 +160,7 @@ class Paragraph(StoryChild):
         character is mapped to a line break. Paragraph-level formatting, such as style,
         is preserved. All run-level formatting, such as bold or italic, is removed.
         """
-        return self._p.text
+        return self._p.texts
 
     @text.setter
     def text(self, text: str | None):

{python_docx_oss-0.3.0 → python_docx_oss-0.3.2}/src/docx/text/run.py

@@ -233,11 +233,11 @@ class Run(StoryChild):
         `<w:cr/>` element. Any existing run content is replaced. Run formatting is
         preserved.
         """
-        return self._r.text
+        return self._r.texts
 
     @text.setter
     def text(self, text: str):
-        self._r.text = text
+        self._r.texts = text
 
     @property
     def underline(self) -> bool | WD_UNDERLINE | None:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-docx-oss
-Version: 0.3.0
+Version: 0.3.2
 Summary: Create, read, and update Microsoft Word .docx files.
 Author: Ethan St Lee
 License-Expression: MIT
@@ -155,6 +155,11 @@ available through `Document.add_float_picture()` and `Run.add_float_picture()`.
 
 - The project maintains broad compatibility with the public `python-docx` API while
   following its own versioning and product roadmap.
+- Clean lxml integration: Low-level OXML elements avoid shadowing lxml's Cython
+  `_Element.text` descriptor (using `.texts` internally). This guarantees that standard
+  `element.itertext()` on parent elements and untyped revision nodes (`w:ins`, `w:del`,
+  `w:txbxContent`) never duplicates text, while high-level proxy APIs (`paragraph.text`,
+  `run.text`) remain fully compatible with `python-docx`.
 - Compatibility does not extend to every private or internal `python-docx` API. Test
   those integrations before migrating production systems.
 - The SDK focuses exclusively on DOCX. It is not a general XLSX/PPTX Office suite.

{python_docx_oss-0.3.0 → python_docx_oss-0.3.2}/tests/integration/customxml/test_custom_xml_roundtrip.py

@@ -11,6 +11,7 @@ import pytest
 
 from docx import Document
 from docx.document import Document as DocumentType
+from docx.oxml.parser import parse_xml
 from docx.parts.customxml import CustomXmlPart
 
 FIXTURE = (
@@ -83,6 +84,28 @@ class DescribeMultipleCustomXmlParts:
         assert "customXml/_rels/item1.xml.rels" in names
         assert "customXml/_rels/item3.xml.rels" in names
 
+    def it_round_trips_replacing_a_custom_xml_part_element(self):
+        document = Document(io.BytesIO(FIXTURE.read_bytes()))
+        customers = _parts_by_name(document)["/customXml/item1.xml"]
+        wrapper = parse_xml('<wrapper xmlns="urn:python-docx-oss:wrapper" version="1"/>')
+        wrapper.append(customers.element)
+        customers.element = wrapper
+
+        output = io.BytesIO()
+        document.save(output)
+        reopened = Document(io.BytesIO(output.getvalue()))
+        replaced = _parts_by_name(reopened)["/customXml/item1.xml"]
+
+        assert replaced.tag == "{urn:python-docx-oss:wrapper}wrapper"
+        assert replaced.attrib["version"] == "1"  # pyright: ignore[reportUnknownMemberType]
+        assert len(replaced.items) == 1
+        assert replaced.items[0].tag == f"{{{CUSTOMERS_NS}}}customers"
+        assert len(replaced.items[0]) == 2
+        with ZipFile(io.BytesIO(output.getvalue())) as package:
+            names = set(package.namelist())
+        assert "customXml/itemProps1.xml" in names
+        assert "customXml/_rels/item1.xml.rels" in names
+
     def it_rejects_an_explicit_partname_collision(self):
         document = Document(io.BytesIO(FIXTURE.read_bytes()))
 

{python_docx_oss-0.3.0 → python_docx_oss-0.3.2}/tests/integration/test_word_roundtrip.py

@@ -10,6 +10,10 @@ from zipfile import ZipFile
 from lxml import etree
 
 from docx import Document
+from docx.opc.constants import CONTENT_TYPE as CT
+from docx.opc.constants import RELATIONSHIP_TYPE as RT
+from docx.oxml import OxmlElement
+from docx.oxml.ns import qn
 
 FIXTURE_DIR = Path(__file__).parent.parent / "fixtures"
 TEST_FILE_DIR = Path(__file__).parent.parent / "test_files"
@@ -73,6 +77,60 @@ class DescribeWordDocumentRoundTrips:
         assert "word/styles.xml" in package
         assert not any(name.startswith("word/media/") for name in package)
 
+    def it_round_trips_a_default_numbering_part_when_the_source_has_none(self):
+        fixture = _fixture("documents", "word-blank.docx")
+        with ZipFile(fixture) as source_package:
+            assert "word/numbering.xml" not in source_package.namelist()
+
+        document = Document(io.BytesIO(fixture.read_bytes()))
+        numbering_part = document.part.numbering_part
+        output = document.to_bytes()
+        reopened = Document(output)
+
+        assert str(numbering_part.partname) == "/word/numbering.xml"
+        assert str(reopened.part.numbering_part.partname) == "/word/numbering.xml"
+        with ZipFile(io.BytesIO(output)) as package_file:
+            package = {name: package_file.read(name) for name in package_file.namelist()}
+        assert "word/numbering.xml" in package
+        assert _content_type(package, "/word/numbering.xml") == CT.WML_NUMBERING
+        relationships = _xml(package, "word/_rels/document.xml.rels")
+        numbering_relationship = relationships.find(
+            f"{{{PR_NS}}}Relationship[@Type='{RT.NUMBERING}']"
+        )
+        assert numbering_relationship is not None
+        assert numbering_relationship.get("Target") == "numbering.xml"
+
+    def it_round_trips_a_changed_external_hyperlink_target(self):
+        document = Document(_fixture("documents", "word-blank.docx").read_bytes())
+        paragraph = document.add_paragraph()
+        relationship_id = document.part.relate_to(
+            "https://example.invalid/objects/old-id",
+            RT.HYPERLINK,
+            is_external=True,
+        )
+        hyperlink = OxmlElement("w:hyperlink")
+        hyperlink.set(qn("r:id"), relationship_id)
+        run = OxmlElement("w:r")
+        text = OxmlElement("w:t")
+        text.text = "Business link"
+        run.append(text)
+        hyperlink.append(run)
+        paragraph._p.append(hyperlink)  # pyright: ignore[reportPrivateUsage]
+
+        new_target = "https://example.invalid/objects/new-id?position=begin"
+        document.part.rels[relationship_id].target_ref = new_target
+        output = document.to_bytes()
+        reopened = Document(output)
+
+        assert reopened.paragraphs[-1].hyperlinks[0].text == "Business link"
+        assert reopened.paragraphs[-1].hyperlinks[0].address == new_target
+        with ZipFile(io.BytesIO(output)) as package_file:
+            relationships = etree.fromstring(package_file.read("word/_rels/document.xml.rels"))
+        relationship = relationships.find(f"{{{PR_NS}}}Relationship[@Id='{relationship_id}']")
+        assert relationship is not None
+        assert relationship.get("Target") == new_target
+        assert relationship.get("TargetMode") == "External"
+
     def it_creates_independent_document_copies_from_one_snapshot(self):
         source = Document(_fixture("customxml", "multiple-custom-xml-parts.docx").read_bytes())
         source.add_paragraph("Shared snapshot")

{python_docx_oss-0.3.0 → python_docx_oss-0.3.2}/tests/oxml/test_xmlchemy.py

@@ -1,6 +1,7 @@
 """Test suite for docx.oxml.xmlchemy."""
 
 import pytest
+from lxml import etree
 
 from docx.oxml.exceptions import InvalidXmlError
 from docx.oxml.ns import qn
@@ -48,6 +49,34 @@ class DescribeBaseOxmlElement:
         element.remove_all(*tagnames)
         assert element.xml == expected_xml
 
+    def it_iterates_text_without_duplication_on_oxml_elements(self):
+        elm = parse_xml(
+            '<w:p xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">'
+            "<w:r><w:t>foo</w:t></w:r>"
+            "<w:hyperlink><w:r><w:t>bar</w:t></w:r></w:hyperlink>"
+            "</w:p>"
+        )
+        assert "".join(elm.itertext()) == "foobar"
+        assert list(elm.itertext(qn("w:t"))) == ["foo", "bar"]
+
+    def it_iterates_text_without_duplication_on_unregistered_bare_elements(self):
+        # Tags like w:ins, w:del, w:txbxContent are not registered in element_class_lookup
+        # and remain bare lxml.etree._Element instances.
+        ins = parse_xml(
+            '<w:ins xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"'
+            ' w:id="1" w:author="t" w:date="2026-01-01T00:00:00Z">'
+            "<w:r><w:t>Beta</w:t></w:r>"
+            "</w:ins>"
+        )
+        assert type(ins) is etree._Element
+        assert list(ins.itertext()) == ["Beta"]
+        assert "".join(ins.itertext()) == "Beta"
+
+        # Verify CT_R inside it has native None for .text and "Beta" for .texts
+        r = ins.findall(qn("w:r"))[0]
+        assert r.text is None
+        assert r.texts == "Beta"
+
     # fixtures ---------------------------------------------
 
     @pytest.fixture(

{python_docx_oss-0.3.0 → python_docx_oss-0.3.2}/tests/oxml/text/test_hyperlink.py

@@ -41,5 +41,6 @@ class DescribeCT_Hyperlink:
         rs = hyperlink.r_lst
 
         assert [type(r) for r in rs] == [CT_R, CT_R]
-        assert rs[0].text == "blog"
-        assert rs[1].text == " post"
+        assert rs[0].texts == "blog"
+        assert rs[1].texts == " post"
+        assert hyperlink.texts == "blog post"

{python_docx_oss-0.3.0 → python_docx_oss-0.3.2}/tests/oxml/text/test_run.py

@@ -38,13 +38,22 @@ class DescribeCT_R:
         cxml = 'w:r/(w:br,w:cr,w:noBreakHyphen,w:ptab,w:t"foobar",w:tab)'
         r = cast(CT_R, element(cxml))
 
-        assert r.text == "\n\n-\tfoobar\t"
+        assert r.texts == "\n\n-\tfoobar\t"
 
-    def it_provides_texts_alias_for_text(self):
+    def it_can_replace_its_text(self):
         r = cast(CT_R, element('w:r/w:t"alias"'))
 
         assert r.texts == "alias"
 
         r.texts = "updated"
 
-        assert r.text == "updated"
+        assert r.texts == "updated"
+
+    def it_iterates_text_without_duplication(self):
+        r = cast(CT_R, element('w:r/(w:br,w:t"foo",w:cr,w:t"bar")'))
+
+        assert "".join(r.itertext()) == "foobar"
+
+    def it_does_not_override_element_text_descriptor(self):
+        r = cast(CT_R, element('w:r/w:t"foo"'))
+        assert r.text is None

{python_docx_oss-0.3.0 → python_docx_oss-0.3.2}/tests/test_sanitize.py

@@ -9,6 +9,7 @@ from zipfile import ZipFile
 from lxml import etree
 
 from docx import Document
+from docx.opc.constants import RELATIONSHIP_TYPE as RT
 from docx.opc.packuri import PackURI
 from docx.opc.part import Part
 from docx.oxml import OxmlElement
@@ -145,6 +146,56 @@ def it_removes_the_entire_web_extension_relationship_tree():
         assert not any(name.startswith("word/webextensions/") for name in archive.namelist())
 
 
+def it_round_trips_cleanup_without_removing_application_content():
+    document = Document(COMMENTS_FIXTURE)
+    custom_xml = document.part.add_custom_xml_part(
+        '<application xmlns="urn:python-docx-oss:application" version="1"/>'
+    )
+    business_relationship_id = document.part.relate_to(
+        "https://example.invalid/business/object-id",
+        RT.HYPERLINK,
+        is_external=True,
+    )
+    package = document.part.package
+    taskpanes = Part(
+        PackURI("/word/webextensions/taskpanes.xml"),
+        "application/vnd.ms-office.webextensiontaskpanes+xml",
+        b"<wetp:taskpanes xmlns:wetp='urn:test'/>",
+        package,
+    )
+    extension = Part(
+        PackURI("/word/webextensions/webextension1.xml"),
+        "application/vnd.ms-office.webextension+xml",
+        b"<we:webextension xmlns:we='urn:test'/>",
+        package,
+    )
+    package.relate_to(
+        taskpanes,
+        "http://schemas.microsoft.com/office/2011/relationships/webextensiontaskpanes",
+    )
+    taskpanes.relate_to(
+        extension,
+        "http://schemas.microsoft.com/office/2011/relationships/webextension",
+    )
+
+    report = document.sanitize(comments=True, web_extensions=True)
+    output = document.to_bytes()
+    reopened = Document(output)
+
+    assert report.removed_comment_markers > 0
+    assert str(custom_xml.partname) not in report.removed_parts
+    assert reopened.part.custom_xml_parts[0].tag == ("{urn:python-docx-oss:application}application")
+    assert reopened.part.rels[business_relationship_id].target_ref == (
+        "https://example.invalid/business/object-id"
+    )
+    assert reopened.sanitize(comments=True, web_extensions=True).changed is False
+    with ZipFile(io.BytesIO(output)) as archive:
+        names = archive.namelist()
+        assert "customXml/item1.xml" in names
+        assert "word/comments.xml" not in names
+        assert not any(name.startswith("word/webextensions/") for name in names)
+
+
 def it_removes_formatting_revisions_and_keeps_current_formatting():
     document = Document()
     paragraph = document.add_paragraph()