support stdout_lxml for advanced functionality

* lxml is in optional requirements

Signed-off-by: Aleksei Stepanov <penguinolog@gmail.com>

Author: penguinolog

CI_REQUIREMENTS.txt

@@ -1,2 +1,3 @@
 mock  # no assert_called_once in py35
 -r requirements.txt
+lxml

README.rst

@@ -205,6 +205,8 @@ Execution result object has a set of useful properties:
 
 * `stdout_xml` - STDOUT decoded as XML to `ElementTree` using `defusedxml` library.
 
+* `stdout_lxml` - STDOUT decoded as XML to `ElementTree` using `lxml` library. Accessible only if lxml library installed. Can be insecure.
+
 * `timestamp` -> `typing.Optional(datetime.datetime)`. Timestamp for received exit code.
 
 SSHClient specific

doc/source/ExecResult.rst

@@ -154,6 +154,16 @@ API: ExecResult
         :rtype: xml.etree.ElementTree.Element
         :raises DeserializeValueError: STDOUT can not be deserialized as XML
 
+    .. py:attribute:: stdout_lxml
+
+        XML from stdout using lxml.
+
+        :rtype: lxml.etree.Element
+        :raises DeserializeValueError: STDOUT can not be deserialized as XML
+        :raises AttributeError: lxml is not installed
+
+        .. note:: Can be insecure.
+
     .. py:method:: read_stdout(src=None, log=None, verbose=False)
 
         Read stdout file-like object to stdout.

exec_helpers/exec_result.py

@@ -1,4 +1,4 @@
-#    Copyright 2018 Alexey Stepanov aka penguinolog.
+#    Copyright 2018 - 2019 Alexey Stepanov aka penguinolog.
 
 #    Copyright 2016 Mirantis, Inc.
 #
@@ -37,6 +37,11 @@
 from exec_helpers import exceptions
 from exec_helpers import proc_enums
 
+try:
+    import lxml.etree  # type: ignore  # nosec
+except ImportError:
+    lxml = None  # pylint: disable=invalid-name
+
 if typing.TYPE_CHECKING:
     import xml.etree.ElementTree  # nosec  # noqa  # pylint: disable=unused-import
 
@@ -496,6 +501,8 @@ def __deserialize(self, fmt):  # type: (typing.Text) -> typing.Any
                 return yaml.safe_load(self.stdout_str)
             if fmt == "xml":
                 return defusedxml.ElementTree.fromstring(bytes(self.stdout_bin))
+            if fmt == "lxml":
+                return lxml.etree.fromstring(bytes(self.stdout_bin))  # nosec
         except Exception:
             tmpl = " stdout is not valid {fmt}:\n" "{{stdout!r}}\n".format(fmt=fmt)
             logger.exception(self.cmd + tmpl.format(stdout=self.stdout_str))
@@ -526,17 +533,32 @@ def stdout_yaml(self):  # type: () -> typing.Any
 
     @property
     def stdout_xml(self):  # type: () -> xml.etree.ElementTree.Element
-        """YAML from stdout.
+        """XML from stdout.
 
         :rtype: xml.etree.ElementTree.Element
         :raises DeserializeValueError: STDOUT can not be deserialized as XML
         """
         with self.stdout_lock:
             return self.__deserialize(fmt="xml")  # type: ignore
 
+    @property
+    def stdout_lxml(self):  # type: () -> "lxml.etree.Element"
+        """XML from stdout using lxml.
+
+        :rtype: lxml.etree.Element
+        :raises DeserializeValueError: STDOUT can not be deserialized as XML
+        :raises AttributeError: lxml is not installed
+
+        .. note:: Can be insecure.
+        """
+        if lxml is None:
+            raise AttributeError("lxml is not installed -> attribute is not functional.")
+        with self.stdout_lock:
+            return self.__deserialize(fmt="lxml")
+
     def __dir__(self):  # type: () -> typing.List[typing.Text]
         """Override dir for IDE and as source for getitem checks."""
-        return [
+        content = [
             "cmd",
             "stdout",
             "stderr",
@@ -554,6 +576,9 @@ def __dir__(self):  # type: () -> typing.List[typing.Text]
             "stdout_xml",
             "lock",
         ]
+        if lxml is not None:
+            content.append("stdout_lxml")
+        return content
 
     def __getitem__(self, item):  # type: (typing.Union[str, typing.Text]) -> typing.Any
         """Dict like get data.

requirements.txt

@@ -5,7 +5,7 @@ threaded>=1.0  # Apache-2.0
 PyYAML>=3.12  # MIT
 advanced-descriptors>=1.0  # Apache-2.0
 typing >= 3.6; python_version < "3.7"  # PSF
-futures>=3.1; python_version == "2.7"
-enum34>=1.1; python_version == "2.7"
-psutil >= 5.0
-defusedxml
+futures>=3.1; python_version == "2.7"  # PSF
+enum34>=1.1; python_version == "2.7"  # PSF
+psutil >= 5.0  # BSD
+defusedxml  # PSF

setup.py

@@ -1,4 +1,4 @@
-#    Copyright 2018 Alexey Stepanov aka penguinolog
+#    Copyright 2018 - 2019 Alexey Stepanov aka penguinolog
 
 #    Copyright 2016 Mirantis, Inc.
 
@@ -178,6 +178,9 @@ def get_simple_vars_from_src(src):
     ],
     use_scm_version=True,
     install_requires=required,
+    extras_require={
+        "lxml": ["lxml!=3.7.0"]
+    },
     package_data={
         str('exec_helpers'): ['py.typed'],
     },

test/test_exec_result.py

@@ -29,6 +29,10 @@
 import exec_helpers
 from exec_helpers import proc_enums
 
+try:
+    import lxml.etree
+except ImportError:
+    lxml = None
 
 cmd = "ls -la | awk '{print $1}'"
 
@@ -315,3 +319,17 @@ def test_stdout_xml(self):
         self.assertEqual(
             xml.etree.ElementTree.tostring(expect), xml.etree.ElementTree.tostring(result.stdout_xml)
         )
+
+    @unittest.skipIf(lxml is None, "no lxml installed")
+    def test_stdout_lxml(self):
+        result = exec_helpers.ExecResult(
+            "test",
+            stdout=[
+                b"<?xml version='1.0'?>\n",
+                b'<data>123</data>\n',
+            ]
+        )
+        expect = lxml.etree.fromstring(b"<?xml version='1.0'?>\n<data>123</data>\n")
+        self.assertEqual(
+            lxml.etree.tostring(expect), lxml.etree.tostring(result.stdout_lxml)
+        )