smartXML 1.0.1__tar.gz → 1.0.9__tar.gz

smartxml-1.0.9/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: smartXML
+Version: 1.0.9
+Summary: smartXML package enables you to read, search, manipulate, and write XML files with ease
+Author-email: Dudu Arbel <duduarbel@gmail.com>
+License-Expression: MIT
+Project-URL: Changelog, https://github.com/duduarbel/smartXML/blob/main/changelog.md
+Keywords: python,example
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: ruff>=0.3; extra == "dev"
+
+# smartXML
+
+The **smartXML** package enables you to read, search, manipulate, and write XML files with ease.
+
+The API is designed to be simple, but it will be enhanced according to usage and requests.
+The package includes a `SmartXML` representing the XML file, and `ElementBase` representing each element in the XML tree
+### SmartXML:
+- properties:
+    - `root`: the root element of the XML file
+    - `declaration`: the XML declaration (e.g., `<?xml version="1.0" encoding="UTF-8"?>`)
+- methods:
+    - `read`: reads the XML file from the root element
+    - `write`: writes the XML to a file
+    - `find`: finds elements from the root element
+
+### ElementBase: (base class for Element, Comment, TextOnlyComment, CData, and Doctype)
+- properties:
+    - `name`: the name of the element
+    - `parent`: the parent element
+- methods:
+    - `find`: finds elements from the current element
+    - `remove`: removes the current element from its parent
+    - `comment_out`: comments out the current element
+    - `add_before`: adds an element before the current element
+    - `add_after`: adds an element after the current element
+    - `add_as_son_of`: adds an element as a son of the current element
+    - `set_as_parent_of`: sets the current element as the parent of another element
+    - `to_string`: converts the current element to a string
+
+
+### Usage Example
+
+```python
+from pathlib import Path
+from smartXML.xmltree import SmartXML, TextOnlyComment
+
+input_file = Path('./example.xml')
+xml = SmartXML(input_file)
+
+firstName = xml.find('students|student|firstName', with_content='Bob')
+bob = firstName.parent
+bob.comment_out()
+header = TextOnlyComment('Bob is out')
+header.add_before(bob)
+
+xml.write()
+```
+result (example.xml):
+```xml
+<students>
+  <!-- Bob is out -->
+  <!--
+    <student id="S002">
+	  <firstName>Bob</firstName>
+	  <lastName>Levi</lastName>
+    </student>
+  -->
+</students>
+```

smartxml-1.0.9/README.md

@@ -0,0 +1,59 @@
+# smartXML
+
+The **smartXML** package enables you to read, search, manipulate, and write XML files with ease.
+
+The API is designed to be simple, but it will be enhanced according to usage and requests.
+The package includes a `SmartXML` representing the XML file, and `ElementBase` representing each element in the XML tree
+### SmartXML:
+- properties:
+    - `root`: the root element of the XML file
+    - `declaration`: the XML declaration (e.g., `<?xml version="1.0" encoding="UTF-8"?>`)
+- methods:
+    - `read`: reads the XML file from the root element
+    - `write`: writes the XML to a file
+    - `find`: finds elements from the root element
+
+### ElementBase: (base class for Element, Comment, TextOnlyComment, CData, and Doctype)
+- properties:
+    - `name`: the name of the element
+    - `parent`: the parent element
+- methods:
+    - `find`: finds elements from the current element
+    - `remove`: removes the current element from its parent
+    - `comment_out`: comments out the current element
+    - `add_before`: adds an element before the current element
+    - `add_after`: adds an element after the current element
+    - `add_as_son_of`: adds an element as a son of the current element
+    - `set_as_parent_of`: sets the current element as the parent of another element
+    - `to_string`: converts the current element to a string
+
+
+### Usage Example
+
+```python
+from pathlib import Path
+from smartXML.xmltree import SmartXML, TextOnlyComment
+
+input_file = Path('./example.xml')
+xml = SmartXML(input_file)
+
+firstName = xml.find('students|student|firstName', with_content='Bob')
+bob = firstName.parent
+bob.comment_out()
+header = TextOnlyComment('Bob is out')
+header.add_before(bob)
+
+xml.write()
+```
+result (example.xml):
+```xml
+<students>
+  <!-- Bob is out -->
+  <!--
+    <student id="S002">
+	  <firstName>Bob</firstName>
+	  <lastName>Levi</lastName>
+    </student>
+  -->
+</students>
+```

