activemodel 0.11.0__py3-none-any.whl → 0.13.0__py3-none-any.whl

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):
         """

activemodel/cli/__init__.py

@@ -0,0 +1,147 @@
+"""
+This module provides utilities for generating Protocol type definitions for SQLAlchemy's
+SelectOfScalar methods, as well as formatting and fixing Python files using ruff.
+"""
+
+import inspect
+import logging
+import os
+import subprocess
+from pathlib import Path
+from typing import Any  # already imported in header of generated file
+
+import sqlmodel as sm
+from sqlmodel.sql.expression import SelectOfScalar
+
+from test.test_wrapper import QueryWrapper
+
+# Set up logging
+logging.basicConfig(level=logging.DEBUG)
+logger = logging.getLogger(__name__)
+
+QUERY_WRAPPER_CLASS_NAME = QueryWrapper.__name__
+
+
+def format_python_file(file_path: str | Path) -> bool:
+    """
+    Format a Python file using ruff.
+
+    Args:
+        file_path: Path to the Python file to format
+
+    Returns:
+        bool: True if formatting was successful, False otherwise
+    """
+    try:
+        subprocess.run(["ruff", "format", str(file_path)], check=True)
+        logger.info(f"Formatted file using ruff at {file_path}")
+        return True
+    except subprocess.CalledProcessError as e:
+        logger.error(f"Error running ruff to format the file: {e}")
+        return False
+
+
+def fix_python_file(file_path: str | Path) -> bool:
+    """
+    Fix linting issues in a Python file using ruff.
+
+    Args:
+        file_path: Path to the Python file to fix
+
+    Returns:
+        bool: True if fixing was successful, False otherwise
+    """
+    try:
+        subprocess.run(["ruff", "check", str(file_path), "--fix"], check=True)
+        logger.info(f"Fixed linting issues using ruff at {file_path}")
+        return True
+    except subprocess.CalledProcessError as e:
+        logger.error(f"Error running ruff to fix the file: {e}")
+        return False
+
+
+def generate_sqlalchemy_protocol():
+    """Generate Protocol type definitions for SQLAlchemy SelectOfScalar methods"""
+    logger.info("Starting SQLAlchemy protocol generation")
+
+    header = """
+# IMPORTANT: This file is auto-generated. Do not edit directly.
+
+from typing import Protocol, TypeVar, Any, Generic
+import sqlmodel as sm
+from sqlalchemy.sql.base import _NoArg
+
+T = TypeVar('T', bound=sm.SQLModel, covariant=True)
+
+class SQLAlchemyQueryMethods(Protocol, Generic[T]):
+    \"""Protocol defining SQLAlchemy query methods forwarded by QueryWrapper.__getattr__\"""
+"""
+    # Initialize output list for generated method signatures
+    output: list = []
+
+    try:
+        # Get all methods from SelectOfScalar
+        methods = inspect.getmembers(SelectOfScalar)
+        logger.debug(f"Discovered {len(methods)} methods from SelectOfScalar")
+
+        for name, method in methods:
+            # Skip private/dunder methods
+            if name.startswith("_"):
+                continue
+
+            if not inspect.isfunction(method) and not inspect.ismethod(method):
+                logger.debug(f"Skipping non-method: {name}")
+                continue
+
+            logger.debug(f"Processing method: {name}")
+            try:
+                signature = inspect.signature(method)
+                params = []
+
+                # Process parameters, skipping 'self'
+                for param_name, param in list(signature.parameters.items())[1:]:
+                    if param.kind == param.VAR_POSITIONAL:
+                        params.append(f"*{param_name}: Any")
+                    elif param.kind == param.VAR_KEYWORD:
+                        params.append(f"**{param_name}: Any")
+                    else:
+                        if param.default is inspect.Parameter.empty:
+                            params.append(f"{param_name}: Any")
+                        else:
+                            default_repr = repr(param.default)
+                            params.append(f"{param_name}: Any = {default_repr}")
+
+                params_str = ", ".join(params)
+                output.append(
+                    f'    def {name}(self, {params_str}) -> "{QUERY_WRAPPER_CLASS_NAME}[T]": ...'
+                )
+            except (ValueError, TypeError) as e:
+                logger.warning(f"Could not get signature for {name}: {e}")
+                # Some methods might not have proper signatures
+                output.append(
+                    f'    def {name}(self, *args: Any, **kwargs: Any) -> "{QUERY_WRAPPER_CLASS_NAME}[T]": ...'
+                )
+
+        # Write the output to a file
+        protocol_path = (
+            Path(__file__).parent.parent / "types" / "sqlalchemy_protocol.py"
+        )
+
+        # Ensure directory exists
+        os.makedirs(protocol_path.parent, exist_ok=True)
+
+        with open(protocol_path, "w") as f:
+            f.write(header + "\n".join(output))
+
+        logger.info(f"Generated SQLAlchemy protocol at {protocol_path}")
+
+        # Format and fix the generated file with ruff
+        format_python_file(protocol_path)
+        fix_python_file(protocol_path)
+    except Exception as e:
+        logger.error(f"Error generating SQLAlchemy protocol: {e}", exc_info=True)
+        raise
+
+
+if __name__ == "__main__":
+    generate_sqlalchemy_protocol()

