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

gisserver/parsers/fes20/operators.py

@@ -1,66 +1,89 @@
 """These classes map to the FES 2.0 specification for operators.
 The class names and attributes are identical to those in the FES spec.
+
+Inheritance structure:
+
+* :class:`Operator`
+
+ * :class:`IdOperator` chains ``<fes:ResourceId>``.
+ * :class:`NonIdOperator`
+
+  * :class:`ComparisonOperator`
+
+   * :class:`BinaryComparisonOperator` for :class:`BinaryComparisonName` tags like ``<fes:PropertyIsEqualTo>``.
+   * :class:`BetweenComparisonOperator` for ``<fes:PropertyIsBetween>``
+   * :class:`LikeOperator` for ``<fes:PropertyIsLike>``.
+   * :class:`NilOperator` for ``<fes:PropertyIsNil>``.
+   * :class:`NullOperator` for ``<fes:PropertyIsNill>``.
+
+  * :class:`SpatialOperator`
+
+   * :class:`DistanceOperator` for the :class:`DistanceOperator` tags: ``<fes:DWithin>`` and ``<fes:Beyond>``.
+   * :class:`BinarySpatialOperator` for :class:`SpatialOperatorName` tags like ``<fes:BBOX>``.
+
+  * :class:`TemporalOperator` for :class:`TemporalOperatorName` tags like ``<fes:After>``.
+  * :class:`LogicalOperator`
+
+   * :class:`BinaryLogicOperator` for the :class:`BinaryLogicType` tags: ``<fes:And>`` and ``<fes:Or>``.
+   * :class:`UnaryLogicOperator` for the :class:`UnaryLogicType` tag: ``<fes:Not>``.
+
+  * :class:`ExtensionOperator` for custom additions.
 """
 
 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, 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 (
+    AstNode,
+    TagNameEnum,
+    expect_children,
+    expect_tag,
+    tag_registry,
+)
+from gisserver.parsers.query import CompiledQuery, RhsTypes, ScalarTypes
+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
-
-SpatialDescription = Union[gml.GM_Object, gml.GM_Envelope, ValueReference]
-TemporalOperand = Union[gml.TM_Object, ValueReference]
-
+from .lookups import ARRAY_LOOKUPS  # also registers the lookups.
 
-# Define interface for any class that has "build_rhs()"
-try:
-    from typing import Protocol
-except ImportError:
-    HasBuildRhs = Any  # Python 3.7 and below
-else:
+logger = logging.getLogger(__name__)
 
-    class HasBuildRhs(Protocol):
-        def build_rhs(self, compiler) -> RhsTypes: ...
+#: Define the types that a ``<gml:SpatialDescription>`` can be:
+SpatialDescription = Union[gml.GM_Object, gml.GM_Envelope, ValueReference]
 
+#: Define the types that a ``<gml:TemporalOperand>`` can be:
+TemporalOperand = Union[gml.TM_Object, ValueReference]
 
-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
+# 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")
+FES1_PROPERTY_NAME = xmlns.fes20.qname("PropertyName")  # old tag sometimes used by clients
 
 
 class MatchAction(Enum):
-    """Values for the 'matchAction' attribute of the BinaryComparisonOperator."""
+    """Values for the 'matchAction' attribute of the :class:`BinaryComparisonOperator`."""
 
     All = "All"
     Any = "Any"
@@ -73,7 +96,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"
@@ -84,15 +107,23 @@ class BinaryComparisonName(TagNameEnum):
     PropertyIsGreaterThanOrEqualTo = "gte"
 
 
+REVERSE_LOOKUPS = {
+    "gt": "lt",
+    "gte": "lte",
+    "lt": "gt",
+    "lte": "gte",
+}
+
+
 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 +134,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
@@ -149,27 +180,46 @@ class UnaryLogicType(TagNameEnum):
 
 
 @dataclass
