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

gisserver/templates/gisserver/wfs/feature_type.html

@@ -1,19 +1,41 @@
-{% load i18n %}
-<h3>{{ feature_type.title }}</h3>
-{% if feature_type.abstract %}{{ feature_type.abstract|linebreaks }}{% endif %}
+{% load i18n gisserver_tags %}
 
-{% block formats %}{% if wfs_output_formats %}
-  <p>
-    {% trans "Formats" %}:
-    {% for output_format in wfs_output_formats %}
-      <a href="?{{ base_query }}SERVICE=WFS&VERSION={{ version }}&REQUEST=GetFeature&TYPENAMES={{ feature_type.name }}&OUTPUTFORMAT={{ output_format.identifier }}">{{ output_format.title|default:output_format }}</a>{% if not forloop.last %},{% endif %}
-    {% endfor %}
-  </p>
-{% endif %}{% endblock %}
+{% block title %}<h3><a id="feature-{{ feature_type.name }}">{{ feature_type.title }}</a></h3>{% endblock %}
+{% block description %}
+  {% if feature_type.abstract %}{{ feature_type.abstract|linebreaks }}{% endif %}
+{% endblock %}
+
+{% block metadata %}
+  <dl>
+  {% block metadata-items %}
+    <dt>{% translate "XML Namespace" %}:</dt><dd><code>{{ feature_type.xml_namespace }}</code></dd>
+    <dt>{% translate "Typename" %}:</dt><dd><abbr title="{{ feature_type.xml_name }}">{% feature_qname feature_type %}</abbr></dd>
+    <dt>{% translate "Supported CRS" %}:</dt>
+    <dd>
+      {% if GISSERVER_SUPPORTED_CRS_ONLY %}
+        {% blocktranslate with default_crs=feature_type.crs %}Any CRS value is supported, source data uses {{ default_crs }}.{% endblocktranslate %}
+      {% else %}
+        {{ feature_type.supported_crs|join:", " }}
+      {% endif %}
+    </dd>
+    {% if wfs_output_formats %}
+      <dt>{% translate "Formats" %}:</dt>
+      <dd>{% block metadata-formats %}
+        {% for output_format in wfs_output_formats %}
+            <a href="?{{ base_query }}SERVICE=WFS&VERSION={{ version }}&REQUEST=GetFeature&TYPENAMES={% feature_qname feature_type %}&OUTPUTFORMAT={{ output_format.identifier }}">{{ output_format.title|default:output_format }}</a>{% block format-sep %},{% endblock %}
+        {% endfor %}
+        <a href="?{{ base_query }}SERVICE=WFS&VERSION={{ version }}&REQUEST=DescribeFeatureType&TYPENAMES={% feature_qname feature_type %}">XML Schema</a>
+      {% endblock %}
+    </dd>
+    {% endif %}
+  {% endblock %}
+  </dl>
+{% endblock %}
 
 {% block fields %}
-<p>{% trans "Fields" %}:</p>
-<table>
+<p>{% translate "The following fields are available:" %}</p>
+<table class="table table-striped">
+  <thead><tr><th>{% translate "Field Name" %}</th><th>{% translate "Type" %}</th><th>{% translate "Description" %}</th></tr></thead>
   <tbody>
   {% for field in feature_type.fields %}
     {% include "gisserver/wfs/feature_field.html" with level=0 %}

gisserver/types.py

@@ -30,9 +30,10 @@ import logging
 import operator
 import re
 from dataclasses import dataclass, field
+from datetime import date, datetime, time, timedelta
 from decimal import Decimal as D
 from enum import Enum
-from functools import cached_property, reduce
+from functools import cached_property
 from typing import TYPE_CHECKING, Literal
 
 import django
@@ -42,16 +43,15 @@ from django.core.exceptions import ObjectDoesNotExist, ValidationError
 from django.db import models
 from django.db.models import Q
 from django.db.models.fields.related import RelatedField
-from django.utils import dateparse
 
 from gisserver.compat import ArrayField, GeneratedField
+from gisserver.crs import CRS
 from gisserver.exceptions import ExternalParsingError, OperationProcessingFailed
-from gisserver.geometries import CRS, BoundingBox
+from gisserver.geometries import BoundingBox
 from gisserver.parsers import values
 from gisserver.parsers.xml import parse_qname, split_ns, xmlns
 
 logger = logging.getLogger(__name__)
