python-general-be-lib 0.10.0.post2__tar.gz → 0.11.0__tar.gz

{python_general_be_lib-0.10.0.post2 → python_general_be_lib-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-general-be-lib
-Version: 0.10.0.post2
+Version: 0.11.0
 Summary: General purpose backend library — SQLAlchemy CRUD/Geometry repositories, FastAPI exceptions, Pydantic base models, logger utilities.
 Author-email: Andrea Di Placido <a.diplacido@arpes.it>, "Arpes S.r.l." <it.admin@arpes.it>
 License: MIT

{python_general_be_lib-0.10.0.post2 → python_general_be_lib-0.11.0}/general/interface/base/declarative_base.py

@@ -8,6 +8,8 @@ from pydantic import create_model, ConfigDict
 from sqlalchemy.inspection import inspect
 from sqlalchemy.orm import Mapper, as_declarative
 
+from ...exception.crud_exceptions import HasNoAttributeException
+
 
 @as_declarative()
 class Base:
@@ -18,7 +20,8 @@ class Base:
     """
 
     @classmethod
-    def to_pydantic(cls, model_name: str = None, full_optional: bool = False, default_values: dict[str, Any] = None, include_only: Sequence[str] = None, **create_model_kwargs):
+    def to_pydantic(cls, model_name: str = None, full_optional: bool = False, default_values: dict[str, Any] = None, include_only: Sequence[str] = None,
+                    exclude: Sequence[str] = None, **create_model_kwargs):
         """Generate a Pydantic model dynamically from the entity columns.
 
         Iterates over the ORM-mapped columns and builds the model fields honouring the
@@ -38,6 +41,9 @@ class Base:
                 overriding the inferred defaults.
             include_only (Sequence[str], optional): Attribute names to restrict the model to.
                 When ``None``, every mapped column is included.
+            exclude (Sequence[str], optional): Attribute names to leave out, applied after
+                ``include_only``: the two intersect, one choosing the set and the other
+                removing from it.
             **create_model_kwargs: Additional arguments passed to ``pydantic.create_model``.
 
         Returns:
@@ -49,14 +55,12 @@ class Base:
         if not default_values:
             default_values = dict()
         mapper: Mapper = inspect(cls)
+        for names in (include_only, exclude):
+            unknown = [name for name in names or () if name not in mapper.columns]
+            if unknown:
+                raise HasNoAttributeException(attr=", ".join(unknown))
 
-        # ``mapper.columns`` è indicizzato per **nome di attributo** e non forza la
-        # configurazione dei mapper: ``column_attrs``/``attrs``/``relationships`` la
-        # forzerebbero, e chiamare ``to_pydantic`` a import-time — il pattern
-        # documentato — romperebbe le relationship con forward-ref non ancora
-        # risolvibili (stessa ragione per cui ``relationship_attributes`` è lazy).
-        selected = [(name, column) for name, column in mapper.columns.items()
-                    if include_only is None or name in include_only]
+        selected = [(name, column) for name, column in mapper.columns.items() if (include_only is None or name in include_only) and (exclude is None or name not in exclude)]
 
         model_name = f"{cls.__name__}Model" if not model_name else model_name
         fields = dict()

{python_general_be_lib-0.10.0.post2 → python_general_be_lib-0.11.0}/general/interface/metadata/crud_metadata.py

@@ -4,11 +4,11 @@ import logging
 from typing import Optional, Any, Type, Iterable, Sequence
 
 from pydantic import BaseModel
-from sqlalchemy import MetaData, Engine, Column, Table, inspect, Connection, select, RowMapping, CursorResult
+from sqlalchemy import ARRAY, MetaData, Engine, Column, Table, func, inspect, Connection, literal, select, Row, RowMapping, CursorResult
 from sqlalchemy.exc import NoSuchTableError
 from sqlalchemy.sql.functions import count
 
-from ...exception.crud_exceptions import HasNoAttributeException, InternalServerException, raise_http_exception
+from ...exception.crud_exceptions import BadRequestException, EntityNotFoundException, HasNoAttributeException, InternalServerException, raise_http_exception
 from ...interface.repository.handler.base_handler import BaseHandler
 from ...interface.repository.handler.statement_manager import StatementManager
 from ...paginator_dto import PaginatorResponseModel, parse_pagination
@@ -295,10 +295,142 @@ class CrudMetadata:
             where = kwhere if kwhere else {}
         manager = self._statement_manager(table)
         stmt = self._select(table=table, columns=columns)
-        stmt = self._add_orders_by_condition(stmt, table, orders_by)
+        stmt = self._add_orders_by_condition(stmt=stmt, table=table, orders_by=orders_by)
         stmt = manager.prepare_statement(stmt=stmt, **where)
-        stmt = self._add_limit_offset_condition(stmt, limit)
-        return self.execute(connection=connection, stmt=stmt, mapping=True)
+        stmt = manager.limit_offset_condition(stmt=stmt, limit=limit)
+
+        return self.execute(connection=connection, stmt=stmt).mappings().all()
+
+    def get(self, from_table: str, pk: Any, connection: Connection = None, columns: list[str] = None,
+            parsing_model: Type[BaseModel] | BaseModel = None, strict: bool = False, **kwhere):
+        """Return the row with the given primary key, or nothing.
+
+        Counterpart of ``CrudRepository.get`` without its identity map, which belongs to the
+        ORM session and has no equivalent on a ``Connection``: here the lookup is always a
+        filtered ``SELECT``, so the method is ``find_one`` on the primary key of the
+        reflected table. The keys of a dictionary ``pk`` are therefore **column names** and
+        not Python attribute names, as everywhere on this layer.
+
+        Args:
+            from_table (str): Name of the table.
+            pk (Any): Primary key value. A scalar, or a tuple for a composite key, or a
+                dictionary ``{column: value}``.
+            connection (Connection, optional): External connection. When ``None``, one is
+                opened and closed at the end.
+            columns (list[str], optional): Columns to select.
+            parsing_model (Type[BaseModel], optional): Model to serialize the row with.
+            strict (bool): If ``True``, raise ``EntityNotFoundException`` when no row
+                matches instead of returning ``None``. Default: ``False``.
+            **kwhere: Additional filters, going through the handler pipeline registered for
+                the table.
+
+        Returns:
+            BaseModel | RowMapping | None: The row, serialized when a ``parsing_model`` is
+                given, or ``None`` when nothing matches and ``strict`` is not set.
+
+        Raises:
+            BadRequestException: If the table has no primary key, or the number of values in
+                ``pk`` does not match its columns.
+            HasNoAttributeException: If a dictionary ``pk`` is missing a primary key column.
+            EntityNotFoundException: If no row matches and ``strict=True``.
+        """
+        keep_open = False if connection is None else True
+        connection = self.open_connection if connection is None else connection
+        table = self.get_table(name=from_table)
+        result = self._get(table=table, connection=connection, pk=pk, columns=columns, **kwhere)
+        rows = self._return(connection=connection, result=result, keep_open=keep_open, commit=False, parsing_model=parsing_model)
+        if rows:
+            return rows[0]
+        if strict:
+            raise EntityNotFoundException()
+        return None
+
+    def _get(self, table: Table, connection: Connection, pk: Any, columns: list[str] = None, **kwhere):
+        values = self._pk_values(table=table, pk=pk)
+        manager = self._statement_manager(table)
+        conditions = list(manager.conditions(where=dict(kwhere)))
+        stmt = self._select(table=table, columns=columns)
+        stmt = stmt.where(*[column == value for column, value in zip(table.primary_key.columns, values)], *conditions)
+        return self.execute(connection=connection, stmt=stmt).mappings().all()
+
+    def _pk_values(self, table: Table, pk: Any) -> tuple:
+        """Normalize a primary key into the tuple of its values, in column order.
+
+        Accepts a scalar for a single-column key, a tuple or a list for a composite one, and
+        a dictionary keyed by **column names**. A string is never unpacked, so a textual
+        primary key stays one value.
+
+        Args:
+            table (Table): Reflected table the primary key is read from.
+            pk (Any): Primary key as a scalar, a sequence or a dictionary.
+
+        Returns:
+            tuple: Values of the primary key columns, in the order of the columns.
+
+        Raises:
+            BadRequestException: If the table has no primary key, or the number of values
+                does not match its columns.
+            HasNoAttributeException: If a dictionary does not carry every primary key
+                column.
+        """
+        names = [column.name for column in table.primary_key.columns]
+        if not names:
+            raise BadRequestException(custom_message=f"la tabella {table.name} non ha una chiave primaria")
+
+        if isinstance(pk, dict):
+            missing = [name for name in names if name not in pk]
+            if missing:
+                raise HasNoAttributeException(attr=", ".join(missing))
+            return tuple(pk[name] for name in names)
+
+        values = tuple(pk) if isinstance(pk, (tuple, list)) else (pk,)
+        if len(values) != len(names):
+            raise BadRequestException(custom_message=f"la chiave primaria di {table.name} ha {len(names)} colonne, ricevuti {len(values)} valori")
+        return values
+
+    def find_one(self, from_table: str, connection: Connection = None, where: dict[str, Any] = None, columns: list[str] = None,
+                 parsing_model: Type[BaseModel] | BaseModel = None, orders_by: dict[str, bool] = None, strict: bool = False, **kwhere):
+        """Return the first row matching the given criteria, or nothing.
+
+        Same read as ``find`` with ``limit=1``, returning one row instead of a sequence of
+        one. Without ``orders_by`` the row is unspecified, a ``LIMIT`` without ``ORDER BY``
+        having no defined order, and no default ordering is applied — the same choice as on
+        the ORM layer. It is not ``one()``: several matching rows are neither detected nor
+        complained about.
+
+        Args:
+            from_table (str): Name of the table.
+            connection (Connection, optional): External connection. When ``None``, one is
+                opened and closed at the end.
+            where (dict[str, Any], optional): Filters as a dictionary. Takes precedence over
+                ``**kwhere``.
+            columns (list[str], optional): Columns to select.
+            parsing_model (Type[BaseModel], optional): Model to serialize the row with.
+            orders_by (dict[str, bool], optional): Ordering as ``{column: ascending}``,
+                deciding which row comes first.
+            strict (bool): If ``True``, raise ``EntityNotFoundException`` when no row
+                matches instead of returning ``None``. Default: ``False``.
+            **kwhere: Additional filters as keyword arguments.
+
+        Returns:
+            BaseModel | RowMapping | None: The row, serialized when a ``parsing_model`` is
+                given, or ``None`` when nothing matches and ``strict`` is not set.
+
+        Raises:
+            EntityNotFoundException: If no row matches and ``strict=True``.
+            HasNoAttributeException: If a column in ``columns`` or ``orders_by`` does not
+                exist on the table.
+        """
+        keep_open = False if connection is None else True
+        connection = self.open_connection if connection is None else connection
+        table = self.get_table(name=from_table)
+        result = self._find(table=table, connection=connection, where=where, columns=columns, limit=1, orders_by=orders_by, **kwhere)
+        rows = self._return(connection=connection, result=result, keep_open=keep_open, commit=False, parsing_model=parsing_model)
+        if rows:
+            return rows[0]
+        if strict:
+            raise EntityNotFoundException()
+        return None
 
     def insert(self, from_table: str, connection: Connection = None, models: list[Type[BaseModel] | BaseModel] = None, values: list[dict[str, Any]] = None, returning: bool = True,
                parsing_model: Type[BaseModel] | BaseModel = None):
@@ -347,7 +479,8 @@ class CrudMetadata:
         if values:
             stmt = table.insert().values(values)
             stmt = stmt if not returning else stmt.returning(*table.c)
-            return self.execute(connection=connection, stmt=stmt, mapping=True)
+            result = self.execute(connection=connection, stmt=stmt)
+            return result.mappings().all() if result.returns_rows else []
         else:
             return []
 
@@ -393,7 +526,8 @@ class CrudMetadata:
         stmt = self._statement_manager(table).prepare_statement(stmt=stmt, **where)
         stmt = stmt.values(**kwargs)
         stmt = stmt if not returning else stmt.returning(*table.c)
-        return self.execute(connection=connection, stmt=stmt, mapping=True)
+        result = self.execute(connection=connection, stmt=stmt)
+        return result.mappings().all() if result.returns_rows else []
 
     def delete(self, from_table: str, connection: Connection = None, where: dict[str, Any] = None, **kwhere):
         """Delete the rows matching the given criteria.
@@ -437,40 +571,41 @@ class CrudMetadata:
             where = kwhere if kwhere else {}
         stmt = table.delete()
         stmt = self._statement_manager(table).prepare_statement(stmt=stmt, **where)
-        return self.execute(connection=connection, stmt=stmt).rowcount
+        result = self.execute(connection=connection, stmt=stmt)
+        return result.rowcount
 
     # --------------
 
-    def execute(self, connection: Connection, stmt, mapping: bool = False):
-        """Execute a statement on the connection, handling the exceptions.
+    def execute(self, connection: Connection, stmt) -> CursorResult:
+        """Execute a statement on the connection and return the result as it is.
 
-        A statement returning no rows — a DML without ``RETURNING`` — yields an empty list
-        when ``mapping=True`` instead of raising: reading its rows would fail **after** the
-        write has already happened, so a retry would duplicate it.
+        The method owns the error handling and nothing else: every exception goes to
+        ``_handle_exception``, which maps the error to an HTTP status through the same table
+        the ORM layer uses. Reading the result is left to the caller, which is the only one
+        knowing the shape it needs — ``.mappings().all()`` for rows, ``.scalar()`` for an
+        aggregate, ``.rowcount`` for a DML without ``RETURNING``. The result is bound to the
+        connection, so it has to be consumed before the connection is closed. Unlike the ORM
+        layer, ``Connection.execute`` always returns a ``CursorResult``: ``returns_rows``
+        tells a statement that produced rows from one that did not, and the callers building
+        an ``INSERT`` or an ``UPDATE`` with an optional ``RETURNING`` use it, because reading
+        the rows of a DML without it would fail **after** the write has already happened.
 
         Args:
             connection (Connection): Connection to execute the statement on.
             stmt: SQLAlchemy Core statement to execute.
-            mapping (bool): If ``True``, return the rows as mappings through
-                ``result.mappings().all()``; otherwise return the raw ``CursorResult``.
-                Default: ``False``.
 
         Returns:
-            Sequence[RowMapping] | CursorResult: Rows as mappings when ``mapping=True``,
-                the raw result otherwise.
+            CursorResult: Result of the execution, not consumed.
 
         Raises:
-            Exception: On error during the execution, through ``_handle_exception``.
+            ServiceUnavailableException | EntityNotFoundException | BadRequestException:
+                On SQLAlchemy errors.
         """
         try:
             result = connection.execute(stmt)
         except Exception as e:
             self._handle_exception(connection, e)
         else:
-            if mapping:
-                # ``returns_rows`` è falso su un DML senza RETURNING: leggerne le righe
-                # solleverebbe ``ResourceClosedError`` **dopo** che la scrittura è avvenuta
-                result = result.mappings().all() if result.returns_rows else []
             return result
 
     def _get_table(self, name: str):
@@ -569,7 +704,147 @@ class CrudMetadata:
             where = kwhere if kwhere else {}
         stmt = select(count()).select_from(table)
         stmt = self._statement_manager(table).prepare_statement(stmt=stmt, **where)
-        return self.execute(connection=connection, stmt=stmt).scalar()
+        result = self.execute(connection=connection, stmt=stmt)
+        return result.scalar()
+
+    def exists(self, from_table: str, connection: Connection = None, where: dict[str, Any] = None, **kwhere) -> bool:
+        """Tell whether at least one row matches the given criteria.
+
+        Runs a ``SELECT 1 ... LIMIT 1``, so the database stops at the first matching row
+        instead of counting every one of them, which is what answering the same question
+        with ``count() > 0`` costs. The filters go through the handler pipeline registered
+        for the table.
+
+        Args:
+            from_table (str): Name of the table.
+            connection (Connection, optional): External connection. When ``None``, one is
+                opened and closed at the end.
+            where (dict[str, Any], optional): Filters as a dictionary.
+            **kwhere: Filters as keyword arguments.
+
+        Returns:
+            bool: ``True`` if at least one row matches, ``False`` otherwise.
+        """
+        keep_open = False if connection is None else True
+        connection = self.open_connection if connection is None else connection
+        table = self.get_table(name=from_table)
+        exists_ = self._exists(table=table, connection=connection, where=where, **kwhere)
+        if not keep_open:
+            connection.close()
+        return exists_
+
+    def _exists(self, table: Table, connection: Connection, where: dict[str, Any] = None, **kwhere) -> bool:
+        if where is None:
+            where = kwhere if kwhere else {}
+        stmt = select(literal(1)).select_from(table).limit(1)
+        stmt = self._statement_manager(table).prepare_statement(stmt=stmt, **where)
+        result = self.execute(connection=connection, stmt=stmt)
+        return result.first() is not None
+
+    def distinct_values(self, from_table: str, column: str, connection: Connection = None, where: dict[str, Any] = None, **kwhere) -> list[Any]:
+        """Return the distinct values of one column among the rows matching ``where``.
+
+        The deduplication runs on the database side with a ``SELECT DISTINCT``, and on an
+        ``ARRAY`` column the elements are unrolled with ``unnest`` first, so what comes back
+        are the distinct **elements** and not the distinct arrays. The values are plain and
+        not serialized: the method takes no ``parsing_model``.
+
+        The order is whatever the database returns, a ``SELECT DISTINCT`` without
+        ``ORDER BY`` having none, and a ``NULL`` in the column is a value like the others
+        and comes back as ``None`` — on an ``ARRAY`` column it does not, because unrolling
+        a ``NULL`` array yields no element at all.
+
+        Args:
+            from_table (str): Name of the table.
+            column (str): Column to read the distinct values of.
+            connection (Connection, optional): External connection. When ``None``, one is
+                opened and closed at the end.
+            where (dict[str, Any], optional): Filters as a dictionary.
+            **kwhere: Filters as keyword arguments.
+
+        Returns:
+            list[Any]: Distinct values of the column.
+
+        Raises:
+            KeyError: If ``column`` is not a column of the table.
+        """
+        keep_open = False if connection is None else True
+        connection = self.open_connection if connection is None else connection
+        table = self.get_table(name=from_table)
+        values = self._distinct_values(table=table, connection=connection, column=column, where=where, **kwhere)
+        if not keep_open:
+            connection.close()
+        return values
+
+    def _distinct_values(self, table: Table, connection: Connection, column: str, where: dict[str, Any] = None, **kwhere) -> list[Any]:
+        if where is None:
+            where = kwhere if kwhere else {}
+        value_col = table.c[column]
+        if isinstance(value_col.type, ARRAY):
+            unrolled = func.unnest(value_col).table_valued("v", joins_implicitly=True).render_derived()
+            stmt = select(unrolled.c.v).select_from(table, unrolled).distinct()
+        else:
+            stmt = select(value_col).distinct()
+        stmt = self._statement_manager(table).prepare_statement(stmt=stmt, **where)
+        result = self.execute(connection=connection, stmt=stmt)
+        return result.scalars().all()
+
+    def distinct_pairs(self, from_table: str, key: str, value: str, connection: Connection = None, where: dict[str, Any] = None, **kwhere) -> list[Row]:
+        """Return the distinct ``(key, value)`` pairs among the rows matching ``where``.
+
+        Counterpart of ``CrudRepository.distinct_pairs``, typically to populate the options
+        of a client-side filter: the deduplication runs on the database side with a
+        ``SELECT DISTINCT`` instead of loading every row and deduplicating in Python. When
+        **both** columns are ``ARRAY`` they are unrolled in parallel with ``unnest``; when
+        only the key is, it is unrolled on its own and the label is read from the row,
+        because a multi-argument ``unnest`` requires every argument to be an array.
+
+        Unlike everything else on this layer it returns positional ``Row`` tuples and not
+        ``RowMapping``, and takes no ``parsing_model``: the names of the two columns are not
+        the same on the two paths — the real column names on a scalar key, ``k`` and ``v``
+        on an ``ARRAY`` one, which is how the table-valued function names them — so reading
+        them by name would work on one path and break on the other. The position is the only
+        stable access, exactly as on the ORM layer.
+
+        Args:
+            from_table (str): Name of the table.
+            key (str): Key column.
+            value (str): Label column.
+            connection (Connection, optional): External connection. When ``None``, one is
+                opened and closed at the end.
+            where (dict[str, Any], optional): Filters as a dictionary.
+            **kwhere: Filters as keyword arguments.
+
+        Returns:
+            list[Row]: Distinct ``(key, value)`` pairs.
+
+        Raises:
+            KeyError: If ``key`` or ``value`` is not a column of the table.
+        """
+        keep_open = False if connection is None else True
+        connection = self.open_connection if connection is None else connection
+        table = self.get_table(name=from_table)
+        pairs = self._distinct_pairs(table=table, connection=connection, key=key, value=value, where=where, **kwhere)
+        if not keep_open:
+            connection.close()
+        return pairs
+
+    def _distinct_pairs(self, table: Table, connection: Connection, key: str, value: str, where: dict[str, Any] = None, **kwhere) -> list[Row]:
+        if where is None:
+            where = kwhere if kwhere else {}
+        key_col, value_col = table.c[key], table.c[value]
+        if isinstance(key_col.type, ARRAY) and isinstance(value_col.type, ARRAY):
+            unrolled = func.unnest(key_col, value_col).table_valued("k", "v", joins_implicitly=True).render_derived()
+            stmt = select(unrolled.c.k, unrolled.c.v).select_from(table, unrolled).distinct()
+        elif isinstance(key_col.type, ARRAY):
+            # ``unnest`` a più argomenti pretende che siano **tutti** array
+            unrolled = func.unnest(key_col).table_valued("k", joins_implicitly=True).render_derived()
+            stmt = select(unrolled.c.k, value_col).select_from(table, unrolled).distinct()
+        else:
+            stmt = select(key_col, value_col).distinct()
+        stmt = self._statement_manager(table).prepare_statement(stmt=stmt, **where)
+        result = self.execute(connection=connection, stmt=stmt)
+        return result.all()
 
     def paging_find(self, from_table: str, connection: Connection = None, where: dict[str, Any] = None, columns: list[str] = None, limit: int = 0, page: int = 1,
                     parsing_model: Type[BaseModel] = None, orders_by: dict[str, bool] = None, **kwhere) -> PaginatorResponseModel:
@@ -637,14 +912,12 @@ class CrudMetadata:
         manager = self._statement_manager(table)
         stmt = self._select(table=table, columns=columns)
         stmt = self._add_orders_by_condition(stmt, table, orders_by)
-        stmt = self._add_limit_offset_condition(stmt, limit, page)
-        # copia: ``conditions`` consuma le chiavi con ``pop`` e il ``where`` è del chiamante
+        stmt = manager.limit_offset_condition(stmt=stmt, limit=limit,page=page)
         conditions = manager.conditions(where=dict(where))
         if conditions:
             stmt = stmt.where(*conditions)
-        stmt = manager.options(stmt=stmt)
 
-        rows = self.execute(connection=connection, stmt=stmt, mapping=True)
+        rows = self.execute(connection=connection, stmt=stmt).mappings().all()
 
         read = len(rows)
         if not limit or (read < limit and page == 1):
@@ -671,7 +944,8 @@ class CrudMetadata:
         stmt = select(count()).select_from(table)
         if where:
             stmt = stmt.where(*where)
-        return self.execute(connection=connection, stmt=stmt).scalar()
+        result = self.execute(connection=connection, stmt=stmt)
+        return result.scalar()
 
     def _add_orders_by_condition(self, stmt, table: Table, orders_by: dict[str, bool] = None):
         """Add one ORDER BY clause per entry of ``orders_by``, in insertion order.
@@ -692,25 +966,3 @@ class CrudMetadata:
         for order_by, asc in (orders_by or {}).items():
             stmt = manager.order_by_condition(stmt=stmt, order_by=order_by, asc=asc)
         return stmt
-
-    def _add_limit_offset_condition(self, stmt, limit: int, page: int = None):
-        """Add the LIMIT and OFFSET clauses to the statement for pagination.
-
-        Nothing is applied when ``limit`` is 0 or negative. The offset is computed as
-        ``(page - 1) * limit``.
-
-        Args:
-            stmt: Statement LIMIT/OFFSET apply to.
-            limit (int): Maximum number of rows. 0 means no limit.
-            page (int, optional): Page number, 1-based. If ``None`` or <= 0, no offset is
-                applied.
-
-        Returns:
-            Statement with LIMIT and/or OFFSET applied.
-        """
-        if limit and limit > 0:
-            stmt = stmt.limit(limit)
-            if page and page > 0:
-                offset = (page - 1) * limit
-                stmt = stmt.offset(offset)
-        return stmt

{python_general_be_lib-0.10.0.post2 → python_general_be_lib-0.11.0}/general/interface/metadata/geom_metadata.py

@@ -13,7 +13,8 @@ class GeomMetadata(CrudMetadata):
     """Core repository with PostGIS spatial operations on reflected tables.
 
     Extends ``CrudMetadata``, that is SQLAlchemy Core without the ORM, adding
-    intersection and containment geographic queries through GeoAlchemy2. Unlike
+    intersection, containment and nearest-neighbour geographic queries through
+    GeoAlchemy2. Unlike
     ``GeometryRepository``, the geometric column and its SRID are not fixed on the class
     but passed as arguments to every method, together with the table name.
 
@@ -113,8 +114,8 @@ class GeomMetadata(CrudMetadata):
 
         stmt = stmt.where(*eq_where)
 
-        stmt = self._add_limit_offset_condition(stmt, limit)
-        return self.execute(connection=connection, stmt=stmt, mapping=True)
+        stmt = manager.limit_offset_condition(stmt=stmt, limit=limit)
+        return self.execute(connection=connection, stmt=stmt).mappings().all()
 
     def contains(self, from_table: str, geom: WKBElement, polygon_column_name: str, polygon_column_srid: int, connection: Connection = None, tolerance: float = 0.0, columns: list[str] = None,
                  where: dict[str, Any] = None, limit: int = 0, contained: bool = False, geom_srid: int = 4326, parsing_model: Type[BaseModel] | BaseModel = None):
@@ -176,6 +177,8 @@ class GeomMetadata(CrudMetadata):
         if where is None:
             where = {}
 
+        manager = self._statement_manager(table)
+
         stmt = self._select(table, columns)
         eq_where = list(self._statement_manager(table).conditions(where=dict(where)))
 
@@ -185,8 +188,59 @@ class GeomMetadata(CrudMetadata):
         eq_where.append(geom_condition)
 
         stmt = stmt.where(*eq_where)
-        stmt = self._add_limit_offset_condition(stmt, limit)
-        return self.execute(connection=connection, stmt=stmt, mapping=True)
+        stmt = manager.limit_offset_condition(stmt=stmt, limit=limit)
+        return self.execute(connection=connection, stmt=stmt).mappings().all()
+
+    def nearest(self, from_table: str, geom: WKBElement, polygon_column_name: str, polygon_column_srid: int, connection: Connection = None, columns: list[str] = None,
+                limit: int = 1, where: dict[str, Any] = None, geom_srid: int = 4326, parsing_model: Type[BaseModel] | BaseModel = None):
+        """Return the rows closest to the given geometry, ordered by distance.
+
+        Counterpart of ``GeometryRepository.nearest`` on a reflected table. The ordering
+        uses the KNN ``<->`` operator (``distance_centroid``) instead of ``ST_Distance``:
+        with a ``LIMIT`` set, PostGIS can serve the nearest-neighbour search through the
+        GiST spatial index, avoiding the distance computation on every row. Only the rows
+        are returned, without the distance value, which is used for the database-side
+        ordering alone.
+
+        Args:
+            from_table (str): Name of the table.
+            geom (WKBElement): Reference geometry for the proximity computation.
+            polygon_column_name (str): Name of the geometric column of the table.
+            polygon_column_srid (int): SRID of the geometric column.
+            connection (Connection, optional): External connection. When ``None``, one is
+                opened and closed at the end.
+            columns (list[str], optional): Columns to select.
+            limit (int): Number of closest rows to return. Default: 1.
+            where (dict[str, Any], optional): Additional filters, going through the handler
+                pipeline registered for the table.
+            geom_srid (int): SRID of the given geometry. Default: 4326.
+            parsing_model (Type[BaseModel], optional): Model to serialize the rows with.
+
+        Returns:
+            list[BaseModel] | Sequence[RowMapping]: Rows from the closest to the farthest.
+
+        Raises:
+            HasNoAttributeException: If a column in ``columns`` does not exist on the table.
+        """
+        keep_open = False if connection is None else True
+        connection = self.open_connection if connection is None else connection
+        table = self.get_table(name=from_table)
+        polygon_column = table.c[polygon_column_name]
+        result = self._nearest(table=table, connection=connection, polygon_column=polygon_column, polygon_column_srid=polygon_column_srid,
+                               geom=geom, columns=columns, limit=limit, where=where, geom_srid=geom_srid)
+        return self._return(connection=connection, result=result, keep_open=keep_open, commit=False, parsing_model=parsing_model)
+
+    def _nearest(self, table: Table, geom: WKBElement, polygon_column: Column, polygon_column_srid: int, connection: Connection = None, columns: list[str] = None,
+                 limit: int = 1, where: dict[str, Any] = None, geom_srid: int = 4326):
+        if where is None:
+            where = {}
+        manager = self._statement_manager(table)
+        stmt = self._select(table, columns)
+        geom_condition = self._geom_condition(geom=geom, geom_srid=geom_srid, polygon_column_srid=polygon_column_srid)
+        stmt = manager.prepare_statement(stmt=stmt, **where)
+        stmt = stmt.order_by(polygon_column.distance_centroid(geom_condition))
+        stmt = manager.limit_offset_condition(stmt=stmt, limit=limit)
+        return self.execute(connection=connection, stmt=stmt).mappings().all()
 
     def _geom_condition(self, geom: WKBElement, polygon_column_srid: int = 4326, geom_srid: int = 4326, buffer: float = 0):
         """Prepare the geometry for the queries applying reprojection and buffer.