oxyde-postgres 0.1.0__py3-none-any.whl

oxyde/queries/insert.py

@@ -0,0 +1,124 @@
+"""INSERT query builder for single and bulk inserts (internal).
+
+InsertQuery is used internally by QueryManager for create() and bulk_create().
+Use Model.objects.create() and Model.objects.bulk_create() instead.
+
+Example (via Manager):
+    user = await User.objects.create(name="Alice", age=30)
+    users = await User.objects.bulk_create([
+        User(name="Alice", age=30),
+        User(name="Bob", age=25),
+    ])
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from oxyde._msgpack import msgpack
+from oxyde.core import ir
+from oxyde.queries.base import (
+    SupportsExecute,
+    _build_column_types,
+    _map_values_to_columns,
+    _model_key,
+    _primary_key_meta,
+)
+from oxyde.queries.expressions import _serialize_value_for_ir
+
+if TYPE_CHECKING:
+    from oxyde.models.base import Model
+
+
+class InsertQuery:
+    """INSERT query builder."""
+
+    def __init__(self, model_class: type[Model]):
+        self.model_class = model_class
+        self._values: dict[str, Any] = {}
+        self._bulk_values: list[dict[str, Any]] | None = None
+
+    def _clone(self) -> InsertQuery:
+        clone = InsertQuery(self.model_class)
+        clone._values = dict(self._values)
+        clone._bulk_values = list(self._bulk_values) if self._bulk_values else None
+        return clone
+
+    def values(self, **kwargs: Any) -> InsertQuery:
+        """Set values to insert."""
+        clone = self._clone()
+        clone._values = dict(kwargs)
+        clone._bulk_values = None
+        return clone
+
+    def bulk_values(self, values: list[dict[str, Any]]) -> InsertQuery:
+        """Set bulk values for batch insert."""
+        clone = self._clone()
+        clone._bulk_values = list(values)
+        clone._values = {}
+        return clone
+
+    def _get_pk_column(self) -> str | None:
+        """Get the database column name for the primary key field."""
+        try:
+            pk_meta = _primary_key_meta(self.model_class)
+            return pk_meta.db_column
+        except Exception:
+            return None
+
+    def to_ir(self) -> dict[str, Any]:
+        """Convert to IR format."""
+        table_name = self.model_class.get_table_name()
+        pk_column = self._get_pk_column()
+        column_types = _build_column_types(self.model_class)
+
+        if self._bulk_values is not None:
+            if not self._bulk_values:
+                raise ValueError("Bulk INSERT requires at least one row")
+
+            # Serialize all rows
+            serialized_bulk = []
+            for row_values in self._bulk_values:
+                mapped = _map_values_to_columns(self.model_class, row_values)
+                serialized = {
+                    key: _serialize_value_for_ir(value) for key, value in mapped.items()
+                }
+                serialized_bulk.append(serialized)
+
+            # Bulk insert: only return PKs for efficiency
+            return ir.build_insert_ir(
+                table=table_name,
+                bulk_values=serialized_bulk,
+                column_types=column_types,
+                model=_model_key(self.model_class),
+                pk_column=pk_column,
+            )
+        else:
+            if not self._values:
+                raise ValueError("INSERT query requires at least one column/value pair")
+
+            mapped_values = _map_values_to_columns(self.model_class, self._values)
+            serialized_values = {
+                key: _serialize_value_for_ir(value)
+                for key, value in mapped_values.items()
+            }
+
+            # Single insert: use RETURNING * to get all fields (including db defaults)
+            return ir.build_insert_ir(
+                table=table_name,
+                values=serialized_values,
+                column_types=column_types,
+                model=_model_key(self.model_class),
+                pk_column=pk_column,
+                returning=True,
+            )
+
+    async def execute(self, client: SupportsExecute) -> dict[str, Any]:
+        """Execute insert query."""
+        ir = self.to_ir()
+        result_bytes = await client.execute(ir)
+        result: dict[str, Any] = msgpack.unpackb(result_bytes, raw=False)
+        return result
+
+
+__all__ = ["InsertQuery"]

oxyde/queries/joins.py

@@ -0,0 +1,66 @@
+"""Internal descriptor for JOIN operations in queries.
+
+_JoinDescriptor holds all metadata needed to generate a JOIN clause
+and map results back to nested model instances.
+
+Attributes:
+    path: Dot-separated relation path (e.g., "author", "author.profile")
+    alias: SQL table alias for this join (e.g., "t1", "t2")
+    result_prefix: Prefix for result columns (e.g., "author__")
+    parent_path: Path to parent join (None for direct joins)
+    parent_alias: SQL alias of parent table
+    attr_name: Attribute name on parent model (e.g., "author")
+    source_column: FK column on source table (e.g., "author_id")
+    target_column: PK column on target table (e.g., "id")
+    columns: List of (field_name, db_column) for SELECT
+    target_model: Model class being joined
+    parent_model: Model class of the parent
+    nullable: Whether this is a LEFT JOIN (True) or INNER JOIN (False)
+
+Join Resolution:
+    JoiningMixin.join("author") creates _JoinDescriptor:
+    - Finds FK field on current model pointing to Author
+    - Resolves source_column (author_id) and target_column (id)
+    - Generates unique alias
+    - Collects columns from target model
+
+Nested Joins:
+    join("author.profile") creates two descriptors:
+    1. Post → Author (path="author")
+    2. Author → Profile (path="author.profile", parent_path="author")
+
+Usage:
+    # Query uses these internally
+    query = Post.objects.join("author", "category")
+    for desc in query._join_specs:
+        print(desc.path, desc.alias)  # "author" "t1", "category" "t2"
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from oxyde.models.base import Model
+
+
+@dataclass(slots=True)
+class _JoinDescriptor:
+    """Descriptor for a join operation."""
+
+    path: str
+    alias: str
+    result_prefix: str
+    parent_path: str | None
+    parent_alias: str | None
+    attr_name: str
+    source_column: str
+    target_column: str
+    columns: list[tuple[str, str]]
+    target_model: type[Model]
+    parent_model: type[Model]
+    nullable: bool
+
+
+__all__ = ["_JoinDescriptor"]

