activemodel 0.8.0__tar.gz → 0.10.0__tar.gz

{activemodel-0.8.0 → activemodel-0.10.0}/.github/workflows/build_and_publish.yml

@@ -5,11 +5,6 @@ on:
       - main
       - master
 
-# write permissions for release-please
-# permissions:
-#   contents: write
-#   pull-requests: write
-
 env:
   # avoid build failures due to flaky pypi
   PIP_DEFAULT_TIMEOUT: 60
@@ -17,10 +12,13 @@ env:
 
   DATABASE_HOST: localhost
 
+  # required otherwise github api calls are rate limited
+  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
 jobs:
   release-please:
     runs-on: ubuntu-latest
-    needs: [build]
+    needs: [matrix-test]
     outputs:
       release_created: ${{ steps.release.outputs.release_created }}
     steps:
@@ -42,17 +40,19 @@ jobs:
       - run: uv build
       - run: uv publish --token ${{ secrets.PYPI_API_TOKEN }}
 
-  build:
-    runs-on: ubuntu-latest
+  matrix-test:
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        # TODO test on macos-latest, does not have docker by default :/
+        # unfortunately, some of the typing stuff we use requires new python versions
+        python-version: ["3.13", "3.12"]
+    runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4
       - uses: jdx/mise-action@v2
-      - run: direnv allow . && direnv export gha >> "$GITHUB_ENV"
+      - run: mise use python@${{ matrix.python-version }}
       - run: docker compose up -d --wait
+      - uses: iloveitaly/github-action-direnv-load-and-mask@master
       - run: uv sync
-
-      # `uv run` prefix is required since the venv is not activated
-
-      - name: Make sure we can import the module
-        run: uv run python -c 'import ${{ github.event.repository.name }}'
       - run: uv run pytest

activemodel-0.10.0/.tool-versions

@@ -0,0 +1,3 @@
+python 3.13.2
+uv 0.6.10
+direnv 2.35.0

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

@@ -1,5 +1,43 @@
 # Changelog
 
