activemodel 0.12.0__py3-none-any.whl → 0.14.0__py3-none-any.whl

activemodel/base_model.py

@@ -1,23 +1,21 @@
 import json
 import typing as t
+import textcase
 from uuid import UUID
+from contextlib import nullcontext
 
 import sqlalchemy as sa
 import sqlmodel as sm
-import textcase
-from sqlalchemy import Connection, event
 from sqlalchemy.dialects.postgresql import insert as postgres_insert
-from sqlalchemy.orm import Mapper, declared_attr
 from sqlalchemy.orm.attributes import flag_modified as sa_flag_modified
-from sqlalchemy.orm.base import instance_state
 from sqlmodel import Column, Field, Session, SQLModel, inspect, select
 from typeid import TypeID
+from sqlalchemy.orm import declared_attr
 
 from activemodel.mixins.pydantic_json import PydanticJSONMixin
 
 # NOTE: this patches a core method in sqlmodel to support db comments
 from . import get_column_from_field_patch  # noqa: F401
-from .logger import logger
 from .query_wrapper import QueryWrapper
 from .session_manager import get_session
 
@@ -42,85 +40,46 @@ SQLModel.metadata.naming_convention = POSTGRES_INDEXES_NAMING_CONVENTION
 
 class BaseModel(SQLModel):
     """
-    Base model class to inherit from so we can hate python less
+    Base model class to inherit from so we can hate python less.
 
-    https://github.com/woofz/sqlmodel-basecrud/blob/main/sqlmodel_basecrud/basecrud.py
+    Some notes:
 
-    - {before,after} lifecycle hooks are modeled after Rails.
-    - class docstrings are converd to table-level comments
-    - save(), delete(), select(), where(), and other easy methods you would expect
+    - Inspired by https://github.com/woofz/sqlmodel-basecrud/blob/main/sqlmodel_basecrud/basecrud.py
+    - lifecycle hooks are modeled after Rails.
+    - class docstrings are converted to table-level comments
+    - save(), delete(), select(), where(), and other easy methods you would expect in a real ORM
     - Fixes foreign key naming conventions
+    - Sane table names
+
+    Here's how hooks work:
+
+        Create/Update: before_create, after_create, before_update, after_update, before_save, after_save, around_save
+        Delete: before_delete, after_delete, around_delete
+
+    around_* hooks must be context managers (method returning a CM or a CM attribute).
+    Ordering (create): before_create -> before_save -> (enter around_save) -> persist -> after_create -> after_save -> (exit around_save)
+    Ordering (update): before_update -> before_save -> (enter around_save) -> persist -> after_update -> after_save -> (exit around_save)
+    Delete: before_delete -> (enter around_delete) -> delete -> after_delete -> (exit around_delete)
+
+        # TODO document this in activemodel, this is an interesting edge case
+    # https://claude.ai/share/f09e4f70-2ff7-4cd0-abff-44645134693a
+
     """
 
-    # this is used for table-level comments
     __table_args__ = None
 
     @classmethod
     def __init_subclass__(cls, **kwargs):
-        "Setup automatic sqlalchemy lifecycle events for the class"
-
         super().__init_subclass__(**kwargs)
 
         from sqlmodel._compat import set_config_value
 
-        # enables field-level docstrings on the pydanatic `description` field, which we then copy into
-        # sa_args, which is persisted to sql table comments
+        # Enables field-level docstrings on the pydantic `description` field, which we
+        # copy into table/column comments by patching SQLModel internals elsewhere.
         set_config_value(model=cls, parameter="use_attribute_docstrings", value=True)
 
         cls._apply_class_doc()
 
