completed xmlproxy

Author: a.pirogov

src/somesy/pom_xml/xmlproxy.py

@@ -11,6 +11,13 @@
 JSONLike = Any
 
 
+def load_xml(path: Path) -> ET.ElementTree:
+    """Parse an XML file into an ElementTree, preserving comments."""
+    path = path if isinstance(path, Path) else Path(path)
+    parser = DET.XMLParser(target=ET.TreeBuilder(insert_comments=True))
+    return DET.parse(path, parser=parser)
+
+
 class XMLProxy:
     """Class providing dict-like access to edit XML via ElementTree.
 
@@ -27,33 +34,38 @@ class XMLProxy:
     * Otherwise, the node is returned
     """
 
-    def __init__(self, el: ET.Element, *, default_namespace: Optional[str] = None):
-        """Wrap an existing XML ElementTree Element."""
-        self._node: ET.Element = el
-        self._def_ns = default_namespace
-
     def _wrap(self, el: ET.Element) -> XMLProxy:
-        """Wrap different element, inheriting the namespace."""
+        """Wrap a different element, inheriting the same namespace."""
         return XMLProxy(el, default_namespace=self._def_ns)
 
+    def _dump(self):
+        """Dump XML to stdout (for debugging)."""
+        ET.dump(self._node)
+
     def _qualified_key(self, key: str):
         """If passed key is not qualified, prepends the default namespace (if set)."""
         if key[0] == "{" or not self._def_ns:
             return key
         return "{" + self._def_ns + "}" + key
 
     def _shortened_key(self, key: str):
-        """Inverse of `_qualified_key`."""
+        """Inverse of `_qualified_key` (strips default namespace from element name)."""
         if key[0] != "{" or not self._def_ns or key.find(self._def_ns) < 0:
             return key
         return key[key.find("}") + 1 :]
 
+    # ----
+
+    def __init__(self, el: ET.Element, *, default_namespace: Optional[str] = None):
+        """Wrap an existing XML ElementTree Element."""
+        self._node: ET.Element = el
+        self._def_ns = default_namespace
+
     @classmethod
     def parse(cls, path: Union[str, Path], **kwargs) -> XMLProxy:
-        """Parse an XML file into an ElementTree, preserving comments."""
+        """Parse an XML file into a wrapped ElementTree, preserving comments."""
         path = path if isinstance(path, Path) else Path(path)
-        parser = DET.XMLParser(target=ET.TreeBuilder(insert_comments=True))
-        return cls(DET.parse(path, parser=parser).getroot(), **kwargs)
+        return cls(load_xml(path).getroot(), **kwargs)
 
     def write(self, path: Union[str, Path], *, header: bool = True, **kwargs):
         """Write the XML DOM to an UTF-8 encoded file."""
@@ -78,25 +90,48 @@ def __iter__(self):
         """Iterate the nested elements in-order."""
         return map(self._wrap, iter(self._node))
 
-    def _dump(self):
-        """Dump XML to stdout (for debugging)."""
-        ET.dump(self._node)
+    @property
+    def namespace(self) -> Optional[str]:
+        """Default namespace of this node."""
+        return self._def_ns
+
+    @property
+    def is_comment(self):
+        """Return whether the current element node is an XML comment."""
+        return not isinstance(self._node.tag, str)
+
+    @property
+    def tag(self) -> Optional[str]:
+        """Return tag name of this element (unless it is a comment)."""
+        if self.is_comment:
+            return None
+        return self._shortened_key(self._node.tag)
+
+    @tag.setter
+    def tag(self, val: str):
+        """Set the tag of this element."""
+        if self.is_comment:
+            raise ValueError("Cannot set tag name for comment element!")
+        self._node.tag = self._qualified_key(val)
 
     # ---- helpers ----
 
     def to_jsonlike(
-        self, *, strip_default_ns: bool = True, keep_root: bool = False
+        self,
+        *,
+        strip_default_ns: bool = True,
+        keep_root: bool = False,
     ) -> JSONLike:
         """Convert XML node to a JSON-like primitive, array or dict (ignoring attributes).
 
-        Note that comments are ignored and all leaf values are strings.
+        Note that all leaf values are strings (i.e. not parsed to bool/int/float etc.).
 
         Args:
             strip_default_ns: Do not qualify keys from the default namespace
             keep_root: If true, the root tag name will be preserved (`{"root_tag": {...}}`)
         """
         if not len(self):  # leaf -> assume it's a primitive value
-            return self._node.text.strip()
+            return self._node.text or ""
 
         dct = {}
         ccnt = 0
