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

gisserver/parsers/fes20/expressions.py

@@ -1,5 +1,18 @@
 """These classes map to the FES 2.0 specification for expressions.
 The class names are identical to those in the FES spec.
+
+Inheritance structure:
+
+* :class:`Expression`
+
+ * :class:`Function` for ``<fes:Function>``.
+ * :class:`Literal` for ``<fes:Literal>``.
+ * :class:`ValueReference` for ``<fes:ValueReference>``.
+ * :class:`BinaryOperator` for FES 1.0 compatibility.
+
+The :class:`BinaryOperator` is included as expression
+to handle FES 1.0 :class:`BinaryOperatorType` arithmetic tags:
+``<fes:Add>``, ``<fes:Sub>``, ``<fes:Mul>``, ``<fes:Div>``.
 """
 
 from __future__ import annotations
@@ -13,6 +26,7 @@ from typing import Union
 
 from django.contrib.gis import geos
 from django.contrib.gis.db import models as gis_models
+from django.core.exceptions import ValidationError
 from django.db import models
 from django.db.models import Q, Value
 from django.db.models.expressions import Combinable
@@ -20,7 +34,7 @@ from django.db.models.expressions import Combinable
 from gisserver.exceptions import ExternalParsingError
 from gisserver.extensions.functions import function_registry
 from gisserver.parsers.ast import (
-    BaseNode,
+    AstNode,
     TagNameEnum,
     expect_no_children,
     expect_tag,
@@ -36,7 +50,7 @@ from gisserver.parsers.gml import (
 from gisserver.parsers.query import RhsTypes
 from gisserver.parsers.values import auto_cast
 from gisserver.parsers.xml import NSElement, parse_qname, xmlns
-from gisserver.types import ORMPath, XsdTypes
+from gisserver.types import XPathMatch, XsdTypes
 
 NoneType = type(None)
 ParsedValue = Union[int, str, date, D, datetime, GM_Object, GM_Envelope, TM_Object, NoneType]
@@ -74,10 +88,11 @@ class BinaryOperatorType(TagNameEnum):
     Div = operator.truediv
 
 
-class Expression(BaseNode):
+class Expression(AstNode):
     """Abstract base class, as defined by FES spec.
 
     The FES spec defines the following subclasses:
+
     * :class:`ValueReference` (pointing to a field name)
     * :class:`Literal` (a scalar value)
     * :class:`Function` (a transformation for a value/field)
@@ -110,13 +125,13 @@ class Expression(BaseNode):
 @dataclass(repr=False)
 @tag_registry.register("Literal")
 class Literal(Expression):
-    """The <fes:Literal> element that holds a literal value.
+    """The ``<fes:Literal>`` element that holds a literal value.
 
     This can be a string value, possibly annotated with a type::
 
         <fes:Literal type="xs:boolean">true</fes:Literal>
 
-    Following the spec, the value may also contain a complete geometry:
+    Following the spec, the value may also contain a complete geometry::
 
         <fes:Literal>
             <gml:Envelope xmlns:gml="http://www.opengis.net/gml/3.2" srsName="urn:ogc:def:crs:EPSG::4326">
@@ -138,7 +153,9 @@ class Literal(Expression):
 
     @cached_property
     def value(self) -> ParsedValue:  # officially <xsd:any>
-        """Access the value of the element, cast to the appropriate data type."""
+        """Access the value of the element, cast to the appropriate data type.
+        :raises ExternalParsingError: When the value can't be converted to the proper type.
+        """
         if not isinstance(self.raw_value, str):
             return self.raw_value  # GML element or None
         elif self.type:
@@ -208,14 +225,22 @@ class Literal(Expression):
 @tag_registry.register("ValueReference")
 @tag_registry.register("PropertyName", hidden=True)  # FES 1.0 name that old clients still use.
 class ValueReference(Expression):
-    """The <fes:ValueReference> element that holds an XPath string.
+    """The ``<fes:ValueReference>`` element that holds an XPath string.
     In the fes XSD, this is declared as a subclass of xsd:string.
 
+    This parses the syntax like::
+
+        <fes:ValueReference>field-name</fes:ValueReference>
+        <fes:ValueReference>path/to/field-name</fes:ValueReference>
+        <fes:ValueReference>collection[@attr=value]/field-name</fes:ValueReference>
+
     The old WFS1/FES1 "PropertyName" is allowed as an alias.
     Various clients still send this, and mapserver/geoserver support this.
     """
 
+    #: The XPath value
     xpath: str
+    #: The known namespaces aliases at this point in the XML tree
     xpath_ns_aliases: dict[str, str] | None = field(compare=False, default=None)
 
     def __str__(self):
@@ -231,35 +256,37 @@ class ValueReference(Expression):
         return cls(xpath=element.text, xpath_ns_aliases=element.ns_aliases)
 
     def build_lhs(self, compiler) -> str:
-        """Optimized LHS: there is no need to alias a field lookup through an annotation."""
+        """Use the field name in a left-hand-side expression."""
+        # Optimized from base class: fields don't need an alias lookup through annotations.
         match = self.parse_xpath(compiler.feature_types)
         return match.build_lhs(compiler)
 
     def build_rhs(self, compiler) -> RhsTypes:
-        """Return the value as F-expression"""
+        """Use the field name in a right-hand expression.
+        This generates an F-expression for the ORM."""
         match = self.parse_xpath(compiler.feature_types)
         return match.build_rhs(compiler)
 
-    def parse_xpath(self, feature_types: list) -> ORMPath:
+    def parse_xpath(self, feature_types: list) -> XPathMatch:
         """Convert the XPath into the required ORM query elements."""
-        if feature_types:
-            # Can resolve against XSD paths, find the correct DB field name
-            return feature_types[0].resolve_element(self.xpath, self.xpath_ns_aliases)
-        else:
-            # Only used by unit testing (when feature_type is not given).
-            parts = [word.strip() for word in self.xpath.split("/")]
-            return ORMPath(orm_path="__".join(parts), orm_filters=None)
-
-    @cached_property
-    def element_name(self):
-        """Tell which element this reference points to."""
-        return self.xpath.rpartition("/")[2]
+        return feature_types[0].resolve_element(self.xpath, self.xpath_ns_aliases)
 
 
 @dataclass
 @tag_registry.register("Function")
 class Function(Expression):
-    """The <fes:Function name="..."> element."""
+    """The ``<fes:Function name="...">`` element.
+
+    This parses the syntax such as::
+
+        <fes:Function name="Add">
+            <fes:ValueReference>field-name</fes:ValueReference>
+            <fes:Literal>2</fes:Literal>
+        </fes:Function>
+
+    Each argument of the function can be another :class:`Expression`,
+    such as a :class:`Function`, :class:`ValueReference` or :class:`Literal`.
+    """
 
     name: str  # scoped name
     arguments: list[Expression]  # xsd:element ref="fes20:expression"
@@ -284,8 +311,17 @@ class Function(Expression):
 class BinaryOperator(Expression):
     """Support for FES 1.0 arithmetic operators.
 
+    This parses a syntax like::
+
+        <fes:Add>
+            <fes:ValueReference>field-name</fes:ValueReference>
+            <fes:Literal>2</fes:Literal>
+        </fes:Add>
+
+    The operator can be a ``<fes:Add>``, ``<fes:Sub>``, ``<fes:Mul>``, ``<fes:Div>``.
+
     These are no longer part of the FES 2.0 spec, but clients (like QGis)
-    still assume the server supports these. Hence, these need to be included.
+    still assume the server use these. Hence, these need to be included.
     """
 
     _operatorType: BinaryOperatorType
@@ -302,9 +338,43 @@ class BinaryOperator(Expression):
         )
 
     def build_rhs(self, compiler) -> RhsTypes:
-        value1 = _make_combinable(self.expression[0].build_rhs(compiler))
-        value2 = _make_combinable(self.expression[1].build_rhs(compiler))
-        return self._operatorType.value(value1, value2)
+        self.validate_arithmetic(compiler, self.expression[0], self.expression[1])
+        value1 = self.expression[0].build_rhs(compiler)
+        value2 = self.expression[1].build_rhs(compiler)
+
+        # Func() + 2 or 2 + Func() are automatically handled,
+        # but Q(..) + 2 or 2 + Q(..) aren't.
+        # When both are values, a direct calculation takes place in Python.
+        if isinstance(value1, Q):
+            value2 = _make_combinable(value2)
+        if isinstance(value2, Q):
+            value1 = _make_combinable(value1)
+
+        try:
+            # This calls somthing like: operator.add(F("field"), 2) or operator.add(1, 2)
+            return self._operatorType.value(value1, value2)
+        except (TypeError, ValueError, ArithmeticError) as e:
+            raise ValidationError(
+                f"Invalid data for the 'fes:{self._operatorType.name}' element: {value1} {value2}"
+            ) from e
+
+    def validate_arithmetic(self, compiler, lhs: Expression, rhs: Expression):
+        """Check whether values support arithmetic operators."""
+        if isinstance(lhs, Literal) and isinstance(rhs, ValueReference):
+            lhs, rhs = rhs, lhs
+
+        if isinstance(lhs, ValueReference):
+            xsd_element = lhs.parse_xpath(compiler.feature_types).child
+            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)
+
+                # Validate the expressions against each other
+                # This raises an ValidationError when values can't be converted
+                xsd_element.to_python(rhs.raw_value)
+
+        return None
 
 
 def _make_combinable(value) -> Combinable | Q:

