async-easy-model 0.2.2__py3-none-any.whl → 0.2.4__py3-none-any.whl

async_easy_model/model.py

@@ -10,6 +10,7 @@ from datetime import datetime, timezone as tz
 import inspect
 import json
 import logging
+import re
 
 T = TypeVar("T", bound="EasyModel")
 
@@ -212,8 +213,9 @@ class EasyModel(SQLModel):
     @classmethod
     async def all(
         cls: Type[T], 
-        include_relationships: bool = True,
-        order_by: Optional[Union[str, List[str]]] = None
+        include_relationships: bool = True, 
+        order_by: Optional[Union[str, List[str]]] = None,
+        max_depth: int = 2
     ) -> List[T]:
         """
         Retrieve all records of this model.
@@ -222,29 +224,20 @@ class EasyModel(SQLModel):
             include_relationships: If True, eagerly load all relationships
             order_by: Field(s) to order by. Can be a string or list of strings.
                       Prefix with '-' for descending order (e.g. '-created_at')
+            max_depth: Maximum depth for loading nested relationships
             
         Returns:
             A list of all model instances
         """
-        async with cls.get_session() as session:
-            statement = select(cls)
-            
-            # Apply ordering
-            statement = cls._apply_order_by(statement, order_by)
-            
-            if include_relationships:
-                # Get all relationship attributes, including auto-detected ones
-                for rel_name in cls._get_auto_relationship_fields():
-                    statement = statement.options(selectinload(getattr(cls, rel_name)))
-                    
-            result = await session.execute(statement)
-            return result.scalars().all()
+        return await cls.select({}, all=True, include_relationships=include_relationships, 
+                               order_by=order_by, max_depth=max_depth)
     
     @classmethod
     async def first(
         cls: Type[T], 
-        include_relationships: bool = True,
-        order_by: Optional[Union[str, List[str]]] = None
+        include_relationships: bool = True, 
+        order_by: Optional[Union[str, List[str]]] = None,
+        max_depth: int = 2
     ) -> Optional[T]:
         """
         Retrieve the first record of this model.
@@ -253,56 +246,37 @@ class EasyModel(SQLModel):
             include_relationships: If True, eagerly load all relationships
             order_by: Field(s) to order by. Can be a string or list of strings.
                       Prefix with '-' for descending order (e.g. '-created_at')
+            max_depth: Maximum depth for loading nested relationships
             
         Returns:
             The first model instance or None if no records exist
         """
-        async with cls.get_session() as session:
-            statement = select(cls)
-            
-            # Apply ordering
-            statement = cls._apply_order_by(statement, order_by)
-            
-            if include_relationships:
-                # Get all relationship attributes, including auto-detected ones
-                for rel_name in cls._get_auto_relationship_fields():
-                    statement = statement.options(selectinload(getattr(cls, rel_name)))
-                    
-            result = await session.execute(statement)
-            return result.scalars().first()
+        return await cls.select({}, first=True, include_relationships=include_relationships, 
+                               order_by=order_by, max_depth=max_depth)
     
     @classmethod
     async def limit(
         cls: Type[T], 
         count: int, 
-        include_relationships: bool = True,
-        order_by: Optional[Union[str, List[str]]] = None
+        include_relationships: bool = True, 
+        order_by: Optional[Union[str, List[str]]] = None,
+        max_depth: int = 2
     ) -> List[T]:
         """
-        Retrieve a limited number of records of this model.
+        Retrieve a limited number of records.
         
         Args:
-            count: Maximum number of records to retrieve
+            count: Maximum number of records to return
             include_relationships: If True, eagerly load all relationships
             order_by: Field(s) to order by. Can be a string or list of strings.
                       Prefix with '-' for descending order (e.g. '-created_at')
+            max_depth: Maximum depth for loading nested relationships
             
         Returns:
-            A list of model instances up to the specified count
+            A list of model instances
         """
-        async with cls.get_session() as session:
-            statement = select(cls).limit(count)
-            
-            # Apply ordering
-            statement = cls._apply_order_by(statement, order_by)
-            
-            if include_relationships:
-                # Get all relationship attributes, including auto-detected ones
-                for rel_name in cls._get_auto_relationship_fields():
-                    statement = statement.options(selectinload(getattr(cls, rel_name)))
-                    
-            result = await session.execute(statement)
-            return result.scalars().all()
+        return await cls.select({}, all=True, include_relationships=include_relationships, 
+                               order_by=order_by, limit=count, max_depth=max_depth)
 
     @classmethod
     async def get_by_id(cls: Type[T], id: int, include_relationships: bool = True) -> Optional[T]:
@@ -327,6 +301,20 @@ class EasyModel(SQLModel):
             else:
                 return await session.get(cls, id)
 
