activemodel 0.13.0__tar.gz → 0.14.0__tar.gz

activemodel-0.14.0/.tool-versions

@@ -0,0 +1,4 @@
+python 3.13.9
+uv 0.8.10
+direnv 2.37.1
+just 1.42.4

{activemodel-0.13.0 → activemodel-0.14.0}/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.14.0](https://github.com/iloveitaly/activemodel/compare/v0.13.0...v0.14.0) (2025-10-16)
+
+
+### Features
+
+* **query_wrapper:** add efficient exists() query method with tests ([257452f](https://github.com/iloveitaly/activemodel/commit/257452fdf976ce263b13997816a3b1b81d2902e9))
+* **query:** add sample() to query wrapper for random row selection ([d35800c](https://github.com/iloveitaly/activemodel/commit/d35800c46244db21fd92e615609b895acdee25dc))
+
+
+### Bug Fixes
+
+* handle tuples and Optionals in JSON mixin ([1aa1018](https://github.com/iloveitaly/activemodel/commit/1aa1018d9714a43089fa9943daf1b4fcbc7742b9))
+
+
+### Documentation
+
+* clarify global_session usage in complex test scenarios ([a131b0f](https://github.com/iloveitaly/activemodel/commit/a131b0f64287b4225ac1eb2289e6ce6f006aa4d5))
+* fastapi-sqla ([2183686](https://github.com/iloveitaly/activemodel/commit/2183686421095856c59649c51c03ba1edaea9515))
+
 ## [0.13.0](https://github.com/iloveitaly/activemodel/compare/v0.12.0...v0.13.0) (2025-09-05)
 
 

{activemodel-0.13.0 → activemodel-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: activemodel
-Version: 0.13.0
+Version: 0.14.0
 Summary: Make SQLModel more like an a real ORM
 Project-URL: Repository, https://github.com/iloveitaly/activemodel
 Author-email: Michael Bianco <iloveitaly@gmail.com>
@@ -290,7 +290,8 @@ https://github.com/DarylStark/my_data/blob/a17b8b3a8463b9953821b89fee895e272f94d
 
 * https://github.com/woofz/sqlmodel-basecrud
 * https://github.com/0xthiagomartins/sqlmodel-controller
-* https://github.com/litestar-org/advanced-alchemy?tab=readme-ov-file
+* https://github.com/litestar-org/advanced-alchemy
+* https://github.com/dialoguemd/fastapi-sqla
 
 ## Inspiration
 

{activemodel-0.13.0 → activemodel-0.14.0}/README.md

@@ -275,7 +275,8 @@ https://github.com/DarylStark/my_data/blob/a17b8b3a8463b9953821b89fee895e272f94d
 
 * https://github.com/woofz/sqlmodel-basecrud
 * https://github.com/0xthiagomartins/sqlmodel-controller
-* https://github.com/litestar-org/advanced-alchemy?tab=readme-ov-file
+* https://github.com/litestar-org/advanced-alchemy
+* https://github.com/dialoguemd/fastapi-sqla
 
 ## Inspiration
 

{activemodel-0.13.0 → activemodel-0.14.0}/activemodel/mixins/pydantic_json.py

@@ -6,9 +6,9 @@ SQLModel lacks a direct JSONField equivalent (like Tortoise ORM's JSONField), ma
 Extensive discussion on the problem: https://github.com/fastapi/sqlmodel/issues/63
 """
 
-from types import UnionType
 from typing import get_args, get_origin
-
+import typing
+import types
 from pydantic import BaseModel as PydanticBaseModel
 from sqlalchemy.orm import reconstructor, attributes
 
@@ -21,6 +21,11 @@ class PydanticJSONMixin:
 
     >>> class ExampleWithJSON(BaseModel, PydanticJSONMixin, table=True):
     >>>    list_field: list[SubObject] = Field(sa_type=JSONB()
+
+    Notes:
+
+    - Tuples of pydantic models are not supported, only lists.
+    - Nested lists of pydantic models are not supported, e.g. list[list[SubObject]]
     """
 
     @reconstructor
@@ -37,6 +42,7 @@ class PydanticJSONMixin:
         for field_name, field_info in self.model_fields.items():
             raw_value = getattr(self, field_name, None)
 
+            # if the field is not set on the model, we can avoid doing anything with it
             if raw_value is None:
                 continue
 
@@ -44,32 +50,43 @@ class PydanticJSONMixin:
             origin = get_origin(annotation)
 
             # e.g. `dict` or `dict[str, str]`, we don't want to do anything with these
-            if origin is dict:
+            if origin in (dict, tuple):
                 continue
 
             annotation_args = get_args(annotation)
             is_top_level_list = origin is list
+            model_cls = annotation
 
+            # TODO not sure what was going on here...
             # if origin is not None:
             #     assert annotation.__class__ == origin
 
-            model_cls = annotation
+            # UnionType is only one way of defining an optional. If older typing syntax is used `Tuple[str] | None` the
+            # type annotation is different: `typing.Optional[typing.Tuple[float, float]]`. This is why we check both
+            # types below.
 
             # e.g. SomePydanticModel | None or list[SomePydanticModel] | None
-            # annotation_args are (type, NoneType) in this case
-            if isinstance(annotation, UnionType):
+            # annotation_args are (type, NoneType) in this case. Remove NoneType.
+            if origin in (typing.Union, types.UnionType):
                 non_none_types = [t for t in annotation_args if t is not type(None)]
 
                 if len(non_none_types) == 1:
                     model_cls = non_none_types[0]
+                else:
+                    # if there's more than one non-none type, it isn't meant to be serialized to JSON
+                    pass
+
+            model_cls_origin = get_origin(model_cls)
 
             # e.g. list[SomePydanticModel] | None, we have to unpack it
             # model_cls will print as a list, but it contains a subtype if you dig into it
             if (
-                get_origin(model_cls) is list
+                model_cls_origin is list
                 and len(list_annotation_args := get_args(model_cls)) == 1
             ):
                 model_cls = list_annotation_args[0]
+                model_cls_origin = get_origin(model_cls)
+
                 is_top_level_list = True
 
             # e.g. list[SomePydanticModel] or list[SomePydanticModel] | None
@@ -82,6 +99,9 @@ class PydanticJSONMixin:
                     attributes.set_committed_value(self, field_name, parsed_value)
                 continue
 
+            if model_cls_origin in (list, tuple):
+                continue
+
             # single class
             if issubclass(model_cls, PydanticBaseModel):
                 attributes.set_committed_value(self, field_name, model_cls(**raw_value))

{activemodel-0.13.0 → activemodel-0.14.0}/activemodel/query_wrapper.py

@@ -1,5 +1,6 @@
 import sqlmodel as sm
 from sqlmodel.sql.expression import SelectOfScalar
+from typing import overload, Literal
 
 from activemodel.types.sqlalchemy_protocol import SQLAlchemyQueryMethods
 
@@ -48,6 +49,8 @@ class QueryWrapper[T: sm.SQLModel](SQLAlchemyQueryMethods[T]):
         with get_session() as session:
             return session.scalar(sm.select(sm.func.count()).select_from(self.target))
 
+    # TODO typing is broken here
+    # TODO would be great to define a default return type if nothing is found
     def scalar(self):
         """
         >>>
@@ -63,6 +66,17 @@ class QueryWrapper[T: sm.SQLModel](SQLAlchemyQueryMethods[T]):
         with get_session() as session:
             return session.delete(self.target)
 
+    def exists(self) -> bool:
+        """Return True if the current query yields at least one row.
+
+        Uses the SQLAlchemy exists() construct against a LIMIT 1 version of
+        the current target for efficiency. Keeps the original target intact.
+        """
+        with get_session() as session:
+            exists_stmt = sm.select(sm.exists(self.target))
+            result = session.scalar(exists_stmt)
+            return bool(result)
+
     def __getattr__(self, name):
         """
         This implements the magic that forwards function calls to sqlalchemy.
@@ -79,7 +93,7 @@ class QueryWrapper[T: sm.SQLModel](SQLAlchemyQueryMethods[T]):
 
             def wrapper(*args, **kwargs):
                 result = sqlalchemy_target(*args, **kwargs)
-                self.target = result
+                self.target = result  # type: ignore[assignment]
                 return self
 
             return wrapper
@@ -95,6 +109,48 @@ class QueryWrapper[T: sm.SQLModel](SQLAlchemyQueryMethods[T]):
 
         return compile_sql(self.target)
 
+    @overload
+    def sample(self) -> T | None: ...
+
+    @overload
+    def sample(self, n: Literal[1]) -> T | None: ...
+
+    @overload
+    def sample(self, n: int) -> list[T]: ...
+
+    def sample(self, n: int = 1) -> T | None | list[T]:
+        """Return a random sample of rows from the current query.
+
+        Parameters
+        ----------
+        n: int
+            Number of rows to return. Defaults to 1.
+
+        Behavior
+        --------
+        - Returns a single model instance when ``n == 1`` (or ``None`` if no rows)
+        - Returns a list[Model] when ``n > 1`` (possibly empty list when no rows)
+        - Sampling is performed by appending an ``ORDER BY RANDOM()`` / ``func.random()``
+          and ``LIMIT n`` clause to the existing query target.
+        - Keeps original query intact (does not mutate ``self.target``) so further
+          chaining works as expected.
+        """
+
+        if n < 1:
+            raise ValueError("n must be >= 1")
+
+        # Build a new randomized limited query leaving self.target untouched
+        randomized = self.target.order_by(sm.func.random()).limit(n)
+
+        with get_session() as session:
+            result = list(session.exec(randomized))
+
+        if n == 1:
+            # Return the single instance or None
+            return result[0] if result else None
+
+        return result
+
     def __repr__(self) -> str:
         # TODO we should improve structure of this a bit more, maybe wrap in <> or something?
         return f"{self.__class__.__name__}: Current SQL:\n{self.sql()}"

{activemodel-0.13.0 → activemodel-0.14.0}/activemodel/session_manager.py

@@ -150,6 +150,14 @@ def global_session(session: Session | None = None):
     This may only be called a single time per callstack. There is one exception: if you call this multiple times
     and pass in the same session reference, it will result in a noop.
 
+    In complex testing code, you'll need to be careful here. For example:
+
+    - Unit test using a transaction db fixture (which sets __sqlalchemy_session__)
+    - Factory has a after_save hook
+    - That hook triggers a celery job
+    - The celery job (properly) calls `with global_session()`
+    - However, since `global_session()` is already set with __sqlalchemy_session__, this will raise an error
+
     Args:
         session: Use an existing session instead of creating a new one
     """

{activemodel-0.13.0 → activemodel-0.14.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "activemodel"
-version = "0.13.0"
+version = "0.14.0"
 description = "Make SQLModel more like an a real ORM"
 readme = "README.md"
 requires-python = ">=3.10"

{activemodel-0.13.0 → activemodel-0.14.0}/test/nested_pydantic_json_test.py

@@ -2,9 +2,11 @@
 By default, fast API does not handle converting JSONB to and from Pydantic models.
 """
 
+from typing import Optional, Tuple
 from pydantic import BaseModel as PydanticBaseModel
 from sqlalchemy.dialects.postgresql import JSONB
 from sqlalchemy.orm.base import instance_state
+from sqlalchemy.types import UserDefinedType
 from sqlmodel import Field, Session
 
 from activemodel import BaseModel
@@ -14,6 +16,25 @@ from activemodel.session_manager import global_session
 from test.models import AnotherExample, ExampleWithComputedProperty
 
 
+class CustomTupleType(UserDefinedType):
+    """Custom SQLAlchemy type for testing tuple serialization."""
+
+    def get_col_spec(self):
+        return "TEXT"
+
+    def bind_processor(self, dialect):
+        return lambda value: None if value is None else ",".join(map(str, value))
+
+    def result_processor(self, dialect, coltype):
+        def process_value(value) -> Tuple[float, float] | None:
+            if value is None:
+                return None
+            parts = value.split(",")
+            return (float(parts[0]), float(parts[1]))
+
+        return process_value
+
+
 class SubObject(PydanticBaseModel):
     name: str
     value: int
@@ -30,7 +51,9 @@ class ExampleWithJSONB(
     unstructured_field: dict = Field(sa_type=JSONB)
     semi_structured_field: dict[str, str] = Field(sa_type=JSONB)
     optional_object_field: SubObject | None = Field(sa_type=JSONB, default=None)
-
+    old_optional_object_field: Optional[SubObject] = Field(sa_type=JSONB, default=None)
+    tuple_field: tuple[float, float] = Field(sa_type=CustomTupleType)
+    optional_tuple: Tuple | None = Field(sa_type=CustomTupleType, default=None)
     normal_field: str | None = Field(default=None)
 
 
@@ -54,14 +77,28 @@ def test_json_serialization(create_and_wipe_database):
         normal_field="test",
         semi_structured_field={"one": "two", "three": "three"},
         optional_object_field=sub_object,
+        old_optional_object_field=sub_object,
+        tuple_field=(1.0, 2.0),
+        optional_tuple=(1.0, 2.0),
     ).save()
 
+    def assert_types_preserved(obj: ExampleWithJSONB):
+        """Helper to verify all JSONB fields maintain their proper types."""
+        assert isinstance(obj.list_field[0], SubObject)
+        assert obj.optional_list_field is not None
+        assert isinstance(obj.optional_list_field[0], SubObject)
+        assert isinstance(obj.object_field, SubObject)
+        assert isinstance(obj.optional_object_field, SubObject)
+        assert isinstance(obj.old_optional_object_field, SubObject)
+        assert isinstance(obj.tuple_field, tuple)
+        assert isinstance(obj.optional_tuple, tuple)
+        assert isinstance(obj.generic_list_field, list)
+        assert isinstance(obj.generic_list_field[0], dict)
+        assert isinstance(obj.unstructured_field, dict)
+        assert isinstance(obj.semi_structured_field, dict)
+
     # make sure the types are preserved when saved
-    assert isinstance(example.list_field[0], SubObject)
-    assert example.optional_list_field
-    assert isinstance(example.optional_list_field[0], SubObject)
-    assert isinstance(example.object_field, SubObject)
-    assert isinstance(example.optional_object_field, SubObject)
+    assert_types_preserved(example)
 
     example.refresh()
 
@@ -69,23 +106,13 @@ def test_json_serialization(create_and_wipe_database):
     assert not instance_state(example).modified
 
     # make sure the types are preserved when refreshed
-    assert isinstance(example.list_field[0], SubObject)
-    assert example.optional_list_field
-    assert isinstance(example.optional_list_field[0], SubObject)
-    assert isinstance(example.object_field, SubObject)
-    assert isinstance(example.optional_object_field, SubObject)
+    assert_types_preserved(example)
 
     fresh_example = ExampleWithJSONB.get(example.id)
 
     assert fresh_example is not None
-    assert isinstance(fresh_example.object_field, SubObject)
-    assert isinstance(fresh_example.optional_object_field, SubObject)
-    assert isinstance(fresh_example.generic_list_field, list)
-    assert isinstance(fresh_example.generic_list_field[0], dict)
-    assert isinstance(fresh_example.list_field[0], SubObject)
-    assert fresh_example.optional_list_field
-    assert isinstance(fresh_example.optional_list_field[0], SubObject)
-    assert isinstance(fresh_example.unstructured_field, dict)
+    # make sure the types are preserved when loaded from database
+    assert_types_preserved(fresh_example)
 
 
 def test_computed_serialization(create_and_wipe_database):
@@ -151,6 +178,7 @@ def test_json_object_update(create_and_wipe_database):
         object_field=sub_object,
         unstructured_field={"one": "two"},
         semi_structured_field={"one": "two"},
+        tuple_field=(1.0, 2.0),
     ).save()
 
     # saving serializes the pydantic model and reloads it, which must not mark the object as dirty!

activemodel-0.14.0/test/test_query_wrapper.py

@@ -0,0 +1,163 @@
+from typing import Any, Generator, assert_type
+import uuid
+
+import sqlmodel as sm
+from sqlmodel.sql.expression import SelectOfScalar
+from sqlalchemy import column
+
+from activemodel.query_wrapper import QueryWrapper
+from test.models import ExampleRecord, UpsertTestModel
+
+
+def test_basic_types(create_and_wipe_database):
+    qw = ExampleRecord.select()
+
+    sm_query = sm.select(ExampleRecord)
+    assert_type(sm_query, SelectOfScalar[ExampleRecord])
+
+    # assert type annotation of qw is QueryWrapper[ExampleRecord]
+    assert_type(qw, QueryWrapper[ExampleRecord])
+    assert isinstance(qw, QueryWrapper)
+
+    all_records = qw.all()
+    assert_type(all_records, Generator[ExampleRecord, Any, None])
+
+    all_records_list = list(all_records)
+    assert_type(all_records_list, list[ExampleRecord])
+
+
+def test_scalar_single_column(create_and_wipe_database):
+    """Ensure QueryWrapper.scalar returns the first column value when selecting a single scalar expression.
+
+    We create a record, build a query selecting only the id column and assert scalar() returns that id.
+    """
+    record = ExampleRecord(something="hello").save()
+
+    # Build a query selecting only the id column from the ExampleRecord table
+    # Using the model .select(...) helper that forwards args to QueryWrapper
+    query = ExampleRecord.select(ExampleRecord.id).where(ExampleRecord.id == record.id)
+
+    value = query.scalar()
+
+    # Should return the primary key of the inserted record
+    assert value == record.id
+
+
+def test_exists_basic(create_and_wipe_database):
+    # empty table
+    assert ExampleRecord.select().exists() is False
+
+    r = ExampleRecord(something="hello").save()
+    assert ExampleRecord.select().exists() is True
+
+    # filter matches
+    assert ExampleRecord.select().where(ExampleRecord.id == r.id).exists() is True
+    # filter no match
+    assert (
+        ExampleRecord.select().where(ExampleRecord.id == str(uuid.uuid4())).exists()
+        is False
+    )
+
+
+def test_exists_does_not_mutate_query(create_and_wipe_database):
+    ExampleRecord(something="one").save()
+    q = ExampleRecord.select()
+    before_sql = q.sql()
+    assert q.exists() is True
+    # ensure calling exists didn't change underlying query
+    assert q.sql() == before_sql
+    # further chaining still works
+    assert q.where(ExampleRecord.something == "one").exists() is True
+
+
+# TODO needs to be fixed
+def test_select_with_args(create_and_wipe_database):
+    result = ExampleRecord.select(sm.func.count()).one()
+
+    assert result == 0
+    # TODO type inference for count() currently returns ExampleRecord | int; skip precise assert_type until generics fixed
+    # assert_type(result, int)
+
+
+# TODO needs to be fixed
+def test_result_types(create_and_wipe_database):
+    "ensure the result types are lists of the specific classes the wrapper was generated from"
+
+    ExampleRecord().save()
+
+    column_results = sm.select(column("id")).select_from(ExampleRecord)
+    # TODO column_results type is unknown
+    _ = column_results
+
+
+def test_scalar_sum_empty_returns_int_zero(create_and_wipe_database):
+    """SUM over empty table should allow easy int coercion via `or 0`."""
+    raw_sum = UpsertTestModel.select(sm.func.sum(UpsertTestModel.value)).scalar()
+    assert raw_sum is None
+
+
+def test_scalar_sum_with_rows_returns_int(create_and_wipe_database):
+    """SUM over table with rows returns an int when coerced; raw may be int already."""
+    UpsertTestModel(name="a", category="c1", value=5).save()
+    UpsertTestModel(name="b", category="c1", value=7).save()
+    UpsertTestModel(name="c", category="c2", value=0).save()
+
+    raw_sum = UpsertTestModel.select(sm.func.sum(UpsertTestModel.value)).scalar()
+    assert isinstance(raw_sum, int)
+    assert raw_sum == 12
+
+    # assert_type(raw_sum, int)  # generic inference currently loose
+
+    # Filtered sum (where no matching rows) again returns None -> coerce
+    filtered_none = (
+        UpsertTestModel.select(sm.func.sum(UpsertTestModel.value))
+        .where(UpsertTestModel.category == "does_not_exist")
+        .scalar()
+    )
+    assert filtered_none is None
+    # assert isinstance(filtered_sum, int)
+
+
+def test_sample_single_none_when_empty(create_and_wipe_database):
+    """sample() with no rows returns None when n==1."""
+    assert ExampleRecord.select().sample() is None
+
+
+def test_sample_single_record(create_and_wipe_database):
+    r = ExampleRecord(something="one").save()
+    # With only one row we always get that row
+    sampled = ExampleRecord.select().sample()
+    assert sampled == r
+
+
+def test_sample_multiple(create_and_wipe_database):
+    # Insert several records
+    records = [ExampleRecord(something=str(i)).save() for i in range(10)]
+
+    sample_n = 5
+    sampled = ExampleRecord.select().sample(sample_n)
+    assert isinstance(sampled, list)
+    assert len(sampled) == sample_n
+    # Ensure all sampled items are part of inserted records set
+    record_ids = {r.id for r in records}
+    for row in sampled:
+        assert row.id in record_ids
+    # Should be unique (very high probability); enforce deterministically by set length
+    assert len({row.id for row in sampled}) == sample_n
+
+
+def test_sample_does_not_mutate_query(create_and_wipe_database):
+    ExampleRecord(something="one").save()
+    q = ExampleRecord.select().where(ExampleRecord.something == "one")
+    before_sql = q.sql()
+    _ = q.sample()  # run sample
+    # underlying query unchanged
+    assert q.sql() == before_sql
+
+
+def test_sample_error_conditions(create_and_wipe_database):
+    try:
+        ExampleRecord.select().sample(0)
+        assert False, "Expected ValueError for n < 1"
+    except ValueError:
+        pass