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

gisserver/parsers/fes20/operators.py

@@ -4,59 +4,56 @@ The class names and attributes are identical to those in the FES spec.
 
 from __future__ import annotations
 
+import logging
 import operator
 from dataclasses import dataclass, field
 from decimal import Decimal
 from enum import Enum
 from functools import cached_property, reduce
 from itertools import groupby
-from typing import Any, Union
-from xml.etree.ElementTree import Element, QName
+from typing import ClassVar, Protocol, Union
 
-from django.conf import settings
 from django.contrib.gis import measure
 from django.db.models import Q
 
-from gisserver.exceptions import ExternalParsingError, OperationProcessingFailed
+from gisserver.exceptions import (
+    ExternalParsingError,
+    InvalidParameterValue,
+    OperationProcessingFailed,
+)
 from gisserver.parsers import gml
-from gisserver.parsers.base import BaseNode, TagNameEnum, tag_registry
-from gisserver.parsers.tags import expect_children, expect_tag, get_attribute, get_child
-from gisserver.types import FES20
-
-from .expressions import Expression, Literal, RhsTypes, ValueReference
+from gisserver.parsers.ast import (
+    BaseNode,
+    TagNameEnum,
+    expect_children,
+    expect_tag,
+    tag_registry,
+)
+from gisserver.parsers.query import CompiledQuery, RhsTypes
+from gisserver.parsers.values import fix_type_name
+from gisserver.parsers.xml import NSElement, xmlns
+from gisserver.types import GeometryXsdElement, XPathMatch
+
+from .expressions import Expression, Literal, ValueReference
 from .identifiers import Id
-from .query import CompiledQuery
+from .lookups import ARRAY_LOOKUPS  # also registers the lookups.
+
+logger = logging.getLogger(__name__)
 
 SpatialDescription = Union[gml.GM_Object, gml.GM_Envelope, ValueReference]
 TemporalOperand = Union[gml.TM_Object, ValueReference]
 
+# Fully qualified tag names
+FES_VALUE_REFERENCE = xmlns.fes20.qname("ValueReference")
+FES_DISTANCE = xmlns.fes20.qname("Distance")
+FES_LOWER_BOUNDARY = xmlns.fes20.qname("LowerBoundary")
+FES_UPPER_BOUNDARY = xmlns.fes20.qname("UpperBoundary")
 
-# Define interface for any class that has "build_rhs()"
-try:
-    from typing import Protocol
-except ImportError:
-    HasBuildRhs = Any  # Python 3.7 and below
-else:
-
-    class HasBuildRhs(Protocol):
-        def build_rhs(self, compiler) -> RhsTypes: ...
 
+class HasBuildRhs(Protocol):
+    """Define interface for any class that has ``build_rhs()``."""
 
-if "django.contrib.postgres" in settings.INSTALLED_APPS:
-    # Comparisons with array fields go through a separate ORM lookup expression,
-    # so these can check whether ANY element matches in the array.
-    # This gives consistency between other repeated elements (e.g. M2M, reverse FK)
-    # where the whole object is returned when one of the sub-objects match.
-    ARRAY_LOOKUPS = {
-        "exact": "fes_anyexact",
-        "fes_notequal": "fes_anynotequal",
-        "lt": "fes_anylt",
-        "lte": "fes_anylte",
-        "gt": "fes_anygt",
-        "gte": "fes_anygte",
-    }
-else:
-    ARRAY_LOOKUPS = None
+    def build_rhs(self, compiler) -> RhsTypes: ...
 
 
 class MatchAction(Enum):
@@ -73,7 +70,7 @@ class MatchAction(Enum):
 
 class BinaryComparisonName(TagNameEnum):
     """XML tag names for value comparisons.
-    Values are the used field lookup.
+    This also maps their names to ORM field lookups.
     """
 
     PropertyIsEqualTo = "exact"
@@ -85,14 +82,14 @@ class BinaryComparisonName(TagNameEnum):
 
 
 class DistanceOperatorName(TagNameEnum):
-    """XML tag names for distance operators"""
+    """XML tag names mapped to distance operators for the ORM."""
 
     Beyond = "fes_beyond"  # using __distance_gt=.. would be slower.
     DWithin = "dwithin"  # ST_DWithin uses indices, distance_lte does not.
 
 
 class SpatialOperatorName(TagNameEnum):