+    @classmethod
+    def _get_unique_fields(cls) -> List[str]:
+        """
+        Get all fields with unique=True constraint
+        
+        Returns:
+            List of field names that have unique constraints
+        """
+        unique_fields = []
+        for name, field in cls.__fields__.items():
+            if name != 'id' and hasattr(field, "field_info") and field.field_info.extra.get('unique', False):
+                unique_fields.append(name)
+        return unique_fields
+
     @classmethod
     async def get_by_attribute(
         cls: Type[T], 
@@ -391,193 +379,76 @@ class EasyModel(SQLModel):
             return result.scalars().first()
 
     @classmethod
-    async def insert(cls: Type[T], data: Union[Dict[str, Any], List[Dict[str, Any]]], include_relationships: bool = True) -> Union[T, List[T]]:
+    async def insert(cls: Type[T], data: Union[Dict[str, Any], List[Dict[str, Any]]], include_relationships: bool = True, max_depth: int = 2) -> Union[T, List[T]]:
         """
         Insert one or more records.
         
         Args:
             data: Dictionary of field values or a list of dictionaries for multiple records
             include_relationships: If True, return the instance(s) with relationships loaded
+            max_depth: Maximum depth for loading nested relationships
             
         Returns:
             The created model instance(s)
         """
-        # Handle list of records
+        if not data:
+            return None
+            
+        # Handle single dict or list of dicts
         if isinstance(data, list):
-            objects = []
-            async with cls.get_session() as session:
-                for item in data:
-                    try:
-                        # Process relationships first
-                        processed_item = await cls._process_relationships_for_insert(session, item)
-                        
-                        # Check if a record with unique constraints already exists
-                        unique_fields = cls._get_unique_fields()
-                        existing_obj = None
-                        
-                        if unique_fields:
-                            unique_criteria = {field: processed_item[field] 
-                                              for field in unique_fields 
-                                              if field in processed_item}
-                            
-                            if unique_criteria:
-                                # Try to find existing record with these unique values
-                                statement = select(cls)
-                                for field, value in unique_criteria.items():
-                                    statement = statement.where(getattr(cls, field) == value)
-                                result = await session.execute(statement)
-                                existing_obj = result.scalars().first()
-                        
-                        if existing_obj:
-                            # Update existing object with new values
-                            for key, value in processed_item.items():
-                                if key != 'id':  # Don't update ID
-                                    setattr(existing_obj, key, value)
-                            objects.append(existing_obj)
-                        else:
-                            # Create new object
-                            obj = cls(**processed_item)
-                            session.add(obj)
-                            objects.append(obj)
-                    except Exception as e:
-                        logging.error(f"Error inserting record: {e}")
-                        await session.rollback()
-                        raise
-                
-                try:
-                    await session.flush()
-                    await session.commit()
-                    
-                    # Refresh with relationships if requested
-                    if include_relationships:
-                        for obj in objects:
-                            await session.refresh(obj)
-                except Exception as e:
-                    logging.error(f"Error committing transaction: {e}")
-                    await session.rollback()
-                    raise
-                        
-                return objects
-        else:
-            # Single record case
-            async with cls.get_session() as session:
-                try:
-                    # Process relationships first
-                    processed_data = await cls._process_relationships_for_insert(session, data)
-                    
-                    # Check if a record with unique constraints already exists
-                    unique_fields = cls._get_unique_fields()
-                    existing_obj = None
-                    
-                    if unique_fields:
-                        unique_criteria = {field: processed_data[field] 
-                                          for field in unique_fields 
-                                          if field in processed_data}
-                        
-                        if unique_criteria:
-                            # Try to find existing record with these unique values
-                            statement = select(cls)
-                            for field, value in unique_criteria.items():
-                                statement = statement.where(getattr(cls, field) == value)
-                            result = await session.execute(statement)
-                            existing_obj = result.scalars().first()
-                    
-                    if existing_obj:
-                        # Update existing object with new values
-                        for key, value in processed_data.items():
-                            if key != 'id':  # Don't update ID
-                                setattr(existing_obj, key, value)
-                        obj = existing_obj
-                    else:
-                        # Create new object
-                        obj = cls(**processed_data)
-                        session.add(obj)
-                    
-                    await session.flush()  # Flush to get the ID
-                    await session.commit()
-                    
-                    if include_relationships:
-                        # Refresh with relationships
-                        statement = select(cls).where(cls.id == obj.id)
-                        for rel_name in cls._get_auto_relationship_fields():
-                            statement = statement.options(selectinload(getattr(cls, rel_name)))
-                        result = await session.execute(statement)
-                        return result.scalars().first()
-                    else:
-                        await session.refresh(obj)
-                        return obj
-                except Exception as e:
-                    logging.error(f"Error inserting record: {e}")
-                    await session.rollback()
-                    raise
-    
-    @classmethod
-    async def insert_with_related(
-        cls: Type[T], 
-        data: Dict[str, Any],
-        related_data: Dict[str, List[Dict[str, Any]]] = None
-    ) -> T:
-        """
-        Create a model instance with related objects in a single transaction.
+            results = []
+            for item in data:
+                result = await cls.insert(item, include_relationships, max_depth)
+                results.append(result)
+            return results
         
-        Args:
-            data: Dictionary of field values for the main model
-            related_data: Dictionary mapping relationship names to lists of data dictionaries
-                          for creating related objects
-                          
-        Returns:
-            The created model instance with relationships loaded
-        """
-        if related_data is None:
-            related_data = {}
-            
+        # Store many-to-many relationship data for later processing
+        many_to_many_data = {}
+        many_to_many_rels = cls._get_many_to_many_relationships()
+        
+        # Extract many-to-many data before processing other relationships
+        for rel_name in many_to_many_rels:
+            if rel_name in data:
+                many_to_many_data[rel_name] = data[rel_name]
+        
+        # Process relationships to convert nested objects to foreign keys
         async with cls.get_session() as session:
-            # Create the main object
-            obj = cls(**data)
-            session.add(obj)
-            await session.flush()  # Flush to get the ID
-            
-            # Create related objects
-            for rel_name, items_data in related_data.items():
-                if not hasattr(cls, rel_name):
-                    continue
-                    
-                rel_attr = getattr(cls, rel_name)
-                if not hasattr(rel_attr, "property"):
-                    continue
-                    
-                # Get the related model class and the back reference attribute
-                related_model = rel_attr.property.mapper.class_
-                back_populates = getattr(rel_attr.property, "back_populates", None)
+            try:
+                processed_data = await cls._process_relationships_for_insert(session, data)
                 
-                # Create each related object
-                for item_data in items_data:
-                    # Set the back reference if it exists
-                    if back_populates:
-                        item_data[back_populates] = obj
-                        
-                    related_obj = related_model(**item_data)
-                    session.add(related_obj)
-            
-            await session.commit()
-            
-            # Refresh with relationships
-            await session.refresh(obj, attribute_names=list(related_data.keys()))
-            return obj
-
-    @classmethod
-    def _get_unique_fields(cls) -> List[str]:
-        """
-        Get all fields with unique=True constraint
-        
-        Returns:
-            List of field names that have unique constraints
-        """
-        unique_fields = []
-        for name, field in cls.__fields__.items():
-            if name != 'id' and hasattr(field, 'field_info') and field.field_info.extra.get('unique', False):
-                unique_fields.append(name)
-        return unique_fields
+                # Create the model instance
+                obj = cls(**processed_data)
+                session.add(obj)
+                
+                # Flush to get the object ID
+                await session.flush()
+                
+                # Now process many-to-many relationships if any
+                for rel_name, rel_data in many_to_many_data.items():
+                    if isinstance(rel_data, list):
+                        await cls._process_many_to_many_relationship(
+                            session, obj, rel_name, rel_data
+                        )
+                
+                # Commit the transaction
+                await session.commit()
+                
+                if include_relationships:
+                    # Reload with relationships
+                    return await cls._load_relationships_recursively(session, obj, max_depth)
+                else:
+                    return obj
+                    
+            except Exception as e:
+                await session.rollback()
+                logging.error(f"Error inserting {cls.__name__}: {e}")
+                if "UNIQUE constraint failed" in str(e):
+                    field_match = re.search(r"UNIQUE constraint failed: \w+\.(\w+)", str(e))
+                    if field_match:
+                        field_name = field_match.group(1)
+                        value = data.get(field_name)
+                        raise ValueError(f"A record with {field_name}='{value}' already exists")
+                raise
 
     @classmethod
     async def _process_relationships_for_insert(cls: Type[T], session: AsyncSession, data: Dict[str, Any]) -> Dict[str, Any]:
@@ -591,6 +462,15 @@ class EasyModel(SQLModel):
             "quantity": 2
         })
         