@@ -120,15 +155,15 @@ def to_jsonlike(
         return dct if not keep_root else {self._shortened_key(self._node.tag): dct}
 
     @classmethod
-    def from_jsonlike_primitive(
+    def _from_jsonlike_primitive(
         cls, val, *, elem_name: Optional[str] = None, **kwargs
     ) -> Union[str, XMLProxy]:
         """Convert a leaf node into a string value (i.e. return inner text).
 
         Returns a string (or an XML element, if elem_name is passed).
         """
         if val is None:
-            ret = "null"  # turn None into Java null
+            ret = ""  # turn None into empty string
         elif isinstance(val, str):
             ret = val
         elif isinstance(val, bool):
@@ -163,7 +198,7 @@ def from_jsonlike(cls, val, *, root_name: Optional[str] = None, **kwargs):
                 map(lambda x: cls.from_jsonlike(x, root_name=root_name, **kwargs), val)
             )
         if not isinstance(val, dict):  # primitive val
-            return cls.from_jsonlike_primitive(val, elem_name=root_name, **kwargs)
+            return cls._from_jsonlike_primitive(val, elem_name=root_name, **kwargs)
 
         # now the dict case remains
         elem = ET.Element(root_name or "root")
@@ -179,7 +214,8 @@ def from_jsonlike(cls, val, *, root_name: Optional[str] = None, **kwargs):
             elif not isinstance(v, dict):  # primitive val
                 # FIXME: use better case-splitting for type of function to avoid cast
                 tmp = cast(
-                    XMLProxy, XMLProxy.from_jsonlike_primitive(v, elem_name=k, **kwargs)
+                    XMLProxy,
+                    XMLProxy._from_jsonlike_primitive(v, elem_name=k, **kwargs),
                 )
                 elem.append(tmp._node)
             else:  # dict
@@ -200,23 +236,27 @@ def get(self, key: str, *, as_nodes: bool = False, deep: bool = False):
             as_nodes: If true, will *always* return a list of (zero or more) XML nodes
             deep: Expand nested XML elements instead of returning them as XML nodes
         """
+        # NOTE: could allow to retrieve comments when using empty string/none as key?
+
         if as_nodes and deep:
             raise ValueError("as_nodes and deep are mutually exclusive!")
         if not key:
             raise ValueError("Key must not be an empty string!")
+        key = self._qualified_key(key)
 
         # if not fully qualified + default NS is given, use it for query
-        if lst := self._node.findall(self._qualified_key(key)):
-            ns: List[XMLProxy] = list(map(self._wrap, lst))
-            if as_nodes:  # return it as a list of xml nodes
-                return ns
-
-            # apply canonical dict-ification
-            ret: Union[List[XMLProxy], List[JSONLike]] = (
-                ns if not deep else [x.to_jsonlike() for x in ns]
-            )
-            if ret:  # if list has just one element -> return that
-                return lst[0] if len(lst) == 1 else lst
+        lst = self._node.findall(key)
+        ns: List[XMLProxy] = list(map(self._wrap, lst))
+        if as_nodes:  # return it as a list of xml nodes
+            return ns
+        if not ns:  # no element
+            return None
+
+        ret = ns if not deep else [x.to_jsonlike() for x in ns]
+        if len(ret) == 1:
+            return ret[0]  # single element
+        else:
+            return ret
 
     def __getitem__(self, key: str):
         """Acts like `dict.__getitem__`, implemented with `get`."""
@@ -259,18 +299,27 @@ def __delitem__(self, key: Union[str, XMLProxy]):
         if not nodes:
             raise KeyError(key)
 
-        self._node.text = ""
+        if self._node.text is not None:
+            self._node.text = ""
         for child in nodes:
             self._node.remove(child._node)
 
+    def _clear(self):
+        """Remove contents of this XML element (e.g. for overwriting in-place)."""
+        self._node.text = ""
+        children = list(iter(self._node))  # need to store, removal invalidates iterator
+        for child in children:
+            self._node.remove(child)
+
     def __setitem__(self, key: Union[str, XMLProxy], val: Union[JSONLike, XMLProxy]):
         """Add or overwrite an inner XML tag.
 
         If there is exactly one matching tag, the value is substituted in-place.
         If the passed value is a list, all list entries are added in their own element.
 
-        If there are multiple existing matches, **all** existing elements are removed
-        and the new value is added with as a new element (i.e. coming last)!
+        If there are multiple existing matches or target values, then
+        **all** existing elements are removed and the new value(s) are added in
+        new element(s) (i.e. coming after other unrelated existing elements)!
 
         To prevent this behavior, instead of a string tag name you can provide the
         exact element to be overwritten, i.e. if a node `node_a` represents the following XML:
@@ -290,38 +339,49 @@ def __setitem__(self, key: Union[str, XMLProxy], val: Union[JSONLike, XMLProxy])
 
         Note that the passed value must be either an XML element already, or be a pure JSON-like object.
         """
-        # TODO: what about assigning a list of stuff? add that, then write tests
-
         if isinstance(key, str):
-            nodes = self.get(key, as_nodes=True) or []
-            if (
-                len(nodes) > 1
-            ):  # delete all existing elements in case there are multiple
+            nodes = self.get(key, as_nodes=True)
+            # delete all existing elements if multiple exist or are passed
+            if len(nodes) > 1 or isinstance(val, list):
                 del self[key]
                 nodes = []
-            if not nodes:  # create new element if there were multiple or none
-                node = self._wrap(ET.SubElement(self._node, self._qualified_key(key)))
-            else:  # take the unique matching node, empty it out (text + inner tags)
-                node = nodes[0]
-        else:  # an XMLProxy object was passed as key -> use that
-            node = key
-
-        # ensure the target node is cleared out (e.g. when reusing existing element)
-        node._node.text = ""
-        for child in list(
-            iter(node._node)
-        ):  # need to store in list, removal invalidates iterator
-            node._node.remove(child)
-
-        # ensure value is represented as an XML node
-        if not isinstance(val, XMLProxy):
-            val = self.from_jsonlike(val, root_name=self._shortened_key(self._node.tag))
-        else:
-            wrapped = self._wrap(ET.Element("dummy"))
-            wrapped._node.append(val._node)
-            val = wrapped
-
-        # transplant node contents into existing element (so it is inserted in-place)
-        node._node.text = val._node.text
-        for child in iter(val):
-            node._node.append(child._node)
+            # now we can assume there's zero or one suitable target elements
+            if nodes:  # if it is one, clear it out
+                nodes[0]._clear()
+        else:  # an XMLProxy object was passed as key -> try to use that
+            if isinstance(val, list):
+                raise ValueError(
+                    "Cannot overwrite a single element with a list of values!"
+                )
+            # ensure the target node is cleared out and use it as target
+            key._clear()
+            nodes = [key]
+            key = key.tag
+
+        # ensure key string is qualified with a namespace
+        key_name: str = self._qualified_key(key)
+
+        # normalize passed value(s) to be list (general case)
+        vals = val if isinstance(val, list) else [val]
+
+        # ensure there is the required number of target element nodes
+        for _ in range(len(vals) - len(nodes)):
+            nodes.append(self._wrap(ET.SubElement(self._node, key_name)))
+
+        # normalize values no XML element nodes
+        nvals = []
+        for val in vals:
+            # ensure value is represented as an XML node
+            if isinstance(val, XMLProxy):
+                obj = self._wrap(ET.Element("dummy"))
+                obj._node.append(val._node)
+            else:
+                obj = self.from_jsonlike(val, root_name=key_name)
+
+            nvals.append(obj)
+
+        for node, val in zip(nodes, nvals):
+            # transplant node contents into existing element (so it is inserted in-place)
+            node._node.text = val._node.text
+            for child in iter(val):
+                node._node.append(child._node)

tests/conftest.py

@@ -10,6 +10,12 @@
 from somesy.package_json.writer import PackageJSON
 from somesy.pyproject import Pyproject
 from somesy.julia import Julia
+from somesy.pom_xml import load_xml
+
+TEST_DIR = Path(__file__).resolve().parent
+
+TEST_DATA_DIR = TEST_DIR / "data"
+"""Location of the test input data."""
 
 
 class FileTypes(Enum):
@@ -101,7 +107,7 @@ def _load_files(files: Set[FileTypes]):
             if not isinstance(file_type, FileTypes):
                 raise ValueError(f"Invalid file type: {file_type}")
 
-            read_file_name = Path("tests/data")
+            read_file_name = TEST_DATA_DIR
             if file_type == FileTypes.CITATION:
                 read_file_name = read_file_name / Path("CITATION.cff")
                 file_instances[file_type] = CFF(read_file_name)
@@ -137,3 +143,11 @@ def person() -> Person:
     ret = Person.model_validate(p)
     ret.set_key_order(list(p.keys()))  # custom order!
     return ret
+
+
+@pytest.fixture
+def xml_examples():
+    def _xml_loader(filename: str) -> Path:
+        return TEST_DATA_DIR / filename
+
+    yield _xml_loader

tests/data/blank_pom.xml

@@ -1,3 +1,4 @@
-<?xml version="1.0" encoding="UTF-8"?>
+<?xml version='1.0' encoding='UTF-8'?>
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
-</project>
+<!-- contents of POM file -->
+</project>

tests/data/example_1.xml

@@ -0,0 +1,17 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <nothing />
+    <emptyString></emptyString>
+    <listEntry>foo</listEntry>
+    <!-- comment 1 -->
+    <aBool>true</aBool>
+    <!-- comment 2 -->
+    <anInt>42</anInt>
+    <listEntry>
+        <someDict>
+            <a>x</a>
+            <b>y</b>
+        </someDict>
+        <someValue>z</someValue>
+    </listEntry>
+    <aFloat>3.14</aFloat>
+</project>