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

gisserver/parsers/wfs20/adhoc.py

@@ -0,0 +1,253 @@
+"""Handle adhoc-query objects.
+
+The adhoc query is based on incoming request parameters,
+such as the "FILTER", "BBOX" and "RESOURCEID" parameters.
+
+These definitions follow the WFS spec.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from functools import cached_property
+
+from django.db.models import Q
+
+from gisserver.crs import CRS
+from gisserver.exceptions import (
+    InvalidParameterValue,
+    MissingParameterValue,
+    OperationNotSupported,
+)
+from gisserver.parsers import fes20
+from gisserver.parsers.ast import tag_registry
+from gisserver.parsers.ows import KVPRequest
+from gisserver.parsers.query import CompiledQuery
+from gisserver.parsers.xml import NSElement, xmlns
+from gisserver.projection import FeatureProjection
+
+from .base import QueryExpression
+from .projection import PropertyName
+
+logger = logging.getLogger(__name__)
+
+ADHOC_QUERY_ELEMENTS = (PropertyName, fes20.Filter, fes20.SortBy)
+
+
+@dataclass
+@tag_registry.register("Query", xmlns.wfs)
+class AdhocQuery(QueryExpression):
+    """The Ad hoc query expression parameters.
+
+    This parses and handles the syntax::
+
+        <wfs:Query typeNames="...">
+            <wfs:PropertyName>...</wfs:PropertyName>
+            <fes:Filter>...</fes:Filter>
+            <fes:SortBy>...</fes:SortBy>
+        </wfs:Query>
+
+    And supports the KVP syntax::
+
+        ?SERVICE=WFS&...&TYPENAMES=ns:myType&FILTER=...&SORTBY=...&SRSNAME=...&PROPERTYNAME=...
+        ?SERVICE=WFS&...&TYPENAMES=ns:myType&BBOX=...&SORTBY=...&SRSNAME=...&PROPERTYNAME=...
+        ?SERVICE=WFS&...&TYPENAMES=ns:myType&RESOURCEID=...
+
+    This represents all dynamic queries received as request (hence "adhoc"),
+    such as the "FILTER" and "BBOX" arguments from an HTTP GET.
+
+    The WFS Spec has 3 class levels for this:
+
+     - AdhocQueryExpression (types, projection, selection, sorting)
+     - Query (adds srsName, featureVersion)
+     - StoredQuery (adds storedQueryID)
+
+    For KVP requests, this class seems almost identifical to the provided parameters.
+    However, the KVP format allows to provide parameter lists,
+    to perform support multiple queries in a single request!
+
+    .. seealso::
+        https://www.mediamaps.ch/ogc/schemas-xsdoc/sld/1.2/query_xsd.html#AbstractAdhocQueryExpressionType
+    """
+
+    # Tag attributes (implements ``fes:AbstractAdhocQueryExpression``)
+    # WFS allows multiple names to construct JOIN queries.
+    # See https://docs.ogc.org/is/09-025r2/09-025r2.html#107
+    # and https://docs.ogc.org/is/09-025r2/09-025r2.html#190
+
+    #: The 'typeNames' value if the request provided them. use :meth:`get_type_names` instead.
+    typeNames: list[str]
+    #: Aliases for typeNames are used for joining the same table twice. (JOIN statements are not supported yet).
+    aliases: list[str] | None = None
+    #: For XML POST requests, this handle value is returned in the ``<ows:Exception>``.
+    handle: str = ""
+
+    # part of the <wfs:Query> tag attributes:
+    #: The Coordinate Reference System to render the tag in
+    srsName: CRS | None = None
+
+    #: Projection clause (implements ``fes:AbstractProjectionClause``)
+    property_names: list[PropertyName] | None = None
+
+    #: Selection clause (implements ``fes:AbstractSelectionClause``).
+    #: - for XML POST this is encoded in a <fes:Filter> tag.
+    #: - for HTTP GET, this is encoded as FILTER, FILTER_LANGUAGE, RESOURCEID, BBOX.
+    filter: fes20.Filter | None = None
+
+    #: Sorting Clause (implements ``fes:AbstractSortingClause``)
+    sortBy: fes20.SortBy | None = None
+
+    def __post_init__(self):
+        if len(self.typeNames) > 1:
+            raise OperationNotSupported("Join queries are not supported", locator="typeNames")
+        if self.aliases:
+            raise OperationNotSupported("Join queries are not supported", locator="aliases")
+
+    @classmethod
+    def from_xml(cls, element: NSElement) -> AdhocQuery:
+        """Parse the XML element of the Query tag."""
+        type_names = [
+            element.parse_qname(qname)
+            for qname in element.get_str_attribute("typeNames").split(" ")
+        ]
+        aliases = element.attrib.get("aliases", None)
+        srsName = element.attrib.get("srsName", None)
+        property_names = []
+        filter = None
+        sortBy = None
+
+        for child in element:
+            # The FES XSD dictates the element ordering, but this is ignored here.
+            node = tag_registry.node_from_xml(child, allowed_types=ADHOC_QUERY_ELEMENTS)
+            if isinstance(node, PropertyName):
+                property_names.append(node)
+            elif isinstance(node, fes20.Filter):
+                filter = node
+            elif isinstance(node, fes20.SortBy):
+                sortBy = node
+            else:
+                raise NotImplementedError(
+                    f"Parsing {node.__class__} not handled in AdhocQuery.from_xml()"
+                )
+
+        return AdhocQuery(
+            typeNames=type_names,
+            aliases=aliases.split(" ") if aliases is not None else None,
+            handle=element.attrib.get("handle", ""),
+            property_names=property_names or None,
+            filter=filter,
+            sortBy=sortBy,
+            srsName=CRS.from_string(srsName) if srsName else None,
+        )
+
+    @classmethod
+    def from_kvp_request(cls, kvp: KVPRequest):
+        """Build this object from an HTTP GET (key-value-pair) request.
+
+        Note the caller should have split the KVP request parameter lists.
+        This class only handles a single parameter pair.
+        """
+        # Parse attributes
+        typeNames = [
+            kvp.parse_qname(qname)
+            for qname in kvp.get_list("typeNames", alias="TYPENAME", default=[])
+        ]
+        aliases = kvp.get_list("aliases", default=None)
+        srsName = kvp.get_custom("srsName", default=None, parser=CRS.from_string)
+
+        # KVP requests may omit the typenames if RESOURCEID=... is given.
+        if not typeNames and "RESOURCEID" not in kvp:
+            raise MissingParameterValue("Empty TYPENAMES parameter", locator="typeNames")
+
+        # Parse elements
+        filter = fes20.Filter.from_kvp_request(kvp)
+        sort_by = fes20.SortBy.from_kvp_request(kvp)
+
+        # Parse projection
+        property_names = None
+        if "PROPERTYNAME" in kvp:
+            names = kvp.get_list("propertyName", default=[])
+            # Check for WFS 1.x syntax of ?PROPERTYNAME=*
+            if names != ["*"]:
+                property_names = [
+                    PropertyName(xpath=name, xpath_ns_aliases=kvp.ns_aliases) for name in names
+                ]
+
+        return AdhocQuery(
+            # Attributes
+            typeNames=typeNames,
+            aliases=aliases,
+            srsName=srsName,
+            # Elements
+            property_names=property_names,
+            filter=filter,
+            sortBy=sort_by,
+        )
+
+    @cached_property
+    def query_locator(self):
+        """Overrides the 'query_locator' attribute, so the 'locator' argument is correctly set."""
+        if self.filter is not None and self.filter.get_resource_id_types():
+            return "resourceId"
+        else:
+            return "filter"
+
+    def get_type_names(self) -> list[str]:
+        """Tell which type names this query uses.
+        Multiple values means a JOIN is made (not supported yet).
+        """
+        if not self.typeNames and self.filter is not None:
+            # Also make the behavior consistent, always supply the type name.
+            return self.filter.get_resource_id_types() or []
+        else:
+            return self.typeNames
+
+    def get_projection(self) -> FeatureProjection:
+        """Tell how the ``<wfs:Query>`` element should be displayed."""
+        return FeatureProjection(
+            self.feature_types,
+            self.property_names,
+            self.value_reference,
+            output_crs=self.srsName,
+        )
+
+    def bind(self, *args, **kwargs):
+        """Override to make sure the 'locator' points to the actual object that defined the type."""
+        try:
+            super().bind(*args, **kwargs)
+        except InvalidParameterValue as e:
+            if not self.typeNames:
+                e.locator = "resourceId"
+            raise
+
+        # Validate the srsName too
+        if self.srsName is not None:
+            self.srsName = self.feature_types[0].resolve_crs(self.srsName, locator="srsName")
+
+    def build_query(self, compiler: CompiledQuery) -> Q | None:
+        """Apply our collected filter data to the compiler."""
+        # Add the sorting
+        if self.sortBy is not None:
+            self.sortBy.build_ordering(compiler)
+
+        if self.filter is not None:
+            # Generate the internal query object from the <fes:Filter>,
+            # this can return a Q object.
+            return self.filter.build_query(compiler)
+        else:
+            return None
+
+    def as_kvp(self) -> dict:
+        """Translate the POST request into KVP GET parameters. This is needed for pagination."""
+        params = super().as_kvp()
+        params["TYPENAMES"] = ",".join(self.typeNames)
+        if self.srsName is not None:
+            params["SRSNAME"] = str(self.srsName)
+
+        if self.filter is not None:
+            raise NotImplementedError()  # not going to parse that, nor does mapserver
+        if self.sortBy is not None:
+            params["SORTBY"] = self.sortBy.as_kvp()
+
+        return params

gisserver/parsers/wfs20/base.py

@@ -0,0 +1,148 @@
+"""Entry point to handle queries.
+
+WFS defines 2 query types:
+- Adhoc queries are constructed directly from request parameters.
+- Stored queries are defined first, and executed later.
+
+Both use the FES (Filter Encoding Syntax) filtering logic internally.
+
+The objects in this module closely follow the WFS spec.
+By using the same type definitions, a lot of code logic follows naturally.
+"""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from django.db.models import Q, QuerySet
+
+from gisserver.exceptions import (
+    ExternalValueError,
+    InvalidParameterValue,
+    OperationNotSupported,
+)
+from gisserver.features import FeatureType
+from gisserver.parsers import fes20, wfs20
+from gisserver.parsers.ast import AstNode
+from gisserver.parsers.query import CompiledQuery
+from gisserver.projection import FeatureProjection
+
+
+class QueryExpression(AstNode):
+    """WFS base class for all queries.
+    This object type is defined in the WFS spec (as ``<fes:AbstractQueryExpression>``).
+
+    The WFS server can initiate queries in multiple ways.
+    This class provides the common interface for all these query types;
+    whether the request provided "ad-hoc" parameters or called a stored procedure.
+    Each query type has its own way of generating the actual database statement to perform.
+
+    The subclasses can override the following logic:
+
+    * :meth:`get_type_names` defines which types this query applies to.
+    * :meth:`build_query` defines how to filter the queryset.
+
+    For full control, these methods can also be overwritten instead:
+
+    * :meth:`get_queryset` defines the full results.
+    """
+
+    #: Configuration for the 'locator' argument in exceptions
+    query_locator: ClassVar[str] = None
+
+    # QueryExpression
+    #: The 'handle' that will be returned in exceptions.
+    handle: str = ""
+
+    #: Projection parameters (overwritten by subclasses)
+    #: In the WFS spec, this is only part of the operation/presentation.
+    #: For Django, we'd like to make this part of the query too.
+    property_names: list[wfs20.PropertyName] | None = None  # PropertyName
+
+    #: The valueReference for the GetPropertyValue call, provided here for extra ORM filtering.
+    value_reference: fes20.ValueReference | None = None
+
+    def bind(
+        self,
+        feature_types: list[FeatureType],
+        value_reference: fes20.ValueReference | None = None,
+    ):
+        """Bind the query to context outside its tag definition.
+
+        :param feature_types: The corresponding feature types for :meth:`get_type_names`.
+        :param value_reference: Which field is returned (by ``GetPropertyValue``)
+        """
+        # Store the resolved feature types
+        self.feature_types = feature_types
+
+        # for GetPropertyValue
+        if value_reference is not None:
+            self.value_reference = value_reference
+
+    def get_queryset(self) -> QuerySet:
+        """Generate the queryset for the specific feature type.
+
+        This method can be overwritten in subclasses to define the returned data.
+        However, consider overwriting :meth:`build_query` instead of simple data.
+        """
+        if len(self.feature_types) > 1:
+            raise OperationNotSupported("Join queries are not supported", locator="typeNames")
+
+        # To apply the filters, an internal CompiledQuery object is created.
+        # This collects all steps, to create the final QuerySet object.
+        # The build_query() method may return an Q object, or fill the compiler itself.
+        compiler = CompiledQuery(self.feature_types)
+        q_object = self.build_query(compiler)
+        if q_object is not None:
+            compiler.add_lookups(q_object)
+
+        # While property names are projection, this hook should
+        # make it possible to perform extra query adjustments for complex expressions.
+        if self.property_names:
+            for property_name in self.property_names:
+                property_name.decorate_query(compiler)
+
+        if self.value_reference is not None:
+            try:
+                self.value_reference.parse_xpath(self.feature_types)
+            except ExternalValueError as e:
+                raise InvalidParameterValue(
+                    f"Field '{self.value_reference.xpath}' does not exist.",
+                    locator="valueReference",
+                ) from e
+
+            # For GetPropertyValue, adjust the query so only that value is requested.
+            # This makes sure XPath attribute selectors are already handled by the
+            # database query, instead of being a presentation-layer handling.
+            # This supports cases like: ``addresses/Address[street="Oxfordstrasse"]/number``
+            field = self.value_reference.build_rhs(compiler)
+
+            queryset = compiler.get_queryset()
+            return queryset.values("pk", member=field)
+        else:
+            return compiler.get_queryset()
+
+    def get_type_names(self) -> list[str]:
+        """Tell which type names this query applies to.
+        Multiple values means a JOIN is made (not supported yet).
+
+        This method needs to be defined in subclasses.
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__}.get_type_names() should be implemented."
+        )
+
+    def get_projection(self) -> FeatureProjection:
+        """Tell how the query should be displayed."""
+        raise NotImplementedError()
+
+    def build_query(self, compiler: CompiledQuery) -> Q | None:
+        """Define the compiled query that filters the queryset."""
+        raise NotImplementedError()
+
+    def as_kvp(self) -> dict:
+        """Translate the POST request into KVP GET parameters. This is needed for pagination."""
+        params = {}
+        if self.property_names:
+            params["PROPERTYNAME"] = ",".join(p.xpath for p in self.property_names)
+        return params

