activemodel 0.11.0__tar.gz → 0.13.0__tar.gz

{activemodel-0.11.0 → activemodel-0.13.0}/.envrc

@@ -10,5 +10,5 @@ export POSTGRES_DB=development
 export DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${DATABASE_HOST}:5432/development
 
 export PYTHONBREAKPOINT=ipdb.set_trace
-
+export PYTHONPATH=.
 # export ACTIVEMODEL_LOG_SQL=true

{activemodel-0.11.0 → activemodel-0.13.0}/.github/workflows/build_and_publish.yml

@@ -4,6 +4,7 @@ on:
     branches:
       - main
       - master
+  pull_request:
 
 env:
   # avoid build failures due to flaky pypi
@@ -34,8 +35,8 @@ jobs:
     needs: [release-please]
     if: needs.release-please.outputs.release_created
     steps:
-      - uses: actions/checkout@v4
-      - uses: jdx/mise-action@v2
+      - uses: actions/checkout@v5
+      - uses: jdx/mise-action@v3
       - run: direnv allow . && direnv export gha >> "$GITHUB_ENV"
       - run: uv build
       - run: uv publish --token ${{ secrets.PYPI_API_TOKEN }}
@@ -49,8 +50,8 @@ jobs:
         python-version: ["3.13", "3.12"]
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v4
-      - uses: jdx/mise-action@v2
+      - uses: actions/checkout@v5
+      - uses: jdx/mise-action@v3
       - run: mise use python@${{ matrix.python-version }}
       - run: docker compose up -d --wait
       - uses: iloveitaly/github-action-direnv-load-and-mask@master

{activemodel-0.11.0 → activemodel-0.13.0}/.github/workflows/repo-sync.yml

@@ -9,7 +9,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Fetching Local Repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
       - name: Repository Metadata Sync
         uses: iloveitaly/github-actions-metadata-sync@main
         with:

activemodel-0.13.0/.tool-versions

@@ -0,0 +1,3 @@
+python 3.13.6
+uv 0.8.10
+direnv 2.37.1

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

@@ -1,5 +1,50 @@
 # Changelog
 
