sqliter-py 0.16.0__py3-none-any.whl → 0.17.0__py3-none-any.whl

sqliter/orm/model.py

@@ -1,4 +1,4 @@
-"""ORM model with lazy loading and reverse relationships."""
+"""ORM model with lazy loading, reverse relationships, and M2M."""
 
 from __future__ import annotations
 
@@ -8,6 +8,7 @@ from pydantic import Field
 
 from sqliter.model.model import BaseDBModel as _BaseDBModel
 from sqliter.orm.fields import ForeignKey, HasPK, LazyLoader
+from sqliter.orm.m2m import ManyToMany
 from sqliter.orm.registry import ModelRegistry
 
 __all__ = ["BaseDBModel"]
@@ -19,12 +20,16 @@ class BaseDBModel(_BaseDBModel):
     Adds:
     - Lazy loading of foreign key relationships
     - Automatic reverse relationship setup
+    - Many-to-many relationships
     - db_context for query execution
     """
 
     # Store FK descriptors per class (not inherited)
     fk_descriptors: ClassVar[dict[str, ForeignKey[Any]]] = {}
 
+    # Store M2M descriptors per class (not inherited)
+    m2m_descriptors: ClassVar[dict[str, ManyToMany[Any]]] = {}
+
     # Database context for lazy loading and reverse queries
     # Using Any since SqliterDB would cause circular import issues with Pydantic
     db_context: Optional[Any] = Field(default=None, exclude=True)
@@ -51,15 +56,19 @@ class BaseDBModel(_BaseDBModel):
         super().__init__(**kwargs)
 
     def model_dump(self, **kwargs: Any) -> dict[str, Any]:  # noqa: ANN401
-        """Dump model, excluding FK descriptor fields.
+        """Dump model, excluding FK and M2M descriptor fields.
 
-        FK descriptor fields (like 'author') are excluded from serialization.
-        Only the _id fields (like 'author_id') are included.
+        FK descriptor fields (like 'author') are excluded from
+        serialization. Only the _id fields (like 'author_id') are
+        included. M2M descriptor fields are also excluded.
         """
         data = super().model_dump(**kwargs)
         # Remove FK descriptor fields from the dump
         for fk_field in self.fk_descriptors:
             data.pop(fk_field, None)
+        # Remove M2M descriptor fields from the dump
+        for m2m_field in self.m2m_descriptors:
+            data.pop(m2m_field, None)
         return data
 
     def __getattribute__(self, name: str) -> object:
@@ -98,8 +107,48 @@ class BaseDBModel(_BaseDBModel):
         # For non-FK fields, use normal attribute access
         return object.__getattribute__(self, name)
 
+    def _handle_reverse_m2m_set(self, name: str, value: object) -> bool:
+        """Check and handle reverse M2M descriptor assignment.
+
+        Args:
+            name: Attribute name being set.
+            value: Value being assigned.
+
+        Returns:
+            True if handled (caller should return), False otherwise.
+        """
+        cls_attr = type(self).__dict__.get(name)
+        if cls_attr is None:
+            for klass in type(self).__mro__:
+                if name in klass.__dict__:
+                    cls_attr = klass.__dict__[name]
+                    break
+        if cls_attr is not None:
+            from sqliter.orm.m2m import (  # noqa: PLC0415
+                ReverseManyToMany,
+            )
+
+            if isinstance(cls_attr, ReverseManyToMany):
+                cls_attr.__set__(self, value)
+                return True
+        return False
+
     def __setattr__(self, name: str, value: object) -> None:
-        """Intercept FK field assignment to convert to _id field."""
+        """Intercept FK, M2M, and reverse M2M field assignment."""
+        # Guard against M2M field assignment
+        m2m_descs = getattr(self, "m2m_descriptors", {})
+        if name in m2m_descs:
+            msg = (
+                f"Cannot assign to ManyToMany field '{name}'. "
+                f"Use .add(), .remove(), .clear(), or .set() "
+                f"instead."
+            )
+            raise AttributeError(msg)
+
+        # Guard against reverse M2M assignment (dynamic descriptors)
+        if self._handle_reverse_m2m_set(name, value):
+            return
+
         # Check if this is a FK field assignment
         fk_descs = getattr(self, "fk_descriptors", {})
         if name in fk_descs:
@@ -143,6 +192,10 @@ class BaseDBModel(_BaseDBModel):
         if "fk_descriptors" not in cls.__dict__:
             cls.fk_descriptors = {}
 
+        # Collect M2M descriptors from class dict
+        if "m2m_descriptors" not in cls.__dict__:
+            cls.m2m_descriptors = {}
+
         # Find all ForeignKeys in the class and add _id field annotations
         # Make a copy of items to avoid modifying dict during iteration
         class_items = list(cls.__dict__.items())
@@ -165,6 +218,13 @@ class BaseDBModel(_BaseDBModel):
                 if name in cls.__annotations__:
                     del cls.__annotations__[name]
 
+            elif isinstance(value, ManyToMany):
+                cls.m2m_descriptors[name] = value
+                # Remove M2M annotation so Pydantic doesn't create a
+                # DB column for it
+                if name in cls.__annotations__:
+                    del cls.__annotations__[name]
+
     @classmethod
     def __pydantic_init_subclass__(cls, **kwargs: Any) -> None:  # noqa: ANN401
         """Set up ORM FK metadata after Pydantic has created model_fields.
@@ -241,3 +301,8 @@ class BaseDBModel(_BaseDBModel):
             # validate it
             if field_name in cls.model_fields:
                 del cls.model_fields[field_name]
+
+        # Remove M2M descriptor fields from model_fields
+        for m2m_name in cls.m2m_descriptors:
+            if m2m_name in cls.model_fields:
+                del cls.model_fields[m2m_name]

sqliter/orm/registry.py

@@ -4,23 +4,89 @@ Central registry for:
 - Model classes by table name
 - Foreign key relationships
 - Pending reverse relationships
+- Many-to-many relationships
 """
 
 from __future__ import annotations
 
-from typing import Any, ClassVar, Optional
+from copy import deepcopy
+from typing import Any, ClassVar, Optional, Protocol, TypedDict
+
+
+class _M2MForwardRef(Protocol):
+    def resolve_forward_ref(self, model_class: type[Any]) -> None: ...
+
+    @property
+    def junction_table(self) -> Optional[str]: ...
+
+
+class _RegistryState(TypedDict):
+    models: dict[str, type[Any]]
+    models_by_name: dict[str, type[Any]]
+    foreign_keys: dict[str, list[dict[str, Any]]]
+    pending_reverses: dict[str, list[dict[str, Any]]]
+    m2m_relationships: dict[str, list[dict[str, Any]]]
+    pending_m2m_reverses: dict[str, list[dict[str, Any]]]
+    pending_m2m_targets: dict[str, list[dict[str, Any]]]
 
 
 class ModelRegistry:
-    """Registry for ORM models and FK relationships.
+    """Registry for ORM models, FK, and M2M relationships.
 
     Uses automatic setup via descriptor __set_name__ hook - no manual setup
     required.
     """
 
     _models: ClassVar[dict[str, type]] = {}
+    _models_by_name: ClassVar[dict[str, type[Any]]] = {}
     _foreign_keys: ClassVar[dict[str, list[dict[str, Any]]]] = {}
     _pending_reverses: ClassVar[dict[str, list[dict[str, Any]]]] = {}
+    _m2m_relationships: ClassVar[dict[str, list[dict[str, Any]]]] = {}
+    _pending_m2m_reverses: ClassVar[dict[str, list[dict[str, Any]]]] = {}
+    _pending_m2m_targets: ClassVar[dict[str, list[dict[str, Any]]]] = {}
+
+    @classmethod
+    def reset(cls) -> None:
+        """Clear all registry state.
+
+        Intended for tests that need isolation between model definitions.
+        """
+        cls._models.clear()
+        cls._models_by_name.clear()
+        cls._foreign_keys.clear()
+        cls._pending_reverses.clear()
+        cls._m2m_relationships.clear()
+        cls._pending_m2m_reverses.clear()
+        cls._pending_m2m_targets.clear()
+
+    @classmethod
+    def snapshot(cls) -> _RegistryState:
+        """Return a deep copy of the registry state.
+
+        Useful for temporarily isolating tests and restoring state afterward.
+        """
+        # Model class references are immutable, so shallow copies are enough
+        # for model maps; relationship dicts are deep-copied for isolation.
+        return {
+            "models": cls._models.copy(),
+            "models_by_name": cls._models_by_name.copy(),
+            "foreign_keys": deepcopy(cls._foreign_keys),
+            "pending_reverses": deepcopy(cls._pending_reverses),
+            "m2m_relationships": deepcopy(cls._m2m_relationships),
+            "pending_m2m_reverses": deepcopy(cls._pending_m2m_reverses),
+            "pending_m2m_targets": deepcopy(cls._pending_m2m_targets),
+        }
+
+    @classmethod
+    def restore(cls, state: _RegistryState) -> None:
+        """Restore registry state from a snapshot."""
+        cls._models = state["models"]
+        cls._models_by_name = state["models_by_name"]
+        cls._foreign_keys = state["foreign_keys"]
+        cls._pending_reverses = state["pending_reverses"]
+        cls._m2m_relationships = state["m2m_relationships"]
+        cls._pending_m2m_reverses = state["pending_m2m_reverses"]
+        cls._pending_m2m_targets = state["pending_m2m_targets"]
 
     @classmethod
     def register_model(cls, model_class: type[Any]) -> None:
@@ -31,6 +97,7 @@ class ModelRegistry:
         """
         table_name = model_class.get_table_name()
         cls._models[table_name] = model_class
+        cls._models_by_name[model_class.__name__] = model_class
 
         # Process any pending reverse relationships for this model
         if table_name in cls._pending_reverses:
@@ -38,6 +105,38 @@ class ModelRegistry:
                 cls._add_reverse_relationship_now(**pending)
             del cls._pending_reverses[table_name]
 
+        # Process any pending M2M reverse relationships
+        if table_name in cls._pending_m2m_reverses:
+            for pending in cls._pending_m2m_reverses[table_name]:
+                cls._add_m2m_reverse_now(
+                    from_model=pending["from_model"],
+                    to_model=pending["to_model"],
+                    m2m_field=pending["m2m_field"],
+                    junction_table=pending["junction_table"],
+                    related_name=pending["related_name"],
+                    symmetrical=pending["symmetrical"],
+                )
+            del cls._pending_m2m_reverses[table_name]
+
+        class_name = model_class.__name__
+        if class_name in cls._pending_m2m_targets:
+            for pending in cls._pending_m2m_targets[class_name]:
+                descriptor = pending["descriptor"]
+                descriptor.resolve_forward_ref(model_class)
+                junction_table = descriptor.junction_table
+                if junction_table is None:
+                    msg = "ManyToMany junction table could not be resolved."
+                    raise ValueError(msg)
+                cls.add_m2m_relationship(
+                    from_model=pending["from_model"],
+                    to_model=model_class,
+                    m2m_field=pending["m2m_field"],
+                    junction_table=junction_table,
+                    related_name=pending["related_name"],
+                    symmetrical=pending["symmetrical"],
+                )
+            del cls._pending_m2m_targets[class_name]
+
     @classmethod
     def register_foreign_key(
         cls,
@@ -82,6 +181,11 @@ class ModelRegistry:
         """
         return cls._models.get(table_name)
 
+    @classmethod
+    def get_model_by_name(cls, class_name: str) -> Optional[type[Any]]:
+        """Get model by class name."""
+        return cls._models_by_name.get(class_name)
+
     @classmethod
     def get_foreign_keys(cls, table_name: str) -> list[dict[str, Any]]:
         """Get FK relationships for a model.
@@ -167,3 +271,170 @@ class ModelRegistry:
             related_name,
             ReverseRelationship(from_model, fk_field, related_name),
         )