activemodel/mixins/timestamps.py

@@ -20,7 +20,10 @@ class TimestampsMixin:
     >>> class MyModel(TimestampsMixin, SQLModel):
     >>>    pass
 
-    Originally pulled from: https://github.com/tiangolo/sqlmodel/issues/252
+    Notes:
+    
+    - Originally pulled from: https://github.com/tiangolo/sqlmodel/issues/252
+    - Related issue: https://github.com/fastapi/sqlmodel/issues/539
     """
 
     created_at: datetime | None = Field(

activemodel/mixins/typeid.py

@@ -17,7 +17,7 @@ def TypeIDMixin(prefix: str):
     # NOTE this will cause issues on code reloads
     assert prefix
     assert prefix not in _prefixes, (
-        f"prefix {prefix} already exists, pick a different one"
+        f"TypeID prefix '{prefix}' already exists, pick a different one"
     )
 
     class _TypeIDMixin:

activemodel/pytest/__init__.py

@@ -1,2 +1,2 @@
-from .transaction import database_reset_transaction
+from .transaction import database_reset_transaction, test_session
 from .truncate import database_reset_truncate

activemodel/pytest/factories.py

@@ -0,0 +1,102 @@
+"""
+Notes on polyfactory:
+
+1. is_supported_type validates that the class can be used to generate a factory
+https://github.com/litestar-org/polyfactory/issues/655#issuecomment-2727450854
+"""
+
+import typing as t
+
+from polyfactory.factories.pydantic_factory import ModelFactory
+from polyfactory.field_meta import FieldMeta
+from typeid import TypeID
+
+from activemodel.session_manager import global_session
+
+# TODO not currently used
+# def type_id_provider(cls, field_meta):
+#     # TODO this doesn't work well with __ args:
+#     # https://github.com/litestar-org/polyfactory/pull/666/files
+#     return str(TypeID("hi"))
+
+
+# BaseFactory.add_provider(TypeIDType, type_id_provider)
+
+
+class SQLModelFactory[T](ModelFactory[T]):
+    """
+    Base factory for SQLModel models:
+
+    1. Ability to ignore all relationship fks
+    2. Option to ignore all pks
+    """
+
+    __is_base_factory__ = True
+
+    @classmethod
+    def should_set_field_value(cls, field_meta: FieldMeta, **kwargs: t.Any) -> bool:
+        # TODO what is this checking for?
+        has_object_override = hasattr(cls, field_meta.name)
+
+        # TODO this should be more intelligent, it's goal is to detect all of the relationship field and avoid settings them
+        if not has_object_override and (
+            field_meta.name == "id" or field_meta.name.endswith("_id")
+        ):
+            return False
+
+        return super().should_set_field_value(field_meta, **kwargs)
+
+
+# TODO we need to think through how to handle relationships and autogenerate them
+class ActiveModelFactory[T](SQLModelFactory[T]):
+    __is_base_factory__ = True
+    __sqlalchemy_session__ = None
+
+    # TODO we shouldn't have to type this, but `save()` typing is not working
+    @classmethod
+    def save(cls, *args, **kwargs) -> T:
+        """
+        Where this gets tricky, is this can be called multiple times within the same callstack. This can happen when
+        a factory uses other factories to create relationships.
+
+        In a truncation strategy, the __sqlalchemy_session__ is set to None.
+        """
+        with global_session(cls.__sqlalchemy_session__):
+            return cls.build(*args, **kwargs).save()
+
+    @classmethod
+    def foreign_key_typeid(cls):
+        """
+        Return a random type id for the foreign key on this model.
+
+        This is helpful for generating TypeIDs for testing 404s, parsing, manually settings, etc
+        """
+        # TODO right now assumes the model is typeid, maybe we should assert against this?
+        primary_key_name = cls.__model__.primary_key_column().name
+        return TypeID(
+            cls.__model__.model_fields[primary_key_name].sa_column.type.prefix
+        )
+
+    @classmethod
+    def should_set_field_value(cls, field_meta: FieldMeta, **kwargs: t.Any) -> bool:
+        # do not default deleted at mixin to deleted!
+        # TODO should be smarter about detecting if the mixin is in place
+        if field_meta.name in ["deleted_at", "updated_at", "created_at"]:
+            return False
+
+        return super().should_set_field_value(field_meta, **kwargs)
+
+    # @classmethod
+    # def build(
+    #     cls,
+    #     factory_use_construct: bool | None = None,
+    #     sqlmodel_save: bool = False,
+    #     **kwargs: t.Any,
+    # ) -> T:
+    #     result = super().build(factory_use_construct=factory_use_construct, **kwargs)
+
+    #     # TODO allow magic dunder method here
+    #     if sqlmodel_save:
+    #         result.save()
+
+    #     return result

activemodel/pytest/plugin.py

@@ -0,0 +1,81 @@
+"""Pytest plugin integration for activemodel.
+
+Currently provides:
+
+* ``db_session`` fixture – quick access to a database session (see ``test_session``)
+* ``activemodel_preserve_tables`` ini option – configure tables to preserve when using
+  ``database_reset_truncate`` (comma separated list or multiple lines depending on config style)
+
+Configuration examples:
+
+pytest.ini::
+
+    [pytest]
+    activemodel_preserve_tables = alembic_version,zip_code,seed_table
+
+pyproject.toml::
+
+    [tool.pytest.ini_options]
+    activemodel_preserve_tables = [
+      "alembic_version",
+      "zip_code",
+      "seed_table",
+    ]
+
+The list always implicitly includes ``alembic_version`` even if not specified.
+"""
+
+from activemodel.session_manager import global_session
+import pytest
+
+from .transaction import set_factory_session, set_polyfactory_session, test_session
+
+
+def pytest_addoption(
+    parser: pytest.Parser,
+) -> None:  # pragma: no cover - executed during collection
+    """Register custom ini options.
+
+    We treat this as a *linelist* so pyproject.toml list syntax works. Comma separated works too because
+    pytest splits lines first; users can still provide one line with commas.
+    """
+
+    parser.addini(
+        "activemodel_preserve_tables",
+        help=(
+            "Tables to preserve when calling activemodel.pytest.database_reset_truncate. "
+        ),
+        type="linelist",
+        default=["alembic_version"],
+    )
+
+
+@pytest.fixture(scope="function")
+def db_session():
+    """
+    Helpful for tests that are more similar to unit tests. If you doing a routing or integration test, you
+    probably don't need this. If your unit test is simple (you are just creating a couple of models) you
+    can most likely skip this.
+
+    This is helpful if you are doing a lot of lazy-loaded params or need a database session to be in place
+    for testing code that will run within a celery worker or something similar.
+
+    >>> def the_test(db_session):
+    """
+    with test_session() as session:
+        yield session
+
+
+@pytest.fixture(scope="function")
+def db_truncate_session():
+    """
+    Provides a database session for testing when using a truncation cleaning strategy.
+
+    When not using a transaction cleaning strategy, no global test session is set
+    """
+    with global_session() as session:
+        # set global database sessions for model factories to avoid lazy loading issues
+        set_factory_session(session)
+        set_polyfactory_session(session)
+
+        yield session