+## [0.10.0](https://github.com/iloveitaly/activemodel/compare/v0.9.0...v0.10.0) (2025-04-01)
+
+
+### Features
+
+* add upsert method for PostgreSQL support in BaseModel ([d639de6](https://github.com/iloveitaly/activemodel/commit/d639de6cb498b72cd4b42422822c7d59ca6a646c))
+* prevent nested global sessions and add test ([3aca2cc](https://github.com/iloveitaly/activemodel/commit/3aca2ccadf3e029801d5e517f5e660af44564f73))
+* return upserted model and enhance upsert tests ([df2359a](https://github.com/iloveitaly/activemodel/commit/df2359a4ba8a00305bd3d5024b9789642b7b4718))
+
+
+### Bug Fixes
+
+* use sa_column default instead of sqlmodel ([37e299d](https://github.com/iloveitaly/activemodel/commit/37e299d43dcec7db2cdfd3bc3b572b31b3234f35))
+
+
+### Documentation
+
+* enhance docstrings in BaseModel for clarity ([12a5dee](https://github.com/iloveitaly/activemodel/commit/12a5deec1ee2480410bbad9250b253991dd12d86))
+
+## [0.9.0](https://github.com/iloveitaly/activemodel/compare/v0.8.0...v0.9.0) (2025-03-26)
+
+
+### Features
+
+* add flag_modified and modified_fields to BaseModel ([3059903](https://github.com/iloveitaly/activemodel/commit/305990387797f4fde26c7c89a8d332b6ef7ff21f))
+* add refresh method to BaseModel for database sync ([59be3bb](https://github.com/iloveitaly/activemodel/commit/59be3bb87c64c865b08a2856f043678650c07194))
+* add robust record retrieval methods to BaseModel ([d15b5a1](https://github.com/iloveitaly/activemodel/commit/d15b5a1ffbbb18b6fde94d64dbc76f45c21f7da8))
+
+
+### Bug Fixes
+
+* use set_committed_value in PydanticJSONMixin ([5446204](https://github.com/iloveitaly/activemodel/commit/5446204fc4b17ed5f1daa4c898f5ba2242b0fc40))
+
+
+### Documentation
+
+* update TODOs and correct typeid return value ([52b2514](https://github.com/iloveitaly/activemodel/commit/52b2514b6d30212a56e34c2fe4c849ff79e36e6a))
+
 ## [0.8.0](https://github.com/iloveitaly/activemodel/compare/v0.7.0...v0.8.0) (2025-03-18)
 
 

{activemodel-0.8.0 → activemodel-0.10.0}/Makefile

@@ -2,6 +2,9 @@ setup:
 	uv venv && uv sync
 	@echo "activate: source ./.venv/bin/activate"
 
+up:
+	docker compose up -d --wait
+
 db_open:
 	open -a TablePlus $$DATABASE_URL
 

{activemodel-0.8.0 → activemodel-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: activemodel
-Version: 0.8.0
+Version: 0.10.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>

{activemodel-0.8.0 → activemodel-0.10.0}/TODO

@@ -1,5 +1,6 @@
 Docs are bad:
 
+- `another_example_id: TypeIDType = AnotherExample.foreign_key(nullable=True)` nullable should be able to be defined via types
 - JSON field, specifically JSONB https://github.com/tiangolo/sqlmodel/discussions/696 and https://github.com/fastapi/sqlmodel/discussions/1105
 - One-to-many relationships
 - Data validation https://github.com/tiangolo/sqlmodel/issues/52
@@ -9,8 +10,8 @@ Docs are bad:
 
 TODO
 
+- [ ] sessions in tests, they don't work right now
 - [ ] snake case for attributes https://github.com/sqlalchemy/sqlalchemy/issues/7149
-- [ ] foreign key names https://github.com/fastapi/sqlmodel/discussions/1213
 
 
 find_or_create

{activemodel-0.8.0 → activemodel-0.10.0}/activemodel/base_model.py

@@ -7,9 +7,10 @@ import sqlalchemy as sa
 import sqlmodel as sm
 from sqlalchemy import Connection, event
 from sqlalchemy.orm import Mapper, declared_attr
-from sqlmodel import Field, MetaData, Session, SQLModel, select
+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 inspect import isclass
 
 from activemodel.mixins.pydantic_json import PydanticJSONMixin
 
@@ -18,6 +19,7 @@ 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",
@@ -136,8 +138,15 @@ class BaseModel(SQLModel):
                 cls.__table_args__ = {"comment": doc}
             elif isinstance(table_args, dict):
                 table_args.setdefault("comment", doc)
+            elif isinstance(table_args, tuple):
+                # If it's a tuple, we need to convert it to a list and add the comment
+                table_args = list(table_args)
+                table_args.append({"comment": doc})
+                cls.__table_args__ = tuple(table_args)
             else:
-                raise ValueError("Unexpected __table_args__ type")
+                raise ValueError(
+                    f"Unexpected __table_args__ type {type(table_args)}, expected dictionary."
+                )
 
     # TODO no type check decorator here
     @declared_attr
@@ -162,8 +171,10 @@ class BaseModel(SQLModel):
         """
         Returns a `Field` object referencing the foreign key of the model.
 
-        >>> other_model_id: int
-        >>> other_model = OtherModel.foreign_key()
+        Helps quickly build a many-to-one or one-to-one relationship.
+
+        >>> other_model_id: int = OtherModel.foreign_key()
+        >>> other_model = Relationship()
         """
 
         field_options = {"nullable": False} | kwargs
@@ -185,6 +196,42 @@ class BaseModel(SQLModel):
         "convenience method to avoid having to write .select().where() in order to add conditions"
         return cls.select().where(*args)
 
+    @classmethod
+    def upsert(
+        cls,
+        data: dict[str, t.Any],
+        unique_by: str | list[str],
+    ) -> None:
+        """
+        This method will insert a new record if it doesn't exist, or update the existing record if it does.
+
+        It uses SQLAlchemy's `on_conflict_do_update` and does not yet support MySQL. Some implementation details below.
+
+        ---
+
+        - `index_elements=["name"]`: Specifies the column(s) to check for conflicts (e.g., unique constraint or index). If a row with the same "name" exists, it triggers the update instead of an insert.
+        - `values`: Defines the data to insert (e.g., `name="example", value=123`). If no conflict occurs, this data is inserted as a new row.
+
+        The `set_` parameter (e.g., `set_=dict(value=123)`) then dictates what gets updated on conflict, overriding matching fields in `values` if specified.
+        """
+        index_elements = [unique_by] if isinstance(unique_by, str) else unique_by
+
+        stmt = (
+            postgres_insert(cls)
+            .values(**data)
+            .on_conflict_do_update(index_elements=index_elements, set_=data)
+            .returning(cls)
+        )
+
+        with get_session() as session:
+            result = session.exec(stmt)
+            session.commit()
+
+            # TODO this is so ugly:
+            result = result.one()[0]
+
+        return result
+
     def delete(self):
         with get_session() as session:
             if old_session := Session.object_session(self):
@@ -214,7 +261,26 @@ class BaseModel(SQLModel):
 
         return self
 
+    def refresh(self):
+        "Refreshes an object from the database"
+
+        with get_session() as session:
+            if (
+                old_session := Session.object_session(self)
+            ) and old_session is not session:
+                old_session.expunge(self)
+
+            session.add(self)
+            session.refresh(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)
+
+        return self
+
     # TODO shouldn't this be handled by pydantic?
+    # TODO where is this actually used? shoudl prob remove this
     def json(self, **kwargs):
         return json.dumps(self.dict(), default=str, **kwargs)
 
@@ -236,6 +302,29 @@ class BaseModel(SQLModel):
     def is_new(self) -> bool:
         return not self._sa_instance_state.has_identity
 
+    def flag_modified(self, *args: str) -> None:
+        """
+        Flag one or more fields as modified/mutated/dirty. Useful for marking a field containing sub-objects as modified.
+
+        Will throw an error if an invalid field is passed.
+        """
+
+        assert len(args) > 0, "Must pass at least one field name"
+
+        for field_name in args:
+            if field_name not in self.__fields__:
+                raise ValueError(f"Field '{field_name}' does not exist in the model.")
+
+            # check if the field exists
+            sa_flag_modified(self, field_name)
+
+    def modified_fields(self) -> set[str]:
+        "set of fields that are modified"
+
+        insp = inspect(self)
+
+        return {attr.key for attr in insp.attrs if attr.history.has_changes()}
+
     @classmethod
     def find_or_create_by(cls, **kwargs):
         """
@@ -268,13 +357,15 @@ class BaseModel(SQLModel):
         return new_model
 
     @classmethod
-    def primary_key_field(cls):
+    def primary_key_column(cls) -> Column:
         """
         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
+        # TODO no reason why this couldn't be cached
 
         pk_columns = list(cls.__table__.primary_key.columns)
 
@@ -297,9 +388,8 @@ class BaseModel(SQLModel):
     @classmethod
     def get(cls, *args: t.Any, **kwargs: t.Any):
         """
-        Gets a single record from the database. Pass an PK ID or a kwarg to filter by.
+        Gets a single record (or None) from the database. Pass an PK ID or kwargs to filter by.
         """
-
         # TODO id is hardcoded, not good! Need to dynamically pick the best uid field
         id_field_name = "id"
 
@@ -313,8 +403,37 @@ class BaseModel(SQLModel):
         with get_session() as session:
             return session.exec(statement).first()
 
+    @classmethod
+    def one(cls, *args: t.Any, **kwargs: t.Any):
+        """
+        Gets a single record from the database. Pass an PK ID or a kwarg to filter by.
+        """
+
+        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()
+
+    @classmethod
+    def __process_filter_args__(cls, *args: t.Any, **kwargs: t.Any):
+        """
+        Helper method to process filter arguments and implement some nice DX for our devs.
+        """
+
+        id_field_name = cls.primary_key_column().name
+
+        # special case for getting by ID without having to specify the field name
+        # TODO should dynamically add new pk types based on column definition
+        if len(args) == 1 and isinstance(args[0], (int, TypeID, str, UUID)):
+            kwargs[id_field_name] = args[0]
+            args = ()
+
+        return args, kwargs
+
     @classmethod
     def all(cls):
+        "get a generator for all records in the database"
         with get_session() as session:
             results = session.exec(sm.select(cls))
 
@@ -325,7 +444,7 @@ class BaseModel(SQLModel):
     @classmethod
     def sample(cls):
         """
-        Pick a random record from the database.
+        Pick a random record from the database. Raises if none exist.
 
         Helpful for testing and console debugging.
         """

{activemodel-0.8.0 → activemodel-0.10.0}/activemodel/mixins/pydantic_json.py

@@ -1,12 +1,16 @@
 """
-https://github.com/fastapi/sqlmodel/issues/63
+Need to store nested Pydantic models in PostgreSQL using FastAPI and SQLModel.
+
+SQLModel lacks a direct JSONField equivalent (like Tortoise ORM's JSONField), making it tricky to handle nested model data as JSON in the DB.
+
+Extensive discussion on the problem: https://github.com/fastapi/sqlmodel/issues/63
 """
 
 from types import UnionType
 from typing import get_args, get_origin
 
 from pydantic import BaseModel as PydanticBaseModel
-from sqlalchemy.orm import reconstructor
+from sqlalchemy.orm import reconstructor, attributes
 
 
 class PydanticJSONMixin:
@@ -26,6 +30,8 @@ class PydanticJSONMixin:
 
         - Reconstructor only runs once, when the object is loaded.
         - We manually call this method on save(), etc to ensure the pydantic types are maintained
+        - `set_committed_value` sets Pydantic models as committed, avoiding `setattr` marking fields as modified
+          after loading from the database.
         """
         # TODO do we need to inspect sa_type
         for field_name, field_info in self.model_fields.items():
@@ -73,10 +79,9 @@ class PydanticJSONMixin:
                     model_cls, PydanticBaseModel
                 ):
                     parsed_value = [model_cls(**item) for item in raw_value]
-                    setattr(self, field_name, parsed_value)
-
+                    attributes.set_committed_value(self, field_name, parsed_value)
                 continue
 
             # single class
             if issubclass(model_cls, PydanticBaseModel):
-                setattr(self, field_name, model_cls(**raw_value))
+                attributes.set_committed_value(self, field_name, model_cls(**raw_value))

activemodel-0.10.0/activemodel/mixins/typeid.py

@@ -0,0 +1,33 @@
+from sqlmodel import Column, Field
+from typeid import TypeID
+
+from activemodel.types.typeid import TypeIDType
+
+# global list of prefixes to ensure uniqueness
+_prefixes: list[str] = []
+
+
+def TypeIDMixin(prefix: str):
+    # make sure duplicate prefixes are not used!
+    # NOTE this will cause issues on code reloads
+    assert prefix
+    assert prefix not in _prefixes, (
+        f"prefix {prefix} already exists, pick a different one"
+    )
+
+    class _TypeIDMixin:
+        __abstract__ = True
+
+        id: TypeIDType = Field(
+            sa_column=Column(
+                TypeIDType(prefix),
+                primary_key=True,
+                nullable=False,
+                default=lambda: TypeID(prefix),
+            ),
+            # default_factory=lambda: TypeID(prefix),
+        )
+
+    _prefixes.append(prefix)
+
+    return _TypeIDMixin

{activemodel-0.8.0 → activemodel-0.10.0}/activemodel/pytest/transaction.py

@@ -28,7 +28,7 @@ def database_reset_transaction():
 
     engine = SessionManager.get_instance().get_engine()
 
-    logger.info("starting database transaction")
+    logger.info("starting global database transaction")
 
     with engine.begin() as connection:
         transaction = connection.begin_nested()

{activemodel-0.8.0 → activemodel-0.10.0}/activemodel/session_manager.py

@@ -72,6 +72,7 @@ class SessionManager:
                 self._database_url,
                 # NOTE very important! This enables pydantic models to be serialized for JSONB columns
                 json_serializer=_serialize_pydantic_model,
+                # TODO move to a constants area
                 echo=config("ACTIVEMODEL_LOG_SQL", cast=bool, default=False),
                 # https://docs.sqlalchemy.org/en/20/core/pooling.html#disconnect-handling-pessimistic
                 pool_pre_ping=True,
@@ -119,6 +120,9 @@ _session_context = contextvars.ContextVar[Session | None](
 
 @contextlib.contextmanager
 def global_session():
+    if _session_context.get() is not None:
+        raise RuntimeError("global session already set")
+
     with SessionManager.get_instance().get_session() as s:
         token = _session_context.set(s)
 
@@ -140,6 +144,9 @@ async def aglobal_session():
     >>> )
     """
 
+    if _session_context.get() is not None:
+        raise RuntimeError("global session already set")
+
     with SessionManager.get_instance().get_session() as s:
         token = _session_context.set(s)
 

{activemodel-0.8.0 → activemodel-0.10.0}/activemodel/types/typeid.py

@@ -188,5 +188,3 @@ class TypeIDType(types.TypeDecorator):
             # "minLength": 24,
             # "maxLength": 24,
         }
-
-        return core_schema.uuid_schema()

activemodel-0.10.0/playground/alternative_typeid_mixin.py

@@ -0,0 +1,22 @@
+# TODO not sure if I love the idea of a dynamic class for each mixin as used above
+#      may give this approach another shot in the future
+
+
+class TypeIDMixin2:
+    """
+    Mixin class that adds a TypeID primary key to models.
+
+
+    >>>    class MyModel(BaseModel, TypeIDMixin, prefix="xyz", table=True):
+    >>>        name: str
+
+    Will automatically have an `id` field with prefix "xyz"
+    """
+
+    def __init_subclass__(cls, *, prefix: str, **kwargs):
+        super().__init_subclass__(**kwargs)
+
+        cls.id: uuid.UUID = Field(
+            sa_column=Column(TypeIDType(prefix), primary_key=True),
+            default_factory=lambda: TypeID(prefix),
+        )

{activemodel-0.8.0 → activemodel-0.10.0}/pyproject.toml

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

activemodel-0.10.0/test/import_test.py

@@ -0,0 +1,5 @@
+import activemodel
+
+
+def test_import() -> None:
+    assert isinstance(activemodel.__name__, str)

{activemodel-0.8.0 → activemodel-0.10.0}/test/models.py

@@ -1,5 +1,6 @@
 from pydantic import computed_field
-from sqlmodel import Field, Relationship
+from sqlalchemy import UniqueConstraint
+from sqlmodel import Column, Field, Integer, Relationship
 
 from activemodel import BaseModel
 from activemodel.mixins import TypeIDMixin
@@ -42,3 +43,15 @@ class ExampleWithComputedProperty(
     @property
     def special_note(self) -> str:
         return f"SPECIAL: {self.another_example.note}"
+
+
+class UpsertTestModel(BaseModel, TypeIDMixin("upsert_test"), table=True):
+    """Test model for upsert operations"""
+
+    name: str = Field(unique=True)
+    category: str = Field(index=True)
+    value: int = Field(default=0)
+    description: str | None = Field(default=None)
+
+    # Add a composite unique constraint for the multiple unique field test
+    __table_args__ = (UniqueConstraint("name", "category", name="compound_constraint"),)

activemodel-0.10.0/test/mutation_test.py

@@ -0,0 +1,35 @@
+import pytest
+from sqlalchemy.orm.base import instance_state
+from test.models import ExampleRecord
+
+
+def assert_modified(model):
+    assert instance_state(model).modified
+
+
+def assert_clean(model):
+    assert not instance_state(model).modified
+
+
+def test_flag_modified(create_and_wipe_database):
+    example = ExampleRecord().save()
+    assert_clean(example)
+
+    example.flag_modified("something")
+    assert example.modified_fields() == {"something"}
+
+
+def test_modified_list(create_and_wipe_database):
+    example = ExampleRecord().save()
+    assert_clean(example)
+
+    example.something = "hi"
+    assert example.modified_fields() == {"something"}
+
+
+def test_error_on_bad_field(create_and_wipe_database):
+    example = ExampleRecord().save()
+    assert_clean(example)
+
+    with pytest.raises(ValueError, match="bad_field"):
+        example.flag_modified("bad_field")