debugorm 0.1.0__py3-none-any.whl

debugorm/__init__.py

@@ -0,0 +1,105 @@
+"""
+DebugORM — a minimal, plugin-driven ORM for understanding and debugging SQL.
+
+Quick start::
+
+    from debugorm import configure, Model
+    from debugorm.fields import IntegerField, StringField
+
+    configure("myapp.db")   # or ":memory:"
+
+    class User(Model):
+        id   = IntegerField(primary_key=True)
+        name = StringField()
+        age  = IntegerField()
+
+    User.create_table()
+
+    alice = User(name="Alice", age=25)
+    alice.save()
+
+    users = User.objects.filter(age__gt=18).order_by("-age").all()
+
+    # Debug any query on the fly
+    User.objects.debug(explain=True, pretty=True).filter(age__gt=18).all()
+
+    # Compare two queries
+    q1 = User.objects.filter(age__gt=18)
+    q2 = User.objects.filter(age__gt=21)
+    print(q1.diff(q2))
+"""
+
+from .core.model import Model
+from .core.query import Query
+from .core.pipeline import QueryPipeline, QueryResult, PipelineContext
+from .core.compiler import SQLCompiler, CompiledQuery
+from .core.manager import Manager, QuerySet
+from .db.connection import configure, get_connection, set_connection, Connection
+from .fields import Field, IntegerField, StringField
+from .plugins import (
+    Plugin,
+    ExplainPlugin,
+    DryRunPlugin,
+    LoggingPlugin,
+    VisualizePlugin,
+    PrettyPrintPlugin,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "Model",
+    "Query",
+    "QueryPipeline",
+    "QueryResult",
+    "PipelineContext",
+    "SQLCompiler",
+    "CompiledQuery",
+    "Manager",
+    "QuerySet",
+    "configure",
+    "get_connection",
+    "set_connection",
+    "Connection",
+    "Field",
+    "IntegerField",
+    "StringField",
+    "Plugin",
+    "ExplainPlugin",
+    "DryRunPlugin",
+    "LoggingPlugin",
+    "VisualizePlugin",
+    "PrettyPrintPlugin",
+    "DebugORM",
+]
+
+
+class DebugORM:
+    """
+    Optional facade for configuring a fixed plugin set across all models::
+
+        orm = DebugORM(":memory:", plugins=[ExplainPlugin(), LoggingPlugin()])
+        orm.install()   # applies the pipeline to every existing Model subclass
+    """
+
+    def __init__(
+        self,
+        db_path: str = ":memory:",
+        plugins: list | None = None,
+    ) -> None:
+        self.connection = configure(db_path)
+        self.plugins: list = plugins or []
+        self._pipeline = QueryPipeline(plugins=self.plugins, connection=self.connection)
+
+    def install(self) -> None:
+        """Push the configured pipeline onto every ``Model`` subclass defined so far."""
+        for subclass in self._all_subclasses(Model):
+            if hasattr(subclass, "objects"):
+                subclass.objects.pipeline = self._pipeline
+
+    @staticmethod
+    def _all_subclasses(base: type) -> list:
+        result = []
+        for cls in base.__subclasses__():
+            result.append(cls)
+            result.extend(DebugORM._all_subclasses(cls))
+        return result

debugorm/core/__init__.py

@@ -0,0 +1,17 @@
+from .model import Model
+from .query import Query
+from .compiler import SQLCompiler, CompiledQuery
+from .pipeline import QueryPipeline, QueryResult, PipelineContext
+from .manager import Manager, QuerySet
+
+__all__ = [
+    "Model",
+    "Query",
+    "SQLCompiler",
+    "CompiledQuery",
+    "QueryPipeline",
+    "QueryResult",
+    "PipelineContext",
+    "Manager",
+    "QuerySet",
+]