oxyde/queries/manager.py

@@ -0,0 +1,409 @@
+"""Django-style QueryManager for Model.objects interface.
+
+This module provides QueryManager - the class behind Model.objects that
+enables Django-like query syntax. Each Model gets a QueryManager
+instance automatically assigned to its `objects` attribute.
+
+Design:
+    QueryManager is a thin proxy that creates Query instances.
+    All actual functionality lives in Query and its mixins.
+    Manager methods just return Query(model) with the appropriate method called.
+
+Example:
+    # Manager is auto-attached to models
+    class User(Model):
+        ...
+
+    # All methods return Query objects or execute queries
+    users = await User.objects.all()
+    user = await User.objects.filter(id=1).get()
+    new_user = await User.objects.create(name="Alice")
+"""
+
+from __future__ import annotations
+
+from collections.abc import Coroutine, Iterable
+from typing import TYPE_CHECKING, Any, Generic, Literal, TypeVar, overload
+
+from oxyde.exceptions import IntegrityError, ManagerError, NotFoundError
+from oxyde.models.serializers import _derive_create_data
+from oxyde.queries.select import Query
+
+if TYPE_CHECKING:
+    from oxyde.models.base import Model
+    from oxyde.queries.base import SupportsExecute
+    from oxyde.queries.typed import (
+        FlatValuesListQuery,
+        ValuesListQuery,
+        ValuesQuery,
+    )
+
+
+TModel = TypeVar("TModel", bound="Model")
+
+
+class QueryManager(Generic[TModel]):
+    """Manager that provides Query access for a model.
+
+    All methods delegate to Query - this is just a factory/proxy.
+    """
+
+    def __init__(self, model_class: type[TModel]) -> None:
+        self.model_class = model_class
+
+    def _query(self) -> Query[TModel]:
+        """Create a new Query for this model."""
+        return Query(self.model_class)
+
+    # --- Query building methods (return Query) ---
+
+    def query(self) -> Query[TModel]:
+        """Return a Query builder for this model."""
+        return self._query()
+
+    def filter(self, *args: Any, **kwargs: Any) -> Query[TModel]:
+        """Filter by Q-expressions or field lookups."""
+        return self._query().filter(*args, **kwargs)
+
+    def exclude(self, *args: Any, **kwargs: Any) -> Query[TModel]:
+        """Exclude rows matching conditions (NOT filter)."""
+        return self._query().exclude(*args, **kwargs)
+
+    def values(self, *fields: str) -> ValuesQuery[TModel]:
+        """Return dicts instead of models."""
+        return self._query().values(*fields)
+
+    @overload
+    def values_list(
+        self, field: str, /, *, flat: Literal[True]
+    ) -> FlatValuesListQuery[TModel]: ...
+
+    @overload
+    def values_list(
+        self, *fields: str, flat: Literal[False] = ...
+    ) -> ValuesListQuery[TModel]: ...
+
+    @overload
+    def values_list(
+        self, *fields: str, flat: bool
+    ) -> ValuesListQuery[TModel] | FlatValuesListQuery[TModel]: ...
+
+    def values_list(self, *fields: str, flat: bool = False) -> Any:
+        """Return tuples/lists instead of models."""
+        return self._query().values_list(*fields, flat=flat)
+
+    def distinct(self, distinct: bool = True) -> Query[TModel]:
+        """Add DISTINCT to query."""
+        return self._query().distinct(distinct)
+
+    def join(self, *paths: str) -> Query[TModel]:
+        """Eager load relations via JOIN."""
+        return self._query().join(*paths)
+
+    def prefetch(self, *paths: str) -> Query[TModel]:
+        """Prefetch relations in separate queries."""
+        return self._query().prefetch(*paths)
+
+    def for_update(self) -> Query[TModel]:
+        """Add FOR UPDATE lock."""
+        return self._query().for_update()
+
+    def for_share(self) -> Query[TModel]:
+        """Add FOR SHARE lock."""
+        return self._query().for_share()
+
+    def order_by(self, *fields: str) -> Query[TModel]:
+        """Order results by fields. Prefix with '-' for descending."""
+        return self._query().order_by(*fields)
+
+    def limit(self, value: int) -> Query[TModel]:
+        """Limit number of results."""
+        return self._query().limit(value)
+
+    def offset(self, value: int) -> Query[TModel]:
+        """Skip first N results."""
+        return self._query().offset(value)
+
+    def annotate(self, **annotations: Any) -> Query[TModel]:
+        """Add aggregate annotations."""
+        return self._query().annotate(**annotations)
+
+    # --- Execution methods (delegate to Query) ---
+
+    @overload
+    def all(
+        self,
+        *,
+        using: str | None = ...,
+        client: SupportsExecute | None = ...,
+        mode: Literal["models"] = ...,
+    ) -> Coroutine[Any, Any, list[TModel]]: ...
+
+    @overload
+    def all(
+        self,
+        *,
+        using: str | None = ...,
+        client: SupportsExecute | None = ...,
+        mode: str,
+    ) -> Coroutine[Any, Any, Any]: ...
+
+    def all(
+        self,
+        *,
+        using: str | None = None,
+        client: SupportsExecute | None = None,
+        mode: str = "models",
+    ) -> Coroutine[Any, Any, Any]:
+        """Execute query and return all results.
+
+        Args:
+            using: Database alias
+            client: Optional database client
+            mode: Result mode ("models", "dict", "list", "msgpack")
+        """
+        q: Query[TModel] = self._query()
+        if mode == "dict":
+            q = q.values()
+        elif mode == "list":
+            q = q.values_list()
+        elif mode == "msgpack":
+            q._result_mode = "msgpack"
+        return q.all(using=using, client=client)
+
+    async def first(
+        self,
+        *,
+        using: str | None = None,
+        client: SupportsExecute | None = None,
+    ) -> TModel | None:
+        """Return first result or None."""
+        return await self._query().first(using=using, client=client)
+
+    async def last(
+        self,
+        *,
+        using: str | None = None,
+        client: SupportsExecute | None = None,
+    ) -> TModel | None:
+        """Return last result or None."""
+        return await self._query().last(using=using, client=client)
+
+    async def get(
+        self,
+        *,
+        using: str | None = None,
+        client: SupportsExecute | None = None,
+        **filters: Any,
+    ) -> TModel:
+        """Return exactly one result. Raises NotFoundError/MultipleObjectsReturned."""
+        q = self._query()
+        if filters:
+            q = q.filter(**filters)
+        return await q.get(using=using, client=client)
+
+    async def get_or_none(
+        self,
+        *,
+        using: str | None = None,
+        client: SupportsExecute | None = None,
+        **filters: Any,
+    ) -> TModel | None:
+        """Return one result or None. Raises MultipleObjectsReturned if many."""
+        q = self._query()
+        if filters:
+            q = q.filter(**filters)
+        return await q.get_or_none(using=using, client=client)
+
+    async def get_or_create(
+        self,
+        *,
+        defaults: dict[str, Any] | None = None,
+        using: str | None = None,
+        client: SupportsExecute | None = None,
+        **filters: Any,
+    ) -> tuple[TModel, bool]:
+        """Get existing object or create a new one.
+
+        Args:
+            defaults: Field values to use when creating (not for lookup)
+            using: Database alias
+            client: Optional database client
+            **filters: Lookup conditions for finding existing object
+
+        Returns:
+            Tuple of (instance, created) where created is True if new object was made
+        """
+        try:
+            obj = await self.get(using=using, client=client, **filters)
+            return obj, False
+        except NotFoundError:
+            create_data = _derive_create_data(filters, defaults)
+            try:
+                obj = await self.create(using=using, client=client, **create_data)
+                return obj, True
+            except IntegrityError:
+                obj = await self.get(using=using, client=client, **filters)
+                return obj, False
+
+    async def exists(
+        self,
+        *,
+        using: str | None = None,
+        client: SupportsExecute | None = None,
+    ) -> bool:
+        """Check if any records match."""
+        return await self._query().exists(using=using, client=client)
+
+    async def count(
+        self,
+        *,
+        using: str | None = None,
+        client: SupportsExecute | None = None,
+    ) -> int:
+        """Count all records using SQL COUNT(*)."""
+        return await self._query().count(using=using, client=client)
+
+    async def sum(
+        self,
+        field: str,
+        *,
+        using: str | None = None,
+        client: SupportsExecute | None = None,
+    ) -> Any:
+        """Calculate sum of field values."""
+        return await self._query().sum(field, using=using, client=client)
+
+    async def avg(
+        self,
+        field: str,
+        *,
+        using: str | None = None,
+        client: SupportsExecute | None = None,
+    ) -> Any:
+        """Calculate average of field values."""
+        return await self._query().avg(field, using=using, client=client)
+
+    async def max(
+        self,
+        field: str,
+        *,
+        using: str | None = None,
+        client: SupportsExecute | None = None,
+    ) -> Any:
+        """Get maximum field value."""
+        return await self._query().max(field, using=using, client=client)
+
+    async def min(
+        self,
+        field: str,
+        *,
+        using: str | None = None,
+        client: SupportsExecute | None = None,
+    ) -> Any:
+        """Get minimum field value."""
+        return await self._query().min(field, using=using, client=client)
+
+    # --- Mutation methods (delegate to Query) ---
+
+    async def create(
+        self,
+        *,
+        instance: TModel | None = None,
+        using: str | None = None,
+        client: SupportsExecute | None = None,
+        _skip_hooks: bool = False,
+        **data: Any,
+    ) -> TModel:
+        """Create a new record in the database."""
+        return await self._query().create(
+            instance=instance,
+            using=using,
+            client=client,
+            _skip_hooks=_skip_hooks,
+            **data,
+        )
+
+    async def bulk_create(
+        self,
+        objects: Iterable[TModel | dict[str, Any]],
+        *,
+        using: str | None = None,
+        client: SupportsExecute | None = None,
+        batch_size: int | None = None,
+    ) -> list[TModel]:
+        """Bulk insert multiple objects efficiently."""
+        return await self._query().bulk_create(
+            objects,
+            using=using,
+            client=client,
+            batch_size=batch_size,
+        )
+
+    async def bulk_update(
+        self,
+        objects: Iterable[TModel],
+        fields: Iterable[str],
+        *,
+        using: str | None = None,
+        client: SupportsExecute | None = None,
+    ) -> int:
+        """Bulk update multiple objects with CASE WHEN."""
+        return await self._query().bulk_update(
+            objects,
+            fields,
+            using=using,
+            client=client,
+        )
+
+    async def update_or_create(
+        self,
+        *,
+        defaults: dict[str, Any] | None = None,
+        using: str | None = None,
+        client: SupportsExecute | None = None,
+        **filters: Any,
+    ) -> tuple[TModel, bool]:
+        """Get existing object and update it, or create it if it does not exist.
+
+        Args:
+            defaults: Field values to use when creating or updating
+            using: Database alias
+            client: Optional database client
+            **filters: Lookup conditions for finding existing object
+
+        Returns:
+            Tuple of (instance, created) where created is True if a new
+            object was made.
+        """
+        try:
+            obj = await self.get(using=using, client=client, **filters)
+        except NotFoundError:
+            create_data = _derive_create_data(filters, defaults)
+            try:
+                obj = await self.create(using=using, client=client, **create_data)
+                return obj, True
+            except IntegrityError:
+                obj = await self.get(using=using, client=client, **filters)
+
+        if not defaults:
+            return obj, False
+
+        for key, value in defaults.items():
+            setattr(obj, key, value)
+
+        saved_obj = await obj.save(
+            client=client,
+            using=using,
+            update_fields=defaults.keys(),
+        )
+        return saved_obj, False
+
+    async def upsert(self, *args: Any, **kwargs: Any) -> Any:
+        """Not implemented yet."""
+        raise ManagerError("upsert() is not implemented yet")
+
+
+__all__ = [
+    "QueryManager",
+]

