activemodel 0.10.0__tar.gz → 0.12.0__tar.gz

{activemodel-0.10.0 → activemodel-0.12.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.10.0 → activemodel-0.12.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.10.0 → activemodel-0.12.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.12.0/.tool-versions

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

{activemodel-0.10.0 → activemodel-0.12.0}/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## [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)
+
+
+### Features
+
+* add pydantic patch for TypeID schema serialization ([767726e](https://github.com/iloveitaly/activemodel/commit/767726eaf2a20f1c65162ba7d3a599495c83f721))
+* add typeid prefix to db field comments ([34e4574](https://github.com/iloveitaly/activemodel/commit/34e457488a6e59c4e7daf1d7495b59ac64bd7ea2))
+* render TypeIDType in plain old pydantic models ([8aa0a4d](https://github.com/iloveitaly/activemodel/commit/8aa0a4db51b425a60889064e723129041e418da5))
+
+
+### Bug Fixes
+
+* typing on upsert properly returns self ([8965113](https://github.com/iloveitaly/activemodel/commit/896511399c818e8a4a1c01ed324921e04073a279))
+
+
+### Documentation
+
+* add advanced SQLAlchemy tips to README.md ([c624ac0](https://github.com/iloveitaly/activemodel/commit/c624ac0712598d06759166ce9f91a37f40fefcfe))
+* update comments in session_manager to clarify usage ([e657a2e](https://github.com/iloveitaly/activemodel/commit/e657a2e5985be6f0770bf945fc062a05dcff8cc8))
+
 ## [0.10.0](https://github.com/iloveitaly/activemodel/compare/v0.9.0...v0.10.0) (2025-04-01)
 
 

{activemodel-0.10.0 → activemodel-0.12.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.10.0 → activemodel-0.12.0}/PKG-INFO

@@ -1,15 +1,15 @@
 Metadata-Version: 2.4
 Name: activemodel
-Version: 0.10.0
+Version: 0.12.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: textcase>=0.4.0
 Requires-Dist: typeid-python>=0.3.1
 Description-Content-Type: text/markdown
 
@@ -59,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):
@@ -81,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:
@@ -110,14 +129,14 @@ index 0d07420..a63631c 100644
  # Use forward slashes (/) also on windows to provide an os agnostic path
 -script_location = .
 +script_location = migrations
- 
+
  # template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
  # Uncomment the line below if you want the files to be prepended with date and time
  # see https://alembic.sqlalchemy.org/en/latest/tutorial.html#editing-the-ini-file
  # for all available tokens
  # file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s
 +file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(rev)s_%%(slug)s
- 
+
  # sys.path path, will be prepended to sys.path if present.
  # defaults to the current working directory.
 diff --git i/test/migrations/env.py w/test/migrations/env.py
@@ -129,12 +148,12 @@ index 36112a3..a1e15c2 100644
 +# isort: off
 +
  from logging.config import fileConfig
- 
+
  from sqlalchemy import engine_from_config
 @@ -14,11 +17,17 @@ config = context.config
  if config.config_file_name is not None:
      fileConfig(config.config_file_name)
- 
+
 +from sqlmodel import SQLModel
 +from test.models import *
 +from test.utils import database_url
@@ -147,7 +166,7 @@ index 36112a3..a1e15c2 100644
  # target_metadata = mymodel.Base.metadata
 -target_metadata = None
 +target_metadata = SQLModel.metadata
- 
+
  # other values from the config, defined by the needs of env.py,
  # can be acquired:
 diff --git i/test/migrations/script.py.mako w/test/migrations/script.py.mako
@@ -155,13 +174,13 @@ index fbc4b07..9dc78bb 100644
 --- i/test/migrations/script.py.mako
 +++ w/test/migrations/script.py.mako
 @@ -9,6 +9,8 @@ from typing import Sequence, Union
- 
+
  from alembic import op
  import sqlalchemy as sa
 +import sqlmodel
 +import activemodel
  ${imports if imports else ""}
- 
+
  # revision identifiers, used by Alembic.
 ```
 
@@ -178,7 +197,7 @@ This tool is added to all `BaseModel`s and makes it easy to write SQL queries. S
 
 ### Easy Database Sessions
 
-I hate the idea f 
+I hate the idea f
 
 * Behavior should be intuitive and easy to understand. If you run `save()`, it should save, not stick the save in a transaction.
 * Don't worry about dead sessions. This makes it easy to lazy-load computed properties and largely eliminates the need to think about database sessions.
@@ -186,7 +205,7 @@ I hate the idea f
 There are a couple of thorny problems we need to solve for here:
 
 * In-memory fastapi servers are not the same as a uvicorn server, which is threaded *and* uses some sort of threadpool model for handling async requests. I don't claim to understand the entire implementation. For global DB session state (a) we can't use global variables (b) we can't use thread-local variables.
-* 
+*
 
 https://github.com/tomwojcik/starlette-context
 
@@ -202,8 +221,12 @@ https://github.com/tomwojcik/starlette-context
 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` 
+* `ModelClass.relationship_name.property.local_columns`
 * Get cached fields from a model `object_state(instance).dict.get(field_name)`
+* 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
 
@@ -267,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
 
@@ -279,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.10.0 → activemodel-0.12.0}/README.md

@@ -44,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):
@@ -66,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:
@@ -95,14 +114,14 @@ index 0d07420..a63631c 100644
  # Use forward slashes (/) also on windows to provide an os agnostic path
 -script_location = .
 +script_location = migrations
- 
+
  # template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
  # Uncomment the line below if you want the files to be prepended with date and time
  # see https://alembic.sqlalchemy.org/en/latest/tutorial.html#editing-the-ini-file
  # for all available tokens
  # file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s
 +file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(rev)s_%%(slug)s
- 
+
  # sys.path path, will be prepended to sys.path if present.
  # defaults to the current working directory.
 diff --git i/test/migrations/env.py w/test/migrations/env.py
@@ -114,12 +133,12 @@ index 36112a3..a1e15c2 100644
 +# isort: off
 +
  from logging.config import fileConfig
- 
+
  from sqlalchemy import engine_from_config
 @@ -14,11 +17,17 @@ config = context.config
  if config.config_file_name is not None:
      fileConfig(config.config_file_name)
- 
+
 +from sqlmodel import SQLModel
 +from test.models import *
 +from test.utils import database_url
@@ -132,7 +151,7 @@ index 36112a3..a1e15c2 100644
  # target_metadata = mymodel.Base.metadata
 -target_metadata = None
 +target_metadata = SQLModel.metadata
- 
+
  # other values from the config, defined by the needs of env.py,
  # can be acquired:
 diff --git i/test/migrations/script.py.mako w/test/migrations/script.py.mako
@@ -140,13 +159,13 @@ index fbc4b07..9dc78bb 100644
 --- i/test/migrations/script.py.mako
 +++ w/test/migrations/script.py.mako
 @@ -9,6 +9,8 @@ from typing import Sequence, Union
- 
+
  from alembic import op
  import sqlalchemy as sa
 +import sqlmodel
 +import activemodel
  ${imports if imports else ""}
- 
+
  # revision identifiers, used by Alembic.
 ```
 
@@ -163,7 +182,7 @@ This tool is added to all `BaseModel`s and makes it easy to write SQL queries. S
 
 ### Easy Database Sessions
 
-I hate the idea f 
+I hate the idea f
 
 * Behavior should be intuitive and easy to understand. If you run `save()`, it should save, not stick the save in a transaction.
 * Don't worry about dead sessions. This makes it easy to lazy-load computed properties and largely eliminates the need to think about database sessions.
@@ -171,7 +190,7 @@ I hate the idea f
 There are a couple of thorny problems we need to solve for here:
 
 * In-memory fastapi servers are not the same as a uvicorn server, which is threaded *and* uses some sort of threadpool model for handling async requests. I don't claim to understand the entire implementation. For global DB session state (a) we can't use global variables (b) we can't use thread-local variables.
-* 
+*
 
 https://github.com/tomwojcik/starlette-context
 
@@ -187,8 +206,12 @@ https://github.com/tomwojcik/starlette-context
 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` 
+* `ModelClass.relationship_name.property.local_columns`
 * Get cached fields from a model `object_state(instance).dict.get(field_name)`
+* 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
 
@@ -252,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
 
@@ -264,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.10.0 → activemodel-0.12.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.10.0 → activemodel-0.12.0}/activemodel/base_model.py

@@ -2,10 +2,11 @@ import json
 import typing as t
 from uuid import UUID
 
-import pydash
 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
@@ -19,7 +20,6 @@ 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",
@@ -152,19 +152,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):
@@ -196,12 +196,13 @@ class BaseModel(SQLModel):
         "convenience method to avoid having to write .select().where() in order to add conditions"
         return cls.select().where(*args)
 
+    # TODO we should add an instance method for this as well
     @classmethod
     def upsert(
         cls,
         data: dict[str, t.Any],
         unique_by: str | list[str],
-    ) -> None:
+    ) -> t.Self:
         """
         This method will insert a new record if it doesn't exist, or update the existing record if it does.
 
@@ -233,6 +234,8 @@ class BaseModel(SQLModel):
         return result
 
     def delete(self):
+        "Delete record completely from the database"
+
         with get_session() as session:
             if old_session := Session.object_session(self):
                 old_session.expunge(self)
@@ -403,6 +406,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):
         """