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

gisserver/db.py

@@ -5,11 +5,13 @@ from __future__ import annotations
 import logging
 from functools import lru_cache, reduce
 
-from django.contrib.gis.db.models import functions
+from django.contrib.gis.db.models import Extent, PolygonField, functions
+from django.contrib.gis.db.models.fields import ExtentField
 from django.db import connection, connections, models
 
 from gisserver import conf
-from gisserver.geometries import CRS
+from gisserver.crs import CRS, WGS84
+from gisserver.geometries import WGS84BoundingBox
 from gisserver.types import GeometryXsdElement
 
 logger = logging.getLogger(__name__)
@@ -29,6 +31,8 @@ class AsEWKT(functions.GeoFunc):
 
 
 class AsGML(functions.AsGML):
+    """An overwritten ST_AsGML() function to handle PostGIS extensions."""
+
     name = "AsGML"
 
     def __init__(
@@ -37,20 +41,61 @@ class AsGML(functions.AsGML):
         version=3,
         precision=conf.GISSERVER_DB_PRECISION,
         envelope=False,
+        is_latlon=False,
+        long_urn=False,
         **extra,
     ):
-        # Note that Django's AsGml, version=2, precision=8
-        # the options is postgres-only.
+        # Note that Django's AsGml the defaults are: version=2, precision=8
         super().__init__(expression, version, precision, **extra)
         self.envelope = envelope
+        self.is_latlon = is_latlon
+        self.long_urn = long_urn
 
     def as_postgresql(self, compiler, connection, **extra_context):
         # Fill options parameter (https://postgis.net/docs/ST_AsGML.html)
-        options = 33 if self.envelope else 1  # 32 = bbox, 1 = long CRS urn
+        options = 0
+        if self.long_urn:
+            options |= 1  # long CRS urn
+        if self.envelope:
+            options |= 32  # bbox
+        if self.is_latlon:
+            # PostGIS provides the data in longitude/latitude format (east/north to look like x/y).
+            # However, WFS 2.0 fixed their axis by following the authority. The ST_AsGML() doesn't
+            # detect this on their own. It needs to be told to flip the coordinates.
+            # Passing option 16 flips the coordinates unconditionally, like using ST_FlipCoordinates()
+            # but more efficiently done during rendering. That happens in:
+            # https://github.com/postgis/postgis/blob/81e2bc783b77cc740291445e992658e1db7179e0/liblwgeom/lwout_gml.c#L121
+            options |= 16
+
         template = f"%(function)s(%(expressions)s, {options})"
         return self.as_sql(compiler, connection, template=template, **extra_context)
 
 
+class ST_SetSRID(functions.Transform):
+    """PostGIS function to assign an SRID to geometry.
+    When this is applied to the result from an ``Extent`` aggegrate,
+    it will convert that ``BBOX(...)`` value into a ``POLYGON(...)``.
+    """
+
+    name = "SetSRID"
+    geom_param_pos = ()
+
+    @property
+    def geo_field(self):
+        return PolygonField(srid=self.source_expressions[1].value)
+
+
+class Box2D(functions.GeomOutputGeoFunc):
+    """PostGIS function (without ST_) that converts a ``POLYGON(...)`` back to a ``BOX(...)``."""
+
+    name = "Box2D"
+    function = "Box2D"  # no ST_ prefix.
+    output_field = ExtentField()
+
+    def convert_value(self, value, expression, connection):
+        return connection.ops.convert_extent(value)
+
+
 class ST_Union(functions.Union):
     name = "Union"
     arity = None
@@ -62,6 +107,31 @@ class ST_Union(functions.Union):
         return self.as_sql(compiler, connection, **extra_context)
 
 
