activemodel 0.7.0__py3-none-any.whl → 0.8.0__py3-none-any.whl

activemodel/base_model.py

@@ -9,6 +9,9 @@ from sqlalchemy import Connection, event
 from sqlalchemy.orm import Mapper, declared_attr
 from sqlmodel import Field, MetaData, Session, SQLModel, select
 from typeid import TypeID
+from inspect import isclass
+
+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
@@ -157,7 +160,10 @@ class BaseModel(SQLModel):
     @classmethod
     def foreign_key(cls, **kwargs):
         """
-        Returns a Field object referencing the foreign key of the model.
+        Returns a `Field` object referencing the foreign key of the model.
+
+        >>> other_model_id: int
+        >>> other_model = OtherModel.foreign_key()
         """
 
         field_options = {"nullable": False} | kwargs
@@ -174,6 +180,11 @@ class BaseModel(SQLModel):
         "create a query wrapper to easily run sqlmodel queries on this model"
         return QueryWrapper[cls](cls, *args)
 
+    @classmethod
+    def where(cls, *args):
+        "convenience method to avoid having to write .select().where() in order to add conditions"
+        return cls.select().where(*args)
+
     def delete(self):
         with get_session() as session:
             if old_session := Session.object_session(self):
@@ -197,11 +208,11 @@ class BaseModel(SQLModel):
             session.commit()
             session.refresh(self)
 
-        return self
+            # 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)
 
-        # except IntegrityError:
-        #     log.quiet(f"{self} already exists in the database.")
-        #     session.rollback()
+        return self
 
     # TODO shouldn't this be handled by pydantic?
     def json(self, **kwargs):
@@ -256,6 +267,27 @@ class BaseModel(SQLModel):
         new_model = cls(**kwargs)
         return new_model
 
+    @classmethod
+    def primary_key_field(cls):
+        """
+        Returns the primary key column of the model by inspecting SQLAlchemy field information.
+
+        >>> ExampleModel.primary_key_field().name
+        """
+        # TODO note_schema.__class__.__table__.primary_key
+
+        pk_columns = list(cls.__table__.primary_key.columns)
+
+        if not pk_columns:
+            raise ValueError("No primary key defined for the model.")
+
+        if len(pk_columns) > 1:
+            raise ValueError(
+                "Multiple primary keys defined. This method supports only single primary key models."
+            )
+
+        return pk_columns[0]
+
     # TODO what's super dangerous here is you pass a kwarg which does not map to a specific
     #      field it will result in `True`, which will return all records, and not give you any typing
     #      errors. Dangerous when iterating on structure quickly

activemodel/celery.py