+        It also handles lists of related objects for one-to-many relationships:
+        publisher = await Publisher.insert({
+            "name": "Example Publisher",
+            "authors": [
+                {"name": "Author 1", "email": "author1@example.com"},
+                {"name": "Author 2", "email": "author2@example.com"}
+            ]
+        })
+        
         For each nested object:
         1. Find the target model class
         2. Check if an object with the same unique fields already exists
@@ -605,175 +485,208 @@ class EasyModel(SQLModel):
         Returns:
             Processed data dictionary with nested objects replaced by their foreign key IDs
         """
-        import copy
-        result = copy.deepcopy(data)
+        if not data:
+            return {}
+            
+        result = dict(data)
         
-        # Get all relationship fields for this model
+        # Get relationship fields for this model
         relationship_fields = cls._get_auto_relationship_fields()
         
-        # Get foreign key fields
-        foreign_key_fields = []
-        for field_name, field_info in cls.__fields__.items():
-            if field_name.endswith("_id") and hasattr(field_info, "field_info"):
-                if field_info.field_info.extra.get("foreign_key"):
-                    foreign_key_fields.append(field_name)
-        
-        # Handle nested relationship objects
-        for key, value in data.items():
-            # Skip if the value is not a dictionary
-            if not isinstance(value, dict):
+        # Get many-to-many relationships separately
+        many_to_many_relationships = cls._get_many_to_many_relationships()
+        
+        # Set of field names already processed as many-to-many relationships
+        processed_m2m_fields = set()
+            
+        # Process each relationship field in the input data
+        for key in list(result.keys()):
+            value = result[key]
+            
+            # Skip empty values
+            if value is None:
                 continue
-                
-            # Check if this is a relationship field (either by name or derived from foreign key)
-            is_rel_field = key in relationship_fields
-            related_key = f"{key}_id"
-            is_derived_rel = related_key in foreign_key_fields
             
-            # If it's a relationship field or derived from a foreign key
-            if is_rel_field or is_derived_rel or related_key in cls.__fields__:
-                # Find the related model class
+            # Check if this is a relationship field
+            if key in relationship_fields:
+                # Get the related model class
                 related_model = None
                 
-                # Try to get the related model from the attribute
-                if hasattr(cls, key) and hasattr(getattr(cls, key), 'property'):
-                    # Get from relationship attribute
+                if hasattr(cls, key):
                     rel_attr = getattr(cls, key)
-                    related_model = rel_attr.property.mapper.class_
-                else:
-                    # Try to find it from foreign key definition
-                    fk_definition = None
-                    for field_name, field_info in cls.__fields__.items():
-                        if field_name == related_key and hasattr(field_info, "field_info"):
-                            fk_definition = field_info.field_info.extra.get("foreign_key")
-                            break
-                    
-                    if fk_definition:
-                        # Parse foreign key definition (e.g. "users.id")
-                        target_table, _ = fk_definition.split(".")
-                        # Try to find the target model
-                        from async_easy_model.auto_relationships import get_model_by_table_name, singularize_name
-                        related_model = get_model_by_table_name(target_table)
-                        if not related_model:
-                            # Try with the singular form
-                            singular_table = singularize_name(target_table)
-                            related_model = get_model_by_table_name(singular_table)
-                    else:
-                        # Try to infer from field name (e.g., "user_id" -> Users)
-                        base_name = related_key[:-3]  # Remove "_id"
-                        from async_easy_model.auto_relationships import get_model_by_table_name, singularize_name, pluralize_name
-                        
-                        # Try singular and plural forms
-                        related_model = get_model_by_table_name(base_name)
-                        if not related_model:
-                            plural_table = pluralize_name(base_name)
-                            related_model = get_model_by_table_name(plural_table)
-                        if not related_model:
-                            singular_table = singularize_name(base_name)
-                            related_model = get_model_by_table_name(singular_table)
+                    if hasattr(rel_attr, 'prop') and hasattr(rel_attr.prop, 'mapper'):
+                        related_model = rel_attr.prop.mapper.class_
                 
                 if not related_model:
-                    logging.warning(f"Could not find related model for {key} in {cls.__name__}")
+                    logging.warning(f"Could not determine related model for {key}, skipping")
                     continue
                 
-                # Look for unique fields in the related model to use for searching
-                unique_fields = []
-                for field_name, field_info in related_model.__fields__.items():
-                    if (hasattr(field_info, "field_info") and 
-                        field_info.field_info.extra.get('unique', False)):
-                        unique_fields.append(field_name)
-                
-                # Create a search dictionary using unique fields
-                search_dict = {}
-                for field in unique_fields:
-                    if field in value and value[field] is not None:
-                        search_dict[field] = value[field]
-                
-                # If no unique fields found but ID is provided, use it
-                if not search_dict and 'id' in value and value['id']:
-                    search_dict = {'id': value['id']}
+                # Check if this is a many-to-many relationship field
+                if key in many_to_many_relationships:
+                    # Store this separately - we'll handle it after the main object is created
+                    processed_m2m_fields.add(key)
+                    continue
                 
-                # Special case for products without uniqueness constraints
-                if not search_dict and related_model.__tablename__ == 'products' and 'name' in value:
-                    search_dict = {'name': value['name']}
+                # Handle different relationship types based on data type
+                if isinstance(value, list):
+                    # Handle one-to-many relationship (list of dictionaries)
+                    related_ids = []
+                    for item in value:
+                        if isinstance(item, dict):
+                            related_obj = await cls._process_single_relationship_item(
+                                session, related_model, item
+                            )
+                            if related_obj:
+                                related_ids.append(related_obj.id)
+                    
+                    # Update result with list of foreign key IDs
+                    foreign_key_list_name = f"{key}_ids"
+                    result[foreign_key_list_name] = related_ids
+                    
+                    # Remove the relationship list from the result
+                    if key in result:
+                        del result[key]
                 
-                # Try to find an existing record
-                related_obj = None
-                if search_dict:
-                    logging.info(f"Searching for existing {related_model.__name__} with {search_dict}")
+                elif isinstance(value, dict):
+                    # Handle one-to-one relationship (single dictionary)
+                    related_obj = await cls._process_single_relationship_item(
+                        session, related_model, value
+                    )
                     
-                    try:
-                        # Create a more appropriate search query based on unique fields
-                        existing_stmt = select(related_model)
-                        for field, field_value in search_dict.items():
-                            existing_stmt = existing_stmt.where(getattr(related_model, field) == field_value)
-                        
-                        existing_result = await session.execute(existing_stmt)
-                        related_obj = existing_result.scalars().first()
+                    if related_obj:
+                        # Update the result with the foreign key ID
+                        foreign_key_name = f"{key}_id"
+                        result[foreign_key_name] = related_obj.id
                         
-                        if related_obj:
-                            logging.info(f"Found existing {related_model.__name__} with ID: {related_obj.id}")
-                    except Exception as e:
-                        logging.error(f"Error finding existing record: {e}")
+                        # Remove the relationship dictionary from the result
+                        if key in result:
+                            del result[key]
+        
+        # Remove any processed many-to-many fields from the result
+        # since we'll handle them separately after the object is created
+        for key in processed_m2m_fields:
+            if key in result:
+                del result[key]
+        
+        return result
+
+    @classmethod
+    async def _process_single_relationship_item(cls, session: AsyncSession, related_model: Type, item_data: Dict[str, Any]) -> Optional[Any]:
+        """
+        Process a single relationship item (dictionary).
+        
+        This helper method is used by _process_relationships_for_insert to handle
+        both singular relationship objects and items within lists of relationships.
+        
+        Args:
+            session: The database session to use
+            related_model: The related model class
+            item_data: Dictionary with field values for the related object
+            
+        Returns:
+            The created or found related object, or None if processing failed
+        """
+        # Look for unique fields in the related model to use for searching
+        unique_fields = []
+        for name, field in related_model.__fields__.items():
+            if (hasattr(field, "field_info") and 
+                field.field_info.extra.get('unique', False)):
+                unique_fields.append(name)
+        
+        # Create a search dictionary using unique fields
+        search_dict = {}
+        for field in unique_fields:
+            if field in item_data and item_data[field] is not None:
+                search_dict[field] = item_data[field]
+        
+        # If no unique fields found but ID is provided, use it
+        if not search_dict and 'id' in item_data and item_data['id']:
+            search_dict = {'id': item_data['id']}
+        
+        # Special case for products without uniqueness constraints
+        if not search_dict and related_model.__tablename__ == 'products' and 'name' in item_data:
+            search_dict = {'name': item_data['name']}
+        
+        # Try to find an existing record
+        related_obj = None
+        if search_dict:
+            logging.info(f"Searching for existing {related_model.__name__} with {search_dict}")
+            
+            try:
+                # Create a more appropriate search query based on unique fields
+                existing_stmt = select(related_model)
+                for field, field_value in search_dict.items():
+                    existing_stmt = existing_stmt.where(getattr(related_model, field) == field_value)
+                
+                existing_result = await session.execute(existing_stmt)
+                related_obj = existing_result.scalars().first()
                 
                 if related_obj:
-                    # Update the existing record with any non-unique field values
-                    for attr, attr_val in value.items():
-                        # Skip ID field
-                        if attr == 'id':
-                            continue
-                            
-                        # Skip unique fields with different values to avoid constraint violations
-                        if attr in unique_fields and getattr(related_obj, attr) != attr_val:
-                            continue
-                            
-                        # Update non-unique fields
-                        current_val = getattr(related_obj, attr, None)
-                        if current_val != attr_val:
-                            setattr(related_obj, attr, attr_val)
+                    logging.info(f"Found existing {related_model.__name__} with ID: {related_obj.id}")
+            except Exception as e:
+                logging.error(f"Error finding existing record: {e}")
+        
+        if related_obj:
+            # Update the existing record with any non-unique field values
+            for attr, attr_val in item_data.items():
+                # Skip ID field
+                if attr == 'id':
+                    continue
                     
-                    # Add the updated object to the session
-                    session.add(related_obj)
-                    logging.info(f"Reusing existing {related_model.__name__} with ID: {related_obj.id}")
-                else:
-                    # Create a new record
-                    logging.info(f"Creating new {related_model.__name__} for {key}")
-                    related_obj = related_model(**value)
-                    session.add(related_obj)
-                
-                # Ensure the object has an ID by flushing
-                try:
-                    await session.flush()
-                except Exception as e:
-                    logging.error(f"Error flushing session for {related_model.__name__}: {e}")
+                # Skip unique fields with different values to avoid constraint violations
+                if attr in unique_fields and getattr(related_obj, attr) != attr_val:
+                    continue
                     
-                    # If there was a uniqueness error, try again to find the existing record
-                    if "UNIQUE constraint failed" in str(e):
-                        logging.info(f"UNIQUE constraint failed, trying to find existing record again")
-                        
-                        # Try to find by any field provided in the search_dict
-                        existing_stmt = select(related_model)
-                        for field, field_value in search_dict.items():
-                            existing_stmt = existing_stmt.where(getattr(related_model, field) == field_value)
-                        
-                        # Execute the search query
-                        existing_result = await session.execute(existing_stmt)
-                        related_obj = existing_result.scalars().first()
-                        
-                        if not related_obj:
-                            # We couldn't find an existing record, re-raise the exception
-                            raise
-                        
-                        logging.info(f"Found existing {related_model.__name__} with ID: {related_obj.id} after constraint error")
+                # Update non-unique fields
+                current_val = getattr(related_obj, attr, None)
+                if current_val != attr_val:
+                    setattr(related_obj, attr, attr_val)
+            
+            # Add the updated object to the session
+            session.add(related_obj)
+            logging.info(f"Reusing existing {related_model.__name__} with ID: {related_obj.id}")
+        else:
+            # Create a new record
+            logging.info(f"Creating new {related_model.__name__}")
+            
+            # Process nested relationships in this item first
+            if hasattr(related_model, '_process_relationships_for_insert'):
+                # This is a recursive call to process nested relationships
+                processed_item_data = await related_model._process_relationships_for_insert(
+                    session, item_data
+                )
+            else:
+                processed_item_data = item_data
+            
+            related_obj = related_model(**processed_item_data)
+            session.add(related_obj)
+        
+        # Ensure the object has an ID by flushing
+        try:
+            await session.flush()
+        except Exception as e:
+            logging.error(f"Error flushing session for {related_model.__name__}: {e}")
+            
+            # If there was a uniqueness error, try again to find the existing record
+            if "UNIQUE constraint failed" in str(e):
+                logging.info(f"UNIQUE constraint failed, trying to find existing record again")
                 
-                # Update the result with the foreign key ID
-                foreign_key_name = f"{key}_id"
-                result[foreign_key_name] = related_obj.id
+                # Try to find by any field provided in the search_dict
+                existing_stmt = select(related_model)
+                for field, field_value in search_dict.items():
+                    existing_stmt = existing_stmt.where(getattr(related_model, field) == field_value)
                 
-                # Remove the relationship dictionary from the result
-                if key in result:
-                    del result[key]
+                # Execute the search query
+                existing_result = await session.execute(existing_stmt)
+                related_obj = existing_result.scalars().first()
+                
+                if not related_obj:
+                    # We couldn't find an existing record, re-raise the exception
+                    raise
+                
+                logging.info(f"Found existing {related_model.__name__} with ID: {related_obj.id} after constraint error")
         
-        return result
+        return related_obj
 
     @classmethod
     async def update(cls: Type[T], data: Dict[str, Any], criteria: Dict[str, Any], include_relationships: bool = True) -> Optional[T]:
@@ -788,6 +701,17 @@ class EasyModel(SQLModel):
         Returns:
             The updated model instance
         """
