kiba-core 0.5.3.dev76__tar.gz → 0.5.3.dev78__tar.gz

{kiba_core-0.5.3.dev76 → kiba_core-0.5.3.dev78}/CHANGELOG.md

@@ -8,6 +8,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 ## [Unreleased]
 
 ### Added
+- [MINOR] Added `core.store.entity_repository.EntityRepository`, which reads and writes rows of a table as pydantic models: `create`, `update`, `upsert`, `upsert_many` (postgres and sqlite), `delete`, `list_many`, `get_first`, `get`, `get_one` and `get_one_or_none`. It exposes UUID columns as strings and datetimes as aware utc datetimes, dumps pydantic values in JSON columns, generates ids for UUID primary keys and stamps `createdDate`/`updatedDate` when the table has them; subclasses can override `_convert_value_from_db`/`_convert_value_to_db` for other columns
+- [MINOR] Added `UUIDFieldFilter` (accepts `uuid.UUID` or `str` values) and module-level `apply_orders`, `apply_field_filters` and `get_field_filters_conditions` (conditions usable on selects, updates and deletes) to `core.store.retriever`; `Retriever` now uses them
+- [PATCH] Updated `DateFieldFilter` to convert values to utc for the column (naive for columns without a timezone, aware otherwise) so aware datetimes in any timezone compare correctly
+- [PATCH] Updated `IntegerFieldFilter` to bind values with the column's type so values outside the int64 range work with `Numeric` columns on asyncpg
+- [MINOR] Added `Database.get_dialect_name`
 - [PATCH] Fixed `json_route` and `streaming_json_route` returning a 500 when the JSON body isn't an object (e.g. `true` or `[1]`); they now raise `BadRequestException` (400)
 - [MINOR] Added `shouldNotifyRetriedFailures` (default `True`) to `MessageQueueProcessor`: when `False`, failure notifications are only sent once the queue gives up on a message, not for failures it will retry. `MessageQueue.fail_message` now returns whether the queue scheduled another attempt: `SqlMessageQueue` and `CosmosMessageQueue` return `True` until `maxAttempts` is reached, while `SqsMessageQueue` and `AqsMessageQueue` always return `False` as the platform decides on redelivery, so they keep notifying every failure
 - [MAJOR] Updated `CosmosMessageQueue` to retry failed messages like `SqlMessageQueue`: added `maxAttempts` (default 3) and `failureRetryDelaySeconds` (default 60). `fail_message` reschedules the message with linear backoff and stores `lastError`, and a visible message whose lease expired counts as an attempt when it is claimed again. Once `postCount` reaches `maxAttempts` the message is removed, along with its deduplication item. Previously failed or abandoned messages reappeared once their lease expired and were retried forever

{kiba_core-0.5.3.dev76 → kiba_core-0.5.3.dev78}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kiba-core
-Version: 0.5.3.dev76
+Version: 0.5.3.dev78
 Summary: Kiba Labs' python utilities
 Project-URL: repository, https://github.com/kibalabs/core-py
 Requires-Python: <4,>=3.12

{kiba_core-0.5.3.dev76 → kiba_core-0.5.3.dev78}/core/store/database.py

@@ -4,7 +4,7 @@ import datetime
 import typing
 import weakref
 from collections.abc import AsyncIterator
-from typing import TypeVar
+from typing import TypeVarTuple
 
 import sqlalchemy
 import sqlalchemy.exc
@@ -20,7 +20,7 @@ from core.exceptions import InternalServerErrorException
 from core.util import json_util
 
 DatabaseConnection = AsyncConnection
-ResultType = TypeVar('ResultType', bound=tuple)  # type: ignore[type-arg]
+ResultType = TypeVarTuple('ResultType')
 
 
 class Database:
@@ -61,10 +61,13 @@ class Database:
             await self._engine.dispose()
             self._engine = None
 
-    def now(self, seconds: float = 0) -> sqlalchemy.ColumnElement[datetime.datetime]:
+    def get_dialect_name(self) -> str:
         if not self._engine:
             raise InternalServerErrorException(message='Engine has not been established. Please called collect() first.')
-        dialectName = self._engine.dialect.name
+        return self._engine.dialect.name
+
+    def now(self, seconds: float = 0) -> sqlalchemy.ColumnElement[datetime.datetime]:
+        dialectName = self.get_dialect_name()
         if dialectName == 'postgresql':
             return sqlalchemy.func.now() + datetime.timedelta(seconds=seconds)
         if dialectName == 'sqlite':