@@ -4,12 +4,17 @@ Do not import unless you have Celery/Kombu installed.
 In order for TypeID objects to be properly handled by celery, a custom encoder must be registered.
 """
 
+# this is not an explicit dependency, only import this file if you have Celery installed
 from kombu.utils.json import register_type
 from typeid import TypeID
 
 
 def register_celery_typeid_encoder():
-    "this ensures TypeID objects passed as arguments to a delayed function are properly serialized"
+    """
+    Ensures TypeID objects passed as arguments to a delayed function are properly serialized.
+
+    Run at the top of your celery initialization script.
+    """
 
     def class_full_name(clz) -> str:
         return ".".join([clz.__module__, clz.__qualname__])

activemodel/get_column_from_field_patch.py

@@ -6,6 +6,8 @@ Making sure these docstrings make their way to the DB schema is helpful for a bu
 This patch mutates a core sqlmodel function which translates pydantic FieldInfo objects into sqlalchemy Column objects. It adds the field description as a comment to the column.
 
 Note that FieldInfo *from pydantic* is used when a "bare" field is defined. This can be confusing, because when inspecting model fields, the class name looks exactly the same.
+
+Some ideas for this originally sourced from: https://github.com/fastapi/sqlmodel/issues/492#issuecomment-2489858633
 """
 
 from typing import (

activemodel/mixins/pydantic_json.py

@@ -1,3 +1,7 @@
+"""
+https://github.com/fastapi/sqlmodel/issues/63
+"""
+
 from types import UnionType
 from typing import get_args, get_origin
 
@@ -9,11 +13,20 @@ class PydanticJSONMixin:
     """
     By default, SQLModel does not convert JSONB columns into pydantic models when they are loaded from the database.
 
-    This mixin, combined with a custom serializer, fixes that issue.
+    This mixin, combined with a custom serializer (`_serialize_pydantic_model`), fixes that issue.
+
+    >>> class ExampleWithJSON(BaseModel, PydanticJSONMixin, table=True):
+    >>>    list_field: list[SubObject] = Field(sa_type=JSONB()
     """
 
     @reconstructor
-    def init_on_load(self):
+    def __transform_dict_to_pydantic__(self):
+        """
+        Transforms dictionary fields into Pydantic models upon loading.
+
+        - Reconstructor only runs once, when the object is loaded.
+        - We manually call this method on save(), etc to ensure the pydantic types are maintained
+        """
         # TODO do we need to inspect sa_type
         for field_name, field_info in self.model_fields.items():
             raw_value = getattr(self, field_name, None)

activemodel/pytest/transaction.py

@@ -1,12 +1,19 @@
 from activemodel import SessionManager
 
+from ..logger import logger
+
 
 def database_reset_transaction():
     """
     Wrap all database interactions for a given test in a nested transaction and roll it back after the test.
 
     >>> from activemodel.pytest import database_reset_transaction
-    >>> pytest.fixture(scope="function", autouse=True)(database_reset_transaction)
+    >>> database_reset_transaction = pytest.fixture(scope="function", autouse=True)(database_reset_transaction)
+
+    Transaction-based DB cleaning does *not* work if the DB mutations are happening in a separate process, which should
+    use spawn, because the same session is not shared across processes. Note that using `fork` is dangerous.
+
+    In this case, you should use the truncate.
 
     References:
 
@@ -14,38 +21,43 @@ def database_reset_transaction():
     - https://aalvarez.me/posts/setting-up-a-sqlalchemy-and-pytest-based-test-suite/
     - https://github.com/nickjj/docker-flask-example/blob/93af9f4fbf185098ffb1d120ee0693abcd77a38b/test/conftest.py#L77
     - https://github.com/caiola/vinhos.com/blob/c47d0a5d7a4bf290c1b726561d1e8f5d2ac29bc8/backend/test/conftest.py#L46
+    - https://stackoverflow.com/questions/64095876/multiprocessing-fork-vs-spawn
+
+    Using a named SAVEPOINT does not give us anything extra, so we are not using it.
     """
 
     engine = SessionManager.get_instance().get_engine()
 
+    logger.info("starting database transaction")
+
     with engine.begin() as connection:
         transaction = connection.begin_nested()
 
+        if SessionManager.get_instance().session_connection is not None:
+            logger.warning("session override already exists")
+            # TODO should we throw an exception here?
+
         SessionManager.get_instance().session_connection = connection
 
         try:
-            yield
+            with SessionManager.get_instance().get_session() as factory_session:
+                try:
+                    from factory.alchemy import SQLAlchemyModelFactory
+
+                    # Ensure that all factories use the same session
+                    for factory in SQLAlchemyModelFactory.__subclasses__():
+                        factory._meta.sqlalchemy_session = factory_session
+                        factory._meta.sqlalchemy_session_persistence = "commit"
+                except ImportError:
+                    pass
+
+                yield
         finally:
-            transaction.rollback()
-            # TODO is this necessary?
-            connection.close()
-
-
-# TODO unsure if this adds any value beyond the above approach
-# def database_reset_named_truncation():
-#     start_truncation_query = """
-#         BEGIN;
-#         SAVEPOINT test_truncation_savepoint;
-#     """
+            logger.debug("rolling back transaction")
 
-#     raw_sql_exec(start_truncation_query)
-
-#     yield
+            transaction.rollback()
 
-#     end_truncation_query = """
-#         ROLLBACK TO SAVEPOINT test_truncation_savepoint;
-#         RELEASE SAVEPOINT test_truncation_savepoint;
-#         ROLLBACK;
-#     """
+            # TODO is this necessary? unclear
+            connection.close()
 
-#     raw_sql_exec(end_truncation_query)
+            SessionManager.get_instance().session_connection = None

activemodel/session_manager.py

@@ -44,6 +44,7 @@ def _serialize_pydantic_model(model: BaseModel | list[BaseModel] | None) -> str
 
 class SessionManager:
     _instance: t.ClassVar[t.Optional["SessionManager"]] = None
+    "singleton instance of SessionManager"
 
     session_connection: Connection | None
     "optionally specify a specific session connection to use for all get_session() calls, useful for testing"
@@ -69,6 +70,7 @@ class SessionManager:
         if not self._engine:
             self._engine = create_engine(
                 self._database_url,
+                # NOTE very important! This enables pydantic models to be serialized for JSONB columns
                 json_serializer=_serialize_pydantic_model,
                 echo=config("ACTIVEMODEL_LOG_SQL", cast=bool, default=False),
                 # https://docs.sqlalchemy.org/en/20/core/pooling.html#disconnect-handling-pessimistic
@@ -87,6 +89,7 @@ class SessionManager:
 
             return _reuse_session()
 
+        # a connection can generate nested transactions
         if self.session_connection:
             return Session(bind=self.session_connection)
 
@@ -94,6 +97,7 @@ class SessionManager:
 
 
 def init(database_url: str):
+    "configure activemodel to connect to a specific database"
     return SessionManager.get_instance(database_url)
 
 
@@ -106,6 +110,8 @@ def get_session():
 
 
 # contextvars must be at the top-level of a module! You will not get a warning if you don't do this.
+# ContextVar is implemented in C, so it's very special and is both thread-safe and asyncio safe. This variable gives us
+# a place to persist a session to use globally across the application.
 _session_context = contextvars.ContextVar[Session | None](
     "session_context", default=None
 )
@@ -117,12 +123,23 @@ def global_session():
         token = _session_context.set(s)
 
         try:
-            yield
+            yield s
         finally:
             _session_context.reset(token)
 
 
 async def aglobal_session():
+    """
+    Use this as a fastapi dependency to get a session that is shared across the request:
+
+    >>> APIRouter(
+    >>>     prefix="/internal/v1",
+    >>>     dependencies=[
+    >>>         Depends(aglobal_session),
+    >>>     ]
+    >>> )
+    """
+
     with SessionManager.get_instance().get_session() as s:
         token = _session_context.set(s)
 

activemodel/types/typeid.py

@@ -137,6 +137,7 @@ class TypeIDType(types.TypeDecorator):
 
         return core_schema.json_or_python_schema(
             json_schema=from_uuid_schema,
+            # TODO in the the future we could add more exact types
             # metadata=core_schema.str_schema(
             #     pattern="^[0-9a-f]{24}$",
             #     min_length=24,

{activemodel-0.7.0.dist-info → activemodel-0.8.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: activemodel
-Version: 0.7.0
+Version: 0.8.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>
@@ -29,10 +29,11 @@ This package provides a thin wrapper around SQLModel that provides a more Active
 First, setup your DB:
 
 ```python
-
+import activemodel
+activemodel.init("sqlite:///database.db")
 ```
 
-Then, setup some models:
+Create models:
 
 ```python
 from activemodel import BaseModel
@@ -51,6 +52,38 @@ class User(
     a_field: str
 ```
 
+You'll need to create the models in the DB. Alembic is the best way to do it, but you can cheat as well:
+
+```python
+from sqlmodel import SQLModel
+
+SQLModel.metadata.create_all(get_engine())
+
+# now you can create a user!
+User(a_field="a").save()
+```
+
+Maybe you like JSON:
+
+```python
+from activemodel import BaseModel
+from pydantic import BaseModel as PydanticBaseModel
+from activemodel.mixins import PydanticJSONMixin, TypeIDMixin, TimestampsMixin
+
+class SubObject(PydanticBaseModel):
+    name: str
+    value: int
+
+class User(
+    BaseModel,
+    TimestampsMixin,
+    PydanticJSONMixin,
+    TypeIDMixin("user"),
+    table=True
+):
+    list_field: list[SubObject] = Field(sa_type=JSONB())
+```
+
 ## Usage
 
 ### Integrating Alembic
@@ -60,6 +93,7 @@ class User(
 * To import all of your models you want in your DB. [Here's my recommended way to do this.](https://github.com/iloveitaly/python-starter-template/blob/master/app/models/__init__.py)
 * Use your DB URL from the ENV
 * Target sqlalchemy metadata to the sqlmodel-generated metadata
+* Most likely you'll want to add [alembic-postgresql-enum](https://pypi.org/project/alembic-postgresql-enum/) so migrations work properly
 
 [Take a look at these scripts for an example of how to fully integrate Alembic into your development workflow.](https://github.com/iloveitaly/python-starter-template/blob/0af2c7e95217e34bde7357cc95be048900000e48/Justfile#L618-L712)
 
@@ -161,6 +195,15 @@ https://github.com/tomwojcik/starlette-context
 * Conditional: `Scrape.select().where(Scrape.id < last_scraped.id).all()`
 * Equality: `MenuItem.select().where(MenuItem.menu_id == menu.id).all()`
 * `IN` example: `CanonicalMenuItem.select().where(col(CanonicalMenuItem.id).in_(canonized_ids)).all()`
+* Compound where query: `User.where((User.last_active_at != None) & (User.last_active_at > last_24_hours)).count()`
+
+### SQLModel Internals
+
+SQLModel & SQLAlchemy are tricky. Here are some useful internal tricks:
+
+* `__sqlmodel_relationships__` is where any `RelationshipInfo` objects are stored. This is used to generate relationship fields on the object.
+* `ModelClass.relationship_name.property.local_columns` 
+* Get cached fields from a model `object_state(instance).dict.get(field_name)`
 
 ### TypeID
 
@@ -186,7 +229,7 @@ class Appointment(
     TypeIDMixin("appointment"),
     table=True
 ):
-    # `foreign_key` is a activemodel-specific method to generate the right `Field` for the relationship
+    # `foreign_key` is a activemodel method to generate the right `Field` for the relationship
     # TypeIDType is really important here for fastapi serialization
     doctor_id: TypeIDType = Doctor.foreign_key()
     doctor: Doctor = Relationship()
@@ -233,3 +276,7 @@ https://github.com/DarylStark/my_data/blob/a17b8b3a8463b9953821b89fee895e272f94d
 * https://github.com/fastapi/full-stack-fastapi-template
 * https://github.com/DarylStark/my_data/
 * https://github.com/petrgazarov/FastAPI-app/tree/main/fastapi_app
+
+## Upstream Changes
+
+- [ ] https://github.com/fastapi/sqlmodel/pull/1293

{activemodel-0.7.0.dist-info → activemodel-0.8.0.dist-info}/RECORD

@@ -1,24 +1,24 @@
 activemodel/__init__.py,sha256=q_lHQyIM70ApvjduTo9GtenQjJXsfYZsAAquD_51kF4,137
-activemodel/base_model.py,sha256=aa5cJYZsRvYYk-TvPP_DoblvtZrn6-KGB7YS0rbAJbw,10964
-activemodel/celery.py,sha256=F2X5VJoNej6yg__nbF2VXaq6MK8jmgUlfo5XXivfgtU,740
+activemodel/base_model.py,sha256=MM-TRlf_0DnCZHeNWxQ1S-VMq8JSBYybPfhtLZHZeRE,12066
+activemodel/celery.py,sha256=L1vKcO_HoPA5ZCfsXjxgPpDUMYDuoQMakGA9rppN7Lo,897
 activemodel/errors.py,sha256=wycWYmk9ws4TZpxvTdtXVy2SFESb8NqKgzdivBoF0vw,115
-activemodel/get_column_from_field_patch.py,sha256=Rl1KIsELSLxDGDb4K7l97Fjr1qyXZtlTJlMa7-ddllc,4869
+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=rNdvueppMse2MIi-RafTEC34GPGRal_wqH2CzhmlWS8,2520
-activemodel/session_manager.py,sha256=JpCN_mTsbYOOud9HsX6mP_HOf3i57O5haMgnv9WOeyU,3874
+activemodel/session_manager.py,sha256=Vtg8Lf8vUNPegdRW-fyE-Ng5wtN3hTMfUezdFUiJ1fs,4585
 activemodel/utils.py,sha256=g17UqkphzTmb6YdpmYwT1TM00eDiXXuWn39-xNiu0AA,2112
 activemodel/mixins/__init__.py,sha256=05EQl2u_Wgf_wkly-GTaTsR7zWpmpKcb96Js7r_rZTw,160
-activemodel/mixins/pydantic_json.py,sha256=HfnUKy_XA7MQcmR9yMTBweaNgxJhhEo3Z07hFz31gIg,2555
+activemodel/mixins/pydantic_json.py,sha256=8A5X6QVzMSvDkBIb1impZ9PYskkUviG1UW7kkoxI8Wg,3057
 activemodel/mixins/soft_delete.py,sha256=Ax4mGsQI7AVTE8c4GiWxpyB_W179-dDct79GtjP0owU,461
 activemodel/mixins/timestamps.py,sha256=Q-IFljeVVJQqw3XHdOi7dkqzefiVg1zhJvq_bldpmjg,992
 activemodel/mixins/typeid.py,sha256=DGjlIg8PRBYoaBbWkkxc6jkScyl-p53KuSR98lLgAvE,1284
 activemodel/pytest/__init__.py,sha256=W9KKQHbPkyq0jrMXaiL8hG2Nsbjy_LN9HhvgGm8W_7g,98
-activemodel/pytest/transaction.py,sha256=rrsoHnbu79kNdnI5fZeOZr5hzrLB-cQH10MueQp5jV4,1670
+activemodel/pytest/transaction.py,sha256=GfUpGUiTHATooVfxU3FMF28FHljBVdfVcb51g2KMzhY,2593
 activemodel/pytest/truncate.py,sha256=IGiPLkUm2yyOKww6c6CKcVbwi2xAAFBopx9q2ABfu8w,1582
 activemodel/types/__init__.py,sha256=y5fiGVtPJxGEhuf-TvyrkhM2yaKRcIWo6XAx-CFFjM8,31
-activemodel/types/typeid.py,sha256=uTCtTm-HdvqZ2_wkIAOkCwDMNiNZna9AbSbOBNBca7o,7225
-activemodel-0.7.0.dist-info/METADATA,sha256=Ht_6c2mD2_qGnrEDfMFxazdNqB9P4POPAU7dCrZ0s94,8216
-activemodel-0.7.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-activemodel-0.7.0.dist-info/entry_points.txt,sha256=YLX62TP_hR-n3HMBkdBex4W7XRiyOtIPkwy22puIjjQ,61
-activemodel-0.7.0.dist-info/licenses/LICENSE,sha256=L8mmpX47rB-xtJ_HsK0zpfO6viEjxbLYGn70BMp8os4,1071
-activemodel-0.7.0.dist-info/RECORD,,
+activemodel/types/typeid.py,sha256=XrwCMvAkoZSeM5WhKH-aGJeiK0e9HoTXCheEDUgBBgQ,7292
+activemodel-0.8.0.dist-info/METADATA,sha256=niH50sWYcT1c8eprDrEhetodN2bx_otnMsuzpKQZAAk,9651
+activemodel-0.8.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+activemodel-0.8.0.dist-info/entry_points.txt,sha256=YLX62TP_hR-n3HMBkdBex4W7XRiyOtIPkwy22puIjjQ,61
+activemodel-0.8.0.dist-info/licenses/LICENSE,sha256=L8mmpX47rB-xtJ_HsK0zpfO6viEjxbLYGn70BMp8os4,1071
+activemodel-0.8.0.dist-info/RECORD,,