gisserver/parsers/fes20/filters.py

@@ -6,7 +6,7 @@ from typing import AnyStr, ClassVar, Union
 from django.db.models import Q
 
 from gisserver.exceptions import InvalidParameterValue
-from gisserver.parsers.ast import BaseNode, expect_tag, tag_registry
+from gisserver.parsers.ast import AstNode, expect_tag, tag_registry
 from gisserver.parsers.gml import GEOSGMLGeometry
 from gisserver.parsers.ows import KVPRequest
 from gisserver.parsers.query import CompiledQuery
@@ -14,6 +14,7 @@ from gisserver.parsers.xml import NSElement, parse_xml_from_string, xmlns
 
 from . import expressions, identifiers, operators
 
+#: The FES element group that can be used as body for the :class:`Filter` element.
 FilterPredicates = Union[expressions.Function, operators.Operator]
 
 # Fully qualified tag names
@@ -22,8 +23,8 @@ FES_RESOURCE_ID = xmlns.fes20.qname("ResourceId")
 
 @dataclass
 @tag_registry.register("Filter", xmlns.fes20)
-class Filter(BaseNode):
-    """The <fes:Filter> element.
+class Filter(AstNode):
+    """The ``<fes:Filter>`` element.
 
     This parses and handles the syntax::
 