+def get_wgs84_bounding_box(
+    queryset: models.QuerySet, geo_element: GeometryXsdElement
+) -> WGS84BoundingBox:
+    """Calculate the WGS84 bounding box for a feature.
+
+    Note that the ``<ows:WGS84BoundingBox>`` element
+    always uses longitude/latitude, and doesn't describe a CRS.
+    """
+    if connections[queryset.db].vendor == "postgresql":
+        # Allow a more efficient way to combine geometry first, transform once later
+        box = queryset.aggregate(
+            box=Box2D(
+                functions.Transform(
+                    ST_SetSRID(Extent(geo_element.orm_path), srid=geo_element.source_srid),
+                    srid=WGS84.srid,
+                )
+            )
+        )["box"]
+    else:
+        # Need to transform each element to srid 4326 before combining it in an extent.
+        box = queryset.aggregate(box=Extent(get_db_geometry_target(geo_element, WGS84)))["box"]
+
+    return WGS84BoundingBox(*box) if box else None
+
+
 def get_geometries_union(
     expressions: list[str | functions.GeoFunc], using="default"
 ) -> str | functions.Union:
@@ -86,6 +156,7 @@ def replace_queryset_geometries(
     geo_elements: list[GeometryXsdElement],
     output_crs: CRS,
     wrapper_func: type[functions.GeoFunc],
+    **wrapper_kwargs,
 ) -> models.QuerySet:
     """Replace the queryset geometry retrieval with a database-rendered version.
 
@@ -98,7 +169,8 @@ def replace_queryset_geometries(
             defer_names.append(geo_element.local_orm_path)
             annotation_name = _as_annotation_name(geo_element.local_orm_path, wrapper_func)
             as_geo_map[annotation_name] = wrapper_func(
-                get_db_geometry_target(geo_element, output_crs, use_relative_path=True)
+                get_db_geometry_target(geo_element, output_crs, use_relative_path=True),
+                **wrapper_kwargs,
             )
 
     if not defer_names:

gisserver/exceptions.py

@@ -8,13 +8,23 @@ https://docs.opengeospatial.org/is/09-025r2/09-025r2.html#35
 https://docs.opengeospatial.org/is/09-025r2/09-025r2.html#411
 """
 
+from __future__ import annotations
+
 import logging
+import typing
 from contextlib import contextmanager
 
 from django.conf import settings
+from django.core.exceptions import FieldError, ValidationError
+from django.db import InternalError, ProgrammingError
 from django.http import HttpResponse
 from django.utils.html import format_html
 
+from gisserver import conf
+
+if typing.TYPE_CHECKING:
+    from gisserver.parsers import wfs20
+
 logger = logging.getLogger(__name__)
 
 
@@ -35,6 +45,90 @@ def wrap_parser_errors(name: str, locator: str):
         raise InvalidParameterValue(f"Invalid {name} argument: {e}", locator=locator) from None
 
 