+
+    @classmethod
+    def add_m2m_relationship(
+        cls,
+        from_model: type[Any],
+        to_model: type[Any],
+        m2m_field: str,
+        junction_table: str,
+        related_name: Optional[str],
+        *,
+        symmetrical: bool = False,
+    ) -> None:
+        """Register a M2M relationship and set up reverse accessor.
+
+        Called by ManyToMany.__set_name__ during class creation. If the
+        target model hasn't been registered yet, the reverse accessor
+        is stored as pending.
+
+        Args:
+            from_model: The model defining the ManyToMany field.
+            to_model: The target model class.
+            m2m_field: Name of the M2M field.
+            junction_table: Name of the junction table.
+            related_name: Name for the reverse accessor.
+            symmetrical: Whether self-referential relationships are symmetric.
+        """
+        from_table = from_model.get_table_name()
+
+        if from_table not in cls._m2m_relationships:
+            cls._m2m_relationships[from_table] = []
+
+        cls._m2m_relationships[from_table].append(
+            {
+                "to_model": to_model,
+                "m2m_field": m2m_field,
+                "junction_table": junction_table,
+                "related_name": related_name,
+                "symmetrical": symmetrical,
+            }
+        )
+
+        if related_name is None:
+            return
+
+        if from_model is to_model and symmetrical:
+            return
+
+        to_table = to_model.get_table_name()
+        pending_info = {
+            "from_model": from_model,
+            "to_model": to_model,
+            "m2m_field": m2m_field,
+            "junction_table": junction_table,
+            "related_name": related_name,
+            "symmetrical": symmetrical,
+        }
+
+        if to_table in cls._models:
+            cls._add_m2m_reverse_now(
+                from_model=from_model,
+                to_model=to_model,
+                m2m_field=m2m_field,
+                junction_table=junction_table,
+                related_name=related_name,
+                symmetrical=symmetrical,
+            )
+        else:
+            if to_table not in cls._pending_m2m_reverses:
+                cls._pending_m2m_reverses[to_table] = []
+            cls._pending_m2m_reverses[to_table].append(pending_info)
+
+    @classmethod
+    def add_pending_m2m_relationship(
+        cls,
+        *,
+        from_model: type[Any],
+        to_model_name: str,
+        m2m_field: str,
+        related_name: Optional[str],
+        symmetrical: bool,
+        descriptor: _M2MForwardRef,
+    ) -> None:
+        """Store a pending M2M relationship targeting a string forward ref."""
+        existing = cls.get_model_by_name(to_model_name)
+        if existing is not None:
+            descriptor.resolve_forward_ref(existing)
+            junction_table = descriptor.junction_table
+            if junction_table is None:
+                msg = "ManyToMany junction table could not be resolved."
+                raise ValueError(msg)
+            cls.add_m2m_relationship(
+                from_model=from_model,
+                to_model=existing,
+                m2m_field=m2m_field,
+                junction_table=junction_table,
+                related_name=related_name,
+                symmetrical=symmetrical,
+            )
+            return
+
+        if to_model_name not in cls._pending_m2m_targets:
+            cls._pending_m2m_targets[to_model_name] = []
+        cls._pending_m2m_targets[to_model_name].append(
+            {
+                "from_model": from_model,
+                "m2m_field": m2m_field,
+                "related_name": related_name,
+                "symmetrical": symmetrical,
+                "descriptor": descriptor,
+            }
+        )
+
+    @classmethod
+    def _add_m2m_reverse_now(
+        cls,
+        from_model: type[Any],
+        to_model: type[Any],
+        m2m_field: str,
+        junction_table: str,
+        related_name: str,
+        *,
+        symmetrical: bool = False,
+    ) -> None:
+        """Add reverse M2M descriptor to the target model.
+
+        Args:
+            from_model: The model defining the ManyToMany field.
+            to_model: The target model (receives the descriptor).
+            m2m_field: Name of the M2M field.
+            junction_table: Name of the junction table.
+            related_name: Name for the reverse accessor.
+            symmetrical: Whether self-referential relationships are symmetric.
+        """
+        from sqliter.orm.m2m import ReverseManyToMany  # noqa: PLC0415
+
+        _ = m2m_field  # kept for signature consistency / future use
+
+        if hasattr(to_model, related_name):
+            msg = (
+                f"Reverse M2M accessor '{related_name}' already "
+                f"exists on {to_model.__name__}"
+            )
+            raise AttributeError(msg)
+
+        setattr(
+            to_model,
+            related_name,
+            ReverseManyToMany(
+                from_model=from_model,
+                to_model=to_model,
+                junction_table=junction_table,
+                related_name=related_name,
+                symmetrical=symmetrical,
+            ),
+        )
+
+    @classmethod
+    def get_m2m_relationships(cls, table_name: str) -> list[dict[str, Any]]:
+        """Get M2M relationships for a model.
+
+        Args:
+            table_name: The table name to look up.
+
+        Returns:
+            List of M2M relationship dictionaries.
+        """
+        return cls._m2m_relationships.get(table_name, [])

