faster XML, better coverage and docs

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

Author: penguinolog

README.rst

@@ -69,9 +69,24 @@ This package includes:
   .. note:: for Windows `ProactorEventLoop` or another non-standard event loop should be used!
 
 * `ExecResult` - class for execution results storage.
-  Contains exit code, stdout, stderr and getters for decoding as JSON, YAML, string, bytearray and brief strings (up to 7 lines).
+  Contains exit code, stdout, stderr and getters for decoding as JSON, YAML, XML (and LXML) element tree, string, bytearray
+  and brief strings (up to 7 lines).
 
-* `ExitCodes` - enumerator for standard Linux exit codes. BASH return codes (broduced from signal codes) also available.
+* `ExitCodes` - enumerator for standard Linux exit codes. BASH return codes (produced from signal codes) also available.
+
+Installation
+============
+
+Standard: `pip install exec-helpers`
+Extras:
+
+* ``yaml`` - install `PyYaml` for yaml decoding (`PyYAML` is main decoder, `ruamel.YAML` also supported as fallback.)
+
+* ``xml`` - install `defusedxml` for safe XML parsing to `xml.etree.ElementTree.Element`.
+
+* ``lxml`` - install `lxml` for advanced XML parsing. Can be unsafe.
+
+* ``ALL_FORMATS`` - install all parsers. When new parsers will be added, it will ne also supported.
 
 Usage
 =====
@@ -105,7 +120,7 @@ Creation from scratch:
     )
 
 Key is a main connection key (always tried first) and keys are alternate keys.
-Key filename is afilename or list of filenames with keys, which should be loaded.
+Key filename is a filename or list of filenames with keys, which should be loaded.
 Passphrase is an alternate password for keys, if it differs from main password.
 If main key now correct for username - alternate keys tried, if correct key found - it became main.
 If no working key - password is used and None is set as main key.
@@ -223,11 +238,14 @@ Execution result object has a set of useful properties:
 
 * `stdout_json` - STDOUT decoded as JSON.
 
-* `stdout_yaml` - STDOUT decoded as YAML. Accessible only if PyYAML or ruamel.YAML library installed. (Option ``yaml``)
+* `stdout_yaml` - STDOUT decoded as YAML. Accessible only if `PyYAML` or `ruamel.YAML` library installed.
+  (Extras: ``yaml``)
 
-* `stdout_xml` - STDOUT decoded as XML to `ElementTree` using `defusedxml` library. Accessible only if `defusedxml` library installed. (Option ``xml``)
+* `stdout_xml` - STDOUT decoded as XML to `ElementTree` using `defusedxml` library. Accessible only if `defusedxml` library installed.
+  (Extras: ``xml``)
 
-* `stdout_lxml` - STDOUT decoded as XML to `ElementTree` using `lxml` library. Accessible only if `lxml` library installed. (Option ``lxml``) Can be insecure.
+* `stdout_lxml` - STDOUT decoded as XML to `ElementTree` using `lxml` library. Accessible only if `lxml` library installed.
+  (Extras: ``lxml``) Can be insecure.
 
 * `timestamp` -> `typing.Optional(datetime.datetime)`. Timestamp for received exit code.
 

exec_helpers/exec_result.py

@@ -514,9 +514,9 @@ def __deserialize(self, fmt: str) -> typing.Any:
                     return yaml.safe_load(self.stdout_str)
                 return ruamel_yaml.YAML(typ="safe").load(self.stdout_str)  # nosec  # Safe
             if fmt == "xml":
-                return defusedxml.ElementTree.fromstring(bytes(self.stdout_bin))
+                return defusedxml.ElementTree.fromstring(b"".join(self.stdout))
             if fmt == "lxml":
-                return lxml.etree.fromstring(bytes(self.stdout_bin))  # nosec
+                return lxml.etree.fromstring(b"".join(self.stdout))  # nosec
         except Exception as e:
             tmpl: str = f"{{self.cmd}} stdout is not valid {fmt}:\n{{stdout!r}}\n"
             LOGGER.exception(tmpl.format(self=self, stdout=self.stdout_str))