+        # Store many-to-many relationship data for later processing
+        many_to_many_data = {}
+        many_to_many_rels = cls._get_many_to_many_relationships()
+        
+        # Extract many-to-many data before processing
+        for rel_name in many_to_many_rels:
+            if rel_name in data:
+                many_to_many_data[rel_name] = data[rel_name]
+                # Remove from original data
+                del data[rel_name]
+        
         async with cls.get_session() as session:
             try:
                 # Find the record(s) to update
@@ -828,6 +752,74 @@ class EasyModel(SQLModel):
                 for key, value in data.items():
                     setattr(record, key, value)
                 
+                # Process many-to-many relationships if any
+                for rel_name, rel_data in many_to_many_data.items():
+                    if isinstance(rel_data, list):
+                        # First, get all existing links for this relation
+                        junction_model, target_model = many_to_many_rels[rel_name]
+                        
+                        from async_easy_model.auto_relationships import get_foreign_keys_from_model
+                        foreign_keys = get_foreign_keys_from_model(junction_model)
+                        
+                        # Find the foreign key fields for this model and the target model
+                        this_model_fk = None
+                        target_model_fk = None
+                        
+                        for fk_field, fk_target in foreign_keys.items():
+                            target_table = fk_target.split('.')[0]
+                            if target_table == cls.__tablename__:
+                                this_model_fk = fk_field
+                            elif target_table == target_model.__tablename__:
+                                target_model_fk = fk_field
+                        
+                        if not this_model_fk or not target_model_fk:
+                            logging.warning(f"Could not find foreign key fields for {rel_name} relationship")
+                            continue
+                            
+                        # Get all existing junctions for this record
+                        junction_stmt = select(junction_model).where(
+                            getattr(junction_model, this_model_fk) == record.id
+                        )
+                        junction_result = await session.execute(junction_stmt)
+                        existing_junctions = junction_result.scalars().all()
+                        
+                        # Get the target IDs from the existing junctions
+                        existing_target_ids = [getattr(junction, target_model_fk) for junction in existing_junctions]
+                        
+                        # Track processed target IDs
+                        processed_target_ids = set()
+                        
+                        # Process each item in rel_data
+                        for item_data in rel_data:
+                            target_obj = await cls._process_single_relationship_item(
+                                session, target_model, item_data
+                            )
+                            
+                            if not target_obj:
+                                logging.warning(f"Failed to process {target_model.__name__} item for {rel_name}")
+                                continue
+                                
+                            processed_target_ids.add(target_obj.id)
+                            
+                            # Check if this link already exists
+                            if target_obj.id not in existing_target_ids:
+                                # Create new junction
+                                junction_data = {
+                                    this_model_fk: record.id,
+                                    target_model_fk: target_obj.id
+                                }
+                                junction_obj = junction_model(**junction_data)
+                                session.add(junction_obj)
+                                logging.info(f"Created junction between {cls.__name__} {record.id} and {target_model.__name__} {target_obj.id}")
+                        
+                        # Delete junctions for target IDs that weren't in the updated data
+                        junctions_to_delete = [j for j in existing_junctions 
+                                              if getattr(j, target_model_fk) not in processed_target_ids]
+                        
+                        for junction in junctions_to_delete:
+                            await session.delete(junction)
+                            logging.info(f"Deleted junction between {cls.__name__} {record.id} and {target_model.__name__} {getattr(junction, target_model_fk)}")
+                
                 await session.flush()
                 await session.commit()
                 
