Add total_bounds of layer to read_info

CHANGES.md

@@ -9,9 +9,10 @@
  unknown count for a data layer (e.g., OSM driver); this may have signficant
  performance impacts for some data sources that would otherwise return an
  unknown count (count is used in `read_info`, `read`, `read_dataframe`) (#271).
+- In `read_info`, the result now also contains the `total_bounds` of the layer as well
+ as some extra `capabilities` of the data source driver (#281)
 - Raise error if `read` or `read_dataframe` is called with parameters to read no
  columns, geometry, or fids (#280)
-
 - Automatically detect supported driver by extension for all available
  write drivers and addition of `detect_write_driver` (#270)
 
@@ -25,6 +26,15 @@
 - Always raise an exception if there is an error when writing a data source
  (#284)
 
+### Potentially breaking changes
+
+- In `read_info` (#281):
+ - the `features` property in the result will now be -1 if calculating the
+ feature count is an expensive operation for this driver. You can force it to be
+ calculated using the `force_feature_count` parameter.
+ - for boolean values in the `capabilities` property, the values will now be 
+ booleans instead of 1 or 0.
+
 ## 0.6.0 (2023-04-27)
 
 ### Improvements

pyogrio/_io.pyx

@@ -320,7 +320,7 @@ cdef get_driver(OGRDataSourceH ogr_dataset):
  return driver
 
 
-cdef get_feature_count(OGRLayerH ogr_layer):
+cdef get_feature_count(OGRLayerH ogr_layer, int force):
  """Get the feature count of a layer.
 
  If GDAL returns an unknown count (-1), this iterates over every feature
@@ -329,6 +329,8 @@ cdef get_feature_count(OGRLayerH ogr_layer):
  Parameters
  ----------
  ogr_layer : pointer to open OGR layer
+ force : bool
+ True if the feature count should be computed even if it is expensive
 
  Returns
  -------
@@ -337,12 +339,12 @@ cdef get_feature_count(OGRLayerH ogr_layer):
  """
 
  cdef OGRFeatureH ogr_feature = NULL
- cdef int feature_count = OGR_L_GetFeatureCount(ogr_layer, 1)
+ cdef int feature_count = OGR_L_GetFeatureCount(ogr_layer, force)
 
  # if GDAL refuses to give us the feature count, we have to loop over all
  # features ourselves and get the count. This can happen for some drivers
  # (e.g., OSM) or if a where clause is invalid but not rejected as error
- if feature_count == -1:
+ if force and feature_count == -1:
  # make sure layer is read from beginning
  OGR_L_ResetReading(ogr_layer)
 
@@ -376,6 +378,34 @@ cdef get_feature_count(OGRLayerH ogr_layer):
  return feature_count
 
 
+cdef get_total_bounds(OGRLayerH ogr_layer, int force):
+ """Get the total bounds of a layer.
+
+ Parameters
+ ----------
+ ogr_layer : pointer to open OGR layer
+ force : bool
+ True if the total bounds should be computed even if it is expensive
+
+ Returns
+ -------
+ tuple of (xmin, ymin, xmax, ymax) or None
+ The total bounds of the layer, or None if they could not be determined.
+ """
+
+ cdef OGREnvelope ogr_envelope
+ try:
+ exc_wrap_ogrerr(OGR_L_GetExtent(ogr_layer, &ogr_envelope, force))
+ bounds = (
+ ogr_envelope.MinX, ogr_envelope.MinY, ogr_envelope.MaxX, ogr_envelope.MaxY
+ )
+
+ except CPLE_BaseError:
+ bounds = None
+
+ return bounds
+
+
 cdef set_metadata(GDALMajorObjectH obj, object metadata):
  """Set metadata on a dataset or layer
 
@@ -598,7 +628,7 @@ cdef validate_feature_range(OGRLayerH ogr_layer, int skip_features=0, int max_fe
  skip_features : number of features to skip from beginning of available range
  max_features : maximum number of features to read from available range
  """
- feature_count = get_feature_count(ogr_layer)
+ feature_count = get_feature_count(ogr_layer, 1)
  num_features = max_features
 
  if feature_count == 0:
@@ -1369,7 +1399,9 @@ def ogr_read_info(
  str path,
  dataset_kwargs,
  object layer=None,
- object encoding=None):
+ object encoding=None,
+ int force_feature_count=False,
+ int force_total_bounds=False):
 
  cdef const char *path_c = NULL
  cdef char **dataset_options = NULL
@@ -1404,12 +1436,15 @@ def ogr_read_info(
  'fields': fields[:,2], # return only names
  'dtypes': fields[:,3],
  'geometry_type': get_geometry_type(ogr_layer),
- 'features': get_feature_count(ogr_layer),
+ 'features': get_feature_count(ogr_layer, force_feature_count),
+ 'total_bounds': get_total_bounds(ogr_layer, force_total_bounds),
  'driver': get_driver(ogr_dataset),
  "capabilities": {
- "random_read": OGR_L_TestCapability(ogr_layer, OLCRandomRead),
- "fast_set_next_by_index": OGR_L_TestCapability(ogr_layer, OLCFastSetNextByIndex),
- "fast_spatial_filter": OGR_L_TestCapability(ogr_layer, OLCFastSpatialFilter),
+ "random_read": OGR_L_TestCapability(ogr_layer, OLCRandomRead) == 1,
+ "fast_set_next_by_index": OGR_L_TestCapability(ogr_layer, OLCFastSetNextByIndex) == 1,
+ "fast_spatial_filter": OGR_L_TestCapability(ogr_layer, OLCFastSpatialFilter) == 1,
+ "fast_feature_count": OGR_L_TestCapability(ogr_layer, OLCFastFeatureCount) == 1,
+ "fast_total_bounds": OGR_L_TestCapability(ogr_layer, OLCFastGetExtent) == 1,
  },
  'layer_metadata': get_metadata(ogr_layer),
  'dataset_metadata': get_metadata(ogr_dataset),

pyogrio/_ogr.pxd

@@ -280,6 +280,7 @@ cdef extern from "ogr_api.h":
  const char* OGR_L_GetName(OGRLayerH layer)
  const char* OGR_L_GetFIDColumn(OGRLayerH layer)
  const char* OGR_L_GetGeometryColumn(OGRLayerH layer)
+ OGRErr OGR_L_GetExtent(OGRLayerH layer, OGREnvelope *psExtent, int bForce)
  OGRSpatialReferenceH OGR_L_GetSpatialRef(OGRLayerH layer)
  int OGR_L_TestCapability(OGRLayerH layer, const char *name)
  OGRFeatureDefnH OGR_L_GetLayerDefn(OGRLayerH layer)
@@ -301,6 +302,8 @@ cdef extern from "ogr_api.h":
  const char* OLCRandomRead
  const char* OLCFastSetNextByIndex
  const char* OLCFastSpatialFilter
+ const char* OLCFastFeatureCount
+ const char* OLCFastGetExtent
  const char* OLCTransactions
 
 

pyogrio/core.py

@@ -184,11 +184,27 @@ def read_bounds(
  return result
 
 
-def read_info(path_or_buffer, /, layer=None, encoding=None, **kwargs):
+def read_info(
+ path_or_buffer,
+ /,
+ layer=None,
+ encoding=None,
+ force_feature_count=False,
+ force_total_bounds=False,
+ **kwargs,
+):
  """Read information about an OGR data source.
 
- ``crs`` and ``geometry`` will be ``None`` and ``features`` will be 0 for a
- nonspatial layer.
+ ``crs``, ``geometry`` and ``total_bounds`` will be ``None`` and ``features`` will be
+ 0 for a nonspatial layer.
+
+ ``features`` will be -1 if this is an expensive operation for this driver. You can
+ force it to be calculated using the ``force_feature_count`` parameter.
+
+ ``total_bounds`` is the 2-dimensional extent of all features within the dataset:
+ (xmin, ymin, xmax, ymax). It will be None if this is an expensive operation for this
+ driver or if the data source is nonspatial. You can force it to be calculated using
+ the ``force_total_bounds`` parameter.
 
  Parameters
  ----------
@@ -199,6 +215,10 @@ def read_info(path_or_buffer, /, layer=None, encoding=None, **kwargs):
  If present, will be used as the encoding for reading string values from
  the data source, unless encoding can be inferred directly from the data
  source.
+ force_feature_count : bool, optional (default: False)
+ True if the feature count should be computed even if it is expensive.
+ force_total_bounds : bool, optional (default: False)
+ True if the total bounds should be computed even if it is expensive.
  **kwargs
  Additional driver-specific dataset open options passed to OGR. Invalid
  options will trigger a warning.
@@ -214,10 +234,12 @@ def read_info(path_or_buffer, /, layer=None, encoding=None, **kwargs):
  "dtypes": <ndarray of field dtypes>,
  "encoding": "<encoding>",
  "geometry": "<geometry type>",
- "features": <feature count>,
+ "features": <feature count or -1>,
+ "total_bounds": <tuple with total bounds or None>,
  "driver": "<driver>",
- "dataset_metadata" "<dict of dataset metadata or None>"
- "layer_metadata" "<dict of layer metadata or None>"
+ "capabilities": "<dict of driver capabilities>"
+ "dataset_metadata": "<dict of dataset metadata or None>"
+ "layer_metadata": "<dict of layer metadata or None>"
  }
  """
  path, buffer = get_vsi_path(path_or_buffer)
@@ -226,7 +248,12 @@ def read_info(path_or_buffer, /, layer=None, encoding=None, **kwargs):
 
  try:
  result = ogr_read_info(
- path, layer=layer, encoding=encoding, dataset_kwargs=dataset_kwargs
+ path,
+ layer=layer,
+ encoding=encoding,
+ force_feature_count=force_feature_count,
+ force_total_bounds=force_total_bounds,
+ dataset_kwargs=dataset_kwargs,
  )
  finally:
  if buffer is not None:

pyogrio/tests/test_core.py

@@ -14,6 +14,7 @@
 )
 from pyogrio.core import detect_write_driver
 from pyogrio.errors import DataSourceError, DataLayerError
+from pyogrio.tests.conftest import prepare_testfile
 
 from pyogrio._env import GDALEnv
 
@@ -279,7 +280,13 @@ def test_read_info(naturalearth_lowres):
  assert meta["fields"].shape == (5,)
  assert meta["dtypes"].tolist() == ["int64", "object", "object", "object", "float64"]
  assert meta["features"] == 177
+ assert allclose(meta["total_bounds"], (-180, -90, 180, 83.64513))
  assert meta["driver"] == "ESRI Shapefile"
+ assert meta["capabilities"]["random_read"] is True
+ assert meta["capabilities"]["fast_set_next_by_index"] is True
+ assert meta["capabilities"]["fast_spatial_filter"] is False
+ assert meta["capabilities"]["fast_feature_count"] is True
+ assert meta["capabilities"]["fast_total_bounds"] is True
 
 
 @pytest.mark.parametrize(
@@ -321,19 +328,48 @@ def test_read_info_invalid_dataset_kwargs(naturalearth_lowres):
 
 def test_read_info_force_feature_count_exception(data_dir):
  with pytest.raises(DataLayerError, match="Could not iterate over features"):
- read_info(data_dir / "sample.osm.pbf", layer="lines")
+ read_info(data_dir / "sample.osm.pbf", layer="lines", force_feature_count=True)
 
 
-def test_read_info_force_feature_count(data_dir):
+@pytest.mark.parametrize(
+ "layer, force, expected",
+ [
+ ("points", False, -1),
+ ("points", True, 8),
+ ("lines", False, -1),
+ ("lines", True, 36),
+ ],
+)
+def test_read_info_force_feature_count(data_dir, layer, force, expected):
  # the sample OSM file has non-increasing node IDs which causes the default
  # custom indexing to raise an exception iterating over features
- meta = read_info(data_dir / "sample.osm.pbf", USE_CUSTOM_INDEXING=False)
- assert meta["features"] == 8
-
  meta = read_info(
- data_dir / "sample.osm.pbf", layer="lines", USE_CUSTOM_INDEXING=False
+ data_dir / "sample.osm.pbf",
+ layer=layer,
+ force_feature_count=force,
+ USE_CUSTOM_INDEXING=False,
  )
- assert meta["features"] == 36
+ assert meta["features"] == expected
+
+
+@pytest.mark.parametrize(
+ "force_total_bounds, expected_total_bounds",
+ [(True, (-180.0, -90.0, 180.0, 83.64513)), (False, None)],
+)
+def test_read_info_force_total_bounds(
+ tmpdir, naturalearth_lowres, force_total_bounds, expected_total_bounds
+):
+ # Geojson files don't hava a fast way to determine total_bounds
+ geojson_path = prepare_testfile(naturalearth_lowres, dst_dir=tmpdir, ext=".geojson")
+ info = read_info(geojson_path, force_total_bounds=force_total_bounds)
+ if expected_total_bounds is not None:
+ assert allclose(info["total_bounds"], expected_total_bounds)
+ else:
+ assert info["total_bounds"] is None
+
+
+def test_read_info_without_geometry(test_fgdb_vsi):
+ assert read_info(test_fgdb_vsi)["total_bounds"] is None
 
 
 @pytest.mark.parametrize(

pyogrio/tests/test_raw_io.py

@@ -490,7 +490,7 @@ def test_write_append_unsupported(tmpdir, naturalearth_lowres, driver, ext):
 
  assert os.path.exists(filename)
 
- assert read_info(filename)["features"] == 177
+ assert read_info(filename, force_feature_count=True)["features"] == 177
 
  with pytest.raises(DataSourceError):
  write(filename, geometry, field_data, driver=driver, append=True, **meta)