Require EPSG when requesting geometry return fields too.

Author: Roel

docs/output_fields.rst

@@ -53,37 +53,23 @@ Finding geometry columns
     from pydov.search.boring import BoringSearch
 
     bs = BoringSearch()
-    print([f for f in bs.get_fields().values() if f['type'] == 'geometry'])
+    print(bs.get_fields(type='geometry'))
 
-    [{'name': 'geom', 'definition': None, 'type': 'geometry', 'notnull': False, 'query': False, 'cost': 1}]
+    {'geom': {'name': 'geom', 'definition': None, 'type': 'geometry', 'list': False, 'notnull': False, 'query': False, 'cost': 1}}
 
 
-Default coordinate reference system
-  When adding the geometry field as return field, you will get the corresponding geometry in the default coordinate reference system (CRS) of the layer - most of our layers use the Belgian Lambert 72 CRS (EPSG:31370) by default::
+Adding geometry return fields
+  To add geometry columns as return field, you can add an instance of :class:`pydov.search.fields.GeometryReturnField` specifying both the geometry field name and the desired CRS::
 
     df = bs.search(
-        return_fields=['pkey_boring', 'geom'],
+        return_fields=['pkey_boring', GeometryReturnField('geom', epsg=31370)],
         max_features=1
     )
     print(df)
 
                                               pkey_boring                  geom
     0  https://www.dov.vlaanderen.be/data/boring/2016...  POINT (92424 170752)
 
-Custom coordinate reference systems
-  To get the geometry in another CRS, instead of adding just the fieldname as return field, you can add an instance of :class:`pydov.search.fields.GeometryReturnField` specifying both the field name and the desired CRS. If you'd like to receive the geometries in GPS coordinates (lon/lat, or EPSG:4326) instead of Belgian Lambert 72, you could::
-
-      from pydov.search.fields import GeometryReturnField
-
-      df = bs.search(
-          return_fields=['pkey_boring', GeometryReturnField('geom', epsg=4326)],
-          max_features=1
-      )
-      print(df)
-
-                                            pkey_boring                    geom
-    0  https://www.dov.vlaanderen.be/data/boring/2016...  POINT (3.5512 50.8443)
-
 
 Turning the result into a GeoPandas GeoDataFrame
   pydov result dataframes which include a geometry column can easily be transformed from a normal Pandas DataFrame into a GeoPandas GeoDataFrame for further (geo) analysis, exporting or use in a new query using a :class:`pydov.util.location.GeopandasFilter`::

docs/reference.rst

@@ -226,6 +226,10 @@ Generic
 Fields
 ------
 
+.. automodule:: pydov.search.fields
+    :members:
+    :show-inheritance:
+
 .. automodule:: pydov.types.fields
     :members:
     :show-inheritance:

pydov/search/abstract.py