@@ -841,9 +833,10 @@ class EasyModel(SQLModel):
                 else:
                     await session.refresh(record)
                     return record
+                    
             except Exception as e:
-                logging.error(f"Error updating record: {e}")
                 await session.rollback()
+                logging.error(f"Error updating {cls.__name__}: {e}")
                 raise
 
     @classmethod
@@ -859,7 +852,7 @@ class EasyModel(SQLModel):
         """
         async with cls.get_session() as session:
             try:
-                # Find the record(s) to delete
+                # Find records to delete
                 statement = select(cls)
                 for field, value in criteria.items():
                     if isinstance(value, str) and '*' in value:
@@ -876,43 +869,50 @@ class EasyModel(SQLModel):
                     logging.warning(f"No records found with criteria: {criteria}")
                     return 0
                 
-                # Get a list of related tables that might need to be cleared first
-                # This helps with foreign key constraints
-                relationship_fields = cls._get_auto_relationship_fields()
-                to_many_relationships = []
-                
-                # Find to-many relationships that need to be handled first
-                for rel_name in relationship_fields:
-                    rel_attr = getattr(cls, rel_name, None)
-                    if rel_attr and hasattr(rel_attr, 'property'):
-                        # Check if this is a to-many relationship (one-to-many or many-to-many)
-                        if hasattr(rel_attr.property, 'uselist') and rel_attr.property.uselist:
-                            to_many_relationships.append(rel_name)
+                # Check if there are many-to-many relationships that need cleanup
+                many_to_many_rels = cls._get_many_to_many_relationships()
                 
-                # For each record, delete related records first (cascade delete)
+                # Delete each record and its related many-to-many junction records
+                count = 0
                 for record in records:
-                    # First load all related collections
-                    if to_many_relationships:
-                        await session.refresh(record, attribute_names=to_many_relationships)
-                    
-                    # Delete related records in collections
-                    for rel_name in to_many_relationships:
-                        related_collection = getattr(record, rel_name, [])
-                        if related_collection:
-                            for related_item in related_collection:
-                                await session.delete(related_item)
+                    # Clean up many-to-many junctions first
+                    for rel_name, (junction_model, _) in many_to_many_rels.items():
+                        # Get foreign keys from the junction model
+                        from async_easy_model.auto_relationships import get_foreign_keys_from_model
+                        foreign_keys = get_foreign_keys_from_model(junction_model)
+                        
+                        # Find which foreign key refers to this model
+                        this_model_fk = None
+                        for fk_field, fk_target in foreign_keys.items():
+                            target_table = fk_target.split('.')[0]
+                            if target_table == cls.__tablename__:
+                                this_model_fk = fk_field
+                                break
+                        
+                        if not this_model_fk:
+                            continue
+                            
+                        # Delete junction records for this record
+                        delete_stmt = select(junction_model).where(
+                            getattr(junction_model, this_model_fk) == record.id
+                        )
+                        junction_result = await session.execute(delete_stmt)
+                        junctions = junction_result.scalars().all()
+                        
+                        for junction in junctions:
+                            await session.delete(junction)
+                            logging.info(f"Deleted junction record for {cls.__name__} id={record.id}")
                     
                     # Now delete the main record
                     await session.delete(record)
+                    count += 1
                 
-                # Commit the changes
-                await session.flush()
                 await session.commit()
+                return count
                 
-                return len(records)
             except Exception as e:
-                logging.error(f"Error deleting records: {e}")
                 await session.rollback()
+                logging.error(f"Error deleting {cls.__name__}: {e}")
                 raise
 
     def to_dict(self, include_relationships: bool = True, max_depth: int = 4) -> Dict[str, Any]:
@@ -991,21 +991,23 @@ class EasyModel(SQLModel):
         first: bool = False,
         include_relationships: bool = True,
         order_by: Optional[Union[str, List[str]]] = None,
+        max_depth: int = 2,
         limit: Optional[int] = None
     ) -> Union[Optional[T], List[T]]:
         """
