Merge branch 'dev' into f-new-debug-tree

src/caoscrawler/structure_elements.py → src/caoscrawler/structure_elements/structure_elements.py

@@ -23,16 +23,24 @@
 # ** end header
 #
 
-from typing import Dict as tDict
 import warnings
 
+import lxml.etree
+
 
 class StructureElement(object):
-    """ base class for elements in the hierarchical data structure """
+    """Base class for elements in the hierarchical data structure.
+
+Parameters
+----------
+
+name: str
+  The name of the StructureElement.  May be used for pattern matching by CFood rules.
+    """
 
-    def __init__(self, name):
+    def __init__(self, name: str):
         # Used to store usage information for debugging:
-        self.metadata: tDict[str, set[str]] = {
+        self.metadata: dict[str, set[str]] = {
             "usage": set()
         }
 
@@ -53,6 +61,18 @@ class StructureElement(object):
 
 
 class FileSystemStructureElement(StructureElement):
+    """StructureElement representing an element of a file system, like a directory or a simple file.
+
+Parameters
+----------
+
+name: str
+  The name of the StructureElement.  May be used for pattern matching by CFood rules.
+
+path: str
+  The path to the file or directory.
+    """
+
     def __init__(self, name: str, path: str):
         super().__init__(name)
         self.path = path
@@ -77,6 +97,7 @@ class Directory(FileSystemStructureElement):
 
 
 class File(FileSystemStructureElement):
+    """StrutureElement representing a file."""
     pass
 
 
@@ -170,3 +191,53 @@ class DictDictElement(DictElement):
     def __init__(self, *args, **kwargs):
         warnings.warn(DeprecationWarning("This class is depricated. Please use DictElement."))
         super().__init__(*args, **kwargs)
+
+
+class XMLTagElement(StructureElement):
+    """
+    Stores elements of an XML tree.
+    """
+
+    def __init__(self, element: lxml.etree.Element):
+        super().__init__(element.getroottree().getelementpath(element))
+        self.tag = element
+
+
+class XMLTextNode(StructureElement):
+    """
+    Stores text nodes of XML trees.
+    """
+
+    def __init__(self, element: lxml.etree.Element):
+        """
+        Initializes this XML text node.
+
+        Please note that, although syntactically similar, it is semantically
+        different from TextElement:
+        - TextElements have a meaningful name, e.g. a key in a key-value pair. This name can
+          be matched using the match_name entry.
+        - XMLTextNodes just have a text and the name is just for identifying the structure element.
+          They can only be matched using the match entry in the XMLTextNodeConverter.
+        """
+        super().__init__(element.getroottree().getelementpath(element) + "/text()")
+        self.tag = element
+        self.value = element.text
+
+
+class XMLAttributeNode(StructureElement):
+    """
+    Stores text nodes of XML trees.
+    """
+
+    def __init__(self, element: lxml.etree.Element,
+                 key: str):
+        """
+        Initializes this XML attribute node.
+
+        element: The xml tree element containing the attribute.
+        key: The key which identifies the attribute in the list of attributes.
+        """
+        super().__init__(element.getroottree().getelementpath(element) + "@" + key)
+        self.value = element.attrib[key]
+        self.key = key
+        self.tag = element

src/caoscrawler/version.py

@@ -17,13 +17,10 @@
 # You should have received a copy of the GNU Affero General Public License
 # along with this program. If not, see <https://www.gnu.org/licenses/>.
 #
-try:
 from importlib import metadata as importlib_metadata
-except ImportError:  # Python<3.8 dowesn"t support this so use
-    import importlib_metadata
+from warnings import warn
 
 from packaging.version import parse as parse_version
-from warnings import warn
 
 
 def get_caoscrawler_version():
@@ -43,7 +40,7 @@ def check_cfood_version(metadata: dict):
     if not metadata or "crawler-version" not in metadata:
 
         msg = """
-No crawler version specified in cfood definition, so there is now guarantee that
+No crawler version specified in cfood definition, so there is no guarantee that
 the cfood definition matches the installed crawler version.
 
 Specifying a version is highly recommended to ensure that the definition works

src/doc/getting_started/helloworld.md

@@ -33,7 +33,7 @@ Then you can do the following interactively in (I)Python. But we recommend that
 copy the code into a script and execute it to spare yourself typing.
 
 ```python
-import caosdb as db
+import linkahead as db
 from datetime import datetime
 from caoscrawler import Crawler, SecurityMode
 from caoscrawler.identifiable_adapters import CaosDBIdentifiableAdapter