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

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

@@ -2,7 +2,15 @@
 
 **Unreleased**
 
-**0.3.1 (2026-09-08)**
+**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.

{python_docx_oss-0.3.1/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.1
+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.1 → 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.1 → 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.1 → 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.1"
+__version__ = "0.3.2"
 
 
 __all__ = ["Document"]

{python_docx_oss-0.3.1 → 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.1 → 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.1 → 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.1 → python_docx_oss-0.3.2}/src/docx/oxml/xmlchemy.py

@@ -5,7 +5,7 @@
 from __future__ import annotations
 
 import re
-from typing import TYPE_CHECKING, Any, Callable, Iterator, Sequence, Type, TypeVar
+from typing import TYPE_CHECKING, Any, Callable, Sequence, Type, TypeVar
 
 from lxml import etree
 from lxml.etree import ElementBase, _Element  # pyright: ignore[reportPrivateUsage]
@@ -653,11 +653,6 @@ class ZeroOrOneChoice(_BaseChildElement):
         return "_remove_%s" % self._prop_name
 
 
-# -- raw lxml text/tail accessors, used to bypass `.text` property overrides --
-_raw_text = _Element.text.__get__
-_raw_tail = _Element.tail.__get__
-
-
 # -- lxml typing isn't quite right here, just ignore this error on _Element --
 class BaseOxmlElement(etree.ElementBase, metaclass=MetaOxmlElement):
     """Effective base class for all custom element classes.
@@ -688,22 +683,6 @@ class BaseOxmlElement(etree.ElementBase, metaclass=MetaOxmlElement):
             self.append(elm)
         return elm
 
-    def itertext(self, tag: Any | None = None, *tags: Any, with_tail: bool = True) -> Iterator[str]:
-        """Iterate over text content of this element and its descendants.
-
-        Bypasses the overridden `.text` properties on custom oxml element classes (such as
-        `CT_P`, `CT_R`, `CT_Hyperlink`), which would otherwise duplicate text, so standard
-        lxml `itertext()` semantics are preserved.
-        """
-        for node in self.iter(tag, *tags):
-            text = _raw_text(node)
-            if text:
-                yield text
-            if with_tail and node is not self:
-                tail = _raw_tail(node)
-                if tail:
-                    yield tail
-
     def remove_all(self, *tagnames: str) -> None:
         """Remove child elements with tagname (e.g. "a:p") in `tagnames`."""
         for tagname in tagnames:

{python_docx_oss-0.3.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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.1
+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.1 → python_docx_oss-0.3.2}/src/python_docx_oss.egg-info/SOURCES.txt

@@ -175,7 +175,6 @@ features/txt-add-break.feature
 features/txt-font-color.feature
 features/txt-font-props.feature
 features/txt-parfmt-props.feature
-features/_scratch/test_out.docx
 features/steps/api.py
 features/steps/block.py
 features/steps/comments.py

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

@@ -97,7 +97,7 @@ class DescribeMultipleCustomXmlParts:
         replaced = _parts_by_name(reopened)["/customXml/item1.xml"]
 
         assert replaced.tag == "{urn:python-docx-oss:wrapper}wrapper"
-        assert replaced.attrib["version"] == "1"
+        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

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

@@ -115,7 +115,7 @@ class DescribeWordDocumentRoundTrips:
         text.text = "Business link"
         run.append(text)
         hyperlink.append(run)
-        paragraph._p.append(hyperlink)
+        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

{python_docx_oss-0.3.1 → 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,7 +49,7 @@ class DescribeBaseOxmlElement:
         element.remove_all(*tagnames)
         assert element.xml == expected_xml
 
-    def it_iterates_text_without_duplication_when_text_property_is_overridden(self):
+    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>"
@@ -58,6 +59,24 @@ class DescribeBaseOxmlElement:
         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.1 → 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.1 → python_docx_oss-0.3.2}/tests/oxml/text/test_run.py

@@ -38,18 +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