+@contextmanager
+def wrap_filter_errors(query: wfs20.QueryExpression):  # noqa:C901
+    """Perform a QuerySet/filter creation operation.
+    and trap many parser errors in the making of it."""
+    try:
+        yield
+    except ExternalParsingError as e:
+        # Bad input data
+        _log_filter_error(query, logging.ERROR, e)
+        raise OperationParsingFailed(str(e), locator=query.query_locator) from e
+    except ExternalValueError as e:
+        # Bad input data
+        _log_filter_error(query, logging.ERROR, e)
+        raise InvalidParameterValue(str(e), locator=query.query_locator) from e
+    except ValidationError as e:
+        # Bad input data
+        _log_filter_error(query, logging.ERROR, e)
+        raise OperationParsingFailed(
+            "\n".join(map(str, e.messages)),
+            locator=query.query_locator,
+        ) from e
+    except FieldError as e:
+        # e.g. doing a LIKE on a foreign key, or requesting an unknown field.
+        if not conf.GISSERVER_WRAP_FILTER_DB_ERRORS:
+            raise
+        _log_filter_error(query, logging.ERROR, e)
+        raise InvalidParameterValue(
+            "Internal error when processing filter",
+            locator=query.query_locator,
+        ) from e
+    except (InternalError, ProgrammingError) as e:
+        # e.g. comparing datetime against integer
+        if not conf.GISSERVER_WRAP_FILTER_DB_ERRORS:
+            raise
+        logger.exception("WFS request failed: %s\nQuery: %r", str(e), query)
+        msg = str(e)
+        locator = "srsName" if "Cannot find SRID" in msg else query.query_locator
+        raise InvalidParameterValue(f"Invalid request: {msg}", locator=locator) from e
+    except (TypeError, ValueError) as e:
+        # TypeError/ValueError could reference a datatype mismatch in an
+        # ORM query, but it could also be an internal bug. In most cases,
+        # this is already caught by XsdElement.validate_comparison().
+        raise
+        if _is_orm_error(e):
+            if query.query_locator == "STOREDQUERY_ID":
+                # This is a fallback, ideally the stored query performs its own validation.
+                raise InvalidParameterValue(
+                    f"Invalid stored query parameter: {e}", locator=query.query_locator
+                ) from e
+            else:
+                raise InvalidParameterValue(
+                    f"Invalid filter query: {e}", locator=query.query_locator
+                ) from e
+        raise
+
+
+def _is_orm_error(exception: Exception) -> bool:
+    """Tell whether an exception is caused by the ORM."""
+    traceback = exception.__traceback__
+    while traceback.tb_next is not None:
+        traceback = traceback.tb_next
+        if "/django/db/models/query" in traceback.tb_frame.f_code.co_filename:
+            return True
+    return False
+
+
+def _log_filter_error(query, level, exc):
+    """Report a filtering parsing error in the logging"""
+    filter = getattr(query, "filter", None)  # AdhocQuery only
+    fes_xml = filter.source if filter is not None else "(not provided)"
+    try:
+        sql = exc.__cause__.cursor.query.decode()
+    except AttributeError:
+        logger.log(level, "WFS query failed: %s\nFilter:\n%s", exc, fes_xml)
+    else:
+        logger.log(
+            level,
+            "WFS query failed: %s\nSQL Query: %s\n\nFilter:\n%s",
+            exc,
+            sql,
+            fes_xml,
+        )
+
+
 class ExternalValueError(ValueError):
     """Raise a ValueError for external input.
     This helps to distinguish between internal bugs
@@ -46,6 +140,14 @@ class ExternalParsingError(ValueError):
     """Raise a ValueError for a parsing problem."""
 
 
+class XmlElementNotSupported(ExternalParsingError):
+    """Raise a ValueError when an XML tag is not known by the parser at all."""
+
+
+class InvalidXmlElement(ExternalParsingError):
+    """Raise a ValueError when a particular XML tag wasn't expected."""
+
+
 class OWSException(Exception):
     """Base class for XML based exceptions in this module."""
 
@@ -68,7 +170,8 @@ class OWSException(Exception):
         self.code = code or self.code or self.__class__.__name__
         self.status_code = status_code or self.status_code
 
-    def as_response(self):
+    def as_response(self) -> HttpResponse:
+        """Return the excetion as HTTP response."""
         logger.debug("Returning HTTP %d for %s: %s", self.status_code, self.code, self.text)
         xml_body = self.as_xml()
         return HttpResponse(
@@ -78,7 +181,8 @@ class OWSException(Exception):
             reason=self.reason,
         )
 