debugorm/core/compiler.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Any, List, Tuple
+
+from .query import Query
+
+
+@dataclass
+class CompiledQuery:
+    """The output of SQL compilation: a statement string and its parameter tuple."""
+
+    sql: str
+    params: Tuple[Any, ...]
+    query: Query
+
+    def __str__(self) -> str:
+        return self.sql
+
+    def interpolated(self) -> str:
+        """SQL with parameters substituted inline — for display only."""
+        result = self.sql
+        for p in self.params:
+            placeholder = f"'{p}'" if isinstance(p, str) else str(p)
+            result = result.replace("?", placeholder, 1)
+        return result
+
+
+class SQLCompiler:
+    """Translates a ``Query`` object into a ``CompiledQuery``."""
+
+    def compile(self, query: Query) -> CompiledQuery:
+        handlers = {
+            "SELECT": self._compile_select,
+            "INSERT": self._compile_insert,
+            "UPDATE": self._compile_update,
+            "DELETE": self._compile_delete,
+        }
+        handler = handlers.get(query.query_type)
+        if handler is None:
+            raise ValueError(f"Unknown query type: {query.query_type!r}")
+        return handler(query)
+
+    def _compile_select(self, query: Query) -> CompiledQuery:
+        fields = "*" if not query.select_fields else ", ".join(query.select_fields)
+        sql = f"SELECT {fields} FROM {query.table}"
+        params: List[Any] = []
+
+        where, where_params = self._compile_where(query)
+        if where:
+            sql += f" WHERE {where}"
+            params.extend(where_params)
+
+        if query.order_by_clauses:
+            order = ", ".join(
+                f"{c.field} {'DESC' if c.descending else 'ASC'}"
+                for c in query.order_by_clauses
+            )
+            sql += f" ORDER BY {order}"
+
+        if query.limit_value is not None:
+            sql += " LIMIT ?"
+            params.append(query.limit_value)
+        elif query.offset_value is not None:
+            # SQLite requires LIMIT before OFFSET; -1 means no upper bound
+            sql += " LIMIT -1"
+
+        if query.offset_value is not None:
+            sql += " OFFSET ?"
+            params.append(query.offset_value)
+
+        return CompiledQuery(sql=sql, params=tuple(params), query=query)
+
+    def _compile_insert(self, query: Query) -> CompiledQuery:
+        columns = list(query.data.keys())
+        values = list(query.data.values())
+        placeholders = ", ".join(["?"] * len(columns))
+        sql = (
+            f"INSERT INTO {query.table} "
+            f"({', '.join(columns)}) VALUES ({placeholders})"
+        )
+        return CompiledQuery(sql=sql, params=tuple(values), query=query)
+
+    def _compile_update(self, query: Query) -> CompiledQuery:
+        pk_name = self._pk_field_name(query)
+        set_parts: List[str] = []
+        params: List[Any] = []
+
+        for col, val in query.data.items():
+            if col != pk_name:
+                set_parts.append(f"{col} = ?")
+                params.append(val)
+
+        sql = f"UPDATE {query.table} SET {', '.join(set_parts)}"
+
+        where, where_params = self._compile_where(query)
+        if where:
+            sql += f" WHERE {where}"
+            params.extend(where_params)
+        elif query.pk_value is not None:
+            sql += f" WHERE {pk_name} = ?"
+            params.append(query.pk_value)
+
+        return CompiledQuery(sql=sql, params=tuple(params), query=query)
+
+    def _compile_delete(self, query: Query) -> CompiledQuery:
+        pk_name = self._pk_field_name(query)
+        sql = f"DELETE FROM {query.table}"
+        params: List[Any] = []
+
+        where, where_params = self._compile_where(query)
+        if where:
+            sql += f" WHERE {where}"
+            params.extend(where_params)
+        elif query.pk_value is not None:
+            sql += f" WHERE {pk_name} = ?"
+            params.append(query.pk_value)
+
+        return CompiledQuery(sql=sql, params=tuple(params), query=query)
+
+    def _compile_where(self, query: Query) -> Tuple[str, List[Any]]:
+        if not query.conditions:
+            return "", []
+
+        parts: List[str] = []
+        params: List[Any] = []
+
+        for cond in query.conditions:
+            if cond.operator == "IN":
+                placeholders = ", ".join(["?"] * len(cond.value))
+                parts.append(f"{cond.field} IN ({placeholders})")
+                params.extend(cond.value)
+            elif cond.operator in ("IS NULL", "IS NOT NULL"):
+                parts.append(f"{cond.field} {cond.operator}")
+            else:
+                parts.append(f"{cond.field} {cond.operator} ?")
+                params.append(cond.value)
+
+        return " AND ".join(parts), params
+
+    def _pk_field_name(self, query: Query) -> str:
+        for name, f in query.model._fields.items():
+            if f.primary_key:
+                return name
+        return "id"

