Repository navigation
Fixes: Issue 396 Associate spatial functions to each type - #618
papacodebear wants to merge 4 commits into
Conversation
|
Hi @papacodebear ! |
|
@codex Review |
There was a problem hiding this comment.
Pull request overview
Implements automatic return-type resolution for polymorphic PostGIS functions (Geometry/Geography/Raster) so callers don’t need to manually pass type_= in common cases, and updates tests/docs accordingly.
Changes:
- Add overload-based return type detection for a curated set of polymorphic functions via
_FUNCTION_OVERLOADS+ runtime resolution inGenericFunction. - Introduce the
GeomValcomposite type and use it forST_DumpAsPolygonsand raster/geometryST_Intersectionoverloads. - Expand test coverage and update tutorials to reflect the new “auto-detected return type” behavior.
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/test_types.py | Adds/updates SQL compilation assertions for polymorphic return types across Geometry/Geography/Raster. |
| tests/test_functions.py | Adds regression test ensuring func.ST_Transform(raster_col, ...) auto-detects Raster return type. |
| geoalchemy2/types/init.py | Introduces GeomVal composite return type and exports it. |
| geoalchemy2/functions.pyi | Updates stubs to reflect new/updated function return types (including GeomVal). |
| geoalchemy2/functions.py | Adds overload-resolution logic to GenericFunction and updates module docs. |
| geoalchemy2/_functions.py | Adds _FUNCTION_OVERLOADS table and updates/extends function metadata (incl. ST_DumpAsPolygons type). |
| geoalchemy2/_functions_helpers.py | Adds PostGIS catalog introspection/parsing helpers to support maintaining overload tables. |
| generate_function_overloads.py | Adds a helper script to compare live PostGIS catalogs vs _FUNCTIONS/_FUNCTION_OVERLOADS. |
| doc/orm_tutorial.rst | Updates Raster-function tutorial to describe auto-detected return types and explicit overrides. |
| doc/core_tutorial.rst | Updates Raster-function tutorial to describe auto-detected return types and explicit overrides. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ('ST_CoverageUnion', types.Geometry, | ||
| '''Computes the union of a set of polygons forming a coverage by removing shared edges.'''), | ||
| ('ST_CreateOverview', None, | ||
| '''Create an reduced resolution version of a given raster coverage.'''), |
There was a problem hiding this comment.
This is coming directly from PostGIS. I agree the fix is technically correct, but it would be overwritten I think: https://postgis.net/docs/manual-2.2/RT_CreateOverview.html
There was a problem hiding this comment.
The latest version of PostGIS changed the description, maybe we should update our registry to import the new functions and the new descriptions?
|
Hi @papacodebear |
There was a problem hiding this comment.
Hi @papacodebear
I finally found some time to review your PR, sorry again for the delay and thank you very much for your work, it looks very promising!!!
I left a few comments in the files and here are more general comments:
- The test
tests/gallery/test_raster_transform.pyfails in CI. The test should be updated since the issue it was designed to demonstrate does not exist anymore thanks to this pull request. - In
geoalchemy2/_functions_helpers.py, as far as I understand_introspect_postgis_functions,_PG_PROC_QUERY, and_diff_function_catalogand not really used in the package, they are only used bygenerate_function_overloads.pyto inspect a database and update code, so they shouldn't be bundled in the published geoalchemy2 runtime package. Note that it also triggers a MyPy error that would be solved if these elements were moved outside of the package. I think these functions could just be move intogenerate_function_overloads.pyand this script could also be moved to a dedicated directory (e.g.tools/). - I think we should add a few more tests to ensure that subclass and
TypeDecoratorare properly handled.
| def _spatial_arg_type(value) -> type | None: | ||
| """Best-effort classification of a function-call argument's GIS type. | ||
|
|
||
| Returns ``types.Geometry``/``types.Geography``/``types.Raster`` when confidently | ||
| identifiable (either a bound column/expression carrying one of those types, or a | ||
| :class:`geoalchemy2.elements._SpatialElement` value), or ``None`` for anything else | ||
| (plain literals like an SRID integer or an algorithm name string). ``None`` results are | ||
| skipped when matching a signature in :data:`geoalchemy2._functions._FUNCTION_OVERLOADS` - | ||
| only the relative order of the *spatial* arguments matters. | ||
| """ | ||
| marker = _GIS_COLUMN_TYPE_MARKERS.get(type(getattr(value, "type", None))) | ||
| if marker is not None: | ||
| return marker | ||
| return _SPATIAL_ELEMENT_MARKERS.get(type(value)) |
There was a problem hiding this comment.
As far as I understand this, using exact-type dictionary lookup causes polymorphic detection to fail for subclasses and TypeDecorator classes. I think we should keep the isinstance checks and inspect the TypeDecorator.impl to get the proper type.
Probably something like the following:
def _spatial_arg_type(value) -> type | None:
value_type = getattr(value, "type", None)
while isinstance(value_type, TypeDecorator):
value_type = value_type.impl
if isinstance(value_type, types.Raster):
return types.Raster
if isinstance(value_type, types.Geography):
return types.Geography
if isinstance(value_type, (types.Geometry, types._DummyGeometry)):
return types.Geometry
if isinstance(value, elements.RasterElement):
return types.Raster
if isinstance(value, elements._SpatialElement):
return types.Geometry
return None| if return_marker is None: | ||
| continue | ||
| collapsed = tuple(m for m in arg_markers if m is not None) | ||
| signatures[collapsed] = return_marker |
There was a problem hiding this comment.
What happens if collapse == tuple()?
As far as I understand, _FUNCTION_OVERLOADS omits non-spatial variants (which is good), but if we only have non-spatial variants in the signature (e.g. ST_Buffer(1.0)), then we end up with an empty tuple, right?
Maybe we should just add this after this line?
if not collapsed:
continueI'm not 100% sure yet.
There was a problem hiding this comment.
Oh and also, if two overloads share the same collapsed signature but return different types (a collision), the first overload would be overwritten by the second one. I don't know if this cases really exists?
| elif doc is not None: | ||
| doc_string_parts.append(_wrap_docstring(doc)) | ||
| doc_string_parts.append(f"see https://postgis.net/docs/{name}.html") | ||
|
|
There was a problem hiding this comment.
These lines always add a docs entry to the functions but for the entries that you marked as "Not documented by PostGIS." (in _functions.py), the created URL will not be reachable since it does not exist in the PostGIS docs. So we should not add the URL to the docs in this case.
f861833 to
d92e4bc
Compare
|
I rebased the branch to fix the CI, so you will have to pull. |
Description
Fixes #396
Checklist
This pull request is:
Fixes: #<issue number>in the description if it solves an existing issue(which must include a complete example of the issue).
mainbranch and pass with the provided fix.Fixes: #<issue number>in the description if it solves an existing issue(which must include a complete example of the feature).