@@ -137,10 +140,10 @@ class Database:
                 self._connectionContext.reset(token)
 
     @typing.overload
-    async def execute(self, query: TypedReturnsRows[ResultType], connection: DatabaseConnection | None = None) -> Result[ResultType]: ...
+    async def execute(self, query: TypedReturnsRows[*ResultType], connection: DatabaseConnection | None = None) -> Result[*ResultType]: ...
     @typing.overload
-    async def execute(self, query: sqlalchemy.sql.Executable, connection: DatabaseConnection | None = None) -> Result[typing.Any]: ...  # type: ignore[explicit-any]
-    async def execute(self, query: sqlalchemy.sql.Executable, connection: DatabaseConnection | None = None) -> Result[typing.Any]:  # type: ignore[explicit-any]
+    async def execute(self, query: sqlalchemy.sql.Executable, connection: DatabaseConnection | None = None) -> Result[*tuple[typing.Any, ...]]: ...  # type: ignore[explicit-any]
+    async def execute(self, query: sqlalchemy.sql.Executable, connection: DatabaseConnection | None = None) -> Result[*tuple[typing.Any, ...]]:  # type: ignore[explicit-any]
         if not self._engine:
             raise InternalServerErrorException(message='Connection has not been established. Please called collect() first.')
         if not connection:
@@ -149,4 +152,4 @@ class Database:
             raise InternalServerErrorException(message='No connection found. Please provide a connection or call create_context_connection() for the context.')
         if isinstance(query, UpdateBase):
             self._connectionsWithWrites.add(connection)
-        return typing.cast(Result[typing.Any], await connection.execute(statement=query))  # type: ignore[explicit-any]
+        return typing.cast(Result[*tuple[typing.Any, ...]], await connection.execute(statement=query))  # type: ignore[explicit-any]

kiba_core-0.5.3.dev78/core/store/entity_repository.py