debugorm/core/manager.py

@@ -0,0 +1,207 @@
+from __future__ import annotations
+from typing import Any, Iterator, List, Optional, TYPE_CHECKING
+
+from .query import Query, OrderByClause
+from .pipeline import QueryPipeline
+
+if TYPE_CHECKING:
+    from .model import Model
+    from ..plugins.base import Plugin
+
+
+class DoesNotExist(Exception):
+    pass
+
+
+class MultipleObjectsReturned(Exception):
+    pass
+
+
+class QuerySet:
+    """
+    Lazy, chainable query builder.
+
+    Every filtering or ordering call returns a *new* ``QuerySet`` — the
+    original is never mutated.  The database is only hit when results are
+    materialised via ``all()``, ``get()``, ``first()``, ``count()``, or
+    direct iteration.
+    """
+
+    def __init__(
+        self,
+        model: type,
+        pipeline: QueryPipeline,
+        query: Optional[Query] = None,
+    ) -> None:
+        self._model = model
+        self._pipeline = pipeline
+        self._query = query if query is not None else Query(model)
+
+    def filter(self, **kwargs: Any) -> "QuerySet":
+        """Append WHERE conditions.  Multiple calls are AND-ed together."""
+        new_query = self._query.copy()
+        for lookup, value in kwargs.items():
+            new_query.add_filter(lookup, value)
+        return QuerySet(self._model, self._pipeline, new_query)
+
+    def order_by(self, *fields: str) -> "QuerySet":
+        """
+        Order results.  Prefix a field name with ``-`` for descending order::
+
+            User.objects.order_by('-age', 'name')
+        """
+        new_query = self._query.copy()
+        for f in fields:
+            descending = f.startswith("-")
+            new_query.order_by_clauses.append(OrderByClause(f.lstrip("-"), descending))
+        return QuerySet(self._model, self._pipeline, new_query)
+
+    def limit(self, n: int) -> "QuerySet":
+        new_query = self._query.copy()
+        new_query.limit_value = n
+        return QuerySet(self._model, self._pipeline, new_query)
+
+    def offset(self, n: int) -> "QuerySet":
+        new_query = self._query.copy()
+        new_query.offset_value = n
+        return QuerySet(self._model, self._pipeline, new_query)
+
+    def all(self) -> List["Model"]:
+        """Execute the query and return a list of model instances."""
+        result = self._pipeline.run(self._query)
+        return [self._model._from_row(row) for row in result.rows]
+
+    def get(self, **kwargs: Any) -> "Model":
+        """Return exactly one object; raise if zero or multiple match."""
+        qs = self.filter(**kwargs) if kwargs else self
+        results = qs.all()
+        if not results:
+            raise self._model.DoesNotExist(
+                f"{self._model.__name__} matching query does not exist"
+            )
+        if len(results) > 1:
+            raise self._model.MultipleObjectsReturned(
+                f"get() returned more than one {self._model.__name__}"
+            )
+        return results[0]
+
+    def first(self) -> Optional["Model"]:
+        results = self.limit(1).all()
+        return results[0] if results else None
+
+    def count(self) -> int:
+        count_query = self._query.copy()
+        count_query.select_fields = ["COUNT(*) as count"]
+        count_query.limit_value = None
+        count_query.offset_value = None
+        count_query.order_by_clauses = []
+        result = self._pipeline.run(count_query)
+        return result.rows[0]["count"] if result.rows else 0
+
+    def exists(self) -> bool:
+        return self.count() > 0
+
+    def debug(
+        self,
+        explain: bool = False,
+        dry_run: bool = False,
+        log: bool = False,
+        visualize: bool = False,
+        pretty: bool = False,
+    ) -> "QuerySet":
+        """
+        Attach debug plugins on the fly::
+
+            User.objects.debug(explain=True, pretty=True).filter(age__gt=18).all()
+        """
+        extra: List["Plugin"] = []
+
+        if visualize:
+            from ..plugins.visualize import VisualizePlugin
+            extra.append(VisualizePlugin())
+        if log:
+            from ..plugins.logging_plugin import LoggingPlugin
+            extra.append(LoggingPlugin())
+        if pretty:
+            from ..plugins.pretty_print import PrettyPrintPlugin
+            extra.append(PrettyPrintPlugin())
+        if explain:
+            from ..plugins.explain import ExplainPlugin
+            extra.append(ExplainPlugin())
+        if dry_run:
+            from ..plugins.dry_run import DryRunPlugin
+            extra.append(DryRunPlugin())
+
+        return QuerySet(self._model, self._pipeline.with_plugins(extra), self._query.copy())
+
+    def diff(self, other: "QuerySet") -> str:
+        """
+        Compare two ``QuerySet`` objects at the internal representation level::
+
+            q1 = User.objects.filter(age__gt=18)
+            q2 = User.objects.filter(age__gt=21)
+            print(q1.diff(q2))
+            # - age > 18
+            # + age > 21
+        """
+        return self._query.diff(other._query)
+
+    def __iter__(self) -> Iterator["Model"]:
+        return iter(self.all())
+
+    def __len__(self) -> int:
+        return self.count()
+
+    def __repr__(self) -> str:
+        return f"QuerySet<{self._model.__name__}>"
+
+
+class Manager:
+    """
+    Entry point for all database queries on a model.
+
+    Attached to every ``Model`` subclass as ``Model.objects`` by ``ModelMeta``.
+    """
+
+    def __init__(self, model_class: type) -> None:
+        self._model = model_class
+        self._pipeline: Optional[QueryPipeline] = None
+
+    @property
+    def pipeline(self) -> QueryPipeline:
+        if self._pipeline is None:
+            self._pipeline = QueryPipeline()
+        return self._pipeline
+
+    @pipeline.setter
+    def pipeline(self, value: QueryPipeline) -> None:
+        self._pipeline = value
+
+    def get_queryset(self) -> QuerySet:
+        return QuerySet(self._model, self.pipeline)
+
+    def filter(self, **kwargs: Any) -> QuerySet:
+        return self.get_queryset().filter(**kwargs)
+
+    def all(self) -> List["Model"]:
+        return self.get_queryset().all()
+
+    def get(self, **kwargs: Any) -> "Model":
+        return self.get_queryset().get(**kwargs)
+
+    def order_by(self, *fields: str) -> QuerySet:
+        return self.get_queryset().order_by(*fields)
+
+    def first(self) -> Optional["Model"]:
+        return self.get_queryset().first()
+
+    def count(self) -> int:
+        return self.get_queryset().count()
+
+    def create(self, **kwargs: Any) -> "Model":
+        instance = self._model(**kwargs)
+        instance.save()
+        return instance
+
+    def debug(self, **kwargs: Any) -> QuerySet:
+        return self.get_queryset().debug(**kwargs)