@@ -41,7 +42,9 @@ class Filter(BaseNode):
 
     query_language: ClassVar[str] = "urn:ogc:def:queryLanguage:OGC-FES:Filter"
 
+    #: The filter predicate (body)
     predicate: FilterPredicates
+
     source: AnyStr | None = field(default=None, compare=False)
 
     @classmethod
@@ -106,7 +109,7 @@ class Filter(BaseNode):
 
     @classmethod
     def from_string(cls, text: AnyStr, ns_aliases: dict[str, str] | None = None) -> Filter:
-        """Parse an XML <fes20:Filter> string.
+        """Parse an XML ``<fes:Filter>`` string.
 
         This uses defusedxml by default, to avoid various XML injection attacks.
 
@@ -156,8 +159,8 @@ class Filter(BaseNode):
         return self.predicate.build_query(compiler)
 
     def get_resource_id_types(self) -> list[str] | None:
-        """When the filter parses ResourceId objects, return those.
-        This can return an empty list in case a ResourceId object doesn't define a type.
+        """When the filter predicate consists of ``<fes:ResourceId>`` elements, return those.
+        This can return an empty list in case a ``<fes:ResourceId>`` object doesn't define a type.
         """
         if isinstance(self.predicate, operators.IdOperator):
             return self.predicate.get_type_names()

gisserver/parsers/fes20/identifiers.py

@@ -1,5 +1,11 @@
 """These classes map to the FES 2.0 specification for identifiers.
 The class names are identical to those in the FES spec.