-class Measure(BaseNode):
-    """The <fes:Distance uom="...> element."""
+@tag_registry.register("Distance")
+class Measure(AstNode):
+    """A measurement for a distance element.
+
+    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.
 
-    xml_ns = FES20
+    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."""
+class Operator(AstNode):
+    """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.")
@@ -177,12 +227,20 @@ class Operator(BaseNode):
 
 @dataclass
 class IdOperator(Operator):
-    """List of ResourceId objects"""
+    """List of :class:`~gisserver.parsers.fes20.identifers.ResourceId`` objects.
+
+    A ``<fes:Filter>`` only has a single predicate.
+    Hence, this operator is used to wrap the ``<fes:ResourceId>`` elements in the syntax::
+
+        <fes:Filter>
+            <fes:ResourceId rid="typename.123" />
+            <fes:ResourceId rid="typename.345" />
+        </fes:Filter>
+    """
 
     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 +250,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 +265,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)
 
 
@@ -216,10 +286,14 @@ class NonIdOperator(Operator):
     """Abstract base class, as defined by FES spec.
 
     This is used for nearly all operators,
-    except those that have <fes:ResourceId> elements as children.
+    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(
@@ -236,18 +310,28 @@ class NonIdOperator(Operator):
         # lhs and rhs are allowed to be reversed. However, the SQL compiler
         # works much simpler when Django can predict the actual data type.
         if isinstance(lhs, Literal) and isinstance(rhs, ValueReference):
+            logger.debug("Filter switches lhs/rhs for %s %s %s", lhs.raw_value, lookup, rhs.xpath)
             lhs, rhs = rhs, lhs
+            lookup = REVERSE_LOOKUPS.get(lookup, lookup)  # >= should become <=
 
-        if compiler.feature_type is not None:
-            lookup = self.validate_comparison(compiler, lhs, lookup, rhs)
+        lookup = self.validate_comparison(compiler, lhs, lookup, rhs)
 
         # Build Django Q-object
-        lhs = lhs.build_lhs(compiler)
+        lhs_orm_name = lhs.build_lhs(compiler)
 
         if isinstance(rhs, (Expression, gml.GM_Object)):
             rhs = rhs.build_rhs(compiler)
-
-        comparison = Q(**{f"{lhs}__{lookup}": rhs})
+            if (
+                isinstance(lhs, ValueReference)
+                and isinstance(rhs, ScalarTypes)
+                and lookup != "isnull"
+            ):
+                # Building the expression resolved as a scalar after all (for BinaryOperator).
+                # It allows performing a better type check:
+                xsd_element = lhs.parse_xpath(compiler.feature_types).child
+                xsd_element.to_python(rhs)
+
+        comparison = Q(**{f"{lhs_orm_name}__{lookup}": rhs})
         return compiler.apply_extra_lookups(comparison)
 
     def validate_comparison(
@@ -255,17 +339,27 @@ class NonIdOperator(Operator):
         compiler: CompiledQuery,
         lhs: Expression,
         lookup: str,
-        rhs: Expression | RhsTypes,
-    ):
+        rhs: Expression | gml.GM_Object | RhsTypes,
+    ) -> str:
         """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.
+
+        :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, Literal) and isinstance(rhs, ValueReference):
+            lhs, rhs = rhs, lhs
+
         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 +367,33 @@ 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)
+            elif isinstance(rhs, ScalarTypes) and lookup != "isnull":
+                # Can still compare two elements, e.g. date >= ((2020 - 12) - 10) by QGis
+                xsd_element.validate_comparison(rhs, lookup=lookup, tag=tag)
+
         return lookup
 
     def build_compare_between(
@@ -303,12 +401,11 @@ 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:
-            self.validate_comparison(compiler, lhs, lookup, rhs[0])
-            self.validate_comparison(compiler, lhs, lookup, rhs[1])
+        self.validate_comparison(compiler, lhs, lookup, rhs[0])
+        self.validate_comparison(compiler, lhs, lookup, rhs[1])
 
         field_name = lhs.build_lhs(compiler)
         comparison = Q(
@@ -327,9 +424,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
 
@@ -337,11 +446,11 @@ class DistanceOperator(SpatialOperator):
     operatorType: DistanceOperatorName
     geometry: gml.GM_Object
     distance: Measure
-    _source: str | None = field(compare=False, default=None)
+    _source: str | None = field(compare=False, default=None, repr=False)
 
     @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 +458,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,19 +475,33 @@ 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
 
     operatorType: SpatialOperatorName
     operand1: ValueReference | None
     operand2: SpatialDescription
-    _source: str | None = field(compare=False, default=None)
+    _source: str | None = field(compare=False, default=None, repr=False)
 
     @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 +515,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,41 +533,105 @@ 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, hidden=True)  # <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
     operand2: TemporalOperand
-    _source: str | None = field(compare=False, default=None)
+    _source: str | None = field(compare=False, default=None, repr=False)
 
     @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"""
-
-    # Start counting fresh here, to collect the capabilities
-    # that are listed in the <fes20:ComparisonOperators> node:
-    xml_tags = []
+    """Base class for comparisons.
+    This class name mirrors the fes-spec name,
+    and allows grouping various comparisons together.
+    """
 
 
 @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]
@@ -454,13 +640,13 @@ class BinaryComparisonOperator(ComparisonOperator):
     _source: str | None = field(compare=False, default=None)
 
     @classmethod
-    @expect_children(2, Expression, Expression)
-    def from_xml(cls, element: Element):
+    @expect_children(2, Expression, silent_allowed=(FES1_PROPERTY_NAME,))
+    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,26 +661,36 @@ 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
     upperBoundary: Expression
-    _source: str | None = field(compare=False, default=None)
+    _source: str | None = field(compare=False, default=None, repr=False)
 
     @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"
-        ):
+    @expect_children(3, Expression, FES_LOWER_BOUNDARY, FES_UPPER_BOUNDARY)
+    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 +698,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,26 +716,34 @@ 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
     singleChar: str
     escapeChar: str
-    _source: str | None = field(compare=False, default=None)
+    _source: str | None = field(compare=False, default=None, repr=False)
 
     @classmethod
-    @expect_children(2, Expression, Expression)
-    def from_xml(cls, element: Element):
+    @expect_children(2, Expression)
+    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 +762,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_name} operator."
+            )
 
         # Use the FesLike lookup
         return self.build_compare(compiler, lhs=lhs, lookup="fes_like", rhs=rhs)
@@ -568,18 +774,30 @@ class LikeOperator(ComparisonOperator):
 @tag_registry.register("PropertyIsNil")
 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.
+    If the WFS returned a property element with ``<app:field 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)
+    _source: str | None = field(compare=False, default=None, repr=False)
+
+    # 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,
         )
@@ -593,16 +811,27 @@ class NilOperator(ComparisonOperator):
 @tag_registry.register("PropertyIsNull")
 class NullOperator(ComparisonOperator):
     """Check whether the property exists.
-    If the WFS would not return the property element <tns:p>, this returns true.
+    If the WFS would not return the property element ``<app:field>``, 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)
+    _source: str | None = field(compare=False, default=None, repr=False)
+
+    # 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,24 +842,38 @@ 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
-    _source: str | None = field(compare=False, default=None)
+    _source: str | None = field(compare=False, default=None, repr=False)
 
     @classmethod
-    @expect_children(2, NonIdOperator, NonIdOperator)
-    def from_xml(cls, element: Element):
+    @expect_children(2, NonIdOperator)
+    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,17 +887,26 @@ 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
-    _source: str | None = field(compare=False, default=None)
+    _source: str | None = field(compare=False, default=None, repr=False)
 
     @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 +917,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.
+    """