debugorm/core/model.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+from typing import Any, Dict, Optional, Tuple, TYPE_CHECKING
+
+from ..fields.base import Field
+from ..db.connection import get_connection
+
+if TYPE_CHECKING:
+    pass
+
+
+class ModelMeta(type):
+    """
+    Metaclass that wires up fields, the table name, and the ``Manager``
+    when a ``Model`` subclass is defined.
+    """
+
+    def __new__(
+        mcs,
+        name: str,
+        bases: Tuple[type, ...],
+        namespace: Dict[str, Any],
+    ) -> "ModelMeta":
+        fields: Dict[str, Field] = {}
+
+        for base in bases:
+            if hasattr(base, "_fields"):
+                fields.update(base._fields)
+
+        for attr_name, attr_val in list(namespace.items()):
+            if isinstance(attr_val, Field):
+                attr_val.name = attr_name
+                fields[attr_name] = attr_val
+
+        namespace["_fields"] = fields
+
+        inner_meta = namespace.get("Meta")
+        if inner_meta is not None and hasattr(inner_meta, "table_name"):
+            namespace["_table_name"] = inner_meta.table_name
+        else:
+            namespace["_table_name"] = name.lower() + "s"
+
+        cls = super().__new__(mcs, name, bases, namespace)
+
+        if name != "Model":
+            from .manager import Manager, DoesNotExist, MultipleObjectsReturned
+
+            cls.objects = Manager(cls)
+            cls.DoesNotExist = type("DoesNotExist", (DoesNotExist,), {})
+            cls.MultipleObjectsReturned = type(
+                "MultipleObjectsReturned", (MultipleObjectsReturned,), {}
+            )
+
+        return cls
+
+
+class Model(metaclass=ModelMeta):
+    """
+    Base class for all DebugORM models::
+
+        class User(Model):
+            id   = IntegerField(primary_key=True)
+            name = StringField()
+            age  = IntegerField()
+    """
+
+    _fields: Dict[str, Field] = {}
+    _table_name: str = ""
+
+    def __init__(self, **kwargs: Any) -> None:
+        for field_name, field_obj in self._fields.items():
+            value = kwargs.get(field_name, field_obj.default)
+            object.__setattr__(self, field_name, value)
+        for key, value in kwargs.items():
+            if key not in self._fields:
+                object.__setattr__(self, key, value)
+
+    @classmethod
+    def _from_row(cls, row: Dict[str, Any]) -> "Model":
+        """Reconstruct a model instance from a raw DB row dict."""
+        instance = cls.__new__(cls)
+        for field_name, field_obj in cls._fields.items():
+            object.__setattr__(instance, field_name, field_obj.from_db(row.get(field_name)))
+        return instance
+
+    def _pk_info(self) -> Tuple[Optional[str], Optional[Field]]:
+        for name, f in self._fields.items():
+            if f.primary_key:
+                return name, f
+        return None, None
+
+    def _pk_value(self) -> Any:
+        pk_name, _ = self._pk_info()
+        return getattr(self, pk_name, None) if pk_name else None
+
+    def save(self) -> None:
+        """INSERT if this is a new instance, UPDATE if it already has a PK."""
+        from .query import Query
+        from .pipeline import QueryPipeline
+
+        pk_name, _ = self._pk_info()
+        pk_val = self._pk_value()
+
+        data: Dict[str, Any] = {}
+        for field_name, field_obj in self._fields.items():
+            value = getattr(self, field_name, None)
+            field_obj.validate(value)
+            if field_obj.primary_key and pk_val is None:
+                continue
+            data[field_name] = field_obj.to_db(value)
+
+        pipeline = QueryPipeline(connection=get_connection())
+
+        if pk_val is None:
+            query = Query(self.__class__)
+            query.query_type = "INSERT"
+            query.data = data
+            result = pipeline.run(query)
+            if pk_name and result.last_insert_id is not None:
+                object.__setattr__(self, pk_name, result.last_insert_id)
+        else:
+            query = Query(self.__class__)
+            query.query_type = "UPDATE"
+            query.data = data
+            query.pk_value = pk_val
+            pipeline.run(query)
+
+    def delete(self) -> None:
+        """Delete this instance from the database and clear its primary key."""
+        from .query import Query
+        from .pipeline import QueryPipeline
+
+        pk_name, _ = self._pk_info()
+        pk_val = self._pk_value()
+
+        if pk_val is None:
+            raise ValueError(
+                f"Cannot delete an unsaved {self.__class__.__name__} instance"
+            )
+
+        query = Query(self.__class__)
+        query.query_type = "DELETE"
+        query.pk_value = pk_val
+        QueryPipeline(connection=get_connection()).run(query)
+
+        if pk_name:
+            object.__setattr__(self, pk_name, None)
+
+    @classmethod
+    def create_table(cls) -> None:
+        """Execute ``CREATE TABLE IF NOT EXISTS`` for this model."""
+        col_defs = []
+        for field_name, field_obj in cls._fields.items():
+            col_def = f"{field_name} {field_obj.get_sql_type()}"
+            if field_obj.primary_key:
+                col_def += " PRIMARY KEY AUTOINCREMENT"
+            elif not field_obj.null:
+                col_def += " NOT NULL"
+            col_defs.append(col_def)
+        get_connection().create_table(cls._table_name, ", ".join(col_defs))
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, self.__class__):
+            return NotImplemented
+        pk_name, _ = self._pk_info()
+        if pk_name:
+            return getattr(self, pk_name) == getattr(other, pk_name)
+        return False
+
+    def __repr__(self) -> str:
+        attrs = ", ".join(
+            f"{k}={getattr(self, k, None)!r}" for k in self._fields
+        )
+        return f"{self.__class__.__name__}({attrs})"