+
+Inheritance structure:
+
+* :class:`Id`
+
+ * :class:`ResourceId`
 """
 
 from __future__ import annotations
@@ -12,7 +18,7 @@ from django.db.models import Q
 
 from gisserver import conf
 from gisserver.exceptions import ExternalValueError, InvalidParameterValue
-from gisserver.parsers.ast import BaseNode, expect_no_children, expect_tag, tag_registry
+from gisserver.parsers.ast import AstNode, expect_no_children, expect_tag, tag_registry
 from gisserver.parsers.values import auto_cast, parse_iso_datetime
 from gisserver.parsers.xml import parse_qname, xmlns
 
@@ -20,7 +26,7 @@ NoneType = type(None)
 
 
 class VersionActionTokens(Enum):
-    """Values for the 'version' attribute of the ResourceId node."""
+    """Values for the 'version' attribute of the :class:`ResourceId` node."""
 
     FIRST = "FIRST"
     LAST = "LAST"
@@ -29,8 +35,11 @@ class VersionActionTokens(Enum):
     PREVIOUS = "PREVIOUS"
 
 
-class Id(BaseNode):
-    """Abstract base class, as defined by FES spec."""
+class Id(AstNode):
+    """Abstract base class, as defined by FES spec.
+    Any custom identifier-element needs to extend from this node.
+    By default, the :class:`ResourceId` element is supported.
+    """
 
     xml_ns = xmlns.fes20
 
@@ -44,19 +53,30 @@ class Id(BaseNode):
 @dataclass
 @tag_registry.register("ResourceId")
 class ResourceId(Id):
-    """The <fes:ResourceId> element.
+    """The ``<fes:ResourceId>`` element.
     This element allow queries to retrieve a resource by their identifier.
+
+    This parses the syntax::
+
+        <fes:ResourceId rid="typename.123" />
+
+    This element is placed inside a :class:`~gisserver.parsers.fes20.filters.Filter`.
     """
 
-    # A raw "resource identifier". Needs to encode the object name somehow,
-    # and it's completely unrelated to XML namespacing.
+    #: A raw "resource identifier". It typically includes the object name,
+    #: which is completely unrelated to XML namespacing.
     rid: str
+
+    #: Internal extra attribute, referencing the inferred typename from the :attr:`rid`.
     type_name: str | None
+
+    #: Unused, this is part of additional conformance classes.
     version: int | datetime | VersionActionTokens | NoneType = None
     startTime: datetime | None = None
     endTime: datetime | None = None
 
     def get_type_name(self):
+        """Implemented/override to expose the inferred type name."""
         return self.type_name
 
     def __post_init__(self):

gisserver/parsers/fes20/lookups.py

@@ -14,7 +14,7 @@ from gisserver.compat import ArrayField
 @models.TextField.register_lookup
 @models.ForeignObject.register_lookup
 class FesLike(lookups.Lookup):
-    """Allow fieldname__fes_like=... lookups in querysets."""
+    """Allow ``fieldname__fes_like=...`` lookups in querysets."""
 
     lookup_name = "fes_like"
 
@@ -36,7 +36,7 @@ class FesLike(lookups.Lookup):
 @models.Field.register_lookup
 @models.ForeignObject.register_lookup
 class FesNotEqual(lookups.Lookup):
-    """Allow fieldname__fes_notequal=... lookups in querysets."""
+    """Allow ``fieldname__fes_notequal=...`` lookups in querysets."""
 
     lookup_name = "fes_notequal"
 
@@ -49,10 +49,12 @@ class FesNotEqual(lookups.Lookup):
 
 @BaseSpatialField.register_lookup
 class FesBeyondLookup(DWithinLookup):
-    """Based on the FES 2.0.3 corrigendum:
+    """Allow ``fieldname__fes_beyond=...`` lookups in querysets.
 
-    DWithin(A,B,d) = Distance(A,B) < d
-    Beyond(A,B,d) = Distance(A,B) > d
+    Based on the FES 2.0.3 corrigendum:
+
+    * ``DWithin(A,B,d) = Distance(A,B) < d``
+    * ``Beyond(A,B,d) = Distance(A,B) > d``
 
     See: https://docs.opengeospatial.org/is/09-026r2/09-026r2.html#61
     """
@@ -130,7 +132,7 @@ else:
 
     @ArrayField.register_lookup
     class FesArrayLike(FesLike):
-        """Allow fieldname__fes_like=... lookups in querysets."""
+        """Allow like lookups for array fields."""
 
         lookup_name = "fes_anylike"