sqliter/sqliter.py

@@ -678,6 +678,47 @@ class SqliterDB:
                 model_class, model_class.Meta.unique_indexes, unique=True
             )
 
+        # Create junction tables for M2M relationships
+        self._create_m2m_junction_tables(model_class)
+
+    def _create_m2m_junction_tables(
+        self, model_class: type[BaseDBModel]
+    ) -> None:
+        """Create junction tables for M2M relationships on a model.
+
+        Queries the ModelRegistry for M2M relationships registered for
+        this model and creates the corresponding junction tables.
+
+        Args:
+            model_class: The model class to check for M2M relationships.
+        """
+        try:
+            from sqliter.orm.m2m import (  # noqa: PLC0415
+                create_junction_table,
+            )
+            from sqliter.orm.registry import (  # noqa: PLC0415
+                ModelRegistry,
+            )
+        except ImportError:
+            return
+
+        table_name = model_class.get_table_name()
+        m2m_rels = ModelRegistry.get_m2m_relationships(table_name)
+
+        for rel in m2m_rels:
+            junction_table = rel["junction_table"]
+            to_model = rel["to_model"]
+            to_table = to_model.get_table_name()
+
+            # Sort alphabetically for consistent column naming
+            sorted_tables = sorted([table_name, to_table])
+            create_junction_table(
+                self,
+                junction_table,
+                sorted_tables[0],
+                sorted_tables[1],
+            )
+
     def _create_indexes(
         self,
         model_class: type[BaseDBModel],

sqliter/tui/demos/orm.py

@@ -3,10 +3,10 @@
 from __future__ import annotations
 
 import io
-from typing import Optional
+from typing import Any, Optional, cast
 
 from sqliter import SqliterDB
-from sqliter.orm import BaseDBModel, ForeignKey
+from sqliter.orm import BaseDBModel, ForeignKey, ManyToMany
 from sqliter.tui.demos.base import Demo, DemoCategory, extract_demo_code
 
 
@@ -203,6 +203,67 @@ def _run_reverse_relationships() -> str:
     return output.getvalue()
 
 
+def _run_many_to_many_basic() -> str:
+    """Show basic many-to-many usage with reverse access."""
+    output = io.StringIO()
+
+    class Tag(BaseDBModel):
+        name: str
+
+    class Article(BaseDBModel):
+        title: str
+        tags: ManyToMany[Tag] = ManyToMany(Tag, related_name="articles")
+
+    db = SqliterDB(memory=True)
+    db.create_table(Tag)
+    db.create_table(Article)
+
+    article = db.insert(Article(title="ORM Guide"))
+    python = db.insert(Tag(name="python"))
+    orm = db.insert(Tag(name="orm"))
+
+    article.tags.add(python, orm)
+    output.write("Article tags:\n")
+    for tag in article.tags.fetch_all():
+        output.write(f"  - {tag.name}\n")
+
+    output.write("\nReverse access (tag.articles):\n")
+    entries = cast("Any", python.articles).fetch_all()
+    for entry in entries:
+        output.write(f"  - {entry.title}\n")
+
+    db.close()
+    return output.getvalue()
+
+
+def _run_many_to_many_symmetrical() -> str:
+    """Show symmetrical self-referential many-to-many."""
+    output = io.StringIO()
+
+    class User(BaseDBModel):
+        name: str
+        friends: ManyToMany[User] = ManyToMany("User", symmetrical=True)
+
+    db = SqliterDB(memory=True)
+    db.create_table(User)
+
+    alice = db.insert(User(name="Alice"))
+    bob = db.insert(User(name="Bob"))
+
+    alice.friends.add(bob)
+
+    output.write("Alice's friends:\n")
+    for friend in alice.friends.fetch_all():
+        output.write(f"  - {friend.name}\n")
+
+    output.write("\nBob's friends (symmetrical):\n")
+    for friend in bob.friends.fetch_all():
+        output.write(f"  - {friend.name}\n")
+
+    db.close()
+    return output.getvalue()
+
+
 def _run_select_related_basic() -> str:
     """Demonstrate eager loading with select_related().
 
@@ -424,6 +485,22 @@ def get_category() -> DemoCategory:
                 code=extract_demo_code(_run_reverse_relationships),
                 execute=_run_reverse_relationships,
             ),
+            Demo(
+                id="orm_m2m_basic",
+                title="Many-to-Many Basics",
+                description="Relate records with a junction table",
+                category="orm",
+                code=extract_demo_code(_run_many_to_many_basic),
+                execute=_run_many_to_many_basic,
+            ),
+            Demo(
+                id="orm_m2m_symmetrical",
+                title="Many-to-Many Symmetry",
+                description="Self-referential symmetrical relationships",
+                category="orm",
+                code=extract_demo_code(_run_many_to_many_symmetrical),
+                execute=_run_many_to_many_symmetrical,
+            ),
             Demo(
                 id="orm_select_related",
                 title="Eager Loading with select_related()",

{sqliter_py-0.16.0.dist-info → sqliter_py-0.17.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqliter-py
-Version: 0.16.0
+Version: 0.17.0
 Summary: Interact with SQLite databases using Python and Pydantic
 Author: Grant Ramsay
 Author-email: Grant Ramsay <grant@gnramsay.com>
@@ -50,8 +50,7 @@ is Pydantic itself.
 
 It does not aim to be a full-fledged ORM like SQLAlchemy, but rather a simple
 and easy-to-use library for basic database operations, especially for small
-projects. It is NOT asynchronous and does not support complex queries (at this
-time).
+projects. It is NOT asynchronous (at this time, though that is planned).
 
 The ideal use case is more for Python CLI tools that need to store data in a
 database-like format without needing to learn SQL or use a full ORM.
@@ -60,11 +59,10 @@ Full documentation is available on the [Website](https://sqliter.grantramsay.dev
 
 > [!CAUTION]
 >
-> This project is still in the early stages of development and is lacking some
-> planned functionality. Please use with caution - Classes and methods may
-> change until a stable release is made. I'll try to keep this to an absolute
-> minimum and the releases and documentation will be very clear about any
-> breaking changes.
+> This project is still in development and is lacking some planned
+> functionality. Please use with caution - Classes and methods may change until
+> a stable release is made. I'll try to keep this to an absolute minimum and the
+> releases and documentation will be very clear about any breaking changes.
 >
 > See the [TODO](TODO.md) for planned features and improvements.