django-gisserver 2.0__py3-none-any.whl → 2.1.1__py3-none-any.whl

gisserver/parsers/ast.py

@@ -3,17 +3,17 @@
 By transforming the XML Element nodes into Python objects, most logic naturally follows.
 For example, the FES filter syntax can be processed into objects that build an ORM query.
 
-Python classes can inherit :class:`BaseNode` and register themselves as the parser/handler
+Python classes can inherit :class:`AstNode` and register themselves as the parser/handler
 for a given tag. Both normal Python classes and dataclass work,
-as long as it has an :meth:`BaseNode.from_xml` class method.
-The custom `from_xml()` method should copy the XML data into local attributes.
+as long as it has an :meth:`AstNode.from_xml` class method.
+The custom ``from_xml()`` method should copy the XML data into local attributes.
 
 Next, when :meth:`TagRegistry.node_from_xml` is called,
 it will detect which class the XML Element refers to and initialize it using the ``from_xml()`` call.
-As convenience, calling :meth:`SomeNode.child_from_xml()` will also
-initialize the right subclass and initialize it.
+As convenience, calling a :meth:`AstNode.child_from_xml`
+on a subclass will also initialize the right subclass and initialize it.
 
-Since clients may not follow the desired XML schema, and make mistakes, one should avoid
+Since clients may not follow the desired XML schema, and make mistakes, we should guard against
 creating an invalid Abstract Syntax Tree. When using :meth:`TagRegistry.node_from_xml`,
 the allowed child types can also be provided, preventing invalid child elements.
 Furthermore, to support the creation of ``from_xml()`` methods, the :func:`expect_tag`,
@@ -27,15 +27,17 @@ from __future__ import annotations
 from collections.abc import Iterable
 from enum import Enum
 from functools import wraps
-from itertools import chain
 from typing import TypeVar
 from xml.etree.ElementTree import QName
 