-    """XML tag names for geometry operators.
+    """XML tag names mapped to geometry operators.
 
     The values correspond with GeoDjango operators. So a ``BBOX`` query
     will translate into ``geometry__intersects=Polygon(...)``.
@@ -103,18 +100,18 @@ class SpatialOperatorName(TagNameEnum):
     # BBOX can either be implemented using bboverlaps (more efficient), or the
     # more correct "intersects" option (e.g. a line near the box would match otherwise).
     BBOX = "intersects"  # ISO version: "NOT DISJOINT"
-    Equals = "equals"  # Test whether t geometries are topologically equal
+    Equals = "equals"  # Test whether two geometries are topologically equal
     Disjoint = "disjoint"  # Tests whether two geometries are disjoint (do not interact)
     Intersects = "intersects"  # Tests whether two geometries intersect
-    Touches = "touches"  # Tests whether two geometries touch
-    Crosses = "crosses"  # Tests whether two geometries cross
-    Within = "within"  # Tests whether a geometry is within another one
-    Contains = "contains"  # Tests whether a geometry contains another one
+    Touches = "touches"  # Tests whether two geometries touch (e.g. country border).
+    Crosses = "crosses"  # Tests whether two geometries cross (e.g. two streets).
+    Within = "within"  # Tests a geometry is within another one (e.g. city within province).
+    Contains = "contains"  # Tests a geometry contains another one (e.g. province contains city).
     Overlaps = "overlaps"  # Test whether two geometries overlap
 
 
 class TemporalOperatorName(TagNameEnum):
-    """XML tag names for datetime operators.
+    """XML tag names mapped to datetime operators.
 
     Explanation here: http://old.geotools.org/Temporal-Filters_211091519.html
     and: https://github.com/geotools/geotools/wiki/temporal-filters
@@ -150,26 +147,44 @@ class UnaryLogicType(TagNameEnum):
 
 @dataclass
 class Measure(BaseNode):
-    """The <fes:Distance uom="...> element."""
+    """A measurement for a distance element.
 
-    xml_ns = FES20
+    This parses and handles the syntax::
+
+        <fes:Distance uom="...">value</fes:Distance>
+
+    This element is used within the :class:`DistanceOperator` that
+    handles the ``<fes:DWithin>`` and ``<fes:Beyond>`` tags.
+
+    The "unit of measurement" (uom) supports most standard units, like meters (``m``),
+    kilometers (``km``), nautical mile (``nm``), miles (``mi``), inches (``inch``).
+    The full list can be found at: https://docs.djangoproject.com/en/5.1/ref/contrib/gis/measure/#supported-units
+    """
+
+    xml_ns = xmlns.fes20
 
     value: Decimal
     uom: str  # Unit of measurement, fes20:UomSymbol | fes20:UomURI
 
     @classmethod
-    @expect_tag(FES20, "Distance")
-    def from_xml(cls, element: Element):
-        return cls(value=Decimal(element.text), uom=get_attribute(element, "uom"))
+    @expect_tag(xmlns.fes20, "Distance")
+    def from_xml(cls, element: NSElement):
+        return cls(value=Decimal(element.text), uom=element.get_str_attribute("uom"))
 
     def build_rhs(self, compiler) -> measure.Distance:
         return measure.Distance(default_unit=self.uom, **{self.uom: self.value})
 
 
 class Operator(BaseNode):
-    """Abstract base class, as defined by FES spec."""
+    """Abstract base class, as defined by FES spec.
 
-    xml_ns = FES20
+    This base class is also used in parsing; for example the ``<fes:Filter>``
+    tag only allows ``Operator`` and ``Expression`` subclasses as allowed arguments.
+    Having all those classes as Python types, makes it very easy to validate
+    whether a given child element is the expected node type.
+    """
+
+    xml_ns = xmlns.fes20
 
     def build_query(self, compiler: CompiledQuery) -> Q | None:
         raise NotImplementedError(f"Using {self.__class__.__name__} is not supported yet.")
@@ -181,8 +196,7 @@ class IdOperator(Operator):
 
     id: list[Id]
 
-    @property
-    def type_names(self) -> list[str]:
+    def get_type_names(self) -> list[str]:
         """Provide a list of all type names accessed by this operator"""
         return [type_name for type_name in self.grouped_ids if type_name is not None]
 