setup.py

@@ -230,7 +230,11 @@ def get_simple_vars_from_src(src):
 
 KEYWORDS = ["logging", "debugging", "development"]
 
-setup_args = dict(
+XML_DEPS = ["defusedxml"]
+LXML_DEPS = ["lxml!=3.7.0"]
+YAML_DEPS = ["PyYAML>=3.12"]
+
+SETUP_ARGS = dict(
     name="exec-helpers",
     author=VARIABLES["__author__"],
     author_email=VARIABLES["__author_email__"],
@@ -259,20 +263,21 @@ def get_simple_vars_from_src(src):
     use_scm_version={'write_to': 'exec_helpers/_version.py'},
     install_requires=REQUIRED,
     extras_require={
-        "xml": ["defusedxml"],
-        "lxml": ["lxml!=3.7.0"],
-        "yaml": ["PyYAML>=3.12"],
+        "xml": XML_DEPS,
+        "lxml": LXML_DEPS,
+        "yaml": YAML_DEPS,
+        "ALL_FORMATS": XML_DEPS + LXML_DEPS + YAML_DEPS
     },
     package_data={"exec_helpers": ["py.typed"]},
 )
 if cythonize is not None:
-    setup_args["ext_modules"] = EXT_MODULES
-    setup_args["cmdclass"] = dict(build_ext=AllowFailRepair)
+    SETUP_ARGS["ext_modules"] = EXT_MODULES
+    SETUP_ARGS["cmdclass"] = dict(build_ext=AllowFailRepair)
 
 try:
-    setuptools.setup(**setup_args)
+    setuptools.setup(**SETUP_ARGS)
 except BuildFailed:
     print("*" * 80 + "\n" "* Build Failed!\n" "* Use clear scripts version.\n" "*" * 80 + "\n")
-    del setup_args["ext_modules"]
-    del setup_args["cmdclass"]
-    setuptools.setup(**setup_args)
+    del SETUP_ARGS["ext_modules"]
+    del SETUP_ARGS["cmdclass"]
+    setuptools.setup(**SETUP_ARGS)

test/test_exec_result.py

@@ -337,3 +337,41 @@ def test_stdout_yaml_ruamel(self):
         expect = {"test": "data"}
         result = result.stdout_yaml
         self.assertEqual(expect, result)
+
+
+class TestExecResultNoExtras(unittest.TestCase):
+    def setUp(self) -> None:
+        self._orig_yaml, exec_helpers.exec_result.yaml = exec_helpers.exec_result.yaml, None
+        self._orig_ruamel_yaml, exec_helpers.exec_result.ruamel_yaml = exec_helpers.exec_result.ruamel_yaml, None
+        self._orig_lxml, exec_helpers.exec_result.lxml = exec_helpers.exec_result.lxml, None
+        self._orig_defusedxml, exec_helpers.exec_result.defusedxml = exec_helpers.exec_result.defusedxml, None
+
+    def tearDown(self) -> None:
+        exec_helpers.exec_result.yaml = self._orig_yaml
+        exec_helpers.exec_result.ruamel_yaml = self._orig_ruamel_yaml
+        exec_helpers.exec_result.lxml = self._orig_lxml
+        exec_helpers.exec_result.defusedxml = self._orig_defusedxml
+
+    def test_stdout_yaml(self):
+        result = exec_helpers.ExecResult(
+            "test",
+            stdout=[
+                b"{test: data}\n"
+            ]
+        )
+        with self.assertRaises(AttributeError):
+            getattr(result, 'stdout_yaml')  # noqa: B009
+
+    def test_stdout_xmls(self):
+        result = exec_helpers.ExecResult(
+            "test",
+            stdout=[
+                b"<?xml version='1.0'?>\n",
+                b'<data>123</data>\n',
+            ]
+        )
+        with self.assertRaises(AttributeError):
+            getattr(result, 'stdout_xml')  # noqa: B009
+
+        with self.assertRaises(AttributeError):
+            getattr(result, 'stdout_lxml')  # noqa: B009