-    def as_xml(self):
+    def as_xml(self) -> str:
+        """Serialize the exception to an XML string."""
         return format_html(
             "<ows:ExceptionReport"
             ' xmlns:ows="http://www.opengis.net/ows/1.1"'

gisserver/extensions/functions.py

@@ -1,4 +1,15 @@
-"""Functions to be callable from fes."""
+"""Functions to be callable from query filters.
+
+By using the :attr:`function_registry`, custom stored functions can be registered in this server.
+These are called by the filter queries using the :class:`~gisserver.parsers.fes20.expressions.Function` element.
+Out of the box, various built-in functions are present.
+
+Built-in options are documented in :ref:`functions`.
+
+Most of the out-of-the box options are inspired
+by `GeoServer <https://docs.geoserver.org/latest/en/user/filter/function_reference.html>`_.
+Functions which already have a fes-syntax equivalent have been are omitted.
+"""
 
 from __future__ import annotations
 
@@ -6,15 +17,16 @@ from collections.abc import Callable
 from dataclasses import dataclass
 from typing import Union
 
+import django
 from django.contrib.gis.db.models import functions as gis
 from django.db import models
 from django.db.models import functions
-from django.db.models.expressions import Combinable
+from django.db.models.expressions import Combinable, Value
 
 from gisserver.exceptions import InvalidParameterValue
 from gisserver.types import XsdTypes
 
-__all__ = ["function_registry"]
+__all__ = ["function_registry", "FesFunctionRegistry", "FesFunction"]
 
 FesArg = Union[Combinable, models.Q]
 FesFunctionBody = Union[models.Func, Callable[..., models.Func]]
@@ -22,7 +34,7 @@ FesFunctionBody = Union[models.Func, Callable[..., models.Func]]
 
 @dataclass(order=True)
 class FesFunction:
-    """A registered database function that can be used by ``<fes:Function name="...">`.
+    """A registered database function that can be used by ``<fes:Function name="...">``.
 
     The :class:`~gisserver.parsers.fes20.expressions.Function` class will resolve
     these registered functions by name, and call :meth:`build_query` to include them
@@ -65,9 +77,11 @@ class FesFunctionRegistry:
         self.functions = {}
 
     def __bool__(self):
+        """Tell whether there are functions"""
         return bool(self.functions)
 
     def __iter__(self):
+        """Iterate over the functions"""
         return iter(sorted(self.functions.values()))  # for template rendering
 
     def register(
@@ -112,15 +126,11 @@ class FesFunctionRegistry:
             ) from None
 
 
+#: The function registry
 function_registry = FesFunctionRegistry()
 
 
 # Register a set of default SQL functions.
-# These are based on GeoServer:
-# https://docs.geoserver.org/latest/en/user/filter/function_reference.html
-# Not implemented:
-# - Aggregates (like Collection_*)
-# - Comparisons (which already has fes variants)
 
 # -- strings
 
@@ -131,6 +141,27 @@ function_registry.register(
     returns=XsdTypes.string,
 )
 
+function_registry.register(
+    "strIndexOf",
+    lambda string, substring: (functions.StrIndex(string, Value(substring)) - 1),
+    arguments={"string": XsdTypes.string, "substring": XsdTypes.string},
+    returns=XsdTypes.string,
+)
+
+function_registry.register(
+    "strSubstring",
+    lambda string, begin, end: functions.Substr(string, begin + 1, end - begin),
+    arguments={"string": XsdTypes.string, "begin": XsdTypes.integer, "end": XsdTypes.integer},
+    returns=XsdTypes.string,
+)
+
+function_registry.register(
+    "strSubstringStart",
+    lambda string, begin, end: functions.Substr(string, begin + 1),
+    arguments={"string": XsdTypes.string, "begin": XsdTypes.integer},
+    returns=XsdTypes.string,
+)
+
 function_registry.register(
     "strToLowerCase",
     functions.Lower,
@@ -312,25 +343,25 @@ function_registry.register(
 # -- geometric
 
 function_registry.register(
-    "Area",
+    "area",
     gis.Area,
-    arguments={"geometry": XsdTypes.gmlAbstractGeometryType},
+    arguments={"geom": XsdTypes.gmlAbstractGeometryType},
     returns=XsdTypes.double,
 )
 
 function_registry.register(
-    "Centroid",
+    "centroid",
     gis.Centroid,
-    arguments={"features": XsdTypes.gmlAbstractGeometryType},
+    arguments={"geom": XsdTypes.gmlAbstractGeometryType},
     returns=XsdTypes.string,
 )
 
 function_registry.register(
-    "Difference",
+    "difference",
     gis.Difference,
     arguments={
-        "geometry1": XsdTypes.gmlAbstractGeometryType,
-        "geometry2": XsdTypes.gmlAbstractGeometryType,
+        "a": XsdTypes.gmlAbstractGeometryType,
+        "b": XsdTypes.gmlAbstractGeometryType,
     },
     returns=XsdTypes.string,
 )
@@ -339,35 +370,98 @@ function_registry.register(
     "distance",
     gis.Distance,
     arguments={
-        "geometry1": XsdTypes.gmlAbstractGeometryType,
-        "geometry2": XsdTypes.gmlAbstractGeometryType,
+        "a": XsdTypes.gmlAbstractGeometryType,
+        "b": XsdTypes.gmlAbstractGeometryType,
     },
     returns=XsdTypes.double,
 )
 
 function_registry.register(
-    "Envelope",
+    "envelope",
     gis.Envelope,
+    arguments={"geom": XsdTypes.gmlAbstractGeometryType},
+    returns=XsdTypes.gmlAbstractGeometryType,  # returns point or polygon
+)
+
+function_registry.register(
+    "geomLength",
+    gis.Length,
     arguments={"geometry": XsdTypes.gmlAbstractGeometryType},
-    returns=XsdTypes.string,
+    returns=XsdTypes.float,
 )
 
 function_registry.register(
-    "Intersection",
+    "intersection",
     gis.Intersection,
     arguments={
-        "geometry1": XsdTypes.gmlAbstractGeometryType,
-        "geometry2": XsdTypes.gmlAbstractGeometryType,
+        "a": XsdTypes.gmlAbstractGeometryType,
+        "b": XsdTypes.gmlAbstractGeometryType,
     },
-    returns=XsdTypes.string,
+    returns=XsdTypes.gmlAbstractGeometryType,
 )
 
+if django.VERSION >= (4, 2):
+    function_registry.register(
+        "isEmpty",
+        gis.IsEmpty,
+        arguments={
+            "geom": XsdTypes.gmlAbstractGeometryType,
+        },
+        returns=XsdTypes.boolean,
+    )
+
 function_registry.register(
-    "Union",
+    "isValid",
+    gis.IsValid,
+    arguments={
+        "geom": XsdTypes.gmlAbstractGeometryType,
+    },
+    returns=XsdTypes.boolean,
+)
+
+function_registry.register(
+    "numGeometries",
+    gis.NumGeometries,
+    arguments={
+        "collection": XsdTypes.gmlAbstractGeometryType,
+    },
+    returns=XsdTypes.integer,
+)
+
+function_registry.register(
+    "numPoints",
+    gis.NumPoints,
+    arguments={
+        "collection": XsdTypes.gmlAbstractGeometryType,
+    },
+    returns=XsdTypes.integer,
+)
+
+function_registry.register(
+    "perimeter",
+    gis.Perimeter,
+    arguments={
+        "geom": XsdTypes.gmlAbstractGeometryType,
+    },
+    returns=XsdTypes.integer,
+)
+
+function_registry.register(
+    "symDifference",
+    gis.SymDifference,
+    arguments={
+        "a": XsdTypes.gmlAbstractGeometryType,
+        "b": XsdTypes.gmlAbstractGeometryType,
+    },
+    returns=XsdTypes.gmlAbstractGeometryType,
+)
+
+function_registry.register(
+    "union",
     gis.Union,
     arguments={
-        "geometry1": XsdTypes.gmlAbstractGeometryType,
-        "geometry2": XsdTypes.gmlAbstractGeometryType,
+        "a": XsdTypes.gmlAbstractGeometryType,
+        "b": XsdTypes.gmlAbstractGeometryType,
     },
-    returns=XsdTypes.string,
+    returns=XsdTypes.gmlAbstractGeometryType,
 )

gisserver/extensions/queries.py

@@ -1,8 +1,8 @@
 """Storage and registry for stored queries.
 These definitions follow the WFS spec.
 
-By using the registry, custom stored queries can be registered in this server.
-Out of the box, only the mandatory built-in ``GetFeatureById`` query is present.
+By using the :attr:`stored_query_registry`, custom stored queries can be registered in this server.
+Out of the box, only the mandatory built-in :class:`GetFeatureById` query is present.
 """
 
 from __future__ import annotations
@@ -30,10 +30,14 @@ __all__ = (
     "StoredQueryDescription",
     "StoredQueryRegistry",
     "stored_query_registry",
+    "WFS_LANGUAGE",
+    "FES_LANGUAGE",
 )
 
-WFS_LANGUAGE = "urn:ogc:def:queryLanguage:OGC-WFS::WFS_QueryExpression"  # body is <wfs:Query>
-FES_LANGUAGE = "urn:ogc:def:queryLanguage:OGC-FES:Filter"  # body is <fes:Filter>
+#: The query body is a ``<wfs:Query>``.
+WFS_LANGUAGE = "urn:ogc:def:queryLanguage:OGC-WFS::WFS_QueryExpression"
+#: The query body is a ``<fes:Filter>``.
+FES_LANGUAGE = "urn:ogc:def:queryLanguage:OGC-FES:Filter"
 
 
 @dataclass
@@ -41,7 +45,7 @@ class QueryExpressionText:
     """Define the body of a stored query.
 
     This object type is defined in the WFS spec.
-    It may contain a wfs:Query or wfs:StoredQuery element.
+    It may contain a ``<wfs:Query>`` or ``<fes:Filter>`` element.
     """
 
     #: Which types the query will return.
@@ -61,7 +65,7 @@ class StoredQueryDescription:
     This is based on the ``<wfs:StoredQueryDescription>`` element,
     and returned in ``DescribeStoredQueries``.
 
-    While it's possible to define multiple QueryExpressionText nodes
+    While it's possible to define multiple :class:`QueryExpressionText` nodes
     as metadata to describe a query, there is still only one implementation.
     Note there is no 'typeNames=...' parameter for stored queries.
     Only direct parameters act as input.
@@ -127,7 +131,7 @@ class StoredQueryImplementation:
 
 
 class StoredQueryRegistry:
-    """Registry of functions to be callable by <wfs:StoredQuery>."""
+    """Registry of functions to be callable by ``<wfs:StoredQuery>`` and ``STOREDQUERY_ID=...``."""
 
     def __init__(self):
         self.stored_queries: dict[str, type(StoredQueryImplementation)] = {}
@@ -157,8 +161,7 @@ class StoredQueryRegistry:
             raise TypeError("Either provide the 'meta' object or 'meta_kwargs'")
 
         if query_expression is not None:
-            self._register(meta, query_expression)
-            return meta
+            return self._register(meta, query_expression)
         else:
             return partial(self._register, meta)  # decorator effect.
 
@@ -174,6 +177,7 @@ class StoredQueryRegistry:
         # for now link both. There is always a single implementation for the metadata.
         meta.implementation_class = implementation_class
         self.stored_queries[meta.id] = meta
+        return implementation_class  # for decorator usage
 
     def resolve_query(self, query_id) -> type[StoredQueryDescription]:
         """Find the stored procedure using the ID."""
@@ -186,6 +190,7 @@ class StoredQueryRegistry:
             ) from None
 
 
+#: The stored query registry
 stored_query_registry = StoredQueryRegistry()
 
 
@@ -211,7 +216,7 @@ class GetFeatureById(StoredQueryImplementation):
 
     The execution of the ``GetFeatureById`` query is essentially the same as::
 
-        <wfs:Query xmlns:wfs='..." xmlns:fes='...'>
+        <wfs:Query xmlns:wfs="..." xmlns:fes="...'>
           <fes:Filter><fes:ResourceId rid='{ID}'/></fes:Filter>
         </wfs:Query>