-        Retrieve record(s) by matching attribute values.
+        Select records based on criteria.
         
         Args:
-            criteria: Dictionary of field values to filter by (field=value)
-            all: If True, return all matching records, otherwise return only the first one
+            criteria: Dictionary of field values to filter by
+            all: If True, return all matching records. If False, return only the first match.
             first: If True, return only the first record (equivalent to all=False)
             include_relationships: If True, eagerly load all relationships
             order_by: Field(s) to order by. Can be a string or list of strings.
                      Prefix with '-' for descending order (e.g. '-created_at')
+            max_depth: Maximum depth for loading nested relationships (when include_relationships=True)
             limit: Maximum number of records to retrieve (if all=True)
                   If limit > 1, all is automatically set to True
-                
+            
         Returns:
             A single model instance, a list of instances, or None if not found
         """
@@ -1016,73 +1018,98 @@ class EasyModel(SQLModel):
         # If limit is specified and > 1, set all to True
         if limit is not None and limit > 1:
             all = True
+            
         # If first is specified, set all to False (first takes precedence)
         if first:
             all = False
-        
+            
         async with cls.get_session() as session:
             # Build the query
             statement = select(cls)
             
-            # Apply criteria
-            for field, value in criteria.items():
+            # Apply criteria filters
+            for key, value in criteria.items():
                 if isinstance(value, str) and '*' in value:
                     # Handle LIKE queries (convert '*' wildcard to '%')
                     like_value = value.replace('*', '%')
-                    statement = statement.where(getattr(cls, field).like(like_value))
+                    statement = statement.where(getattr(cls, key).like(like_value))
                 else:
                     # Regular equality check
-                    statement = statement.where(getattr(cls, field) == value)
+                    statement = statement.where(getattr(cls, key) == value)
             
             # Apply ordering
             if order_by:
-                statement = cls._apply_order_by(statement, order_by)
+                order_clauses = []
+                if isinstance(order_by, str):
+                    order_by = [order_by]
+                
+                for field_name in order_by:
+                    if field_name.startswith("-"):
+                        # Descending order
+                        field_name = field_name[1:]  # Remove the "-" prefix
+                        # Handle relationship field ordering with dot notation
+                        if "." in field_name:
+                            rel_name, attr_name = field_name.split(".", 1)
+                            if hasattr(cls, rel_name):
+                                rel_model = getattr(cls, rel_name)
+                                if hasattr(rel_model, "property"):
+                                    target_model = rel_model.property.entity.class_
+                                    if hasattr(target_model, attr_name):
+                                        order_clauses.append(getattr(target_model, attr_name).desc())
+                        else:
+                            order_clauses.append(getattr(cls, field_name).desc())
+                    else:
+                        # Ascending order
+                        # Handle relationship field ordering with dot notation
+                        if "." in field_name:
+                            rel_name, attr_name = field_name.split(".", 1)
+                            if hasattr(cls, rel_name):
+                                rel_model = getattr(cls, rel_name)
+                                if hasattr(rel_model, "property"):
+                                    target_model = rel_model.property.entity.class_
+                                    if hasattr(target_model, attr_name):
+                                        order_clauses.append(getattr(target_model, attr_name).asc())
+                        else:
+                            order_clauses.append(getattr(cls, field_name).asc())
+                
+                if order_clauses:
+                    statement = statement.order_by(*order_clauses)
             
             # Apply limit
             if limit:
                 statement = statement.limit(limit)
             
-            # Include relationships if requested
+            # Load relationships if requested
             if include_relationships:
                 for rel_name in cls._get_auto_relationship_fields():
                     statement = statement.options(selectinload(getattr(cls, rel_name)))
             
-            # Execute the query
             result = await session.execute(statement)
             
             if all:
-                # Return all results
-                instances = result.scalars().all()
+                objects = result.scalars().all()
                 
-                # Materialize relationships if requested - this ensures they're fully loaded
-                if include_relationships:
-                    for instance in instances:
-                        # For each relationship, access it once to ensure it's loaded
-                        for rel_name in cls._get_auto_relationship_fields():
-                            try:
-                                # This will force loading the relationship while session is active
-                                _ = getattr(instance, rel_name)
-                            except Exception:
-                                # Skip if the relationship can't be loaded
-                                pass
+                # Load nested relationships if requested
+                if include_relationships and objects and max_depth > 1:
+                    loaded_objects = []
+                    for obj in objects:
+                        loaded_obj = await cls._load_relationships_recursively(
+                            session, obj, max_depth
+                        )
+                        loaded_objects.append(loaded_obj)
+                    return loaded_objects
                 
-                return instances
+                return objects
             else:
-                # Return only the first result
-                instance = result.scalars().first()
+                obj = result.scalars().first()
                 
-                # Materialize relationships if requested and instance exists
-                if include_relationships and instance:
-                    # For each relationship, access it once to ensure it's loaded
-                    for rel_name in cls._get_auto_relationship_fields():
-                        try:
-                            # This will force loading the relationship while session is active
-                            _ = getattr(instance, rel_name)
-                        except Exception:
-                            # Skip if the relationship can't be loaded
-                            pass
-                            
-                return instance
+                # Load nested relationships if requested
+                if include_relationships and obj and max_depth > 1:
+                    obj = await cls._load_relationships_recursively(
+                        session, obj, max_depth
+                    )
+                
+                return obj
 
     @classmethod
     async def get_or_create(cls: Type[T], search_criteria: Dict[str, Any], defaults: Optional[Dict[str, Any]] = None) -> Tuple[T, bool]:
@@ -1110,6 +1137,226 @@ class EasyModel(SQLModel):
         new_record = await cls.insert(data)
         return new_record, True
 
+    @classmethod
+    async def insert_with_related(
+        cls: Type[T], 
+        data: Dict[str, Any],
+        related_data: Dict[str, List[Dict[str, Any]]] = None
+    ) -> T:
+        """
+        Create a model instance with related objects in a single transaction.
+        
+        Args:
+            data: Dictionary of field values for the main model
+            related_data: Dictionary mapping relationship names to lists of data dictionaries
+                          for creating related objects
+                          
+        Returns:
+            The created model instance with relationships loaded
+        """
+        if related_data is None:
+            related_data = {}
+            
+        # Create a copy of data for modification
+        insert_data = data.copy()
+        
+        # Add relationship fields to the data
+        for rel_name, items_data in related_data.items():
+            if items_data:
+                insert_data[rel_name] = items_data
+        
+        # Use the enhanced insert method to handle all relationships
+        return await cls.insert(insert_data, include_relationships=True)
+
+    @classmethod
+    def _get_many_to_many_relationships(cls) -> Dict[str, Tuple[Type['EasyModel'], Type['EasyModel']]]:
+        """
+        Get all many-to-many relationships for this model.
+        
+        Returns:
+            Dictionary mapping relationship field names to tuples of (junction_model, target_model)
+        """
+        from async_easy_model.auto_relationships import get_model_by_table_name
+        
+        many_to_many_relationships = {}
+        
+        # Check if this is a class attribute rather than an instance attribute
+        relationship_fields = cls._get_auto_relationship_fields()
+        
+        for rel_name in relationship_fields:
+            if not hasattr(cls, rel_name):
+                continue
+                
+            rel_attr = getattr(cls, rel_name)
+            
+            # Check if this is a many-to-many relationship by looking for secondary table
+            if hasattr(rel_attr, 'prop') and hasattr(rel_attr.prop, 'secondary'):
+                secondary = rel_attr.prop.secondary
+                if isinstance(secondary, str):  # For string table names (our implementation)
+                    junction_model = get_model_by_table_name(secondary)
+                    if junction_model:
+                        target_model = rel_attr.prop.mapper.class_
+                        many_to_many_relationships[rel_name] = (junction_model, target_model)
+                        
+        return many_to_many_relationships
+        
+    @classmethod
+    async def _process_many_to_many_relationship(
+        cls, 
+        session: AsyncSession, 
+        parent_obj: 'EasyModel',
+        rel_name: str, 
+        items: List[Dict[str, Any]]
+    ) -> None:
+        """
+        Process a many-to-many relationship for an object.
+        
+        Args:
+            session: The database session
+            parent_obj: The parent object (e.g., Book)
+            rel_name: The name of the relationship (e.g., 'tags')
+            items: List of data dictionaries for the related items
+            
+        Returns:
+            None
+        """
+        # Get information about this many-to-many relationship
+        many_to_many_rels = cls._get_many_to_many_relationships()
+        if rel_name not in many_to_many_rels:
+            logging.warning(f"Relationship {rel_name} is not a many-to-many relationship")
+            return
+            
+        junction_model, target_model = many_to_many_rels[rel_name]
+        
+        # Get the foreign key fields from the junction model that reference this model and the target model
+        from async_easy_model.auto_relationships import get_foreign_keys_from_model
+        foreign_keys = get_foreign_keys_from_model(junction_model)
+        
+        # Find the foreign key fields for this model and the target model
+        this_model_fk = None
+        target_model_fk = None
+        
+        for fk_field, fk_target in foreign_keys.items():
+            target_table = fk_target.split('.')[0]
+            if target_table == cls.__tablename__:
+                this_model_fk = fk_field
+            elif target_table == target_model.__tablename__:
+                target_model_fk = fk_field
+        
+        if not this_model_fk or not target_model_fk:
+            logging.warning(f"Could not find foreign key fields for {rel_name} relationship")
+            return
+        
+        # Process each related item
+        for item_data in items:
+            # First, create or find the target model instance
+            target_obj = await cls._process_single_relationship_item(
+                session, target_model, item_data
+            )
+            
+            if not target_obj:
+                logging.warning(f"Failed to process {target_model.__name__} item for {rel_name}")
+                continue
+            
+            # Now create a junction record linking the parent to the target
+            # Check if this link already exists
+            junction_stmt = select(junction_model).where(
+                getattr(junction_model, this_model_fk) == parent_obj.id,
+                getattr(junction_model, target_model_fk) == target_obj.id
+            )
+            junction_result = await session.execute(junction_stmt)
+            existing_junction = junction_result.scalars().first()
+            
+            if not existing_junction:
+                # Create new junction
+                junction_data = {
+                    this_model_fk: parent_obj.id,
+                    target_model_fk: target_obj.id
+                }
+                junction_obj = junction_model(**junction_data)
+                session.add(junction_obj)
+                logging.info(f"Created junction between {cls.__name__} {parent_obj.id} and {target_model.__name__} {target_obj.id}")
+
+    @classmethod
+    async def _load_relationships_recursively(cls, session, obj, max_depth=2, current_depth=0, visited_ids=None):
+        """
+        Recursively load all relationships for an object and its related objects.
+        
+        Args:
+            session: SQLAlchemy session
+            obj: The object to load relationships for
+            max_depth: Maximum depth to recurse to prevent infinite loops
+            current_depth: Current recursion depth (internal use)
+            visited_ids: Set of already visited object IDs to prevent cycles
+            
+        Returns:
+            The object with all relationships loaded
+        """
+        if visited_ids is None:
+            visited_ids = set()
+            
+        # Use object ID and class for tracking instead of the object itself (which isn't hashable)
+        obj_key = (obj.__class__.__name__, obj.id)
+            
+        # Stop if we've reached max depth or already visited this object
+        if current_depth >= max_depth or obj_key in visited_ids:
+            return obj
+            
+        # Mark as visited to prevent cycles
+        visited_ids.add(obj_key)
+        
+        # Load all relationship fields for this object
+        obj_class = obj.__class__
+        relationship_fields = obj_class._get_auto_relationship_fields()
+        
+        # For each relationship, load it and recurse
+        for rel_name in relationship_fields:
+            try:
+                # Fetch the objects using selectinload
+                stmt = select(obj_class).where(obj_class.id == obj.id)
+                stmt = stmt.options(selectinload(getattr(obj_class, rel_name)))
+                result = await session.execute(stmt)
+                refreshed_obj = result.scalars().first()
+                
+                # Get the loaded relationship
+                related_objs = getattr(refreshed_obj, rel_name, None)
+                
+                # Update the object's relationship
+                setattr(obj, rel_name, related_objs)
+                
+                # Skip if no related objects
+                if related_objs is None:
+                    continue
+                    
+                # Recurse for related objects
+                if isinstance(related_objs, list):
+                    for related_obj in related_objs:
+                        if hasattr(related_obj.__class__, '_get_auto_relationship_fields'):
+                            # Only recurse if the object has an ID (is persistent)
+                            if hasattr(related_obj, 'id') and related_obj.id is not None:
+                                await cls._load_relationships_recursively(
+                                    session, 
+                                    related_obj, 
+                                    max_depth, 
+                                    current_depth + 1, 
+                                    visited_ids
+                                )
+                else:
+                    if hasattr(related_objs.__class__, '_get_auto_relationship_fields'):
+                        # Only recurse if the object has an ID (is persistent)
+                        if hasattr(related_objs, 'id') and related_objs.id is not None:
+                            await cls._load_relationships_recursively(
+                                session, 
+                                related_objs, 
+                                max_depth, 
+                                current_depth + 1, 
+                                visited_ids
+                            )
+            except Exception as e:
+                logging.warning(f"Error loading relationship {rel_name}: {e}")
+                
+        return obj
+
 # Register an event listener to update 'updated_at' on instance modifications.
 @event.listens_for(Session, "before_flush")
 def _update_updated_at(session, flush_context, instances):