@@ -192,7 +206,7 @@ class IdOperator(Operator):
         ids = sorted(self.id, key=operator.attrgetter("rid"))
         return {
             type_name: list(items)
-            for type_name, items in groupby(ids, key=operator.attrgetter("type_name"))
+            for type_name, items in groupby(ids, key=lambda id: id.get_type_name())
         }
 
     def build_query(self, compiler):
@@ -207,8 +221,20 @@ class IdOperator(Operator):
             compiler.mark_empty()
             return
 
+        type_names = {ft.xml_name for ft in compiler.feature_types}
         for type_name, items in self.grouped_ids.items():
-            ids_subset = reduce(operator.or_, [id.build_query(compiler=None) for id in items])
+            type_name = fix_type_name(type_name, compiler.feature_types[0].xml_namespace)
+            if type_name not in type_names:
+                # When ResourceId + typenames is defined, it should be a value from typenames see WFS spec 7.9.2.4.1
+                # This is tested here for RESOURCEID with a typename.id format.
+                # Otherwise, this breaks the CITE RESOURCEID=test-UUID parameter.
+                raise InvalidParameterValue(
+                    "When TYPENAMES and RESOURCEID are combined, "
+                    "the RESOURCEID type should be included in TYPENAMES.",
+                    locator="resourceId",
+                )
+
+            ids_subset = reduce(operator.or_, [id.build_query(compiler) for id in items])
             compiler.add_lookups(ids_subset, type_name=type_name)
 
 
@@ -217,9 +243,13 @@ class NonIdOperator(Operator):
 
     This is used for nearly all operators,
     except those that have <fes:ResourceId> elements as children.
+
+    Some operators, such as the ``<fes:And>``, ``<fes:Or>`` and ``<fes:Not>`` operators
+    explicitly support only ``NonIdOperator`` elements as arguments.
+    Hence, having this base class as Python type simplifies parsing.
     """
 
-    _source = None
+    _source = None  # often declared as non-comparing in dataclasses below.
     allow_geometries = False
 
     def build_compare(
@@ -238,7 +268,7 @@ class NonIdOperator(Operator):
         if isinstance(lhs, Literal) and isinstance(rhs, ValueReference):
             lhs, rhs = rhs, lhs
 
-        if compiler.feature_type is not None:
+        if compiler.feature_types:
             lookup = self.validate_comparison(compiler, lhs, lookup, rhs)
 
         # Build Django Q-object
@@ -255,17 +285,27 @@ class NonIdOperator(Operator):
         compiler: CompiledQuery,
         lhs: Expression,
         lookup: str,
-        rhs: Expression | RhsTypes,
+        rhs: Expression | gml.GM_Object | RhsTypes,
     ):
         """Validate whether a given comparison is even possible.