-_unbounded = Literal["unbounded"]
 
 __all__ = [
     "GeometryXsdElement",
@@ -98,13 +98,13 @@ class XsdAnyType:
 
 
 class XsdTypes(XsdAnyType, Enum):
-    """Brief enumeration of basic XMLSchema types.
+    """Brief enumeration of common XMLSchema types.
 
     The :class:`XsdElement` and :class:`XsdAttribute` can use these enum members
     to indicate their value is a well-known XML Schema. Some GML types are included as well.
 
-    The default namespace is the "xs:" (XMLSchema).
-    Based on https://www.w3.org/TR/xmlschema-2/#built-in-datatypes
+    Each member value is a fully qualified XML name.
+    The output rendering will convert these to the chosen prefixes.
     """
 
     anyType = xmlns.xs.qname("anyType")  # not "xsd:any", that is an element.
@@ -149,16 +149,25 @@ class XsdTypes(XsdAnyType, Enum):
     gmlMultiCurvePropertyType = xmlns.gml.qname("MultiCurvePropertyType")
     gmlMultiGeometryPropertyType = xmlns.gml.qname("MultiGeometryPropertyType")
 
-    # Other typical GML values
+    # Other typical GML values:
+
+    #: The type for ``<gml:name>`` elements.
     gmlCodeType = xmlns.gml.qname("CodeType")  # for <gml:name>
-    gmlBoundingShapeType = xmlns.gml.qname("BoundingShapeType")  # for <gml:boundedBy>
 
-    #: A direct geometry value (used as function argument type)
+    #: The type for ``<gml:boundedBy>`` elements.
+    gmlBoundingShapeType = xmlns.gml.qname("BoundingShapeType")
+
+    #: The type for ``<gml:Envelope>`` elements, sometimes used as function argument type.
+    gmlEnvelopeType = xmlns.gml.qname("EnvelopeType")
+
+    #: A direct geometry value, sometimes used as function argument type.
     gmlAbstractGeometryType = xmlns.gml.qname("AbstractGeometryType")
 
     #: A feature that has a gml:name and gml:boundedBy as possible child element.
     gmlAbstractFeatureType = xmlns.gml.qname("AbstractFeatureType")
-    gmlAbstractGMLType = xmlns.gml.qname("AbstractGMLType")  # base of gml:AbstractFeatureType
+
+    #: The base of gml:AbstractFeatureType
+    gmlAbstractGMLType = xmlns.gml.qname("AbstractGMLType")
 
     def __str__(self):
         return self.value
@@ -184,9 +193,12 @@ class XsdTypes(XsdAnyType, Enum):
             raise NotImplementedError(f'Casting to "{self}" is not implemented.') from None
 
     def to_python(self, raw_value):
-        """Convert a raw string value to this type representation"""
-        if self.is_geometry:
-            # Leave complex values as-is.
+        """Convert a raw string value to this type representation.
+
+        :raises ExternalParsingError: When the value can't be converted to the proper type.
+        """
+        if self.is_geometry or isinstance(raw_value, TYPES_AS_PYTHON[self]):
+            # Detect when the value was already parsed, no need to reparse a date for example.
             return raw_value
 
         try:
@@ -195,6 +207,7 @@ class XsdTypes(XsdAnyType, Enum):
             raise  # subclass of ValueError so explicitly caught and reraised
         except (TypeError, ValueError, ArithmeticError) as e:
             # ArithmeticError is base of DecimalException
+            logger.debug("Parsing error for %r: %s", raw_value, e)
             name = self.name if self.namespace == xmlns.xsd.value else self.value
             raise ExternalParsingError(f"Can't cast '{raw_value}' to {name}.") from e
 
@@ -221,12 +234,12 @@ def _as_is(v):
     return v
 
 
-TYPES_TO_PYTHON = {
-    XsdTypes.date: dateparse.parse_date,
-    XsdTypes.dateTime: values.parse_iso_datetime,
-    XsdTypes.time: dateparse.parse_time,
-    XsdTypes.string: _as_is,
-    XsdTypes.boolean: values.parse_bool,
+TYPES_AS_PYTHON = {
+    XsdTypes.date: date,
+    XsdTypes.dateTime: datetime,
+    XsdTypes.time: time,
+    XsdTypes.string: str,
+    XsdTypes.boolean: bool,
     XsdTypes.integer: int,
     XsdTypes.int: int,
     XsdTypes.long: int,
@@ -236,9 +249,28 @@ TYPES_TO_PYTHON = {
     XsdTypes.unsignedLong: int,
     XsdTypes.unsignedShort: int,
     XsdTypes.unsignedByte: int,
-    XsdTypes.float: D,
+    XsdTypes.float: D,  # auto_cast() always converts to decimal
     XsdTypes.double: D,
     XsdTypes.decimal: D,
+    XsdTypes.duration: timedelta,
+    XsdTypes.nonNegativeInteger: int,
+    XsdTypes.gYear: int,
+    XsdTypes.hexBinary: bytes,
+    XsdTypes.base64Binary: bytes,
+    XsdTypes.token: str,
+    XsdTypes.language: str,
+    XsdTypes.gmlCodeType: str,
+    XsdTypes.anyType: type(Ellipsis),
+}
+
+TYPES_TO_PYTHON = {
+    **TYPES_AS_PYTHON,
+    XsdTypes.date: values.parse_iso_date,
+    XsdTypes.dateTime: values.parse_iso_datetime,
+    XsdTypes.time: values.parse_iso_time,
+    XsdTypes.string: _as_is,
+    XsdTypes.boolean: values.parse_bool,
+    XsdTypes.duration: values.parse_iso_duration,
     XsdTypes.gmlCodeType: _as_is,
     XsdTypes.anyType: values.auto_cast,
 }
@@ -252,11 +284,16 @@ class XsdNode:
     parse query input and read model attributes to write as output.
     """
 
+    #: Whether this node is an :class:`XsdAttribute` (avoids slow ``isinstance()`` checks)
     is_attribute = False
+    #: Whether this node can occur multiple times.
     is_many = False
 
+    #: The local name of the XML element
     name: str
-    type: XsdAnyType  # Both XsdComplexType and XsdType are allowed
+
+    #: The data type of the element/attribute, both :class:`XsdComplexType` and :class:`XsdTypes` are allowed.
+    type: XsdAnyType
 
     #: XML Namespace of the element
     namespace: xmlns | str | None
@@ -269,7 +306,7 @@ class XsdNode:
     #: This supports dot notation to access related attributes.
     model_attribute: str | None
 
-    #: A link back to the parent that described the featuyre this node is a part of.
+    #: A link back to the parent that described the feature this node is a part of.
     #: This helps to perform additional filtering in side meth:get_value: based on user policies.
     feature_type: FeatureType | None
 
@@ -291,7 +328,8 @@ class XsdNode:
         :param source: Original Model field, which can provide more metadata/parsing.
         :param model_attribute: The Django model path that this element accesses.
         :param absolute_model_attribute: The full path, including parent elements.
-        :param feature_type: Typically assigned in :meth:`bind`, needed by some :meth:`get_value` functions.
+        :param feature_type: Typically assigned in :meth:`~gisserver.features.FeatureField.bind`,
+                             needed by some :meth:`get_value` functions.
         """
         if ":" in name:
             raise ValueError(
@@ -466,7 +504,9 @@ class XsdNode:
         return value
 
     def to_python(self, raw_value: str):
-        """Convert a raw value to the Python data type for this element type."""
+        """Convert a raw value to the Python data type for this element type.
+        :raises ValidationError: When the value isn't allowed for the field type.
+        """
         try:
             raw_value = self.type.to_python(raw_value)
             if self.source is not None:
@@ -493,30 +533,33 @@ class XsdNode:
         :param tag: The filter operator tag name, e.g. ``PropertyIsEqualTo``.
         :returns: The parsed Python value.
         """
-        if self.source is not None:
-            # Not calling self.source.validate() as that checks for allowed choices,
-            # which shouldn't be checked against for a filter query.
-            raw_value = self.to_python(raw_value)
-
-            # Check whether the Django model field supports the lookup
-            # This prevents calling LIKE on a datetime or float field.
-            # For foreign keys, this depends on the target field type.
-            if self.source.get_lookup(lookup) is None or (
+        # Not calling self.source.validate() as that checks for allowed choices,
+        # which shouldn't be checked against for a filter query.
+        raw_value = self.to_python(raw_value)
+
+        # Check whether the Django model field supports the lookup
+        # This prevents calling LIKE on a datetime or float field.
+        # For foreign keys, this depends on the target field type.
+        if (
+            self.source is not None
+            and self.source.get_lookup(lookup) is None
+            or (
                 isinstance(self.source, RelatedField)
                 and self.source.target_field.get_lookup(lookup) is None
-            ):
-                logger.debug(
-                    "Model field '%s.%s' does not support ORM lookup '%s' used by '%s'.",
-                    self.feature_type.model._meta.model_name,
-                    self.absolute_model_attribute,
-                    lookup,
-                    tag,
-                )
-                raise OperationProcessingFailed(
-                    f"Operator '{tag}' is not supported for the '{self.name}' property.",
-                    locator="filter",
-                    status_code=400,  # not HTTP 500 here. Spec allows both.
-                )
+            )
+        ):
+            logger.debug(
+                "Model field '%s.%s' does not support ORM lookup '%s' used by '%s'.",
+                self.feature_type.model._meta.model_name,
+                self.absolute_model_attribute,
+                lookup,
+                tag,
+            )
+            raise OperationProcessingFailed(
+                f"Operator '{tag}' is not supported for the '{self.name}' property.",
+                locator="filter",
+                status_code=400,  # not HTTP 500 here. Spec allows both.
+            )
 
         return raw_value
 
@@ -529,18 +572,21 @@ class XsdElement(XsdNode):
     This holds the definition for a single property in the WFS server.
     It's used in ``DescribeFeatureType`` to output the field metadata,
     and used in ``GetFeature`` to access the actual value from the object.
-    Overriding :meth:`get_value` allows to override this logic.
+    Overriding :meth:`XsdNode.get_value` allows to override this logic.
 
-    The :attr:`name` may differ from the underlying :attr:`model_attribute`,
+    The :attr:`name` may differ from the underlying :attr:`XsdNode.model_attribute`,
     so the WFS server can use other field names then the underlying model.
 
-    A dotted-path notation can be used for :attr:`model_attribute` to access
+    A dotted-path notation can be used for :attr:`XsdNode.model_attribute` to access
     a related field. For the WFS client, the data appears to be flattened.
     """
 
+    #: Whether the element can be null
     nillable: bool | None
+    #: The minimal number of times the element occurs in the output.
     min_occurs: int | None
-    max_occurs: int | _unbounded | None
+    #: The maximum number of times this element occurs in the output.
+    max_occurs: int | Literal["unbounded"] | None
 
     def __init__(
         self,
@@ -550,7 +596,7 @@ class XsdElement(XsdNode):
         *,
         nillable: bool | None = None,
         min_occurs: int | None = None,
-        max_occurs: int | _unbounded | None = None,
+        max_occurs: int | Literal["unbounded"] | None = None,
         source: models.Field | models.ForeignObjectRel | None = None,
         model_attribute: str | None = None,
         absolute_model_attribute: str | None = None,
@@ -661,8 +707,8 @@ class GeometryXsdElement(XsdElement):
 
 
 class GmlIdAttribute(XsdAttribute):
-    """A virtual 'gml:id' attribute that can be queried.
-    This subclass has overwritten get_value() logic to format the value.
+    """A virtual ``gml:id="..."`` attribute that can be queried.
+    This subclass has overwritten :meth:`get_value` logic to format the value.
     """
 
     type_name: str
@@ -686,6 +732,7 @@ class GmlIdAttribute(XsdAttribute):
         object.__setattr__(self, "type_name", type_name)
 
     def get_value(self, instance: models.Model):
+        """Render the value."""
         pk = super().get_value(instance)  # handle dotted-name notations
         return f"{self.type_name}.{pk}"
 
@@ -695,7 +742,7 @@ class GmlIdAttribute(XsdAttribute):
 
 
 class GmlNameElement(XsdElement):
-    """A subclass to handle the <gml:name> element.
+    """A subclass to handle the ``<gml:name>`` element.
     This displays a human-readable title for the object.
 
     Currently, this just reads a single attribute,
@@ -731,7 +778,7 @@ class GmlNameElement(XsdElement):
 
 
 class GmlBoundedByElement(XsdElement):
-    """A subclass to handle the <gml:boundedBy> element.
+    """A subclass to handle the ``<gml:boundedBy>`` element.
 
     This override makes sure this non-model element data
     can be included in the XML tree like every other element.
@@ -780,38 +827,55 @@ class GmlBoundedByElement(XsdElement):
         if not geometries:
             return None
 
-        # Perform the combining of geometries inside libgeos
-        if len(geometries) == 1:
-            geometry = geometries[0]
-        else:
-            geometry = reduce(operator.or_, geometries)
-            if crs is not None and geometry.srid != crs.srid:
-                crs.apply_to(geometry)  # avoid clone
-
-        return BoundingBox.from_geometry(geometry, crs=crs)
+        return BoundingBox.from_geometries(geometries, crs)
 
 
 @dataclass(frozen=True)
 class XsdComplexType(XsdAnyType):
-    """Define an <xsd:complexType> that represents a whole class definition.
+    """Define an ``<xsd:complexType>`` that represents a whole class definition.
 
     Typically, this maps into a Django model, with each element pointing to a model field.
+    For example:
+
+    .. code-block:: python
+
+        XsdComplexType(
+            "PersonType",
+            elements=[
+                XsdElement("name", type=XsdTypes.string),
+                XsdElement("age", type=XsdTypes.integer),
+                XsdElement("address", type=XsdComplexType(
+                    "AddressType",
+                    elements=[
+                        XsdElement("street", type=XsdTypes.string),
+                        ...
+                    ]
+                )),
+            ],
+            attributes=[
+                XsdAttribute("id", type=XsdTypes.integer),
+            ],
+        )
 
     A complex type can hold multiple :class:`XsdElement` and :class:`XsdAttribute`
-    nodes as children, composing an object. The elements themselves can point
-    to a complex type themselves, to create a nested class structure.
+    nodes as children, composing an object. Its :attr:`base` may point to a :class:`XsdComplexType`
+    as base class, allowing to define those inherited elements too.
+
+    Each element can be a complex type themselves, to create a nested class structure.
     That also allows embedding models with their relations into a single response.
 
-    This object definition is the internal "source of truth" regarding
-    which field names and field elements are used in the WFS server.
-    The ``DescribeFeatureType`` request uses this definition to render the matching XMLSchema.
-    Incoming XPath queries are parsed using this object to resolve the XPath to model attributes.
+    .. note:: Good to know
+        This object definition is the internal "source of truth" regarding
+        which field names and field elements are used in the WFS server:
+
+        * The ``DescribeFeatureType`` request uses this definition to render the matching XMLSchema.
+        * Incoming XPath queries are parsed using this object to resolve the XPath to model attributes.
 
-    Objects of this type are typically generated by the ``FeatureType`` and
-    ``ComplexFeatureField`` classes, using the Django model data.
+    Objects of this type are typically generated by the :class:`~gisserver.features.FeatureType` and
+    :class:`~gisserver.features.ComplexFeatureField` classes, using the Django model data.
 
-    By default, The type is declared as subclass of <gml:AbstractFeatureType>,
-    which allows child elements like <gml:name> and <gml:boundedBy>.
+    By default, The :attr:`base` type is detected as ``<gml:AbstractFeatureType>``,
+    when there is a geometry element in the definition.
     """
 
     #: Internal class name (without XML namespace/prefix)
@@ -852,7 +916,8 @@ class XsdComplexType(XsdAnyType):
         return f"{{{self.namespace}}}{self.name}" if self.namespace else self.name
 
     @property
-    def is_complex_type(self):
+    def is_complex_type(self) -> bool:
+        """Always indicates this is a complex type."""
         return True  # a property to avoid being used as field.
 
     @cached_property
@@ -981,7 +1046,7 @@ class ORMPath:
 
     def build_lhs(self, compiler: CompiledQuery):
         """Give the ORM part when this element is used as left-hand-side of a comparison.
-        For example: "path == value".
+        For example: ``path == value``.
         """
         if self.is_many:
             compiler.add_distinct()
@@ -991,7 +1056,7 @@ class ORMPath:
 
     def build_rhs(self, compiler: CompiledQuery):
         """Give the ORM part when this element would be used as right-hand-side.
-        For example: "path == path" or "value == path".
+        For example: ``path1 == path2`` or ``value == path``.
         """
         if self.is_many:
             compiler.add_distinct()
@@ -1049,7 +1114,9 @@ class XPathMatch(ORMPath):
         return any(node.is_many for node in self.nodes)
 
     def build_lhs(self, compiler: CompiledQuery):
-        """Delegate the LHS construction to the final XsdNode."""
+        """Give the ORM part when this element is used as left-hand-side of a comparison.
+        For example: ``path == value``.
+        """
         if self.is_many:
             compiler.add_distinct()
         if self.orm_filters:
@@ -1057,7 +1124,9 @@ class XPathMatch(ORMPath):
         return self.child.build_lhs_part(compiler, self)
 
     def build_rhs(self, compiler: CompiledQuery):
-        """Delegate the RHS construction to the final XsdNode."""
+        """Give the ORM part when this element would be used as right-hand-side.
+        For example: ``path1 == path2`` or ``value == path``.
+        """
         if self.is_many:
             compiler.add_distinct()
         if self.orm_filters: