activemodel 0.9.0__tar.gz → 0.10.0__tar.gz

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

@@ -1,5 +1,24 @@
 # 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)
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: activemodel
-Version: 0.9.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.9.0 → activemodel-0.10.0}/activemodel/base_model.py

@@ -4,11 +4,11 @@ from uuid import UUID
 
 import pydash
 import sqlalchemy as sa
-from sqlalchemy.orm.attributes import flag_modified as sa_flag_modified
-from sqlalchemy.orm.base import instance_state
 import sqlmodel as sm
 from sqlalchemy import Connection, event
 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
 
@@ -19,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",
@@ -137,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
@@ -163,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
@@ -186,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):
@@ -256,9 +302,9 @@ class BaseModel(SQLModel):
     def is_new(self) -> bool:
         return not self._sa_instance_state.has_identity
 
-    def flag_modified(self, *args: str):
+    def flag_modified(self, *args: str) -> None:
         """
-        Flag one or more fields as modified. Useful for marking a field containing sub-objects as modified.
+        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.
         """

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.9.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.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.9.0 → activemodel-0.10.0}/pyproject.toml

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

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

@@ -1,4 +1,5 @@
 from pydantic import computed_field
+from sqlalchemy import UniqueConstraint
 from sqlmodel import Column, Field, Integer, Relationship
 
 from activemodel import BaseModel
@@ -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/orm/test_upsert.py

@@ -0,0 +1,185 @@
+import pytest
+from sqlalchemy import UniqueConstraint
+from sqlmodel import Field
+
+from activemodel import BaseModel
+from activemodel.mixins.typeid import TypeIDMixin
+from test.models import UpsertTestModel
+
+
+def test_upsert_single_unique_field(create_and_wipe_database):
+    """Test upsert with a single unique field"""
+    # Create initial record
+    result = UpsertTestModel.upsert(
+        data={"name": "test1", "category": "A", "value": 10},
+        unique_by="name",
+    )
+
+    # 3. Ensure return value is never null
+    assert result is not None
+
+    # 2. Check field values on returned model
+    assert result.name == "test1"
+    assert result.category == "A"
+    assert result.value == 10
+
+    # Get record to verify it was created
+    db_record = UpsertTestModel.one(name="test1")
+
+    # 1. Check that returned model's ID matches the DB record
+    assert db_record.id == result.id
+
+    # Perform upsert that updates the existing record
+    updated_result = UpsertTestModel.upsert(
+        data={"name": "test1", "category": "B", "value": 20},
+        unique_by="name",
+    )
+
+    # 4. Ensure multiple upserts with same unique_by keys return object with same ID
+    assert updated_result.id == result.id
+
+    # 2. Check field values on returned model
+    assert updated_result.name == "test1"
+    assert updated_result.category == "B"
+    assert updated_result.value == 20
+
+    assert UpsertTestModel.count() == 1
+    record = UpsertTestModel.get(name="test1")
+    # 1. Double-check that DB record matches what was returned
+    assert record.id == updated_result.id
+    assert record.category == "B"
+    assert record.value == 20
+
+
+def test_upsert_multiple_unique_fields(create_and_wipe_database):
+    """Test upsert with multiple unique fields"""
+    # Create initial records
+    result1 = UpsertTestModel.upsert(
+        data={"name": "multi1", "category": "X", "value": 100},
+        unique_by=["name", "category"],
+    )
+
+    # 3. Ensure return value is never null
+    assert result1 is not None
+    # 2. Check field values on returned model
+    assert result1.name == "multi1"
+    assert result1.category == "X"
+    assert result1.value == 100
+
+    # 1. Check that returned model's ID matches the DB record
+    db_record1 = UpsertTestModel.get(name="multi1", category="X")
+    assert db_record1.id == result1.id
+
+    result2 = UpsertTestModel.upsert(
+        data={"name": "multi2", "category": "X", "value": 200},
+        unique_by=["name", "category"],
+    )
+
+    # Different name should create a new record with different ID
+    assert result2.id != result1.id
+    # 2. Check field values on returned model
+    assert result2.name == "multi2"
+    assert result2.category == "X"
+    assert result2.value == 200
+
+    assert UpsertTestModel.count() == 2
+
+    # Update one record based on both unique fields
+    updated_result = UpsertTestModel.upsert(
+        data={"name": "multi1", "category": "X", "value": 150},
+        unique_by=["name", "category"],
+    )
+
+    # 4. Ensure multiple upserts with same unique_by keys return object with same ID
+    assert updated_result.id == result1.id
+    # 2. Check field values on returned model
+    assert updated_result.name == "multi1"
+    assert updated_result.category == "X"
+    assert updated_result.value == 150
+
+    # Get records to verify one was updated and one unchanged
+    record_x = UpsertTestModel.one(name="multi1", category="X")
+    record_y = UpsertTestModel.one(name="multi2", category="X")
+
+    # 1. Check that DB records match what was returned
+    assert record_x.id == updated_result.id
+    assert record_x.value == 150  # Updated
+    assert record_y.value == 200  # Unchanged
+
+
+def test_upsert_single_update_field(create_and_wipe_database):
+    """Test upsert that updates a single field"""
+    # Create initial record
+    result = UpsertTestModel.upsert(
+        data={"name": "update1", "category": "Z", "value": 5, "description": "Initial"},
+        unique_by="name",
+    )
+
+    # 3. Ensure return value is never null
+    assert result is not None
+    # 2. Check field values on returned model
+    assert result.name == "update1"
+    assert result.category == "Z"
+    assert result.value == 5
+    assert result.description == "Initial"
+
+    # Perform upsert that only updates the value
+    updated_result = UpsertTestModel.upsert(
+        data={"name": "update1", "category": "Z", "value": 25},
+        unique_by="name",
+    )
+
+    # 4. Ensure multiple upserts with same unique_by keys return object with same ID
+    assert updated_result.id == result.id
+    # 2. Check field values on returned model
+    assert updated_result.name == "update1"
+    assert updated_result.category == "Z"
+    assert updated_result.value == 25
+    assert updated_result.description == "Initial"  # Should be preserved
+
+    # Get record to verify field was updated
+    record = UpsertTestModel.get(name="update1")
+    # 1. Check that DB record matches what was returned
+    assert record.id == updated_result.id
+    assert record.value == 25  # Updated
+    assert record.category == "Z"  # Unchanged
+    assert record.description == "Initial"  # Unchanged
+
+
+def test_upsert_multiple_update_fields(create_and_wipe_database):
+    """Test upsert that updates multiple fields"""
+    # Create initial record
+    result = UpsertTestModel.upsert(
+        data={"name": "update2", "category": "M", "value": 42, "description": "Old"},
+        unique_by="name",
+    )
+
+    # 3. Ensure return value is never null
+    assert result is not None
+    # 2. Check field values on returned model
+    assert result.name == "update2"
+    assert result.category == "M"
+    assert result.value == 42
+    assert result.description == "Old"
+
+    # Perform upsert that updates multiple fields
+    updated_result = UpsertTestModel.upsert(
+        data={"name": "update2", "value": 99, "description": "New", "category": "N"},
+        unique_by="name",
+    )
+
+    # 4. Ensure multiple upserts with same unique_by keys return object with same ID
+    assert updated_result.id == result.id
+    # 2. Check field values on returned model
+    assert updated_result.name == "update2"
+    assert updated_result.category == "N"
+    assert updated_result.value == 99
+    assert updated_result.description == "New"
+
+    # Get record to verify all fields were updated
+    record = UpsertTestModel.get(name="update2")
+    # 1. Check that DB record matches what was returned
+    assert record.id == updated_result.id
+    assert record.value == 99
+    assert record.description == "New"
+    assert record.category == "N"

activemodel-0.10.0/test/session_manager_test.py

@@ -0,0 +1,22 @@
+import contextlib
+import pytest
+from activemodel.session_manager import global_session
+
+
+def test_global_session_raises_when_nested():
+    """Test that global_session raises an error when used in a nested context."""
+
+    # First global_session should work fine
+    with global_session() as outer_session:
+        assert outer_session is not None
+
+        # Attempting to create a nested global_session should fail
+        with pytest.raises(RuntimeError) as excinfo:
+            with global_session() as _:
+                pass  # This code shouldn't execute
+
+        assert "global session already set" in str(excinfo.value)
+
+    # After exiting the outer context, we should be able to use global_session again
+    with global_session() as session:
+        assert session is not None