-from gisserver.exceptions import ExternalParsingError
+from django.utils.functional import classproperty
+
+from gisserver.exceptions import InvalidXmlElement, XmlElementNotSupported
+from gisserver.parsers.xml import NSElement, xmlns
 
 __all__ = (
     "TagNameEnum",
-    "BaseNode",
+    "AstNode",
     "TagRegistry",
     "tag_registry",
     "expect_children",
@@ -43,11 +45,9 @@ __all__ = (
     "expect_no_children",
 )
 
-from gisserver.parsers.xml import NSElement, xmlns
-
 
 class TagNameEnum(Enum):
-    """An enumeration of XML tag names.
+    """An base clas for enumerations of XML tag names.
 
     All enumerations that represent tag names inherit from this.
     Each member name should be exactly the XML tag that it refers to.
@@ -55,7 +55,12 @@ class TagNameEnum(Enum):
 
     @classmethod
     def from_xml(cls, element: NSElement):
-        """Cast the element tag name into the enum member"""
+        """Cast the element tag name into the enum member.
+
+        This translates the element name
+        such as ``{http://www.opengis.net/fes/2.0}PropertyIsEqualTo``
+        into a ``PropertyIsEqualTo`` member.
+        """
         tag_name = element.tag
         if tag_name.startswith("{"):
             # Split the element tag into the namespace and local name.
@@ -74,7 +79,7 @@ class TagNameEnum(Enum):
         return f"{self.__class__.__name__}.{self.name}"
 
 
-class BaseNode:
+class AstNode:
     """The base node for all classes that represent an XML tag.
 
     All subclasses of this class build an Abstract Syntax Tree (AST)
@@ -85,24 +90,33 @@ class BaseNode:
     an XML tag into a Python (data) class.
     """
 
+    #: Default namespace of the element and subclasses, if not given by ``@tag_registry.register()``.
     xml_ns: xmlns | str | None = None
-    xml_tags = []
+
+    _xml_tags = []
+
+    @classproperty
+    def xml_name(cls) -> str:
+        """Tell the default tag by which this class is registered"""
+        return cls._xml_tags[0]
+
+    xml_name.__doc__ = "Tell the default tag by which this class is registered"
 
     def __init_subclass__(cls):
         # Each class level has a fresh list of supported child tags.
-        cls.xml_tags = []
+        cls._xml_tags = []
 
     @classmethod
     def from_xml(cls, element: NSElement):
         """Initialize this Python class from the data of the corresponding XML tag.
-        Each subclass overrides this to implement the XMl parsing of that particular XML tag.
+        Each subclass overrides this to implement the XML parsing of that particular XML tag.
         """
         raise NotImplementedError(
             f"{cls.__name__}.from_xml() is not implemented to parse <{element.tag}>"
         )
 
     @classmethod
-    def child_from_xml(cls, element: NSElement) -> BaseNode:
+    def child_from_xml(cls, element: NSElement) -> AstNode:
         """Parse the element, returning the correct subclass of this tag.
 
         When ``Expression.child_from_xml(some_node)`` is given, it may
@@ -112,12 +126,23 @@ class BaseNode:
         return sub_class.from_xml(element)
 
     @classmethod
-    def get_tag_names(cls) -> Iterable[str]:
-        """Provide all known XMl tags that this code can parse."""
-        return chain.from_iterable(sub_type.xml_tags for sub_type in cls.__subclasses__())
+    def get_tag_names(cls) -> list[str]:
+        """Provide all known XML tags that this code can parse."""
+        try:
+            # Because a cached class property is hard to build
+            return _KNOWN_TAG_NAMES[cls]
+        except KeyError:
+            all_xml_tags = cls._xml_tags.copy()
+            for sub_cls in cls.__subclasses__():
+                all_xml_tags.extend(sub_cls.get_tag_names())
+            _KNOWN_TAG_NAMES[cls] = all_xml_tags
+            return all_xml_tags
+
 
+_KNOWN_TAG_NAMES = {}
 
-BN = TypeVar("BN", bound=BaseNode)
+BaseNode = AstNode  # keep old name around
+A = TypeVar("A", bound=AstNode)
 
 
 class TagRegistry:
@@ -126,7 +151,7 @@ class TagRegistry:
     The same class can be registered multiple times for different tag names.
     """
 
-    parsers: dict[str, type[BaseNode]]
+    parsers: dict[str, type[AstNode]]
 
     def __init__(self):
         self.parsers = {}
@@ -141,9 +166,11 @@ class TagRegistry:
 
         Usage:
 
+        .. code-block:: python
+
             @dataclass
             @tag_registry.register()
-            class SomeXmlTag(BaseNode):
+            class SomeXmlTag(AstNode):
                 xml_ns = FES
 
                 @classmethod
@@ -159,7 +186,7 @@ class TagRegistry:
         each member name is assumed to be an XML tag name.
         """
 
-        def _dec(node_class: type[BaseNode]) -> type[BaseNode]:
+        def _dec(node_class: type[AstNode]) -> type[AstNode]:
             if tag is None or isinstance(tag, str):
                 # Single tag name for the class.
                 self._register_tag_parser(
@@ -170,7 +197,9 @@ class TagRegistry:
                 # Note using __members__, not _member_names_.
                 # The latter will skip aliased items (like BBOX/Within).
                 for member_name in tag.__members__:
-                    self._register_tag_parser(node_class, tag=member_name, namespace=namespace)
+                    self._register_tag_parser(
+                        node_class, tag=member_name, namespace=namespace, hidden=hidden
+                    )
             else:
                 raise TypeError("tag type incorrect")
 
@@ -180,14 +209,14 @@ class TagRegistry:
 
     def _register_tag_parser(
         self,
-        node_class: type[BaseNode],
+        node_class: type[AstNode],
         tag: str,
         namespace: xmlns | str | None = None,
         hidden: bool = False,
     ):
         """Register a Python (data) class as parser for an XML node."""
-        if not issubclass(node_class, BaseNode):
-            raise TypeError(f"{node_class} must be a subclass of BaseNode")
+        if not issubclass(node_class, AstNode):
+            raise TypeError(f"{node_class} must be a subclass of AstNode")
 
         if namespace is None and node_class.xml_ns is None:
             raise RuntimeError(
@@ -202,49 +231,46 @@ class TagRegistry:
 
         self.parsers[xml_name] = node_class  # Track this parser to resolve the tag.
         if not hidden:
-            node_class.xml_tags.append(xml_name)  # Allow fetching all names later
+            node_class._xml_tags.append(xml_name)  # Allow fetching all names later
 
-    def node_from_xml(
-        self, element: NSElement, allowed_types: tuple[type[BN]] | None = None
-    ) -> BN:
-        """Find the ``BaseNode`` subclass that corresponds to the given XML element,
+    def node_from_xml(self, element: NSElement, allowed_types: tuple[type[A]] | None = None) -> A:
+        """Find the ``AstNode`` subclass that corresponds to the given XML element,
         and initialize it with the element. This is a convenience shortcut.
-        ``"""
+        """
         node_class = self.resolve_class(element, allowed_types)
         return node_class.from_xml(element)
 
     def resolve_class(
-        self, element: NSElement, allowed_types: tuple[type[BN]] | None = None
-    ) -> type[BN]:
-        """Find the ``BaseNode`` subclass that corresponds to the given XML element."""
+        self, element: NSElement, allowed_types: tuple[type[A]] | None = None
+    ) -> type[A]:
+        """Find the :class:`AstNode` subclass that corresponds to the given XML element."""
         try:
             node_class = self.parsers[element.tag]
         except KeyError:
-            msg = f"Unsupported tag: <{element.tag}>"
+            msg = f"Unsupported tag: <{element.qname}>"
             if "{" not in element.tag:
                 msg = f"{msg} without an XML namespace"
             if allowed_types:
-                # Show better exception message
-                types = ", ".join(chain.from_iterable(c.get_tag_names() for c in allowed_types))
-                msg = f"{msg}, expected one of: {types}"
+                allowed = _tag_names_to_text(_get_allowed_tag_names(*allowed_types), element)
+                msg = f"{msg}, expected one of: {allowed}."
 
-            raise ExternalParsingError(msg) from None
+            raise XmlElementNotSupported(msg) from None
 
         # Check whether the resolved class is indeed a valid option here.
         if allowed_types is not None and not issubclass(node_class, allowed_types):
             types = ", ".join(c.__name__ for c in allowed_types)
-            raise ExternalParsingError(
-                f"Unexpected {node_class.__name__} for <{element.tag}> node, "
+            raise InvalidXmlElement(
+                f"Unexpected {node_class.__name__} for <{element.qname}> node, "
                 f"expected one of: {types}"
             )
 
         return node_class
 
-    def get_parser_class(self, xml_qname) -> type[BaseNode]:
+    def get_parser_class(self, xml_qname) -> type[AstNode]:
         """Provide the parser class for a given XML Qualified name."""
         return self.parsers[xml_qname]
 
-    def find_subclasses(self, node_type: type[BN]) -> list[type[BN]]:
+    def find_subclasses(self, node_type: type[A]) -> list[type[A]]:
         """Find all registered parsers for a given node."""
         return {
             tag: node_class
@@ -254,7 +280,19 @@ class TagRegistry:
 
 
 def expect_tag(namespace: xmlns | str, *tag_names: str):
-    """Validate whether a given tag is need."""
+    """Decorator for ``from_xml()`` methods that validate whether a given tag is provided.
+
+    For example:
+
+    .. code-block:: python
+
+        @classmethod
+        @expect_tag(xmlns.fes20, "Literal")
+        def from_xml(cls, element):
+            ...
+
+    This guard is needed when nodes are passed directly to a ``from_xml()`` method.
+    """
     valid_tags = {QName(namespace, name).text for name in tag_names}
     expect0 = QName(namespace, tag_names[0]).text
 
@@ -262,8 +300,9 @@ def expect_tag(namespace: xmlns | str, *tag_names: str):
         @wraps(func)
         def _expect_tag_decorator(cls, element: NSElement, *args, **kwargs):
             if element.tag not in valid_tags:
-                raise ExternalParsingError(
-                    f"{cls.__name__} parser expects an <{expect0}> node, got <{element.tag}>"
+                raise InvalidXmlElement(
+                    f"{cls.__name__} parser expects an <{_replace_common_ns(expect0, element)}> node,"
+                    f" got <{element.qname}>"
                 )
             return func(cls, element, *args, **kwargs)
 
@@ -273,13 +312,25 @@ def expect_tag(namespace: xmlns | str, *tag_names: str):
 
 
 def expect_no_children(from_xml_func):
-    """Validate that the XML tag has no child nodes."""
+    """Decorator for ``from_xml()`` methods that validate that the XML tag has no child nodes.
+
+    For example:
+
+    .. code-block:: python
+
+        @classmethod
+        @expect_tag(xmlns.fes20, "ResourceId")
+        @expect_no_children
+        def from_xml(cls, element):
+            ...
+    """
 
     @wraps(from_xml_func)
     def _expect_no_children_decorator(cls, element: NSElement, *args, **kwargs):
         if len(element):
-            raise ExternalParsingError(
-                f"Unsupported child element for {element.tag} element: {element[0].tag}."
+            raise InvalidXmlElement(
+                f"Element <{element.qname}> does not support child elements,"
+                f" found <{element[0].qname}>."
             )
 
         return from_xml_func(cls, element, *args, **kwargs)
@@ -287,28 +338,53 @@ def expect_no_children(from_xml_func):
     return _expect_no_children_decorator
 
 
-def expect_children(min_child_nodes, *expect_types: str | type[BaseNode]):
-    """Validate whether an element has enough children to continue parsing."""
-    known_tag_names = set()
-    for child_type in expect_types:
-        if isinstance(child_type, type) and issubclass(child_type, BaseNode):
-            known_tag_names.update(child_type.get_tag_names())
-        elif isinstance(child_type, str):
-            known_tag_names.add(child_type)
-        else:
+def expect_children(  # noqa: C901
+    min_child_nodes, *expect_types: str | type[AstNode], silent_allowed: tuple[str] = ()
+):
+    """Decorator for ``from_xml()`` methods to validate whether an element has the expected children.
+
+    For example:
+
+    .. code-block:: python
+
+        @classmethod
+        @expect_children(2, Expression)
+        def from_xml(cls, element):
+            ...
+    """
+    # Validate arguments early
+    for child_type in expect_types + silent_allowed:
+        if isinstance(child_type, str):
+            if not child_type.startswith("{"):
+                raise ValueError(
+                    f"String arguments to @expect_children() should be"
+                    f" fully qualified XML namespaces, not {child_type!r}"
+                )
+        elif not isinstance(child_type, type) or not issubclass(child_type, AstNode):
             raise TypeError(f"Unexpected {child_type!r}")
-    known_tag_names = sorted(known_tag_names)
+
+    def _get_allowed(known_tag_names, element):
+        return _tag_names_to_text(sorted(set(known_tag_names) - set(silent_allowed)), element)
 
     def _wrapper(func):
         @wraps(func)
         def _expect_children_decorator(cls, element: NSElement, *args, **kwargs):
+            known_tag_names = _get_allowed_tag_names(*expect_types, *silent_allowed)
+
             if len(element) < min_child_nodes:
-                type_names = ", ".join(known_tag_names)
-                suffix = f" (possible tags: {type_names})" if type_names else ""
-                raise ExternalParsingError(
-                    f"<{element.tag}> should have {min_child_nodes} child nodes, "
-                    f"got {len(element)}{suffix}"
+                allowed = _get_allowed(known_tag_names, element)
+                raise InvalidXmlElement(
+                    f"<{element.qname}> should have {min_child_nodes} child nodes,"
+                    f" got only {len(element)}."
+                    f" Allowed types are: {allowed}."
                 )
+            for child in element:
+                if child.tag not in known_tag_names:
+                    allowed = _get_allowed(known_tag_names, element)
+                    raise InvalidXmlElement(
+                        f"<{element.qname}> does not support a <{child.qname}> child node."
+                        f" Allowed types are: {allowed}."
+                    )
 
             return func(cls, element, *args, **kwargs)
 
@@ -317,4 +393,37 @@ def expect_children(min_child_nodes, *expect_types: str | type[BaseNode]):
     return _wrapper
 
 
+def _get_allowed_tag_names(*expect_types: type[AstNode] | str) -> list[str]:
+    # Resolve arguments later, as get_tag_names() depends on __subclasses__()
+    # which may not be completely known at this point.
+    tag_names = []
+    for child_type in expect_types:
+        if isinstance(child_type, type) and issubclass(child_type, AstNode):
+            tag_names.extend(child_type.get_tag_names())
+        elif isinstance(child_type, str):
+            if not child_type.startswith("{"):
+                raise ValueError(
+                    f"String arguments should be fully qualified XML namespaces, not {child_type!r}"
+                )
+            tag_names.append(child_type)
+        else:
+            raise TypeError(f"Unexpected {child_type!r}")
+    return tag_names
+
+
+def _tag_names_to_text(tag_names: Iterable[str], user_element: NSElement) -> str:
+    body = _replace_common_ns(">, <".join(tag_names), user_element)
+    return f"<{body}>"
+
+
+def _replace_common_ns(text: str, user_element: NSElement):
+    """In error messages, replace the full XML names with QName/prefixed versions.
+    The chosen prefixes reference the tags that the client submitted in their XML body.
+    """
+    for prefix, ns in user_element.ns_aliases.items():
+        text = text.replace(f"{{{ns}}}", f"{prefix}:")
+    return text
+
+
+#: The tag registry to register new parsing classes at.
 tag_registry = TagRegistry()

gisserver/parsers/fes20/__init__.py

@@ -13,16 +13,88 @@ can be very helpful to see which options each object type should support.
 from __future__ import annotations
 
 from . import lookups  # noqa: F401 (need to register ORM lookups)
-from .expressions import ValueReference
+from .expressions import (
+    BinaryOperator,
+    BinaryOperatorType,
+    Expression,
+    Function,
+    Literal,
+    ValueReference,
+)
 from .filters import Filter
-from .identifiers import ResourceId
-from .operators import IdOperator
-from .sorting import SortBy
+from .identifiers import Id, ResourceId, VersionActionTokens
+from .operators import (
+    BetweenComparisonOperator,
+    BinaryComparisonName,
+    BinaryComparisonOperator,
+    BinaryLogicOperator,
+    BinaryLogicType,
+    BinarySpatialOperator,
+    ComparisonOperator,
+    DistanceOperator,
+    DistanceOperatorName,
+    ExtensionOperator,
+    IdOperator,
+    LikeOperator,
+    LogicalOperator,
+    MatchAction,
+    Measure,
+    NilOperator,
+    NonIdOperator,
+    NullOperator,
+    Operator,
+    SpatialOperator,
+    SpatialOperatorName,
+    TemporalOperator,
+    TemporalOperatorName,
+    UnaryLogicOperator,
+    UnaryLogicType,
+)
+from .sorting import SortBy, SortOrder, SortProperty
 
 __all__ = [
     "Filter",
+    # Expressions
+    "Expression",
+    "Function",
+    "Literal",
     "ValueReference",
+    # WFS 1.0 expressions
+    "BinaryOperator",
+    "BinaryOperatorType",
+    # Identifiers
+    "Id",
     "ResourceId",
+    "VersionActionTokens",
+    # Operators
+    "BetweenComparisonOperator",
+    "BinaryComparisonName",
+    "BinaryComparisonOperator",
+    "BinaryLogicOperator",
+    "BinaryLogicType",
+    "BinarySpatialOperator",
+    "ComparisonOperator",
+    "DistanceOperator",
+    "DistanceOperatorName",
+    "ExtensionOperator",
     "IdOperator",
+    "LikeOperator",
+    "LogicalOperator",
+    "MatchAction",
+    "Measure",
+    "NilOperator",
+    "NonIdOperator",
+    "NullOperator",
+    "Operator",
+    "SpatialOperator",
+    "SpatialOperatorName",
+    "TemporalOperator",
+    "TemporalOperatorName",
+    "UnaryLogicOperator",
+    "UnaryLogicType",
+    # Sorting
+    "SortBy",
+    "SortOrder",
+    "SortProperty",
     "SortBy",
 ]