@@ -650,6 +650,9 @@ def _search(self, location=None, query=None, return_fields=None,
             When a field that can only be used as a query parameter is used as
             a return field.
 
+            When a geometry field is referenced by name in the return fields,
+            instead of as instance of GeometryReturnField.
+
         """
         self._pre_search_validation(location, query, sort_by, return_fields,
                                     max_features)
@@ -693,6 +696,16 @@ def _search(self, location=None, query=None, return_fields=None,
             else:
                 geom_return_crs = None
 
+            geom_fields = self.get_fields(type='geometry')
+            for f in return_fields:
+                if not isinstance(f, GeometryReturnField) \
+                        and f.name in geom_fields:
+                    raise InvalidFieldError(
+                        f"Cannot use field '{f.name}' of type 'geometry' in "
+                        "return_fields by name, use GeometryReturnField "
+                        f"instead, e.g. GeometryReturnField('{f.name}', "
+                        "epsg=31370).")
+
         extra_custom_fields = set()
         for custom_field in self._type.get_fields(
                 source=('custom_wfs',)).values():

pydov/search/fields.py

@@ -1,6 +1,7 @@
 
 from pydov.util.notebook import HtmlFormatter
 from pydov.util.wrappers import AbstractDictLike
+from pydov.util.location import EpsgValidator
 
 
 class ReturnFieldList(list):
@@ -121,24 +122,33 @@ def __init__(self, name):
         super().__init__(name)
 
 
-class GeometryReturnField(AbstractReturnField):
+class GeometryReturnField(AbstractReturnField, EpsgValidator):
     def __init__(self, geometry_field, epsg=None):
         """Initialise a geometry return field.
 
         Parameters
         ----------
         geometry_field : str
             Name of the geometry field.
-        epsg : int, optional
+        epsg : int
             EPSG code of the CRS of the geometries that will be returned.
-            Defaults to None, which means the default CRS of the WFS layer.
+
+        Raises
+        ------
+        TypeError
+            If `epsg` is None, missing or not an integer.
+
+        ValueError
+            If `epsg` invalid.
+
+        Notes
+        -----
+        See https://epsg.io for a list of valid EPSG codes.
+
         """
         super().__init__(geometry_field)
 
-        if epsg is not None:
-            if not isinstance(epsg, int):
-                raise TypeError('epsg should be an integer value')
-
+        self._validate_epsg(epsg)
         self.epsg = epsg
 
 

pydov/util/location.py

@@ -16,28 +16,10 @@
 from owslib.fes2 import Or
 
 
-class AbstractLocation(object):
-    """Abstract base class for location types (f.ex. point, box, polygon).
-
-    Locations are GML elements, for inclusion in the WFS GetFeature request.
-    As described in the Filter Encoding 2.0 standard, locations are expressed
-    using GML 3.2.
-
-    The initialisation should require all necessary parameters to construct
-    a valid location of this type: i.e. all locations should be valid after
-    initialisation.
-
-    """
-
-    def _get_id_seed(self):
-        """Get the seed for generating a random but stable GML ID for this
-        location.
-
-        Should return the same value for locations considered equal.
-        """
-        raise NotImplementedError('This should be implemented in a subclass.')
+class EpsgValidator(object):
+    """Class grouping methods for enforcing and validating EPSG parameters."""
 
-    def _is_valid_epsg(self, epsg):
+    def _is_existing_epsg(self, epsg):
         """Check whether the provided EPSG code is a valid EPSG code according
         to pyproj. Pass if pyproj is not installed.
 
@@ -62,7 +44,8 @@ def _is_valid_epsg(self, epsg):
 
     def _validate_epsg(self, epsg):
         """
-        Validate the provided EPSG code.
+        Validate the provided EPSG code, raising an exception if the EPSG
+        code is either missing or invalid.
 
         Parameters
         ----------
@@ -80,8 +63,9 @@ def _validate_epsg(self, epsg):
             how to provide a valid code.
 
         Notes
-        --------
+        -----
         https://epsg.io for a list of valid EPSG codes.
+
         """
 
         generic_error = (f"Example usage: {self.__class__.__name__}"
@@ -101,11 +85,33 @@ def _validate_epsg(self, epsg):
                             f"got {type(epsg).__name__}.\n" + generic_error)
 
         try:
-            self._is_valid_epsg(epsg)
+            self._is_existing_epsg(epsg)
         except ValueError:
             raise ValueError(f"Invalid EPSG code: {epsg}.\n" + generic_error) \
                 from None
 
+
+class AbstractLocation(EpsgValidator):
+    """Abstract base class for location types (f.ex. point, box, polygon).
+
+    Locations are GML elements, for inclusion in the WFS GetFeature request.
+    As described in the Filter Encoding 2.0 standard, locations are expressed
+    using GML 3.2.
+
+    The initialisation should require all necessary parameters to construct
+    a valid location of this type: i.e. all locations should be valid after
+    initialisation.
+
+    """
+
+    def _get_id_seed(self):
+        """Get the seed for generating a random but stable GML ID for this
+        location.
+
+        Should return the same value for locations considered equal.
+        """
+        raise NotImplementedError('This should be implemented in a subclass.')
+
     def _get_id(self):
         random.seed(self._get_id_seed())
         random_id = ''.join(random.choice(
@@ -246,14 +252,17 @@ def __init__(self, minx, miny, maxx, maxy, epsg=None):
 
         Raises
         ------
+        TypeError
+            If `epsg` is None, missing or not an integer.
+
         ValueError
             If `maxx` is lower than or equal to `minx`.
             If `maxy` is lower than or equal to `miny`.
-            If `epsg` is None or invalid
+            If `epsg` is invalid
 
         Notes
-        --------
-        https://epsg.io for a list of valid EPSG codes.
+        -----
+        See https://epsg.io for a list of valid EPSG codes.
 
         """
 
@@ -319,12 +328,15 @@ def __init__(self, x, y, epsg=None):
 
         Raises
         ------
+        TypeError
+            If `epsg` is None, missing or not an integer.
+
         ValueError
-            If `epsg` is None or invalid
+            If `epsg` invalid.
 
         Notes
-        --------
-        https://epsg.io for a list of valid EPSG codes.
+        -----
+        See https://epsg.io for a list of valid EPSG codes.
 
         """
 
@@ -392,7 +404,7 @@ def __init__(self, gml_element):
 
         try:
             epsg = int(self.element.attrib.get("srsName").split(':')[-1])
-            self._is_valid_epsg(epsg)
+            self._is_existing_epsg(epsg)
         except ValueError:
             raise ValueError("GML element has an invalid attribute srsName")
 

tests/abstract.py

@@ -618,6 +618,29 @@ def test_search_wrongreturnfieldstype(self):
                 query=self.valid_query_single,
                 return_fields=self.valid_returnfields[0])
 
+    def test_search_geometry_field_without_class(self):
+        """Test the search method with the query parameter and a geometry
+        return field.
+
+        Test whether an InvalidFieldError is raised, as geometry fields need
+        to be specified using GeometryReturnField (with CRS).
+
+        """
+        geom_fields = [
+            f for f in self.search_instance.get_fields(type='geometry')]
+
+        if len(geom_fields) < 1:
+            return
+
+        return_fields = list(self.valid_returnfields)
+        return_fields.append(geom_fields[0])
+
+        with pytest.raises(InvalidFieldError):
+            self.search_instance.search(
+                query=self.valid_query_single,
+                return_fields=return_fields
+            )
+
     def test_search_query_wrongfield(self):
         """Test the search method with the query parameter using an
         inexistent query field.

tests/test_search_fields.py

@@ -109,12 +109,12 @@ class TestGeometryReturnField():
     """Class grouping tests for the GeometryReturnField class."""
 
     def test_no_srs(self):
-        """Test initialisation of a GeometryReturnField without an SRS."""
-        rf = GeometryReturnField('shape')
+        """Test initialisation of a GeometryReturnField without an SRS.
 
-        assert isinstance(rf, GeometryReturnField)
-        assert rf.name == 'shape'
-        assert rf.epsg is None
+        Test whether a TypeError is raised.
+        """
+        with pytest.raises(TypeError):
+            GeometryReturnField('shape')
 
     def test_srs_31370(self):
         """Test initialisation of a GeometryReturnField with CRS set to Belgian Lambert 72."""
@@ -132,6 +132,14 @@ def test_wrong_srs_type(self):
         with pytest.raises(TypeError):
             GeometryReturnField('shape', 'EPSG:31370')
 
+    def test_wrong_srs_value(self):
+        """Test initialisation of a GeometryReturnField with a wrong CRS type.
+
+        Test whether a TypeError is raised.
+        """
+        with pytest.raises(ValueError):
+            GeometryReturnField('shape', 404000)
+
 
 class TestFieldMetadata():
     """Class grouping tests for the FieldMetadata class."""