Merge pull request #29 from BlackBoiler/DEV-4746-pickle-serialize

v1.2.0: Support Serialization of python-docx/ lxml.Etree elements

Author: ryanamannion

HISTORY.rst

@@ -3,6 +3,11 @@
 Release History
 ---------------
 
+1.2.0 (2025-05-22)
+++++++++++++++++++
+- DEV-4746: Support Serialization of python-docx/ lxml.Etree elements
+
+
 1.1.0 (2025-03-25)
 ++++++++++++++++++
 - DEV-4646: add new color_val property to ``CT_RPr``

src/docx/__init__.py

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

src/docx/oxml/parser.py

@@ -5,6 +5,7 @@
 from __future__ import annotations
 
 from typing import TYPE_CHECKING, Dict, Type, cast
+import copyreg
 
 from lxml import etree
 
@@ -19,6 +20,21 @@
 oxml_parser = etree.XMLParser(remove_blank_text=True, resolve_entities=False)
 oxml_parser.set_element_class_lookup(element_class_lookup)
 
+# -- serialization support --
+def _pickle_element(elem):
+    """Function for pickling lxml.etree._Element objects."""
+    xml_str = etree.tostring(elem)
+    return _deserialize_oxml_element, (xml_str,)
+
+
+def _deserialize_oxml_element(xml_str):
+    """Deserialize bytes back into an object using parse_xml."""
+    return parse_xml(xml_str)
+
+
+copyreg.pickle(etree._Element, _pickle_element)
+# --
+
 
 def parse_xml(xml: str | bytes) -> "BaseOxmlElement":
     """Root lxml element obtained by parsing XML character string `xml`.
@@ -39,6 +55,7 @@ def register_element_cls(tag: str, cls: Type["BaseOxmlElement"]):
     nspfx, tagroot = tag.split(":")
     namespace = element_class_lookup.get_namespace(nsmap[nspfx])
     namespace[tagroot] = cls
+    copyreg.pickle(cls, _pickle_element)
 
 
 def OxmlElement(

src/docx/shared.py

@@ -142,6 +142,10 @@ def __str__(self):
         """Return a hex string rgb value, like '3C2F80'."""
         return "%02X%02X%02X" % self
 
+    def __reduce__(self):
+        # Return a tuple of (callable, args) that will recreate this object
+        return RGBColor, (self[0], self[1], self[2])
+
     @classmethod
     def from_string(cls, rgb_hex_str: str) -> RGBColor:
         """Return a new instance from an RGB color hex string like ``'3C2F80'``."""