-        Where needed, the lhs/rhs are already ordered in a logical sequence.
+
+        For example, comparisons like ``name == "test"`` are fine,
+        but ``geometry < 4`` or ``datefield == 35.2" raise an error.
+
+        The lhs/rhs are expected to be ordered in a logical sequence.
+        So ``<value> == <element>`` should be provided as ``<element> == <value>``.
+
+        :param compiler: The object that holds the intermediate state
+        :param lhs: The left-hand-side of the comparison (e.g. the element).
+        :param lookup: The ORM lookup expression being used (e.g. ``equals`` or ``fes_like``).
+        :param rhs: The right-hand-side of the comparison (e.g. the value).
         """
         if isinstance(lhs, ValueReference):
-            xsd_element = compiler.feature_type.resolve_element(lhs.xpath).child
+            xsd_element = lhs.parse_xpath(compiler.feature_types).child
             tag = self._source if self._source is not None else None
 
             # e.g. deny <PropertyIsLessThanOrEqualTo> against <gml:boundedBy>
-            if xsd_element.is_geometry and not self.allow_geometries:
+            if xsd_element.type.is_geometry and not self.allow_geometries:
                 raise OperationProcessingFailed(
                     f"Operator '{tag}' does not support comparing"
                     f" geometry properties: '{xsd_element.xml_name}'.",
@@ -273,29 +313,30 @@ class NonIdOperator(Operator):
                     status_code=400,  # not HTTP 500 here. Spec allows both.
                 )
 
-            if isinstance(rhs, Literal):
-                # Since the element is resolved, inform the Literal how to parse the value.
-                # This avoids various validation errors along the path.
-                rhs.bind_type(xsd_element.type)
-
-                # When a common case of value comparison is done, the inputs
-                # can be validated before the ORM query is constructed.
-                xsd_element.validate_comparison(rhs.raw_value, lookup=lookup, tag=tag)
-
             # Checking scalar values against array fields will fail.
             # However, to make the queries consistent with other unbounded types (i.e. M2M fields),
             # it makes sense to return an object when *one* entry in the array matches.
             if xsd_element.is_array:
                 try:
-                    return ARRAY_LOOKUPS[lookup]
+                    lookup = ARRAY_LOOKUPS[lookup]
                 except KeyError:
+                    logger.debug("No array lookup known for %s", lookup)
                     raise OperationProcessingFailed(
-                        "filter",
                         f"Operator '{tag}' is not supported for "
                         f"the '{xsd_element.name}' property.",
+                        locator="filter",
                         status_code=400,  # not HTTP 500 here. Spec allows both.
                     ) from None
 
+            if isinstance(rhs, Literal):
+                # Since the element is resolved, inform the Literal how to parse the value.
+                # This avoids various validation errors along the path.
+                rhs.bind_type(xsd_element.type)
+
+                # When a common case of value comparison is done, the inputs
+                # can be validated before the ORM query is constructed.
+                xsd_element.validate_comparison(rhs.raw_value, lookup=lookup, tag=tag)
+
         return lookup
 
     def build_compare_between(
@@ -303,10 +344,10 @@ class NonIdOperator(Operator):
         compiler: CompiledQuery,
         lhs: Expression,
         lookup: str,
-        rhs: tuple[HasBuildRhs, HasBuildRhs],
+        rhs: tuple[Expression | ValueReference | gml.GM_Object, Expression | Measure],
     ) -> Q:
         """Use the value in comparison with 2 other values (e.g. between query)"""
-        if compiler.feature_type is not None:
+        if compiler.feature_types:
             self.validate_comparison(compiler, lhs, lookup, rhs[0])
             self.validate_comparison(compiler, lhs, lookup, rhs[1])
 
@@ -327,9 +368,21 @@ class SpatialOperator(NonIdOperator):
 
 
 @dataclass
-@tag_registry.register_names(DistanceOperatorName)  # <Beyond>, <DWithin>
+@tag_registry.register("Beyond")
+@tag_registry.register("DWithin")
 class DistanceOperator(SpatialOperator):
-    """Comparing the distance to a geometry."""
+    """Comparing the distance to a geometry.
+
+    This parses and handles the syntax::
+
+        <fes:DWithin>
+            <fes:ValueReference>geometry</fes:ValueReference>
+            <gml:Point srsDimension="2">
+                <gml:pos>43.55749 1.525864</gml:pos>
+            </gml:Point>
+            <fes:Distance oum="m:>100</fes:Distance>
+        </fes:DWithin>
+    """
 
     allow_geometries = True  # override static attribute
 
@@ -341,7 +394,7 @@ class DistanceOperator(SpatialOperator):
 
     @classmethod
     @expect_children(3, ValueReference, gml.GM_Object, Measure)
-    def from_xml(cls, element: Element):
+    def from_xml(cls, element: NSElement):
         geometries = gml.find_gml_nodes(element)
         if not geometries:
             raise ExternalParsingError(f"Missing gml element in <{element.tag}>")
@@ -349,10 +402,10 @@ class DistanceOperator(SpatialOperator):
             raise ExternalParsingError(f"Multiple gml elements found in <{element.tag}>")
 
         return cls(
-            valueReference=ValueReference.from_xml(get_child(element, FES20, "ValueReference")),
+            valueReference=ValueReference.from_xml(element.find(FES_VALUE_REFERENCE)),
             operatorType=DistanceOperatorName.from_xml(element),
             geometry=gml.parse_gml_node(geometries[0]),
-            distance=Measure.from_xml(get_child(element, FES20, "Distance")),
+            distance=Measure.from_xml(element.find(FES_DISTANCE)),
             _source=element.tag,
         )
 
@@ -366,9 +419,23 @@ class DistanceOperator(SpatialOperator):
 
 
 @dataclass
-@tag_registry.register_names(SpatialOperatorName)  # <BBOX>, <Equals>, ...
+@tag_registry.register(SpatialOperatorName)  # <BBOX>, <Equals>, ...
 class BinarySpatialOperator(SpatialOperator):
-    """A comparison of geometries using 2 values, e.g. A Within B."""
+    """A comparison of geometries using 2 values, e.g. A Within B.
+
+    This parses and handles the syntax, and its variants::
+
+        <fes:BBOX>
+            <fes:ValueReference>Geometry</fes:ValueReference>
+            <gml:Envelope srsName="http://www.opengis.net/def/crs/epsg/0/4326">
+                <gml:lowerCorner>13.0983 31.5899</gml:lowerCorner>
+                <gml:upperCorner>35.5472 42.8143</gml:upperCorner>
+            </gml:Envelope>
+        </fes:BBOX>
+
+    It also handles the ``<fes:Equals>``, ``<fes:Within>``, ``<fes:Intersects>``, etc..
+    that exist in the :class:`SpatialOperatorName` enum.
+    """
 
     allow_geometries = True  # override static attribute
 
@@ -378,7 +445,7 @@ class BinarySpatialOperator(SpatialOperator):
     _source: str | None = field(compare=False, default=None)
 
     @classmethod
-    def from_xml(cls, element: Element):
+    def from_xml(cls, element: NSElement):
         operator_type = SpatialOperatorName.from_xml(element)
         if operator_type is SpatialOperatorName.BBOX and len(element) == 1:
             # For BBOX, the geometry operator is optional
@@ -392,16 +459,15 @@ class BinarySpatialOperator(SpatialOperator):
         return cls(
             operatorType=operator_type,
             operand1=ValueReference.from_xml(ref) if ref is not None else None,
-            operand2=tag_registry.from_child_xml(
-                geo, allowed_types=SpatialDescription.__args__  # get_args() in 3.8
-            ),
+            operand2=tag_registry.node_from_xml(geo, allowed_types=SpatialDescription.__args__),
             _source=element.tag,
         )
 
     def build_query(self, compiler: CompiledQuery) -> Q:
         operant1 = self.operand1
         if operant1 is None:
-            operant1 = ValueReference(xpath=compiler.feature_type.geometry_field.name)
+            # BBOX element points to the existing geometry element by default.
+            operant1 = _ResolvedValueReference(compiler.feature_types[0].main_geometry_element)
 
         return self.build_compare(
             compiler,
@@ -411,10 +477,61 @@ class BinarySpatialOperator(SpatialOperator):
         )
 
 
+class _ResolvedValueReference(ValueReference):
+    """Internal ValueReference subclass that already knows which element it resolve to.
+    This avoids translating back and forth between an XPath path and the desired node.
+    """
+
+    def __init__(self, geo_element: GeometryXsdElement):
+        self.xpath = f"(mocked {geo_element.orm_path})"  # keep __str__ and __repr__ happy.
+        self.xpath_ns_aliases = {}
+        self.geo_element = geo_element
+        self.orm_path = geo_element.orm_path
+
+    def parse_xpath(
+        self, feature_types: list, ns_aliases: dict[str, str] | None = None
+    ) -> XPathMatch:
+        return XPathMatch(feature_types[0], [self.geo_element], query="")
+
+    def build_lhs(self, compiler: CompiledQuery):
+        return self.orm_path
+
+
 @dataclass
-@tag_registry.register_names(TemporalOperatorName)  # <After>, <Before>, ...
+@tag_registry.register(TemporalOperatorName)  # <After>, <Before>, ...
 class TemporalOperator(NonIdOperator):
-    """Comparisons with dates"""
+    """Comparisons with dates.
+
+    For these operators, only the parsing is implemented.
+    These are not translated into ORM queries yet.
+
+    It supports a syntax such as::
+
+       <fes:TEquals>
+          <fes:ValueReference>SimpleTrajectory/gml:validTime/gml:TimeInstant</fes:ValueReference>
+          <gml:TimeInstant gml:id="TI1">
+             <gml:timePosition>2005-05-19T09:28:40Z</gml:timePosition>
+          </gml:TimeInstant>
+       </fes:TEquals>
+
+    or::
+
+       <fes:During>
+          <fes:ValueReference>SimpleTrajectory/gml:validTime/gml:TimeInstant</fes:ValueReference>
+          <gml:TimePeriod gml:id="TP1">
+             <gml:begin>
+                <gml:TimeInstant gml:id="TI1">
+                   <gml:timePosition>2005-05-17T00:00:00Z</gml:timePosition>
+                </gml:TimeInstant>
+             </gml:begin>
+             <gml:end>
+                <gml:TimeInstant gml:id="TI2">
+                   <gml:timePosition>2005-05-23T00:00:00Z</gml:timePosition>
+                </gml:TimeInstant>
+             </gml:end>
+          </gml:TimePeriod>
+       </fes:During>
+    """
 
     operatorType: TemporalOperatorName
     operand1: ValueReference
@@ -422,20 +539,23 @@ class TemporalOperator(NonIdOperator):
     _source: str | None = field(compare=False, default=None)
 
     @classmethod
-    @expect_children(2, ValueReference, TemporalOperand)
-    def from_xml(cls, element: Element):
+    @expect_children(2, ValueReference, *TemporalOperand.__args__)
+    def from_xml(cls, element: NSElement):
         return cls(
             operatorType=TemporalOperatorName.from_xml(element),
             operand1=ValueReference.from_xml(element[0]),
-            operand2=tag_registry.from_child_xml(
-                element[1], allowed_types=TemporalOperand.__args__  # get_args() in 3.8
+            operand2=tag_registry.node_from_xml(
+                element[1], allowed_types=TemporalOperand.__args__
             ),
             _source=element.tag,
         )
 
 
 class ComparisonOperator(NonIdOperator):
-    """Base class for comparisons"""
+    """Base class for comparisons.
+    This class name mirrors the fes-spec name,
+    and allows grouping various comparisons together.
+    """
 
     # Start counting fresh here, to collect the capabilities
     # that are listed in the <fes20:ComparisonOperators> node:
@@ -443,9 +563,23 @@ class ComparisonOperator(NonIdOperator):
 
 
 @dataclass
-@tag_registry.register_names(BinaryComparisonName)  # <PropertyIs...>
+@tag_registry.register(BinaryComparisonName)  # <PropertyIs...>
 class BinaryComparisonOperator(ComparisonOperator):
-    """A comparison between 2 values, e.g. A == B."""
+    """A comparison between 2 values, e.g. A == B.
+
+    This parses and handles the syntax::
+
+        <fes:PropertyIsEqualTo>
+            <fes:ValueReference>city/name</fes:ValueReference>
+            <fes:Literal>CloudCity</fes:Literal>
+        </fes:PropertyIsEqualTo>
+
+    ...and all variations (``<fes:PropertyIsLessThan>``, etc...)
+    that are listed in the :class:`BinaryComparisonName` enum.
+
+    Note that both arguments are expressions, so these can be value references, literals
+    or functions. The ``<fes:Literal>`` element may hold a GML element as its value.
+    """
 
     operatorType: BinaryComparisonName
     expression: tuple[Expression, Expression]
@@ -455,12 +589,12 @@ class BinaryComparisonOperator(ComparisonOperator):
 
     @classmethod
     @expect_children(2, Expression, Expression)
-    def from_xml(cls, element: Element):
+    def from_xml(cls, element: NSElement):
         return cls(
             operatorType=BinaryComparisonName.from_xml(element),
             expression=(
-                Expression.from_child_xml(element[0]),
-                Expression.from_child_xml(element[1]),
+                Expression.child_from_xml(element[0]),
+                Expression.child_from_xml(element[1]),
             ),
             matchCase=element.get("matchCase", True),
             matchAction=MatchAction(element.get("matchAction", default=MatchAction.Any)),
@@ -475,7 +609,19 @@ class BinaryComparisonOperator(ComparisonOperator):
 @dataclass
 @tag_registry.register("PropertyIsBetween")
 class BetweenComparisonOperator(ComparisonOperator):
-    """Check whether a value is between two elements."""
+    """Check whether a value is between two elements.
+
+    This parses and handles the syntax::
+
+        <fes:PropertyIsBetween>
+            <fes:ValueReference>DEPTH</fes:ValueReference>
+            <fes:LowerBoundary><fes:Literal>100</fes:Literal></fes:LowerBoundary>
+            <fes:UpperBoundary><fes:Literal>200</fes:Literal></fes:UpperBoundary>
+        </fes:PropertyIsBetween>
+
+    Note that both boundary arguments receive expressions, so these can be value
+    references, literals or functions!
+    """
 
     expression: Expression
     lowerBoundary: Expression
@@ -484,17 +630,15 @@ class BetweenComparisonOperator(ComparisonOperator):
 
     @classmethod
     @expect_children(3, Expression, "LowerBoundary", "UpperBoundary")
-    def from_xml(cls, element: Element):
-        if element[1].tag != QName(FES20, "LowerBoundary") or element[2].tag != QName(
-            FES20, "UpperBoundary"
-        ):
+    def from_xml(cls, element: NSElement):
+        if (element[1].tag != FES_LOWER_BOUNDARY) or (element[2].tag != FES_UPPER_BOUNDARY):
             raise ExternalParsingError(
                 f"{element.tag} should have 3 child nodes: "
                 f"(expression), <LowerBoundary>, <UpperBoundary>"
             )
 
-        lower = get_child(element, FES20, "LowerBoundary")
-        upper = get_child(element, FES20, "UpperBoundary")
+        lower = element[1]
+        upper = element[2]
 
         if len(lower) != 1:
             raise ExternalParsingError(f"{lower.tag} should have 1 expression child node")
@@ -502,9 +646,9 @@ class BetweenComparisonOperator(ComparisonOperator):
             raise ExternalParsingError(f"{upper.tag} should have 1 expression child node")
 
         return cls(
-            expression=Expression.from_child_xml(element[0]),
-            lowerBoundary=Expression.from_child_xml(lower[0]),
-            upperBoundary=Expression.from_child_xml(upper[0]),
+            expression=Expression.child_from_xml(element[0]),
+            lowerBoundary=Expression.child_from_xml(lower[0]),
+            upperBoundary=Expression.child_from_xml(upper[0]),
             _source=element.tag,
         )
 
@@ -520,7 +664,15 @@ class BetweenComparisonOperator(ComparisonOperator):
 @dataclass
 @tag_registry.register("PropertyIsLike")
 class LikeOperator(ComparisonOperator):
-    """Perform wildcard matching."""
+    """Perform wildcard matching.
+
+    This parses and handles the syntax::
+
+        <fes:PropertyIsLike wildCard="*" singleChar="#" escapeChar="!">
+            <fes:ValueReference>last_name</fes:ValueReference>
+            <fes:Literal>John*</fes:Literal>
+        </fes:PropertyIsLike>
+    """
 
     expression: tuple[Expression, Expression]
     wildCard: str
@@ -530,16 +682,16 @@ class LikeOperator(ComparisonOperator):
 
     @classmethod
     @expect_children(2, Expression, Expression)
-    def from_xml(cls, element: Element):
+    def from_xml(cls, element: NSElement):
         return cls(
             expression=(
-                Expression.from_child_xml(element[0]),
-                Expression.from_child_xml(element[1]),
+                Expression.child_from_xml(element[0]),
+                Expression.child_from_xml(element[1]),
             ),
             # These attributes are required by the WFS spec:
-            wildCard=get_attribute(element, "wildCard"),
-            singleChar=get_attribute(element, "singleChar"),
-            escapeChar=get_attribute(element, "escapeChar"),
+            wildCard=element.get_str_attribute("wildCard"),
+            singleChar=element.get_str_attribute("singleChar"),
+            escapeChar=element.get_str_attribute("escapeChar"),
             _source=element.tag,
         )
 
@@ -558,7 +710,9 @@ class LikeOperator(ComparisonOperator):
 
             rhs = Literal(raw_value=value)
         else:
-            raise ExternalParsingError(f"Expected a literal value for the {self.tag} operator.")
+            raise ExternalParsingError(
+                f"Expected a literal value for the {self.xml_tags[0]} operator."
+            )
 
         # Use the FesLike lookup
         return self.build_compare(compiler, lhs=lhs, lookup="fes_like", rhs=rhs)
@@ -569,17 +723,29 @@ class LikeOperator(ComparisonOperator):
 class NilOperator(ComparisonOperator):
     """Check whether the value evaluates to null/None.
     If the WFS returned a property element with <tns:p xsi:nil='true'>, this returns true.