@@ -0,0 +1,205 @@
+import typing
+import uuid
+from collections.abc import Sequence
+
+import sqlalchemy
+from pydantic import BaseModel
+from sqlalchemy.dialects import postgresql as sqlalchemy_psql
+from sqlalchemy.dialects import sqlite as sqlalchemy_sqlite
+from sqlalchemy.engine import Result
+from sqlalchemy.engine import RowMapping
+from sqlalchemy.sql import Select
+
+from core.exceptions import KibaException
+from core.exceptions import NotFoundException
+from core.store.database import Database
+from core.store.database import DatabaseConnection
+from core.store.retriever import FieldFilter
+from core.store.retriever import Order
+from core.store.retriever import apply_field_filters
+from core.store.retriever import apply_orders
+from core.store.retriever import datetime_to_column_value
+from core.store.retriever import get_field_filters_conditions
+from core.store.retriever import uuid_from_value
+from core.util import date_util
+
+EntityType = typing.TypeVar('EntityType', bound=BaseModel)
+
+
+class EntityRepository(typing.Generic[EntityType]):  # noqa: UP046
+    """Reads and writes rows of a table as pydantic models.
+
+    UUID columns are exposed as strings, datetimes as aware utc datetimes and pydantic values in JSON columns are dumped
+    on write. `createdDate` and `updatedDate` columns are stamped automatically when the table has them. Override
+    `_convert_value_from_db` and `_convert_value_to_db` to add conversions for other columns, and `list_select_columns`
+    with `_get_field_values` to read extra (e.g. computed) columns into the model.
+    """
+
+    def __init__(
+        self,
+        table: sqlalchemy.Table,
+        modelClass: type[EntityType],
+    ) -> None:
+        self.table = table
+        self.modelClass = modelClass
+        try:
+            self.idColumn = next(column for column in table.columns if column.primary_key)
+        except StopIteration:
+            raise KibaException(f'Failed to find id column for table: {table.name}')
+
+    def _convert_value_from_db(self, column: sqlalchemy.Column[typing.Any], value: typing.Any | None) -> typing.Any | None:  # type: ignore[explicit-any]
+        if value is None:
+            return None
+        if isinstance(column.type, sqlalchemy.Uuid):
+            return str(value)
+        if isinstance(column.type, sqlalchemy.DateTime):
+            return date_util.datetime_to_utc(dt=value)
+        return value
+
+    def _convert_value_to_db(self, column: sqlalchemy.Column[typing.Any], value: typing.Any | None) -> typing.Any | None:  # type: ignore[explicit-any]
+        if value is None:
+            return None
+        if isinstance(column.type, sqlalchemy.Uuid):
+            return uuid_from_value(value=value)
+        if isinstance(column.type, sqlalchemy.DateTime):
+            return datetime_to_column_value(column=column, dt=value)
+        if isinstance(column.type, sqlalchemy.JSON) and isinstance(value, BaseModel):
+            return value.model_dump()
+        return value
+
+    def list_select_columns(self) -> list[sqlalchemy.ColumnElement[typing.Any]]:  # type: ignore[explicit-any]
+        return list(self.table.columns)
+
+    def build_select(self) -> Select[*tuple[typing.Any, ...]]:  # type: ignore[explicit-any]
+        return sqlalchemy.select(*self.list_select_columns())
+
+    def _get_field_values(self, row: RowMapping) -> dict[str, typing.Any]:  # type: ignore[explicit-any]
+        return {column.key: self._convert_value_from_db(column=column, value=row[column]) for column in self.table.columns}
+
+    def from_row(self, row: RowMapping) -> EntityType:
+        return self.modelClass.model_validate(self._get_field_values(row=row))
+
+    def force_from_result(self, result: Result[*tuple[typing.Any, ...]]) -> EntityType:  # type: ignore[explicit-any]
+        row = result.mappings().first()
+        if row is None:
+            raise NotFoundException
+        return self.from_row(row=row)
+
+    def _get_column_names(self) -> str:
+        return ', '.join(column.key for column in self.table.columns)
+
+    def _create_values(self, kwargs: dict[str, typing.Any], shouldAddCreatedDate: bool = False, shouldAddUpdatedDate: bool = False) -> dict[sqlalchemy.Column[typing.Any], typing.Any]:  # type: ignore[explicit-any]
+        currentDate = date_util.datetime_from_now()
+        values: dict[sqlalchemy.Column[typing.Any], typing.Any] = {}  # type: ignore[explicit-any]
+        # NOTE(krishan711): immutable tables (e.g. event logs) may have no `updatedDate` column, so this only stamps the
+        # columns the table actually defines.
+        createdDateColumn = self.table.c.get('createdDate')
+        if shouldAddCreatedDate and createdDateColumn is not None:
+            values[createdDateColumn] = self._convert_value_to_db(column=createdDateColumn, value=currentDate)
+        updatedDateColumn = self.table.c.get('updatedDate')
+        if shouldAddUpdatedDate and updatedDateColumn is not None:
+            values[updatedDateColumn] = self._convert_value_to_db(column=updatedDateColumn, value=currentDate)
+        for key, value in kwargs.items():
+            column = self.table.c.get(key)
+            if column is None:
+                raise KibaException(f'Unknown column: {key}. Valid columns are: {self._get_column_names()}')
+            values[column] = self._convert_value_to_db(column=column, value=value)
+        return values
+
+    def _add_generated_id(self, values: dict[sqlalchemy.Column[typing.Any], typing.Any]) -> None:  # type: ignore[explicit-any]
+        if isinstance(self.idColumn.type, sqlalchemy.Uuid) and values.get(self.idColumn) is None:
+            values[self.idColumn] = uuid.uuid4()
+
+    def _create_upsert_insert(self, database: Database) -> sqlalchemy_psql.Insert | sqlalchemy_sqlite.Insert:
+        dialectName = database.get_dialect_name()
+        if dialectName == 'postgresql':
+            return sqlalchemy_psql.insert(self.table)
+        if dialectName == 'sqlite':
+            return sqlalchemy_sqlite.insert(self.table)
+        raise KibaException(f'EntityRepository upserts do not support dialect: {dialectName}')
+
+    # Writing
+
+    async def create(self, database: Database, connection: DatabaseConnection | None = None, **kwargs) -> EntityType:  # type: ignore[no-untyped-def]  # noqa: ANN003
+        createValues = self._create_values(kwargs=kwargs, shouldAddCreatedDate=True, shouldAddUpdatedDate=True)
+        self._add_generated_id(values=createValues)
+        result = await database.execute(query=self.table.insert().values(createValues).returning(*self.list_select_columns()), connection=connection)
+        return self.force_from_result(result=result)
+
+    async def update(self, database: Database, connection: DatabaseConnection | None = None, **kwargs) -> EntityType:  # type: ignore[no-untyped-def]  # noqa: ANN003
+        updateValues = self._create_values(kwargs=kwargs, shouldAddUpdatedDate=True)
+        idValue: typing.Any | None = updateValues.pop(self.idColumn, None)  # type: ignore[explicit-any]
+        if idValue is None:
+            raise KibaException(f'Failed to find id value for update to {self.table.name}')
+        result = await database.execute(query=self.table.update().where(self.idColumn == idValue).values(updateValues).returning(*self.list_select_columns()), connection=connection)
+        return self.force_from_result(result=result)
+
+    async def upsert(self, database: Database, constraintColumnNames: list[str], connection: DatabaseConnection | None = None, **kwargs) -> EntityType:  # type: ignore[no-untyped-def]  # noqa: ANN003
+        updateValues = self._create_values(kwargs=kwargs, shouldAddUpdatedDate=True, shouldAddCreatedDate=False)
+        insertValues = self._create_values(kwargs=kwargs, shouldAddUpdatedDate=True, shouldAddCreatedDate=True)
+        self._add_generated_id(values=insertValues)
+        insertStatement = self._create_upsert_insert(database=database).values(insertValues)
+        constraintColumns = [self.table.c[columnName] for columnName in constraintColumnNames]
+        doUpdateStatement = insertStatement.on_conflict_do_update(
+            index_elements=constraintColumns,
+            set_=updateValues,
+        )
+        result = await database.execute(query=doUpdateStatement.returning(*self.list_select_columns()), connection=connection)
+        return self.force_from_result(result=result)
+
+    async def upsert_many(self, database: Database, constraintColumnNames: list[str], rowDicts: list[dict[str, typing.Any]], connection: DatabaseConnection | None = None) -> list[EntityType]:  # type: ignore[explicit-any]
+        if not rowDicts:
+            return []
+        insertValuesList = [self._create_values(kwargs=row, shouldAddUpdatedDate=True, shouldAddCreatedDate=True) for row in rowDicts]
+        for insertValues in insertValuesList:
+            self._add_generated_id(values=insertValues)
+        constraintColumns = [self.table.c[columnName] for columnName in constraintColumnNames]
+        insertStatement = self._create_upsert_insert(database=database).values(insertValuesList)
+        excludedColumnKeys = {self.idColumn.key, 'createdDate'}
+        updateColumnKeys = {column.key for insertValues in insertValuesList for column in insertValues} - excludedColumnKeys
+        doUpdateStatement = insertStatement.on_conflict_do_update(
+            index_elements=constraintColumns,
+            set_={key: insertStatement.excluded[key] for key in updateColumnKeys},
+        )
+        result = await database.execute(query=doUpdateStatement.returning(*self.list_select_columns()), connection=connection)
+        return [self.from_row(row=row) for row in result.mappings().all()]
+
+    async def delete(self, database: Database, fieldFilters: Sequence[FieldFilter], connection: DatabaseConnection | None = None) -> None:
+        query = self.table.delete().where(*get_field_filters_conditions(table=self.table, fieldFilters=fieldFilters))
+        await database.execute(query=query, connection=connection)
+
+    # Reading
+
+    async def list_many(self, database: Database, fieldFilters: Sequence[FieldFilter] | None = None, orders: Sequence[Order] | None = None, limit: int | None = None, offset: int | None = None, connection: DatabaseConnection | None = None) -> list[EntityType]:
+        query = self.build_select()
+        if fieldFilters is not None:
+            query = apply_field_filters(query=query, table=self.table, fieldFilters=fieldFilters)
+        if orders is not None:
+            query = apply_orders(query=query, table=self.table, orders=orders)
+        if limit is not None:
+            query = query.limit(limit)
+        if offset is not None:
+            query = query.offset(offset)
+        result = await database.execute(query=query, connection=connection)
+        return [self.from_row(row=row) for row in result.mappings()]
+
+    async def get_first(self, database: Database, fieldFilters: Sequence[FieldFilter] | None = None, orders: Sequence[Order] | None = None, connection: DatabaseConnection | None = None) -> EntityType | None:
+        entities = await self.list_many(database=database, fieldFilters=fieldFilters, orders=orders, limit=1, connection=connection)
+        return next(iter(entities), None)
+
+    async def get(self, database: Database, idValue: typing.Any, connection: DatabaseConnection | None = None) -> EntityType:  # type: ignore[explicit-any]
+        query = self.build_select().where(self.idColumn == self._convert_value_to_db(column=self.idColumn, value=idValue))
+        result = await database.execute(query=query, connection=connection)
+        return self.force_from_result(result=result)
+
+    async def get_one(self, database: Database, fieldFilters: Sequence[FieldFilter], connection: DatabaseConnection | None = None) -> EntityType:
+        query = apply_field_filters(query=self.build_select(), table=self.table, fieldFilters=fieldFilters)
+        result = await database.execute(query=query, connection=connection)
+        # TODO(krishan711): raise an exception if there is more than one result
+        return self.force_from_result(result=result)
+
+    async def get_one_or_none(self, database: Database, fieldFilters: Sequence[FieldFilter], connection: DatabaseConnection | None = None) -> EntityType | None:
+        try:
+            return await self.get_one(database=database, fieldFilters=fieldFilters, connection=connection)
+        except NotFoundException:
+            return None