gisserver/parsers/wfs20/projection.py

@@ -0,0 +1,103 @@
+"""Projection tag parsing for WFS 2.0"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+from gisserver.exceptions import (
+    InvalidParameterValue,
+    OperationParsingFailed,
+    OperationProcessingFailed,
+)
+from gisserver.parsers.ast import AstNode, tag_registry
+from gisserver.parsers.query import CompiledQuery
+from gisserver.parsers.xml import NSElement, xmlns
+from gisserver.types import XPathMatch
+
+
+class ResolveValue(Enum):
+    """The ``wfs:ResolveValueType`` enum, used by :class:`StandardResolveParameters`."""
+
+    local = "local"
+    remote = "remote"
+    all = "all"
+    none = "none"
+
+    @classmethod
+    def _missing_(cls, value):
+        raise OperationParsingFailed(f"Invalid resolve value: {value}", locator="resolve")
+
+
+@dataclass
+@tag_registry.register("PropertyName", xmlns.wfs)
+class PropertyName(AstNode):
+    """The ``<wfs:PropertyName>`` element in the projection clause.
+
+    This parses and handles the syntax::
+
+        <wfs:PropertyName>ns0:tagname</wfs:PropertyName>
+
+    More advanced syntax is not supported, such as::
+
+      <wfs:PropertyName resolve="all" resolvePath="valueOf(relatedTo)">valueOf(registerEntry)</wfs:PropertyName>
+
+    Note this element exists in the WFS namespace, not the FES namespace!
+    The ``<fes:PropertyName>`` is an old FES 1.x element that has been replaced by ``<fes:ValueReference>``.
+    The old ``<fes:PropertyName>`` is still supported as an alias by this server.
+    """
+
+    xpath: str  # Officially only a 'QName'
+    xpath_ns_aliases: dict[str, str]
+
+    # Unused, yet included for completeness.
+    # These are available in the XML syntax, and override
+    # the default given in the <wfs:GetFeature> element.
+    resolve: ResolveValue = ResolveValue.none
+    resolve_depth: int | None = None
+    resolve_path: str | None = None
+    resolve_timeout: int = 300
+
+    @classmethod
+    def from_xml(cls, element: NSElement):
+        """Parse the XML tag."""
+        depth = parse_resolve_depth(element.attrib.get("resolveDepth", None))
+        return cls(
+            xpath=element.text,
+            resolve=ResolveValue[element.attrib.get("resolve", "none")],
+            resolve_depth=depth,
+            resolve_path=element.attrib.get("resolvePath"),
+            resolve_timeout=element.get_int_attribute("resolveTimeout", 300),
+            xpath_ns_aliases=element.ns_aliases,
+        )
+
+    def parse_xpath(self, feature_types: list) -> XPathMatch:
+        """Convert the XPath into the required ORM query elements."""
+        if self.resolve_path:
+            raise OperationProcessingFailed("resolvePath is not supported", locator="propertyName")
+        if "valueOf(" in self.xpath or (self.resolve_path and "valueOf(" in self.resolve_path):
+            raise OperationProcessingFailed(
+                "valueOf(..) syntax is not supported", locator="propertyName"
+            )
+
+        # Can resolve against XSD paths, find the correct DB field name
+        return feature_types[0].resolve_element(self.xpath, self.xpath_ns_aliases)
+
+    def decorate_query(self, compiler: CompiledQuery):
+        """Update the low-level query based on this property projection."""
+        # This will also validate the name because it resolves the ORM path.
+        # The actual limiting of fields happens inside the decorate_queryset() of the renderer.
+        xpath_match = self.parse_xpath(compiler.feature_types)
+        if xpath_match.orm_filters:
+            # Apply any xpath [attr=value] lookups.
+            compiler.add_extra_lookup(xpath_match.orm_filters)
+
+
+def parse_resolve_depth(depth: str | None) -> int | None:
+    """Parse the resolve depth value."""
+    try:
+        return None if depth is None or depth == "*" else int(depth)
+    except (ValueError, TypeError) as e:
+        raise InvalidParameterValue(
+            "ResolveDepth must be an integer or '*'", locator="resolveDepth"
+        ) from e