oxyde/queries/mixins/__init__.py

@@ -0,0 +1,68 @@
+"""Query mixins providing modular functionality for Query class.
+
+The Query class inherits from all these mixins, each providing a specific
+category of query operations. This keeps the code organized and testable.
+
+Mixins:
+    FilteringMixin:
+        filter(), exclude() - WHERE clause building
+
+    PaginationMixin:
+        select() - choose specific columns
+        limit(), offset() - result pagination
+        order_by() - ORDER BY clause
+        distinct() - DISTINCT modifier
+        values(), values_list() - return dicts/tuples instead of models
+        __getitem__ - slice syntax for limit/offset
+
+    JoiningMixin:
+        join() - eager loading with SQL JOINs
+        prefetch() - prefetch related objects (separate queries)
+
+    AggregationMixin:
+        annotate() - add computed columns (COUNT, SUM, etc.)
+        group_by() - GROUP BY clause
+        having() - HAVING clause
+        count(), sum(), avg(), max(), min() - terminal aggregates
+
+    ExecutionMixin:
+        fetch_all(), fetch_one() - raw execution returning dicts
+        fetch_rows() - raw execution returning list of tuples
+        fetch_models() - execution returning model instances
+        fetch_msgpack() - execution returning raw MessagePack bytes
+        all(), first(), last(), exists() - convenience methods
+
+    MutationMixin:
+        create(), bulk_create() - INSERT operations
+        update(), bulk_update() - UPDATE operations
+        delete() - DELETE from SELECT query
+        increment() - atomic increment via F()
+
+    DebugMixin:
+        sql() - get generated SQL string
+        query - property to inspect IR dict
+        explain() - get query execution plan
+        union(), union_all() - combine queries
+
+Design:
+    Each mixin expects certain attributes on self (from Query.__init__).
+    Mixins use _clone() to maintain immutability.
+"""
+
+from oxyde.queries.mixins.aggregation import AggregationMixin
+from oxyde.queries.mixins.debug import DebugMixin
+from oxyde.queries.mixins.execution import ExecutionMixin
+from oxyde.queries.mixins.filtering import FilteringMixin
+from oxyde.queries.mixins.joining import JoiningMixin
+from oxyde.queries.mixins.mutation import MutationMixin
+from oxyde.queries.mixins.pagination import PaginationMixin
+
+__all__ = [
+    "FilteringMixin",
+    "PaginationMixin",
+    "JoiningMixin",
+    "AggregationMixin",
+    "ExecutionMixin",
+    "MutationMixin",
+    "DebugMixin",
+]