kiba_core-0.5.3.dev78/core/store/retriever.py

@@ -0,0 +1,298 @@
+import dataclasses
+import datetime
+import typing
+import uuid
+from collections.abc import Sequence
+from enum import Enum
+
+import sqlalchemy
+import sqlalchemy.sql.functions
+from sqlalchemy import Table
+from sqlalchemy.sql import ColumnElement
+from sqlalchemy.sql import Select
+
+from core.store.database import Database
+from core.store.database import ResultType
+from core.util import date_util
+
+
+class Direction(Enum):
+    ASCENDING = 'ascending'
+    DESCENDING = 'descending'
+
+
+@dataclasses.dataclass
+class Order:
+    fieldName: str
+    direction: Direction = Direction.DESCENDING
+
+
+@dataclasses.dataclass
+class RandomOrder(Order):
+    fieldName: str = '__KIBA_RANDOM'
+
+
+@dataclasses.dataclass
+class FieldFilter:
+    fieldName: str
+    isNull: bool | None = None
+    isNotNull: bool | None = None
+
+
+@dataclasses.dataclass
+class StringFieldFilter(FieldFilter):
+    eq: str | None = None
+    ne: str | None = None
+    containedIn: Sequence[str] | None = None
+    notContainedIn: Sequence[str] | None = None
+
+
+@dataclasses.dataclass
+class UUIDFieldFilter(FieldFilter):
+    eq: uuid.UUID | str | None = None
+    ne: uuid.UUID | str | None = None
+    containedIn: Sequence[uuid.UUID | str] | None = None
+    notContainedIn: Sequence[uuid.UUID | str] | None = None
+
+
+@dataclasses.dataclass
+class DateFieldFilter(FieldFilter):
+    eq: datetime.datetime | None = None
+    ne: datetime.datetime | None = None
+    lte: datetime.datetime | None = None
+    lt: datetime.datetime | None = None
+    gte: datetime.datetime | None = None
+    gt: datetime.datetime | None = None
+    containedIn: Sequence[datetime.datetime] | None = None
+    notContainedIn: Sequence[datetime.datetime] | None = None
+
+
+@dataclasses.dataclass
+class IntegerFieldFilter(FieldFilter):
+    eq: int | None = None
+    ne: int | None = None
+    lte: int | None = None
+    lt: int | None = None
+    gte: int | None = None
+    gt: int | None = None
+    containedIn: Sequence[int] | None = None
+    notContainedIn: Sequence[int] | None = None
+
+
+@dataclasses.dataclass
+class FloatFieldFilter(FieldFilter):
+    eq: float | None = None
+    ne: float | None = None
+    lte: float | None = None
+    lt: float | None = None
+    gte: float | None = None
+    gt: float | None = None
+    containedIn: Sequence[float] | None = None
+    notContainedIn: Sequence[float] | None = None
+
+
+@dataclasses.dataclass
+class BooleanFieldFilter(FieldFilter):
+    eq: bool | None = None
+    ne: bool | None = None
+
+
+def uuid_from_value(value: uuid.UUID | str) -> uuid.UUID:
+    if isinstance(value, uuid.UUID):
+        return value
+    return uuid.UUID(hex=value)
+
+
+def datetime_to_column_value(column: sqlalchemy.ColumnElement[typing.Any], dt: datetime.datetime) -> datetime.datetime:  # type: ignore[explicit-any]
+    # NOTE(krishan711): columns without a timezone store naive utc datetimes, columns with one store aware utc datetimes
+    if getattr(column.type, 'timezone', False):
+        return date_util.datetime_to_utc(dt=dt)
+    return date_util.datetime_to_utc_naive_datetime(dt=dt)
+
+
+def apply_order(query: Select[*ResultType], table: Table, order: Order) -> Select[*ResultType]:
+    if isinstance(order, RandomOrder):
+        query = query.order_by(sqlalchemy.sql.functions.random())
+    else:
+        field = table.c[order.fieldName]
+        query = query.order_by(field.asc() if order.direction == Direction.ASCENDING else field.desc())
+    return query
+
+
+def apply_orders(query: Select[*ResultType], table: Table, orders: Sequence[Order]) -> Select[*ResultType]:
+    for order in orders:
+        query = apply_order(query=query, table=table, order=order)
+    return query
+
+
+def get_string_field_filter_conditions(table: Table, fieldFilter: StringFieldFilter) -> list[ColumnElement[bool]]:
+    field = table.c[fieldFilter.fieldName]
+    conditions: list[ColumnElement[bool]] = []
+    if fieldFilter.eq is not None:
+        conditions.append(field == fieldFilter.eq)
+    if fieldFilter.ne is not None:
+        conditions.append(field != fieldFilter.ne)
+    if fieldFilter.containedIn is not None:
+        conditions.append(field.in_(fieldFilter.containedIn))
+    if fieldFilter.notContainedIn is not None:
+        conditions.append(field.not_in(fieldFilter.notContainedIn))
+    return conditions
+
+
+def get_uuid_field_filter_conditions(table: Table, fieldFilter: UUIDFieldFilter) -> list[ColumnElement[bool]]:
+    field = table.c[fieldFilter.fieldName]
+    conditions: list[ColumnElement[bool]] = []
+    if fieldFilter.eq is not None:
+        conditions.append(field == uuid_from_value(value=fieldFilter.eq))
+    if fieldFilter.ne is not None:
+        conditions.append(field != uuid_from_value(value=fieldFilter.ne))
+    if fieldFilter.containedIn is not None:
+        conditions.append(field.in_([uuid_from_value(value=value) for value in fieldFilter.containedIn]))
+    if fieldFilter.notContainedIn is not None:
+        conditions.append(field.not_in([uuid_from_value(value=value) for value in fieldFilter.notContainedIn]))
+    return conditions
+
+
+def get_date_field_filter_conditions(table: Table, fieldFilter: DateFieldFilter) -> list[ColumnElement[bool]]:
+    field = table.c[fieldFilter.fieldName]
+    conditions: list[ColumnElement[bool]] = []
+    if fieldFilter.eq is not None:
+        conditions.append(field == datetime_to_column_value(column=field, dt=fieldFilter.eq))
+    if fieldFilter.ne is not None:
+        conditions.append(field != datetime_to_column_value(column=field, dt=fieldFilter.ne))
+    if fieldFilter.lte is not None:
+        conditions.append(field <= datetime_to_column_value(column=field, dt=fieldFilter.lte))
+    if fieldFilter.lt is not None:
+        conditions.append(field < datetime_to_column_value(column=field, dt=fieldFilter.lt))
+    if fieldFilter.gte is not None:
+        conditions.append(field >= datetime_to_column_value(column=field, dt=fieldFilter.gte))
+    if fieldFilter.gt is not None:
+        conditions.append(field > datetime_to_column_value(column=field, dt=fieldFilter.gt))
+    if fieldFilter.containedIn is not None:
+        conditions.append(field.in_([datetime_to_column_value(column=field, dt=value) for value in fieldFilter.containedIn]))
+    if fieldFilter.notContainedIn is not None:
+        conditions.append(field.not_in([datetime_to_column_value(column=field, dt=value) for value in fieldFilter.notContainedIn]))
+    return conditions
+
+
+def get_integer_field_filter_conditions(table: Table, fieldFilter: IntegerFieldFilter) -> list[ColumnElement[bool]]:
+    # NOTE(krishan711): `field == value` / `field.in_(values)` let SQLAlchemy's `Numeric.coerce_compared_value`
+    # re-infer a bind param type from the compared Python `int` (typically `BigInteger`, i.e. int64) instead of
+    # keeping `field.type` (e.g. `Numeric(78, 0)` for uint256 columns). Binding explicitly with `type_=field.type`
+    # avoids an asyncpg `OverflowError` for any value outside the int64 range.
+    field = table.c[fieldFilter.fieldName]
+    conditions: list[ColumnElement[bool]] = []
+    if fieldFilter.eq is not None:
+        conditions.append(field == sqlalchemy.bindparam(None, fieldFilter.eq, type_=field.type))
+    if fieldFilter.ne is not None:
+        conditions.append(field != sqlalchemy.bindparam(None, fieldFilter.ne, type_=field.type))
+    if fieldFilter.lte is not None:
+        conditions.append(field <= sqlalchemy.bindparam(None, fieldFilter.lte, type_=field.type))
+    if fieldFilter.lt is not None:
+        conditions.append(field < sqlalchemy.bindparam(None, fieldFilter.lt, type_=field.type))
+    if fieldFilter.gte is not None:
+        conditions.append(field >= sqlalchemy.bindparam(None, fieldFilter.gte, type_=field.type))
+    if fieldFilter.gt is not None:
+        conditions.append(field > sqlalchemy.bindparam(None, fieldFilter.gt, type_=field.type))
+    if fieldFilter.containedIn is not None:
+        conditions.append(field.in_(sqlalchemy.bindparam(None, fieldFilter.containedIn, type_=field.type, expanding=True)))
+    if fieldFilter.notContainedIn is not None:
+        conditions.append(field.not_in(sqlalchemy.bindparam(None, fieldFilter.notContainedIn, type_=field.type, expanding=True)))
+    return conditions
+
+
+def get_float_field_filter_conditions(table: Table, fieldFilter: FloatFieldFilter) -> list[ColumnElement[bool]]:
+    field = table.c[fieldFilter.fieldName]
+    conditions: list[ColumnElement[bool]] = []
+    if fieldFilter.eq is not None:
+        conditions.append(field == fieldFilter.eq)
+    if fieldFilter.ne is not None:
+        conditions.append(field != fieldFilter.ne)
+    if fieldFilter.lte is not None:
+        conditions.append(field <= fieldFilter.lte)
+    if fieldFilter.lt is not None:
+        conditions.append(field < fieldFilter.lt)
+    if fieldFilter.gte is not None:
+        conditions.append(field >= fieldFilter.gte)
+    if fieldFilter.gt is not None:
+        conditions.append(field > fieldFilter.gt)
+    if fieldFilter.containedIn is not None:
+        conditions.append(field.in_(fieldFilter.containedIn))
+    if fieldFilter.notContainedIn is not None:
+        conditions.append(field.not_in(fieldFilter.notContainedIn))
+    return conditions
+
+
+def get_boolean_field_filter_conditions(table: Table, fieldFilter: BooleanFieldFilter) -> list[ColumnElement[bool]]:
+    field = table.c[fieldFilter.fieldName]
+    conditions: list[ColumnElement[bool]] = []
+    if fieldFilter.eq is not None:
+        conditions.append(field == fieldFilter.eq)
+    if fieldFilter.ne is not None:
+        conditions.append(field != fieldFilter.ne)
+    return conditions
+
+
+def get_field_filter_conditions(table: Table, fieldFilter: FieldFilter) -> list[ColumnElement[bool]]:
+    field = table.c[fieldFilter.fieldName]
+    conditions: list[ColumnElement[bool]] = []
+    if fieldFilter.isNull:
+        conditions.append(field.is_(None))
+    if fieldFilter.isNotNull:
+        conditions.append(field.is_not(None))
+    if isinstance(fieldFilter, StringFieldFilter):
+        conditions += get_string_field_filter_conditions(table=table, fieldFilter=fieldFilter)
+    if isinstance(fieldFilter, UUIDFieldFilter):
+        conditions += get_uuid_field_filter_conditions(table=table, fieldFilter=fieldFilter)
+    if isinstance(fieldFilter, DateFieldFilter):
+        conditions += get_date_field_filter_conditions(table=table, fieldFilter=fieldFilter)
+    if isinstance(fieldFilter, IntegerFieldFilter):
+        conditions += get_integer_field_filter_conditions(table=table, fieldFilter=fieldFilter)
+    if isinstance(fieldFilter, FloatFieldFilter):
+        conditions += get_float_field_filter_conditions(table=table, fieldFilter=fieldFilter)
+    if isinstance(fieldFilter, BooleanFieldFilter):
+        conditions += get_boolean_field_filter_conditions(table=table, fieldFilter=fieldFilter)
+    return conditions
+
+
+def get_field_filters_conditions(table: Table, fieldFilters: Sequence[FieldFilter]) -> list[ColumnElement[bool]]:
+    return [condition for fieldFilter in fieldFilters for condition in get_field_filter_conditions(table=table, fieldFilter=fieldFilter)]
+
+
+def apply_field_filters(query: Select[*ResultType], table: Table, fieldFilters: Sequence[FieldFilter]) -> Select[*ResultType]:
+    return query.where(*get_field_filters_conditions(table=table, fieldFilters=fieldFilters))
+
+
+class Retriever:
+    def __init__(self, database: Database) -> None:
+        self.database = database
+
+    def _apply_order(self, query: Select[*ResultType], table: Table, order: Order) -> Select[*ResultType]:
+        return apply_order(query=query, table=table, order=order)
+
+    def _apply_orders(self, query: Select[*ResultType], table: Table, orders: Sequence[Order]) -> Select[*ResultType]:
+        return apply_orders(query=query, table=table, orders=orders)
+
+    def _apply_string_field_filter(self, query: Select[*ResultType], table: Table, fieldFilter: StringFieldFilter) -> Select[*ResultType]:
+        return query.where(*get_string_field_filter_conditions(table=table, fieldFilter=fieldFilter))
+
+    def _apply_uuid_field_filter(self, query: Select[*ResultType], table: Table, fieldFilter: UUIDFieldFilter) -> Select[*ResultType]:
+        return query.where(*get_uuid_field_filter_conditions(table=table, fieldFilter=fieldFilter))
+
+    def _apply_date_field_filter(self, query: Select[*ResultType], table: Table, fieldFilter: DateFieldFilter) -> Select[*ResultType]:
+        return query.where(*get_date_field_filter_conditions(table=table, fieldFilter=fieldFilter))
+
+    def _apply_integer_field_filter(self, query: Select[*ResultType], table: Table, fieldFilter: IntegerFieldFilter) -> Select[*ResultType]:
+        return query.where(*get_integer_field_filter_conditions(table=table, fieldFilter=fieldFilter))
+
+    def _apply_float_field_filter(self, query: Select[*ResultType], table: Table, fieldFilter: FloatFieldFilter) -> Select[*ResultType]:
+        return query.where(*get_float_field_filter_conditions(table=table, fieldFilter=fieldFilter))
+
+    def _apply_boolean_field_filter(self, query: Select[*ResultType], table: Table, fieldFilter: BooleanFieldFilter) -> Select[*ResultType]:
+        return query.where(*get_boolean_field_filter_conditions(table=table, fieldFilter=fieldFilter))
+
+    def _apply_field_filter(self, query: Select[*ResultType], table: Table, fieldFilter: FieldFilter) -> Select[*ResultType]:
+        return query.where(*get_field_filter_conditions(table=table, fieldFilter=fieldFilter))
+
+    def _apply_field_filters(self, query: Select[*ResultType], table: Table, fieldFilters: Sequence[FieldFilter]) -> Select[*ResultType]:
+        return apply_field_filters(query=query, table=table, fieldFilters=fieldFilters)