+
+    It parses and handles syntax such as::
+
+        <fes:PropertyIsNil>
+            <fes:ValueReference>city/name</fes:ValueReference>
+        </fes:PropertyIsNil>
+
+    Note that the provided argument can be any expression, not just a value reference.
+    Thus, it can also check whether a function returns null.
     """
 
     expression: Expression | None
     nilReason: str
     _source: str | None = field(compare=False, default=None)
 
+    # Allow checking whether the geometry is null
+    allow_geometries: ClassVar[bool] = True
+
     @classmethod
     @expect_children(1, Expression)
-    def from_xml(cls, element: Element):
+    def from_xml(cls, element: NSElement):
         return cls(
-            expression=Expression.from_child_xml(element[0]) if element else None,
+            expression=Expression.child_from_xml(element[0]) if element is not None else None,
             nilReason=element.get("nilReason"),
             _source=element.tag,
         )
@@ -594,15 +760,26 @@ class NilOperator(ComparisonOperator):
 class NullOperator(ComparisonOperator):
     """Check whether the property exists.
     If the WFS would not return the property element <tns:p>, this returns true.
+
+    It parses and handles syntax such as::
+
+        <fes:PropertyIsNull>
+            <fes:ValueReference>city/name</fes:ValueReference>
+        </fes:PropertyIsNull>
+
+    Note that the provided argument can be any expression, not just a value reference.
     """
 
     expression: Expression
     _source: str | None = field(compare=False, default=None)
 
+    # Allow checking whether the geometry is null
+    allow_geometries: ClassVar[bool] = True
+
     @classmethod
     @expect_children(1, Expression)
-    def from_xml(cls, element: Element):
-        return cls(expression=Expression.from_child_xml(element[0]), _source=element.tag)
+    def from_xml(cls, element: NSElement):
+        return cls(expression=Expression.child_from_xml(element[0]), _source=element.tag)
 
     def build_query(self, compiler: CompiledQuery) -> Q:
         # For now, the implementation is identical to PropertyIsNil.
@@ -613,14 +790,28 @@ class NullOperator(ComparisonOperator):
 
 
 class LogicalOperator(NonIdOperator):
-    """Base class for AND, OR, NOT comparisons"""
+    """Base class in the fes-spec for AND, OR, NOT comparisons"""
 
 
 @dataclass
 @tag_registry.register("And")
 @tag_registry.register("Or")
 class BinaryLogicOperator(LogicalOperator):
-    """Apply an 'AND' or 'OR' operator"""
+    """Apply an 'AND' or 'OR' operator.
+
+    This parses and handles the syntax::
+
+        <fes:And>
+            <fes:PropertyIsGreaterThanOrEqualTo>
+                ...
+            </fes:PropertyIsGreaterThanOrEqualTo>
+            <fes:BBOX>
+                ...
+            </fes:BBOX>
+        </fes:And>
+
+    Any tag deriving from :class:`NonIdOperator` is allowed here.
+    """
 
     operands: list[NonIdOperator]
     operatorType: BinaryLogicType
@@ -628,9 +819,9 @@ class BinaryLogicOperator(LogicalOperator):
 
     @classmethod
     @expect_children(2, NonIdOperator, NonIdOperator)
-    def from_xml(cls, element: Element):
+    def from_xml(cls, element: NSElement):
         return cls(
-            operands=[NonIdOperator.from_child_xml(child) for child in element],
+            operands=[NonIdOperator.child_from_xml(child) for child in element],
             operatorType=BinaryLogicType.from_xml(element),
             _source=element.tag,
         )
@@ -644,7 +835,16 @@ class BinaryLogicOperator(LogicalOperator):
 @dataclass
 @tag_registry.register("Not")
 class UnaryLogicOperator(LogicalOperator):
-    """Apply a NOT operator"""
+    """Apply a NOT operator.
+
+    This parses and handles the syntax::
+
+        <fes:Not>
+            <fes:PropertyIsNil>
+                <fes:ValueReference>city/name</fes:ValueReference>
+            </fes:PropertyIsNil>
+        </fes:Not>
+    """
 
     operands: NonIdOperator
     operatorType: UnaryLogicType
@@ -652,9 +852,9 @@ class UnaryLogicOperator(LogicalOperator):
 
     @classmethod
     @expect_children(1, NonIdOperator)
-    def from_xml(cls, element: Element):
+    def from_xml(cls, element: NSElement):
         return cls(
-            operands=NonIdOperator.from_child_xml(element[0]),
+            operands=NonIdOperator.child_from_xml(element[0]),
             operatorType=UnaryLogicType.from_xml(element),
             _source=element.tag,
         )
@@ -665,4 +865,8 @@ class UnaryLogicOperator(LogicalOperator):
 
 
 class ExtensionOperator(NonIdOperator):
-    """Base class for extensions to FES20"""
+    """Base class for extensions to FES 2.0.
+
+    It's fully allowed to introduce new operators on your own namespace.
+    These need to inherit from this class.
+    """