{smartxml-1.0.1 → smartxml-1.0.9}/pyproject.toml

@@ -4,10 +4,10 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "smartXML"
-version = "1.0.1"
+version = "1.0.9"
 description = "smartXML package enables you to read, search, manipulate, and write XML files with ease"
 readme = "README.md"
-requires-python = ">=3.10"
+requires-python = ">=3.9"
 license = "MIT"
 
 authors = [
@@ -18,6 +18,7 @@ keywords = ["python", "example"]
 classifiers = [
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
@@ -28,6 +29,9 @@ dependencies = [
     "requests>=2.31",
 ]
 
+[project.urls]
+Changelog = "https://github.com/duduarbel/smartXML/blob/main/changelog.md"
+
 [project.optional-dependencies]
 dev = [
     "pytest>=8.0",

{smartxml-1.0.1 → smartxml-1.0.9}/src/smartXML/element.py

@@ -1,4 +1,5 @@
 from typing import Union
+import warnings
 
 from ._elements_utils import (
     _find_one,
@@ -80,11 +81,21 @@ class ElementBase:
 
     def add_as_son_of(self, parent: "Element"):
         """Add this element as a son of the given parent element."""
+        warnings.warn(
+            "add_as_son_of() is deprecated and will be removed in version 1.1.0 . add_before() ot add_after() instead.",
+            category=DeprecationWarning,
+            stacklevel=2
+        )
         parent._sons.append(self)
         self._parent = parent
 
     def set_as_parent_of(self, son: "Element"):
         """Set this element as the parent of the given son element."""
+        warnings.warn(
+            "set_as_parent_of() is deprecated and will be removed in version 1.1.0 . add_before() ot add_after() instead.",
+            category=DeprecationWarning,
+            stacklevel=2
+        )
         self._sons.append(son)
         son._parent = self
 
@@ -190,7 +201,7 @@ class Element(ElementBase):
             children_str = "".join(son._to_string(index + 1, indentation) for son in self._sons)
 
             if children_str:
-                result = f"{indent}{opening_tag}" f"{self.content}" f"{"\n"}" f"{children_str}{indent}{closing_tag}"
+                result = f"{indent}{opening_tag}{self.content}\n{children_str}{indent}{closing_tag}"
             else:
                 result = f"{indent}{opening_tag}{self.content}{closing_tag}"
 

{smartxml-1.0.1 → smartxml-1.0.9}/src/smartXML/xmltree.py

@@ -122,7 +122,7 @@ class SmartXML:
             self._tree, self._doctype = self._read(self._file_name)
 
     @property
-    def tree(self) -> str:
+    def tree(self) -> ElementBase:
         """Get the root element of the XML tree."""
         return self._tree
 
@@ -149,10 +149,19 @@ class SmartXML:
         """
         Read and parse the XML file into an element tree.
         :param file_name: Path to the XML file
+        :raises:
+            TypeError: if file_name is not a pathlib.Path object
+            FileNotFoundError: if file_name does not exist
+            BadXMLFormat: if the XML format is invalid
         """
-        self.read(file_name)
+        if not isinstance(file_name, Path):
+            raise TypeError("file_name must be a pathlib.Path object")
+        if not file_name.exists():
+            raise FileNotFoundError(f"File {file_name} does not exist")
 
-    def _read(self, file_name: Path) -> tuple[Any, None] | tuple[Any, Any]:
+        self._tree, self._doctype = self._read(file_name)
+
+    def _read(self, file_name: Path) -> tuple[Any, Any]:
         self._file_name = file_name
         ready_nodes = {}  # depth -> list of elements
         incomplete_nodes = []
@@ -264,10 +273,17 @@ class SmartXML:
         :param file_name: Path to the XML file, if None, overwrite the original file
         :param indentation: string used for indentation, default is tab character
         :return: XML string if file_name is None, else None
+        :raises:
+            ValueError: if file name is not specified
+            TypeError: if file_name is not a pathlib.Path object
+            FileNotFoundError: if file_name does not exist
         """
 
         if file_name:
             self._file_name = file_name
+        if not self._file_name:
+            raise ValueError("File name is not specified")
+
         with open(self._file_name, "w") as file:
             if self._declaration:
                 file.write(f"<?xml {self._declaration}?>\n")
@@ -284,7 +300,7 @@ class SmartXML:
 
     def find(
         self,
-        name: str = None,
+        name: str = "",
         only_one: bool = True,
         with_content: str = None,
     ) -> Element | list[Element] | None:
@@ -296,7 +312,10 @@ class SmartXML:
         :return: the elements found,
                 if found, return the elements that match the last name in the path,
                 if not found, return None if only_one is True, else return empty list
+        :raises:
+            ValueError: if neither name nor with_content is provided
+
         """
-        if name is None and with_content is None:
+        if not name and with_content is None:
             raise ValueError("At least one search criteria must be provided")
         return self._tree.find(name, only_one, with_content)

smartxml-1.0.9/src/smartXML.egg-info/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: smartXML
+Version: 1.0.9
+Summary: smartXML package enables you to read, search, manipulate, and write XML files with ease
+Author-email: Dudu Arbel <duduarbel@gmail.com>
+License-Expression: MIT
+Project-URL: Changelog, https://github.com/duduarbel/smartXML/blob/main/changelog.md
+Keywords: python,example
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: ruff>=0.3; extra == "dev"
+
+# smartXML
+
+The **smartXML** package enables you to read, search, manipulate, and write XML files with ease.
+
+The API is designed to be simple, but it will be enhanced according to usage and requests.
+The package includes a `SmartXML` representing the XML file, and `ElementBase` representing each element in the XML tree
+### SmartXML:
+- properties:
+    - `root`: the root element of the XML file
+    - `declaration`: the XML declaration (e.g., `<?xml version="1.0" encoding="UTF-8"?>`)
+- methods:
+    - `read`: reads the XML file from the root element
+    - `write`: writes the XML to a file
+    - `find`: finds elements from the root element
+
+### ElementBase: (base class for Element, Comment, TextOnlyComment, CData, and Doctype)
+- properties:
+    - `name`: the name of the element
+    - `parent`: the parent element
+- methods:
+    - `find`: finds elements from the current element
+    - `remove`: removes the current element from its parent
+    - `comment_out`: comments out the current element
+    - `add_before`: adds an element before the current element
+    - `add_after`: adds an element after the current element
+    - `add_as_son_of`: adds an element as a son of the current element
+    - `set_as_parent_of`: sets the current element as the parent of another element
+    - `to_string`: converts the current element to a string
+
+
+### Usage Example
+
+```python
+from pathlib import Path
+from smartXML.xmltree import SmartXML, TextOnlyComment
+
+input_file = Path('./example.xml')
+xml = SmartXML(input_file)
+
+firstName = xml.find('students|student|firstName', with_content='Bob')
+bob = firstName.parent
+bob.comment_out()
+header = TextOnlyComment('Bob is out')
+header.add_before(bob)
+
+xml.write()
+```
+result (example.xml):
+```xml
+<students>
+  <!-- Bob is out -->
+  <!--
+    <student id="S002">
+	  <firstName>Bob</firstName>
+	  <lastName>Levi</lastName>
+    </student>
+  -->
+</students>
+```

{smartxml-1.0.1 → smartxml-1.0.9}/tests/test.py

@@ -7,6 +7,8 @@ import pytest
 import random
 
 
+test_file_name = "./files/test.tmp.xml"
+
 def _test_tree_integrity(xml_tree: SmartXML):
 
     def node_tree_integrity(xml: SmartXML, element: Element, name: str):
@@ -25,12 +27,11 @@ def _test_tree_integrity(xml_tree: SmartXML):
 
 
 def __create_file(content: str) -> Path:
-    file_name = "./test.tmp.txt"
-    f = open(file_name, "w")
+    f = open(test_file_name, "w")
     f.write(content)
     f.close()
 
-    return Path(file_name)
+    return Path(test_file_name)
 
 
 @pytest.mark.all
@@ -988,7 +989,7 @@ def test_complex_comment_2():
 
 @pytest.mark.all
 def test_file_test_1():
-    file_name = Path("./test_1.xml")
+    file_name = Path("./files/test_1.xml")
     xml = SmartXML(file_name)
     _test_tree_integrity(xml)
     tag = xml.find("lib:title")
@@ -998,10 +999,10 @@ def test_file_test_1():
 
 @pytest.mark.all
 def test_file_test_2():
-    file_name = Path("./test_2.xml")
+    file_name = Path("./files/test_2.xml")
     xml = SmartXML(file_name)
     _test_tree_integrity(xml)
-    xml.write(Path("./test.tmp.txt"))
+    xml.write(Path(test_file_name))
     pass
 
 
@@ -1132,7 +1133,6 @@ def test_find_name_2():
 
 
 @pytest.mark.all
-@pytest.mark.one
 def test_find_1():
     src = textwrap.dedent(
         """\
@@ -1427,7 +1427,7 @@ def test_bad_format_12():
 @pytest.mark.all
 def test_read_me_example():
     # README example test
-    input_file = Path('./readme_example.xml')
+    input_file = Path('./files/readme_example.xml')
 
     xml = SmartXML(input_file)
     firstName = xml.find('students|student|firstName', with_content='Bob')
@@ -1436,7 +1436,7 @@ def test_read_me_example():
     header = TextOnlyComment('Bob is out')
     header.add_before(bob)
 
-    output_file = Path("./test.tmp.txt")
+    output_file = Path(test_file_name)
     xml.write(output_file)
     result = output_file.read_text()
 
@@ -1523,6 +1523,7 @@ def test_find_all_with_content():
                 </tag2>
             </tag2>
             <tag3/>
+            <tag4>xxx</tag4>
         </head>
         """
     )
@@ -1535,9 +1536,19 @@ def test_find_all_with_content():
     for index in range(4):
         assert tags[index].attributes["id"] == str(index + 1)
 
+    tag4 = xml.find(with_content="xxx")
+    assert tag4
+    assert tag4.name == "tag4"
+
+    tag4 = xml.find(with_content="xxx", only_one=False)
+    assert len(tag4) == 1
+    assert tag4[0].name == "tag4"
+
+
+
 @pytest.mark.all
 def test_read_me_example_ver1():
-    input_file = Path('./readme_example.xml')
+    input_file = Path('./files/readme_example.xml')
 
     xml = SmartXML(input_file)
     names = xml.find('students|student|firstName', only_one=False)
@@ -1548,7 +1559,7 @@ def test_read_me_example_ver1():
             header = TextOnlyComment('Bob is out')
             header.add_before(bob)
 
-    output_file = Path("./test.tmp.txt")
+    output_file = Path(test_file_name)
     xml.write(output_file)
     result = output_file.read_text()
 
@@ -1622,7 +1633,7 @@ def test_build_tree():
 
     _test_tree_integrity(xml)
 
-    file_name = Path("./test.tmp.txt")
+    file_name = Path(test_file_name)
     xml.write(file_name)
     result = file_name.read_text()
     assert result == dst
@@ -1964,4 +1975,72 @@ def test_c_data_3():
     assert result == src
 
 
-# TODO add tests for read() and write and to_string()
+@pytest.mark.all
+def test_to_string():
+    src = textwrap.dedent(
+        """\
+        <root>
+            <tag1>
+                <bbbbb/>
+                <ccccc></ccccc> 
+            </tag1>
+        </root>
+        """
+    )
+
+    dst1 = textwrap.dedent(
+        """\
+        <tag1>
+        \t<bbbbb/>
+        \t<ccccc></ccccc>
+        </tag1>
+        """
+    )
+
+    file_name = __create_file(src)
+    xml = SmartXML(file_name)
+
+    tag1 = xml.find("tag1")
+
+    tag1_str = tag1.to_string()
+    assert tag1_str == dst1
+
+@pytest.mark.all
+@pytest.mark.one
+def test_read():
+
+    xml = SmartXML()
+
+    with pytest.raises(ValueError) as error:
+        xml.write()
+    assert str(error.value) == "File name is not specified"
+    assert error.type is ValueError
+
+    with pytest.raises(TypeError) as error:
+        xml.read('ssss')
+    assert str(error.value) == "file_name must be a pathlib.Path object"
+    assert error.type is TypeError
+
+    with pytest.raises(FileNotFoundError) as error:
+        xml.read(Path('ssss'))
+    assert str(error.value) == "File ssss does not exist"
+    assert error.type is FileNotFoundError
+
+
+
+    src = textwrap.dedent(
+        """\
+        <root>
+        \t<AAA/>
+        \t<![CDATA[A story about <coding> & "logic". The <tags> inside here are ignored by the parser.]]>
+        \t<AAA/>
+        </root>
+        """
+    )
+
+    file_name = __create_file(src)
+    xml.read(file_name)
+    xml.write()
+    result = file_name.read_text()
+    assert result == src
+

smartxml-1.0.1/PKG-INFO

@@ -1,45 +0,0 @@
-Metadata-Version: 2.4
-Name: smartXML
-Version: 1.0.1
-Summary: smartXML package enables you to read, search, manipulate, and write XML files with ease
-Author-email: Dudu Arbel <duduarbel@gmail.com>
-License-Expression: MIT
-Keywords: python,example
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-Requires-Dist: requests>=2.31
-Provides-Extra: dev
-Requires-Dist: pytest>=8.0; extra == "dev"
-Requires-Dist: mypy>=1.8; extra == "dev"
-Requires-Dist: ruff>=0.3; extra == "dev"
-
-# smartXML
-
-The **smartXML** package enables you to read, search, manipulate, and write XML files with ease.
-
-The API is designed to be as simple as possible, but it will be enhanced according to usage and requests.
-
----
-
-## Usage Example
-
-```python
-from pathlib import Path
-from smartxml import SmartXML, TextOnlyComment
-
-input_file = Path('./example.xml')
-xml = SmartXML(input_file)
-
-firstName = xml.find('students|student|firstName', with_content='Bob')
-bob = firstName.parent
-bob.comment_out()
-header = TextOnlyComment('Bob is out')
-header.add_before(bob)
-
-xml.write()

smartxml-1.0.1/README.md

@@ -1,24 +0,0 @@
-# smartXML
-
-The **smartXML** package enables you to read, search, manipulate, and write XML files with ease.
-
-The API is designed to be as simple as possible, but it will be enhanced according to usage and requests.
-
----
-
-## Usage Example
-
-```python
-from pathlib import Path
-from smartxml import SmartXML, TextOnlyComment
-
-input_file = Path('./example.xml')
-xml = SmartXML(input_file)
-
-firstName = xml.find('students|student|firstName', with_content='Bob')
-bob = firstName.parent
-bob.comment_out()
-header = TextOnlyComment('Bob is out')
-header.add_before(bob)
-
-xml.write()

smartxml-1.0.1/src/smartXML.egg-info/PKG-INFO

@@ -1,45 +0,0 @@
-Metadata-Version: 2.4
-Name: smartXML
-Version: 1.0.1
-Summary: smartXML package enables you to read, search, manipulate, and write XML files with ease
-Author-email: Dudu Arbel <duduarbel@gmail.com>
-License-Expression: MIT
-Keywords: python,example
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-Requires-Dist: requests>=2.31
-Provides-Extra: dev
-Requires-Dist: pytest>=8.0; extra == "dev"
-Requires-Dist: mypy>=1.8; extra == "dev"
-Requires-Dist: ruff>=0.3; extra == "dev"
-
-# smartXML
-
-The **smartXML** package enables you to read, search, manipulate, and write XML files with ease.
-
-The API is designed to be as simple as possible, but it will be enhanced according to usage and requests.
-
----
-
-## Usage Example
-
-```python
-from pathlib import Path
-from smartxml import SmartXML, TextOnlyComment
-
-input_file = Path('./example.xml')
-xml = SmartXML(input_file)
-
-firstName = xml.find('students|student|firstName', with_content='Bob')
-bob = firstName.parent
-bob.comment_out()
-header = TextOnlyComment('Bob is out')
-header.add_before(bob)
-
-xml.write()