{kiba_core-0.5.3.dev76 → kiba_core-0.5.3.dev78}/core/store/saver.py

@@ -39,7 +39,7 @@ class Saver:
         async with self.database.create_transaction() as connection:
             yield connection
 
-    async def _execute(self, query: TypedReturnsRows[ResultType], connection: DatabaseConnection | None = None) -> Result[ResultType]:
+    async def _execute(self, query: TypedReturnsRows[*ResultType], connection: DatabaseConnection | None = None) -> Result[*ResultType]:
         try:
             if connection:
                 return await self.database.execute(query=query, connection=connection)

{kiba_core-0.5.3.dev76 → kiba_core-0.5.3.dev78}/kiba_core.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kiba-core
-Version: 0.5.3.dev76
+Version: 0.5.3.dev78
 Summary: Kiba Labs' python utilities
 Project-URL: repository, https://github.com/kibalabs/core-py
 Requires-Python: <4,>=3.12

{kiba_core-0.5.3.dev76 → kiba_core-0.5.3.dev78}/kiba_core.egg-info/SOURCES.txt

@@ -69,6 +69,7 @@ core/requester/__init__.py
 core/requester/requester.py
 core/store/__init__.py
 core/store/database.py
+core/store/entity_repository.py
 core/store/retriever.py
 core/store/saver.py
 core/util/__init__.py
@@ -97,6 +98,7 @@ kiba_core.egg-info/requires.txt
 kiba_core.egg-info/top_level.txt
 tests/__init__.py
 tests/test_database.py
+tests/test_entity_repository.py
 tests/test_exceptions.py
 tests/test_logging.py
 tests/api/test_api_response.py

{kiba_core-0.5.3.dev76 → kiba_core-0.5.3.dev78}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kiba-core"
-version = "0.5.3.dev76"
+version = "0.5.3.dev78"
 description = "Kiba Labs' python utilities"
 readme = "README.md"
 requires-python = ">=3.12, <4"