+## [0.13.0](https://github.com/iloveitaly/activemodel/compare/v0.12.0...v0.13.0) (2025-09-05)
+
+
+### Features
+
+* rewritten lifecycle hooks that actually work ([af4e6fe](https://github.com/iloveitaly/activemodel/commit/af4e6fe75099ef1cc6a998b471f48f32ee8b7d5d))
+
+## [0.12.0](https://github.com/iloveitaly/activemodel/compare/v0.11.0...v0.12.0) (2025-09-03)
+
+
+### Features
+
+* add ActiveModelFactory helpers for session management and typeid generation ([a6b9915](https://github.com/iloveitaly/activemodel/commit/a6b9915cc0c74c3b0d1421bc3d0300c1a2f63426))
+* add base SQLModel and ActiveModel polyfactory factories ([12a5e1d](https://github.com/iloveitaly/activemodel/commit/12a5e1db9be741f12db174d5a25f6c2eee61a446))
+* add one_or_none method to BaseModel for safe queries ([7574777](https://github.com/iloveitaly/activemodel/commit/75747773f99a7a6cc82d2ca784ce607abd7ae511))
+* add pytest db_session fixture ([22d2ad8](https://github.com/iloveitaly/activemodel/commit/22d2ad8cbd77260c1c73524f3251ef7fd145caec))
+* add scalar method to QueryWrapper and return from delete ([3d68097](https://github.com/iloveitaly/activemodel/commit/3d680972b6a60b43de6d3826d4289b0f81847b74))
+* add SQLAlchemy protocol generation script ([6e4524e](https://github.com/iloveitaly/activemodel/commit/6e4524ed73644bea5b837ce2a9a7a1994b19df00))
+* add test_session context manager for test DB interactions ([d7a8112](https://github.com/iloveitaly/activemodel/commit/d7a8112f6b303a50df62ca55a0ca8a9c864e4686))
+* export test_session from activemodel.pytest ([9bf692a](https://github.com/iloveitaly/activemodel/commit/9bf692a72937d9a87a1ba2e574cff6dc4000bafd))
+* **pytest:** omit truncation tables, truncation db fixture ([f20f17e](https://github.com/iloveitaly/activemodel/commit/f20f17ea0854dfbde09e86f9446d57d33ab516e8))
+* support engine options ([9b00ecd](https://github.com/iloveitaly/activemodel/commit/9b00ecd4a7b1ac95a6a16b1e7727ef37afe81e00))
+* support passing session to global_session context manager ([567708a](https://github.com/iloveitaly/activemodel/commit/567708aeb6642e75b21932d599cd1431f62c4c65))
+
+
+### Bug Fixes
+
+* add return type to ActiveModelFactory save method ([96f4a0a](https://github.com/iloveitaly/activemodel/commit/96f4a0a70eb72b14dea8df16b9e92a4b79122285))
+* add ruff link + check on autogenerated types ([91ae5ea](https://github.com/iloveitaly/activemodel/commit/91ae5ea079533dc7e5600cf99c757ec5c6cd872f))
+* allow reentrant global_session when using same session reference ([d4d7949](https://github.com/iloveitaly/activemodel/commit/d4d79493afdf7ef6ae36f9f6d1c2949eb2b7c393))
+* clarify duplicate TypeID prefix error message ([a73c221](https://github.com/iloveitaly/activemodel/commit/a73c221fd51c1efa70812eb1a21a96f0af7faadc))
+* prevent factories from setting timestamp fields by default ([5d78745](https://github.com/iloveitaly/activemodel/commit/5d7874506047b7ae91f22566e1dc2c64d68814f4))
+
+
+### Documentation
+
+* added related issue ([3c47e60](https://github.com/iloveitaly/activemodel/commit/3c47e601b8f3eb8a85d9cb84a3e64df68ea10d90))
+* clarify session management and querying in usage section ([cdadaff](https://github.com/iloveitaly/activemodel/commit/cdadafffa1ac835f2f6419f40de5bf2f281f94d2))
+* connection pool tip ([5d92b99](https://github.com/iloveitaly/activemodel/commit/5d92b992d4f71af0bf8244826cd4d12281fe350b))
+* fix JSONB usage in example and clarify imports in README ([386e69d](https://github.com/iloveitaly/activemodel/commit/386e69d5ad99baddfba119f62b6d3c6a53809857))
+* improve base model tablename docstring ([de98cbc](https://github.com/iloveitaly/activemodel/commit/de98cbcff0b2ef903207f4c65fb1aa6e014cf40c))
+* **pytest:** clarify ActiveModelFactory.save behavior with relationships and truncation ([6ee2cbe](https://github.com/iloveitaly/activemodel/commit/6ee2cbef23601943271a36a90f2f453de4519c72))
+* **typeid:** clarify exception on invalid UUID string ([bf13a7e](https://github.com/iloveitaly/activemodel/commit/bf13a7e7e537d41a94ff926dcabf316b0d62625b))
+* update TODOs for testing, constraints, and unique key suggestions ([6010f8f](https://github.com/iloveitaly/activemodel/commit/6010f8fec1c3bdb22d68ac3b545ebeafd6bd04ef))
+
 ## [0.11.0](https://github.com/iloveitaly/activemodel/compare/v0.10.0...v0.11.0) (2025-04-05)
 
 

{activemodel-0.11.0 → activemodel-0.13.0}/Makefile

@@ -8,6 +8,10 @@ up:
 db_open:
 	open -a TablePlus $$DATABASE_URL
 
+lint:
+	pyright
+	ruff format
+
 clean:
 	rm -rf *.egg-info
 	rm -rf .venv

activemodel-0.11.0/README.md → activemodel-0.13.0/PKG-INFO

@@ -1,3 +1,18 @@
+Metadata-Version: 2.4
+Name: activemodel
+Version: 0.13.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>
+License-File: LICENSE
+Keywords: activemodel,activerecord,orm,sqlalchemy,sqlmodel
+Requires-Python: >=3.10
+Requires-Dist: python-decouple-typed>=3.11.0
+Requires-Dist: sqlmodel>=0.0.22
+Requires-Dist: textcase>=0.4.0
+Requires-Dist: typeid-python>=0.3.1
+Description-Content-Type: text/markdown
+
 # ActiveModel: ORM Wrapper for SQLModel
 
 No, this isn't *really* [ActiveModel](https://guides.rubyonrails.org/active_model_basics.html). It's just a wrapper around SQLModel that provides a more ActiveRecord-like interface.
@@ -44,15 +59,17 @@ from sqlmodel import SQLModel
 
 SQLModel.metadata.create_all(get_engine())
 
-# now you can create a user!
+# now you can create a user! without managing sessions!
 User(a_field="a").save()
 ```
 
 Maybe you like JSON:
 
 ```python
-from activemodel import BaseModel
+from sqlalchemy.dialects.postgresql import JSONB
 from pydantic import BaseModel as PydanticBaseModel
+
+from activemodel import BaseModel
 from activemodel.mixins import PydanticJSONMixin, TypeIDMixin, TimestampsMixin
 
 class SubObject(PydanticBaseModel):
@@ -66,11 +83,28 @@ class User(
     TypeIDMixin("user"),
     table=True
 ):
-    list_field: list[SubObject] = Field(sa_type=JSONB())
+    list_field: list[SubObject] = Field(sa_type=JSONB)
+```
+
+You'll probably want to query the model. Look ma, no sessions!
+
+```python
+User.where(id="user_123").all()
+
+# or, even better, for this case
+User.one("user_123")
 ```
 
+Magically creating sessions for DB operations is one of the main problems this project tackles. Even better, you can set
+a single session object to be used for all DB operations. This is helpful for DB transactions, [specifically rolling back
+DB operations on each test.](#pytest)
+
 ## Usage
 
+### Pytest
+
+TODO detail out truncation and transactions
+
 ### Integrating Alembic
 
 `alembic init` will not work out of the box. You need to mutate a handful of files:
@@ -192,6 +226,7 @@ SQLModel & SQLAlchemy are tricky. Here are some useful internal tricks:
 * Set the value on a field, without marking it as dirty `attributes.set_committed_value(instance, field_name, val)`
 * Is a model dirty `instance_state(instance).modified`
 * `select(Table).outerjoin??` won't work in a ipython session, but `Table.__table__.outerjoin??` will. `__table__` is a reference to the underlying SQLAlchemy table record.
+* `get_engine().pool.stats()` is helpful for inspecting connection pools and limits\
 
 ### TypeID
 
@@ -255,6 +290,7 @@ 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
 
 ## Inspiration
 
@@ -267,4 +303,4 @@ https://github.com/DarylStark/my_data/blob/a17b8b3a8463b9953821b89fee895e272f94d
 
 ## Upstream Changes
 
-- [ ] https://github.com/fastapi/sqlmodel/pull/1293
+- [ ] https://github.com/fastapi/sqlmodel/pull/1293

activemodel-0.11.0/PKG-INFO → activemodel-0.13.0/README.md

@@ -1,18 +1,3 @@
-Metadata-Version: 2.4
-Name: activemodel
-Version: 0.11.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>
-License-File: LICENSE
-Keywords: activemodel,activerecord,orm,sqlalchemy,sqlmodel
-Requires-Python: >=3.10
-Requires-Dist: pydash>=8.0.4
-Requires-Dist: python-decouple-typed>=3.11.0
-Requires-Dist: sqlmodel>=0.0.22
-Requires-Dist: typeid-python>=0.3.1
-Description-Content-Type: text/markdown
-
 # ActiveModel: ORM Wrapper for SQLModel
 
 No, this isn't *really* [ActiveModel](https://guides.rubyonrails.org/active_model_basics.html). It's just a wrapper around SQLModel that provides a more ActiveRecord-like interface.
@@ -59,15 +44,17 @@ from sqlmodel import SQLModel
 
 SQLModel.metadata.create_all(get_engine())
 
-# now you can create a user!
+# now you can create a user! without managing sessions!
 User(a_field="a").save()
 ```
 
 Maybe you like JSON:
 
 ```python
-from activemodel import BaseModel
+from sqlalchemy.dialects.postgresql import JSONB
 from pydantic import BaseModel as PydanticBaseModel
+
+from activemodel import BaseModel
 from activemodel.mixins import PydanticJSONMixin, TypeIDMixin, TimestampsMixin
 
 class SubObject(PydanticBaseModel):
@@ -81,11 +68,28 @@ class User(
     TypeIDMixin("user"),
     table=True
 ):
-    list_field: list[SubObject] = Field(sa_type=JSONB())
+    list_field: list[SubObject] = Field(sa_type=JSONB)
+```
+
+You'll probably want to query the model. Look ma, no sessions!
+
+```python
+User.where(id="user_123").all()
+
+# or, even better, for this case
+User.one("user_123")
 ```
 
+Magically creating sessions for DB operations is one of the main problems this project tackles. Even better, you can set
+a single session object to be used for all DB operations. This is helpful for DB transactions, [specifically rolling back
+DB operations on each test.](#pytest)
+
 ## Usage
 
+### Pytest
+
+TODO detail out truncation and transactions
+
 ### Integrating Alembic
 
 `alembic init` will not work out of the box. You need to mutate a handful of files:
@@ -207,6 +211,7 @@ SQLModel & SQLAlchemy are tricky. Here are some useful internal tricks:
 * Set the value on a field, without marking it as dirty `attributes.set_committed_value(instance, field_name, val)`
 * Is a model dirty `instance_state(instance).modified`
 * `select(Table).outerjoin??` won't work in a ipython session, but `Table.__table__.outerjoin??` will. `__table__` is a reference to the underlying SQLAlchemy table record.
+* `get_engine().pool.stats()` is helpful for inspecting connection pools and limits\
 
 ### TypeID
 
@@ -270,6 +275,7 @@ 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
 
 ## Inspiration
 
@@ -282,4 +288,4 @@ https://github.com/DarylStark/my_data/blob/a17b8b3a8463b9953821b89fee895e272f94d
 
 ## Upstream Changes
 
-- [ ] https://github.com/fastapi/sqlmodel/pull/1293
+- [ ] https://github.com/fastapi/sqlmodel/pull/1293

{activemodel-0.11.0 → activemodel-0.13.0}/TODO

@@ -10,9 +10,12 @@ Docs are bad:
 
 TODO
 
+- [ ] nested sessions, maybe only with connections
+- [ ] tests for polyfactory support, setting session across all factories
 - [ ] sessions in tests, they don't work right now
 - [ ] snake case for attributes https://github.com/sqlalchemy/sqlalchemy/issues/7149
-
+- [ ] compound unique constraints don't have great names
+- [ ] https://grok.com/share/bGVnYWN5_7bfd5140-2351-4e4f-a8ba-bdedb59ac1e1 figure out better json tracking
 
 find_or_create
 
@@ -50,3 +53,14 @@ clear engine
 #         _engine = None
 #         _connection = None
 ```
+
+---
+
+There should be a better way to add unique keys
+
+```
+    __table_args__ = (
+        # users should never see two schemas with the same name
+        UniqueConstraint("note_type", "doctor_id", name="doctor_and_note_type_unique"),
+    )
+```

{activemodel-0.11.0 → activemodel-0.13.0}/activemodel/base_model.py

@@ -1,25 +1,23 @@
 import json
 import typing as t
+import textcase
 from uuid import UUID
+from contextlib import nullcontext
 
-import pydash
 import sqlalchemy as sa
 import sqlmodel as sm
-from sqlalchemy import Connection, event
-from sqlalchemy.orm import Mapper, declared_attr
+from sqlalchemy.dialects.postgresql import insert as postgres_insert
 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
-from sqlalchemy.dialects.postgresql import insert as postgres_insert
 
 POSTGRES_INDEXES_NAMING_CONVENTION = {
     "ix": "%(column_0_label)s_idx",
@@ -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):
         """
@@ -152,19 +111,19 @@ class BaseModel(SQLModel):
     @declared_attr
     def __tablename__(cls) -> str:
         """
-        Automatically generates the table name for the model by converting the class name from camel case to snake case.
-        This is the recommended format for table names:
+        Automatically generates the table name for the model by converting the model's class name from camel case to snake case.
+        This is the recommended text case style for table names:
 
         https://wiki.postgresql.org/wiki/Don%27t_Do_This#Don.27t_use_upper_case_table_or_column_names
 
-        By default, the class is lower cased which makes it harder to read.
+        By default, the model's class name is lower cased which makes it harder to read.
 
-        Many snake_case libraries struggle with snake case for names like LLMCache, which is why we are using a more
-        complicated implementation from pydash.
+        Also, many text case conversion libraries struggle handling words like "LLMCache", this is why we are using
+        a more precise library which processes such acronyms: [`textcase`](https://pypi.org/project/textcase/).
 
         https://stackoverflow.com/questions/1175208/elegant-python-function-to-convert-camelcase-to-snake-case
         """
-        return pydash.strings.snake_case(cls.__name__)
+        return textcase.snake(cls.__name__)
 
     @classmethod
     def foreign_key(cls, **kwargs):
@@ -234,34 +193,81 @@ class BaseModel(SQLModel):
         return result
 
     def delete(self):
+        """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"
 
@@ -282,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)
 
@@ -297,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:
@@ -404,6 +416,19 @@ class BaseModel(SQLModel):
         with get_session() as session:
             return session.exec(statement).first()
 
+    @classmethod
+    def one_or_none(cls, *args: t.Any, **kwargs: t.Any):
+        """
+        Gets a single record from the database. Pass an PK ID or a kwarg to filter by.
+        Returns None if no record is found. Throws an error if more than one record is found.
+        """
+
+        args, kwargs = cls.__process_filter_args__(*args, **kwargs)
+        statement = select(cls).filter(*args).filter_by(**kwargs)
+
+        with get_session() as session:
+            return session.exec(statement).one_or_none()
+
     @classmethod
     def one(cls, *args: t.Any, **kwargs: t.Any):
         """