Skip to content

Fixes: Issue 396 Associate spatial functions to each type - #618

Open
papacodebear wants to merge 4 commits into
geoalchemy:mainfrom
papacodebear:papacodebear/issue396-v2
Open

papacodebear wants to merge 4 commits into
geoalchemy:mainfrom
papacodebear:papacodebear/issue396-v2

Conversation

@papacodebear

@papacodebear papacodebear commented Jul 23, 2026 •

Copy link
Copy Markdown

Description

Fixes #396

Checklist

This pull request is:

  • A documentation / typographical error fix
    • Good to go, no issue or tests are needed
  • A short code fix
    • Please include: Fixes: #<issue number> in the description if it solves an existing issue
      (which must include a complete example of the issue).
    • Please include tests that fail with the main branch and pass with the provided fix.
  • A new feature implementation or update an existing feature
    • Please include: Fixes: #<issue number> in the description if it solves an existing issue
      (which must include a complete example of the feature).
    • Please include tests that cover every lines of the new/updated feature.
    • Please update the documentation to describe the new/updated feature.

@papacodebear papacodebear changed the title Issue 396 Associate spatial functions to each type Fixes: Issue 396 Associate spatial functions to each type Jul 25, 2026
@adrien-berchet

Copy link
Copy Markdown
Member

Hi @papacodebear !
Thank you very much for this work!
I'm quite busy at the moment so it will take some time for me to review it. In the mean time, I requested reviews from 2 AI agents (Copilot and Codex) but you don't have to fix everything they report (or even anything), it's just to help me in the reviewing process. I will ping you when my review is finished.
Thanks again

@adrien-berchet

Copy link
Copy Markdown
Member

@codex Review

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 in GenericFunction.
  • Introduce the GeomVal composite type and use it for ST_DumpAsPolygons and raster/geometry ST_Intersection overloads.
  • 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.

Comment thread generate_function_overloads.py Resolved
Comment thread doc/core_tutorial.rst Resolved
Comment thread doc/orm_tutorial.rst Resolved
Comment thread geoalchemy2/_functions.py
('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.'''),

@papacodebear papacodebear Jul 25, 2026 •

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The latest version of PostGIS changed the description, maybe we should update our registry to import the new functions and the new descriptions?

@adrien-berchet

Copy link
Copy Markdown
Member

Hi @papacodebear
Sorry for the very long delay... I could still not find enough time to review your work, sorry :-/
I will try to come back to this soon!

@adrien-berchet adrien-berchet left a comment •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

  1. The test tests/gallery/test_raster_transform.py fails in CI. The test should be updated since the issue it was designed to demonstrate does not exist anymore thanks to this pull request.
  2. In geoalchemy2/_functions_helpers.py, as far as I understand _introspect_postgis_functions, _PG_PROC_QUERY, and _diff_function_catalog and not really used in the package, they are only used by generate_function_overloads.py to 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 into generate_function_overloads.py and this script could also be moved to a dedicated directory (e.g. tools/).
  3. I think we should add a few more tests to ensure that subclass and TypeDecorator are properly handled.

Comment thread geoalchemy2/functions.py
Comment on lines +242 to +255
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))

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:
    continue

I'm not 100% sure yet.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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")

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@adrien-berchet
adrien-berchet force-pushed the papacodebear/issue396-v2 branch from f861833 to d92e4bc Compare November 2, 2026 23:07
@adrien-berchet

Copy link
Copy Markdown
Member

I rebased the branch to fix the CI, so you will have to pull.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Associate spatial functions to each type

3 participants