-        def event_wrapper(method_name: str):
-            """
-            This does smart heavy lifting for us to make sqlalchemy lifecycle events nicer to work with:
-
-            * Passes the target first to the lifecycle method, so it feels like an instance method
-            * Allows as little as a single positional argument, so methods can be simple
-            * Removes the need for decorators or anything fancy on the subclass
-            """
-
-            def wrapper(mapper: Mapper, connection: Connection, target: BaseModel):
-                if hasattr(cls, method_name):
-                    method = getattr(cls, method_name)
-
-                    if callable(method):
-                        arg_count = method.__code__.co_argcount
-
-                        if arg_count == 1:  # Just self/cls
-                            method(target)
-                        elif arg_count == 2:  # Self, mapper
-                            method(target, mapper)
-                        elif arg_count == 3:  # Full signature
-                            method(target, mapper, connection)
-                        else:
-                            raise TypeError(
-                                f"Method {method_name} must accept either 1 to 3 arguments, got {arg_count}"
-                            )
-                    else:
-                        logger.warning(
-                            "SQLModel lifecycle hook found, but not callable hook_name=%s",
-                            method_name,
-                        )
-
-            return wrapper
-
-        event.listen(cls, "before_insert", event_wrapper("before_insert"))
-        event.listen(cls, "before_update", event_wrapper("before_update"))
-
-        # before_save maps to two type of events
-        event.listen(cls, "before_insert", event_wrapper("before_save"))
-        event.listen(cls, "before_update", event_wrapper("before_save"))
-
-        # now, let's handle after_* variants
-        event.listen(cls, "after_insert", event_wrapper("after_insert"))
-        event.listen(cls, "after_update", event_wrapper("after_update"))
-
-        # after_save maps to two type of events
-        event.listen(cls, "after_insert", event_wrapper("after_save"))
-        event.listen(cls, "after_update", event_wrapper("after_save"))
-
-        # def foreign_key()
-        # table.id
-
     @classmethod
     def _apply_class_doc(cls):
         """
@@ -234,36 +193,81 @@ class BaseModel(SQLModel):
         return result
 
     def delete(self):
-        "Delete record completely from the database"
+        """Delete instance running delete hooks and optional around_delete context manager."""
+
+        cm = self._get_around_context_manager("around_delete") or nullcontext()
 
         with get_session() as session:
-            if old_session := Session.object_session(self):
+            if (
+                old_session := Session.object_session(self)
+            ) and old_session is not session:
                 old_session.expunge(self)
-
             session.delete(self)
-            session.commit()
-            return True
+
+            self._call_hook("before_delete")
+            with cm:
+                session.commit()
+            self._call_hook("after_delete")
+
+        return True
 
     def save(self):
+        """Persist instance running create/update hooks and optional around_save context manager."""
+
+        is_new = self.is_new()
+        cm = self._get_around_context_manager("around_save") or nullcontext()
+
         with get_session() as session:
-            if old_session := Session.object_session(self):
-                # I was running into an issue where the object was already
-                # associated with a session, but the session had been closed,
-                # to get around this, you need to remove it from the old one,
-                # then add it to the new one (below)
+            if (
+                old_session := Session.object_session(self)
+            ) and old_session is not session:
                 old_session.expunge(self)
 
             session.add(self)
-            # NOTE very important method! This triggers sqlalchemy lifecycle hooks automatically
-            session.commit()
-            session.refresh(self)
+
+            # the order and placement of these hooks is really important
+            # we need the current object to be in a session otherwise it will not be able to
+            # load any relationships.
+            self._call_hook("before_create" if is_new else "before_update")
+            self._call_hook("before_save")
+
+            with cm:
+                session.commit()
+                session.refresh(self)
+
+            self._call_hook("after_create" if is_new else "after_update")
+            self._call_hook("after_save")
 
             # Only call the transform method if the class is a subclass of PydanticJSONMixin
             if issubclass(self.__class__, PydanticJSONMixin):
                 self.__class__.__transform_dict_to_pydantic__(self)
-
         return self
 
+    def _call_hook(self, hook_name: str) -> None:
+        method = getattr(self, hook_name, None)
+        if callable(method):
+            if method.__code__.co_argcount != 1:
+                raise TypeError(
+                    f"Hook '{hook_name}' must accept exactly 1 positional argument (self)"
+                )
+            method()
+
+    def _get_around_context_manager(self, name: str) -> t.ContextManager | None:
+        obj = getattr(self, name, None)
+        if obj is None:
+            return None
+
+        # If it's a callable (method/function), call it to obtain the CM
+        if callable(obj):
+            obj = obj()
+
+        cm = obj
+        if not (hasattr(cm, "__enter__") and hasattr(cm, "__exit__")):
+            raise TypeError(
+                f"{name} must return or be a context manager implementing __enter__/__exit__"
+            )
+        return t.cast(t.ContextManager, cm)
+
     def refresh(self):
         "Refreshes an object from the database"
 
@@ -284,6 +288,7 @@ class BaseModel(SQLModel):
 
     # TODO shouldn't this be handled by pydantic?
     # TODO where is this actually used? shoudl prob remove this
+    # TODO should we even do this? Can we specify a better json rendering class?
     def json(self, **kwargs):
         return json.dumps(self.dict(), default=str, **kwargs)
 
@@ -299,7 +304,12 @@ class BaseModel(SQLModel):
     # TODO got to be a better way to fwd these along...
     @classmethod
     def first(cls):
-        return cls.select().first()
+        # TODO should use dynamic pk
+        return cls.select().order_by(sa.desc(cls.id)).first()
+
+    # @classmethod
+    # def last(cls):
+    #     return cls.select().first()
 
     # TODO throw an error if this field is set on the model
     def is_new(self) -> bool:

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/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/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.12.0.dist-info → activemodel-0.14.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: activemodel
-Version: 0.12.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.12.0.dist-info → activemodel-0.14.0.dist-info}/RECORD

@@ -1,15 +1,15 @@
 activemodel/__init__.py,sha256=q_lHQyIM70ApvjduTo9GtenQjJXsfYZsAAquD_51kF4,137
-activemodel/base_model.py,sha256=zku7nKOcN4_YpIpHjP3_sWeJWGTf141gUYtPPilY0MU,17359
+activemodel/base_model.py,sha256=0QRs2C_QtJFx6voSWr0jFXsbEgtn_PmYA2rrwejVzCU,17496
 activemodel/celery.py,sha256=L1vKcO_HoPA5ZCfsXjxgPpDUMYDuoQMakGA9rppN7Lo,897
 activemodel/errors.py,sha256=wycWYmk9ws4TZpxvTdtXVy2SFESb8NqKgzdivBoF0vw,115
 activemodel/get_column_from_field_patch.py,sha256=wAEDm_ZvSqyJwfgkXVpxsevw11hd-7VLy7zuJG8Ak7Y,4986
 activemodel/logger.py,sha256=vU7QiGSy_AJuJFmClUocqIJ-Ltku_8C24ZU8L6fLJR0,53
-activemodel/query_wrapper.py,sha256=gXpEAAFpRqQNUbTubTX-qkMNHeztFnyxtjdJbplCkKA,2867
-activemodel/session_manager.py,sha256=Aqc96ByAgrcuRRPsMZiTN3tlSXUFZvM3U7N8vCO2TIk,6720
+activemodel/query_wrapper.py,sha256=DLfmpMQr5veBjQIU2KEsp7Pe3MvdxQ-R-C6tkj0SgU8,4832
+activemodel/session_manager.py,sha256=4jK0rs3KxU84WOvHCX6iuy0mauJg02tQ2VUQj-OEk68,7124
 activemodel/utils.py,sha256=tZlAk0G46g6dwYuN7dIr8xU9QC_aLZYqjDXYkGiCtUg,888
 activemodel/cli/__init__.py,sha256=HrgJjB5pRuE6hbwgy0Dw4oHvGZ47kH0LPVAdG9l6-vw,5021
 activemodel/mixins/__init__.py,sha256=05EQl2u_Wgf_wkly-GTaTsR7zWpmpKcb96Js7r_rZTw,160
-activemodel/mixins/pydantic_json.py,sha256=0pprGZA95BGZL4WOh--NJcvxLWey4YW85lLk4GGTjFM,3530
+activemodel/mixins/pydantic_json.py,sha256=Nm8Y0ra7N-2lEvLHtmZYq1XE1-4n2BIff812DzKgOb4,4461
 activemodel/mixins/soft_delete.py,sha256=Ax4mGsQI7AVTE8c4GiWxpyB_W179-dDct79GtjP0owU,461
 activemodel/mixins/timestamps.py,sha256=C6QQNnzrNUOW1EAsMpEVpImEeTIYDMPP0wocEw2RDQw,1078
 activemodel/mixins/typeid.py,sha256=777btWRUW6YBGPApeaEdHQaoKmwblehukHzmkKoXv6o,1340
@@ -23,8 +23,8 @@ activemodel/types/sqlalchemy_protocol.py,sha256=2MSuGIp6pcIyiy8uK7qX3FLWABBMQOJG
 activemodel/types/sqlalchemy_protocol.pyi,sha256=SP4Z50SGcw6qSexGgNd_4g6E_sQwpIE44vgNT4ncmeI,5667
 activemodel/types/typeid.py,sha256=qycqklKv5nKuCqjJRnxA-6MjtcWJ4vFUsAVBc1ySwfg,7865
 activemodel/types/typeid_patch.py,sha256=y6kiCJQ_NzeKfuI4UtRAs7QW_nEog5RIA_-k4HUBMkU,575
-activemodel-0.12.0.dist-info/METADATA,sha256=j9sLMrYMP-2pnGE5yFFYELUqgbO-H8uKNCFrpHgw-8Q,10724
-activemodel-0.12.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-activemodel-0.12.0.dist-info/entry_points.txt,sha256=rytVrsNgUT4oDiW9RvRH6JBTHQn0hPZLK-jzQt3dY9s,51
-activemodel-0.12.0.dist-info/licenses/LICENSE,sha256=L8mmpX47rB-xtJ_HsK0zpfO6viEjxbLYGn70BMp8os4,1071
-activemodel-0.12.0.dist-info/RECORD,,
+activemodel-0.14.0.dist-info/METADATA,sha256=pnDgnDPyY5Nz0ooqF0rrxe1DE7JcFFKcMqXbO-6aGOs,10750
+activemodel-0.14.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+activemodel-0.14.0.dist-info/entry_points.txt,sha256=rytVrsNgUT4oDiW9RvRH6JBTHQn0hPZLK-jzQt3dY9s,51
+activemodel-0.14.0.dist-info/licenses/LICENSE,sha256=L8mmpX47rB-xtJ_HsK0zpfO6viEjxbLYGn70BMp8os4,1071
+activemodel-0.14.0.dist-info/RECORD,,