oxyde-postgres 0.1.0__py3-none-any.whl

oxyde/models/metadata.py

@@ -0,0 +1,174 @@
+"""Dataclasses for storing parsed model and field metadata.
+
+This module defines the internal data structures used to store metadata
+extracted from Model class definitions. These are populated by
+Model._parse_field_tags() during model initialization.
+
+Hierarchy:
+    ModelMeta (table-level)
+        ├── table_name: str
+        ├── schema: str (PostgreSQL schema)
+        ├── indexes: list[Index]
+        ├── constraints: list[Check]
+        ├── field_metadata: dict[str, ColumnMeta]
+        └── relations: dict[str, RelationInfo]
+
+    ColumnMeta (field-level)
+        ├── name: Field name in Python
+        ├── db_column: Column name in database
+        ├── python_type: Python type (str, int, datetime, etc.)
+        ├── nullable: bool
+        ├── primary_key: bool
+        ├── index/unique: bool
+        ├── foreign_key: ForeignKeyInfo | None
+        └── db_default: SQL DEFAULT expression
+
+    ForeignKeyInfo (FK constraint)
+        ├── target: Target model key ("module.ClassName")
+        ├── column_name: Column in this table ("author_id")
+        ├── target_field: Target column ("id")
+        └── on_delete/on_update: CASCADE, RESTRICT, etc.
+
+    RelationInfo (virtual relation, not stored in DB)
+        ├── kind: "one_to_many" | "many_to_many"
+        ├── target: Target model name
+        ├── remote_field: FK field on related model
+        └── through: M2M junction table
+
+Usage:
+    # Access via model's _db_meta attribute
+    User._db_meta.table_name  # "users"
+    User._db_meta.field_metadata["email"].unique  # True
+    User._db_meta.field_metadata["author"].foreign_key.target  # "myapp.Author"
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from dataclasses import field as dataclass_field
+from typing import Any
+
+from pydantic.fields import PydanticUndefined
+
+from oxyde.core.column_types import compute_column_type
+from oxyde.models.decorators import Check, Index
+
+
+@dataclass(slots=True)
+class ForeignKeyInfo:
+    """Metadata describing a foreign key relationship."""
+
+    target: (
+        str  # Target model key (e.g., "__main__.User") or table name for primitive FK
+    )
+    column_name: str  # Column name in this table (e.g., "author_id")
+    target_field: str  # Target field name in referenced table (e.g., "id", "uuid")
+    nullable: bool
+    on_delete: str | None = None
+    on_update: str | None = None
+
+
+@dataclass(slots=True)
+class ColumnMeta:
+    """Metadata captured for a single model field."""
+
+    name: str
+    db_column: str
+    python_type: Any
+    nullable: bool
+    db_type: str | None = None
+    index: bool = False
+    index_name: str | None = None
+    index_method: str | None = None  # btree, hash, gin, gist
+    unique: bool = False
+    primary_key: bool = False
+    comment: str | None = None
+    default: Any = PydanticUndefined
+    default_factory: Any | None = None
+    db_default: str | None = None  # Raw SQL DEFAULT expression
+    max_length: int | None = None
+    max_digits: int | None = None
+    decimal_places: int | None = None
+    foreign_key: ForeignKeyInfo | None = None
+    checks: list[str] = dataclass_field(default_factory=list)
+    extra: dict[str, Any] = dataclass_field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class RelationInfo:
+    """Metadata describing a relationship between models."""
+
+    name: str
+    kind: str  # one_to_many, many_to_many
+    target: str
+    remote_field: str | None = None
+    through: str | None = None
+    back_populates: str | None = None
+
+
+@dataclass(slots=True)
+class ModelMeta:
+    """Container for model metadata."""
+
+    table_name: str | None = None
+    schema: str | None = None
+    comment: str | None = None
+    indexes: list[Index] = dataclass_field(default_factory=list)
+    unique_together: list[tuple[str, ...]] = dataclass_field(default_factory=list)
+    constraints: list[Check] = dataclass_field(default_factory=list)
+    field_metadata: dict[str, ColumnMeta] = dataclass_field(default_factory=dict)
+    relations: dict[str, RelationInfo] = dataclass_field(default_factory=dict)
+    extra: dict[str, Any] = dataclass_field(default_factory=dict)
+    # Cached IR type hints for Rust decoding (computed at finalization)
+    column_types: dict[str, dict] | None = None
+    # Column db_type overrides for PostgreSQL array casts and JSON lookups
+    column_db_types: dict[str, str] | None = None
+    # Reverse mapping: db_column → field_name (only where they differ)
+    reverse_column_map: dict[str, str] = dataclass_field(default_factory=dict)
+    # Primary key field name and db column (cached at finalization)
+    pk_field: str | None = None
+    pk_column: str | None = None
+
+
+def is_column_field(meta: ColumnMeta) -> bool:
+    """Whether a field is backed by its own column.
+
+    Virtual relation fields (reverse FK, m2m) and FK model fields
+    (author: Author) are not columns; the synthetic FK field (author_id) is.
+    """
+    return not (
+        meta.extra.get("reverse_fk")
+        or meta.extra.get("m2m")
+        or meta.foreign_key is not None
+    )
+
+
+def column_type_for_meta(meta: ColumnMeta) -> dict[str, Any] | None:
+    """ColumnTypeSpec dict of a field's column, or None when it has none
+    (see ``is_column_field``)."""
+    if not is_column_field(meta):
+        return None
+    return compute_column_type(
+        meta.python_type,
+        meta.db_type,
+        max_length=meta.max_length,
+        max_digits=meta.max_digits,
+        decimal_places=meta.decimal_places,
+    )
+
+
+class RelationDescriptorBase:
+    """Marker base class for relation descriptors."""
+
+    _is_relation_descriptor = True
+
+
+__all__ = [
+    "ForeignKeyInfo",
+    "ColumnMeta",
+    "RelationInfo",
+    "ModelMeta",
+    "RelationDescriptorBase",
+    "column_type_for_meta",
+    "is_column_field",
+]

oxyde/models/registry.py

@@ -0,0 +1,170 @@
+"""Global registry of Model table classes.
+
+This module maintains a global dict mapping model keys to model classes.
+Models are auto-registered when defined with Meta.is_table = True.
+
+Model Key Format:
+    "{module}.{qualname}" e.g., "myapp.models.User"
+
+This ensures unique identification even for models with same class names
+in different modules.
+
+Functions:
+    register_table(model, overwrite=False):
+        Add model to registry. Raises ValueError if already registered
+        and overwrite=False.
+
+    unregister_table(model):
+        Remove model from registry (no-op if not registered).
+
+    registered_tables() -> dict[str, type[Model]]:
+        Return copy of registry.
+
+    iter_tables() -> tuple[type[Model], ...]:
+        Return tuple of registered model classes.
+
+    clear_registry():
+        Remove all models (used in tests for cleanup).
+
+    finalize_pending():
+        Finalize all pending models: FK resolve + metadata parse + PK cache.
+
+    assert_no_pending_models():
+        Fail-fast check that all models are finalized.
+
+Auto-Registration:
+    Models with Meta.is_table = True are automatically registered in
+    Model.__init_subclass__(). This happens at class definition time.
+
+    class User(Model):
+        class Meta:
+            is_table = True  # Auto-registers as "myapp.models.User"
+
+Migration Integration:
+    The migration system uses registered_tables() to discover models
+    and generate schema diffs.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from oxyde.models.base import Model
+
+_TABLES: dict[str, type[Model]] = {}
+_PENDING_MODELS: set[type[Model]] = set()
+
+
+def _model_key(model: type[Model]) -> str:
+    return f"{model.__module__}.{model.__qualname__}"
+
+
+def _finalize_model(model: type[Model]) -> bool:
+    """Try to fully finalize a single model: FK resolve → parse → column_types → PK cache.
+
+    Returns True if model is fully finalized, False if it should be retried later.
+    """
+    # Step 1: Resolve FK fields if needed
+    pending_fk = getattr(model, "__pending_fk_fields__", [])
+    if pending_fk:
+        fk_resolved = getattr(model, "__fk_fields_resolved__", False)
+        if not fk_resolved:
+            model.__fk_fields_resolved__ = False
+            model._resolve_fk_fields()
+            if not getattr(model, "__fk_fields_resolved__", False):
+                return False
+
+    # Step 2: Parse field tags → field_metadata
+    if not model._db_meta.field_metadata:
+        try:
+            model._parse_field_tags()
+        except NameError:
+            return False
+
+    # Step 3: Compute column_types for IR
+    if model._db_meta.column_types is None:
+        model._compute_column_types()
+
+    # Step 4: Cache PK field
+    if model._db_meta.pk_field is None:
+        for field_name, meta in model._db_meta.field_metadata.items():
+            if meta.primary_key:
+                model._db_meta.pk_field = field_name
+                model._db_meta.pk_column = meta.db_column
+                break
+
+    return True
+
+
+def finalize_pending() -> None:
+    """Finalize all pending models: FK resolve + metadata parse + PK cache.
+
+    Called from OxydeModelMeta.__new__ after Pydantic completes model creation.
+    Models that can't be finalized (forward refs not yet available) stay in
+    _PENDING_MODELS and are retried on next class definition.
+    """
+    for model in list(_PENDING_MODELS):
+        if _finalize_model(model):
+            _PENDING_MODELS.discard(model)
+
+
+def register_table(model: type[Model], *, overwrite: bool = False) -> None:
+    """Register an ORM model that represents a database table.
+
+    All table models are added to _PENDING_MODELS for finalization.
+    Finalization is triggered from OxydeModelMeta.__new__ after Pydantic completes.
+    """
+    key = _model_key(model)
+    existing = _TABLES.get(key)
+    if existing is model:
+        return
+    if existing is not None:
+        if not overwrite:
+            raise ValueError(f"Table '{key}' is already registered")
+        _PENDING_MODELS.discard(existing)
+    _TABLES[key] = model
+    _PENDING_MODELS.add(model)
+
+
+def unregister_table(model: type[Model]) -> None:
+    """Remove a model from the registry if present."""
+    _TABLES.pop(_model_key(model), None)
+    _PENDING_MODELS.discard(model)
+
+
+def registered_tables() -> dict[str, type[Model]]:
+    """Return a copy of the registered table mapping."""
+    return dict(_TABLES)
+
+
+def iter_tables() -> tuple[type[Model], ...]:
+    """Return tuple of registered model classes."""
+    return tuple(_TABLES.values())
+
+
+def clear_registry() -> None:
+    """Reset the registry (intended for tests)."""
+    _TABLES.clear()
+    _PENDING_MODELS.clear()
+
+
+def assert_no_pending_models() -> None:
+    """Verify all models are finalized. Call at startup after all imports.
+
+    Raises RuntimeError if any models are still pending finalization.
+    """
+    if _PENDING_MODELS:
+        names = ", ".join(m.__name__ for m in _PENDING_MODELS)
+        raise RuntimeError(f"Models not finalized (unresolved forward refs?): {names}")
+
+
+__all__ = [
+    "register_table",
+    "unregister_table",
+    "registered_tables",
+    "iter_tables",
+    "clear_registry",
+    "finalize_pending",
+    "assert_no_pending_models",
+]

oxyde/models/serializers.py

@@ -0,0 +1,144 @@
+"""Serialization utilities for INSERT/UPDATE operations.
+
+This module handles conversion of Model instances to dict payloads
+suitable for database operations. It filters out virtual fields and
+handles Pydantic's model_dump() options.
+
+Virtual Fields:
+    Fields with db_reverse_fk or db_m2m are "virtual" - they represent
+    relations loaded via JOINs but don't have actual database columns.
+    These must be excluded from INSERT/UPDATE payloads.
+
+    class Post(Model):
+        id: int = Field(db_pk=True)
+        author_id: int  # Real column
+        comments: list[Comment] = Field(db_reverse_fk="post")  # Virtual
+
+Functions:
+    _get_virtual_fields(model_class) -> set[str]:
+        Return names of virtual (relation) fields.
+
+    _dump_insert_data(instance) -> dict:
+        Serialize instance for INSERT. Includes default/default_factory
+        values; omits a column only when it is None and was not set
+        explicitly. Excludes virtual fields.
+
+    _dump_update_data(instance, fields) -> dict:
+        Serialize specific fields for UPDATE. Includes None values.
+        Excludes virtual fields.
+
+    _derive_create_data(filters, defaults) -> dict:
+        Merge filter kwargs with defaults for get_or_create().
+        Only includes exact lookups (no __gte, __contains, etc.).
+
+    _normalize_instance(model_class, payload) -> Model:
+        Convert dict to model instance, or return instance as-is.
+        Used by bulk_create() to accept mixed input.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING, Any, TypeVar
+
+from oxyde.exceptions import ManagerError
+from oxyde.models.metadata import is_column_field
+
+if TYPE_CHECKING:
+    from oxyde.models.base import Model
+
+
+TModel = TypeVar("TModel", bound="Model")
+
+
+def _get_virtual_fields(model_class: type[Model]) -> set[str]:
+    """Get field names that are virtual and don't correspond to database columns.
+
+    Virtual fields include:
+    - db_reverse_fk: reverse FK relations (e.g., posts: list[Post])
+    - db_m2m: many-to-many relations (e.g., tags: list[Tag])
+    - FK model fields: (e.g., author: Author) — real column is author_id
+    """
+    return {
+        name
+        for name, meta in model_class._db_meta.field_metadata.items()
+        if not is_column_field(meta)
+    }
+
+
+def _dump_insert_data(instance: Model) -> dict[str, Any]:
+    """Serialize model instance for INSERT operation.
+
+    Excludes virtual relation fields (db_reverse_fk, db_m2m) and Pydantic
+    computed fields that don't correspond to actual database columns.
+
+    Values filled from ``default=`` / ``default_factory`` are included. A
+    column is omitted only when its value is None AND the field was not set
+    explicitly: an untouched ``Field(default=None, db_pk=True)`` pk stays out
+    of the INSERT so the database sequence fills it, while an explicit
+    ``field=None`` reaches the database as NULL (e.g. to override a
+    server-side default).
+    """
+    virtual_fields = _get_virtual_fields(instance.__class__)
+    computed_fields = set(instance.__class__.model_computed_fields.keys())
+    data = instance.model_dump(mode="python", exclude=virtual_fields | computed_fields)
+    explicitly_set = instance.model_fields_set
+    return {
+        name: value
+        for name, value in data.items()
+        if value is not None or name in explicitly_set
+    }
+
+
+def _dump_update_data(instance: Model, fields: Iterable[str]) -> dict[str, Any]:
+    """Serialize specific fields of model instance for UPDATE operation.
+
+    Excludes virtual relation fields (db_reverse_fk, db_m2m) and Pydantic
+    computed fields that don't correspond to actual database columns.
+    """
+    virtual_fields = _get_virtual_fields(instance.__class__)
+    computed_fields = set(instance.__class__.model_computed_fields.keys())
+    excluded = virtual_fields | computed_fields
+    snapshot = instance.model_dump(mode="python", exclude_none=False)
+    return {
+        field: snapshot[field]
+        for field in fields
+        if field in snapshot and field not in excluded
+    }
+
+
+def _derive_create_data(
+    filters: dict[str, Any],
+    defaults: dict[str, Any] | None,
+) -> dict[str, Any]:
+    """Derive data for create operation from filters and defaults."""
+    data: dict[str, Any] = {}
+    for key, value in filters.items():
+        if "__" not in key:
+            data[key] = value
+    if defaults:
+        data.update(defaults)
+    return data
+
+
+def _normalize_instance(
+    model_class: type[TModel],
+    payload: Any,
+) -> TModel:
+    """Normalize payload to model instance."""
+    if isinstance(payload, model_class):
+        return payload
+    if isinstance(payload, dict):
+        return model_class(**payload)
+    raise ManagerError(
+        f"Unsupported payload type for {model_class.__name__}: {type(payload).__name__}"
+    )
+
+
+__all__ = [
+    "_get_virtual_fields",
+    "_dump_insert_data",
+    "_dump_update_data",
+    "_derive_create_data",
+    "_normalize_instance",
+]

oxyde/models/utils.py

@@ -0,0 +1,116 @@
+"""Type introspection utilities for Model field parsing.
+
+This module provides helper functions for extracting type information
+from Python type hints. Used during model metadata parsing.
+
+Functions:
+    _unpack_annotated(hint) -> (base_type, metadata_tuple):
+        Extract base type from Annotated[T, ...].
+        Returns (hint, ()) if not Annotated.
+
+        Annotated[int, Field(ge=0)]  →  (int, (Field(ge=0),))
+
+    _unwrap_optional(hint) -> (inner_type, is_optional):
+        Check if type is Optional[T] or T | None.
+        Returns (T, True) if nullable, (hint, False) otherwise.
+
+        int | None  →  (int, True)
+        str         →  (str, False)
+
+    _extract_constraints(field_info) -> dict[str, int]:
+        Extract type constraints from top-level FieldInfo.
+        Used for VARCHAR(n), DECIMAL(m,d) type inference.
+
+        Field(max_length=100)           →  {"max_length": 100}
+        Field(max_digits=10, decimal_places=2)  →  {"max_digits": 10, "decimal_places": 2}
+
+    _extract_inner_constraints(field_info) -> dict[str, int]:
+        Extract constraints from inner Annotated for list[Annotated[T, Field(...)]].
+
+        list[Annotated[str, Field(max_length=100)]]  →  {"max_length": 100}
+"""
+
+from __future__ import annotations
+
+from types import NoneType, UnionType
+from typing import Annotated, Any, Union, get_args, get_origin
+
+from pydantic.fields import FieldInfo
+
+
+def _unpack_annotated(hint: Any) -> tuple[Any, tuple[Any, ...]]:
+    """Extract base type and metadata from Annotated type hint."""
+    if get_origin(hint) is Annotated:
+        args = get_args(hint)
+        if args:
+            return args[0], tuple(args[1:])
+    return hint, ()
+
+
+def _unwrap_optional(hint: Any) -> tuple[Any, bool]:
+    """Check if type is Optional/Union with None and extract base type."""
+    origin = get_origin(hint)
+    if origin in (Union, UnionType):
+        args = []
+        nullable = False
+        for arg in get_args(hint):
+            if arg is NoneType:
+                nullable = True
+            else:
+                args.append(arg)
+        if nullable and len(args) == 1:
+            return args[0], True
+    return hint, False
+
+
+_CONSTRAINT_ATTRS = ("max_length", "max_digits", "decimal_places")
+
+
+def _collect_attrs(sources: list[Any]) -> dict[str, int]:
+    """Collect constraint attributes from a list of metadata sources."""
+    result: dict[str, int] = {}
+    for attr in _CONSTRAINT_ATTRS:
+        for source in sources:
+            val = getattr(source, attr, None)
+            if val is not None:
+                try:
+                    result[attr] = int(val)
+                except (TypeError, ValueError):
+                    continue
+                break
+    return result
+
+
+def _extract_constraints(field_info: FieldInfo) -> dict[str, int]:
+    """Extract type constraints from top-level FieldInfo."""
+    return _collect_attrs([field_info, *getattr(field_info, "metadata", ())])
+
+
+def _extract_inner_constraints(field_info: FieldInfo) -> dict[str, int]:
+    """Extract constraints from inner Annotated type for list fields.
+
+    For list[Annotated[T, Field(max_length=100)]], extracts max_length=100
+    from the inner FieldInfo metadata.
+    """
+    annotation = getattr(field_info, "annotation", None)
+    if annotation is None:
+        return {}
+    unwrapped, _ = _unwrap_optional(annotation)
+    if get_origin(unwrapped) is not list:
+        return {}
+    inner_args = get_args(unwrapped)
+    if not inner_args or get_origin(inner_args[0]) is not Annotated:
+        return {}
+    sources: list[Any] = []
+    for ann in get_args(inner_args[0])[1:]:
+        sources.append(ann)
+        sources.extend(getattr(ann, "metadata", ()))
+    return _collect_attrs(sources)
+
+
+__all__ = [
+    "_unpack_annotated",
+    "_unwrap_optional",
+    "_extract_constraints",
+    "_extract_inner_constraints",
+]

oxyde/queries/__init__.py

@@ -0,0 +1,79 @@
+"""Query building system for Oxyde ORM.
+
+This module provides Django-style query building via Model.objects interface.
+Queries are converted to IR (Intermediate Representation) and sent to the
+Rust core for SQL generation.
+
+Query Building:
+    Use Model.objects for all queries:
+        - filter(), exclude(): Add WHERE conditions
+        - order_by(), limit(), offset(): Pagination
+        - join(), prefetch(): Related objects
+        - values(), values_list(): Dict/tuple results
+        - annotate(), group_by(), having(): Aggregation
+
+Execution Methods:
+    - all(): Get all matching objects
+    - first(), last(): Get single object
+    - get(): Get exactly one object (raises if not found)
+    - get_or_none(): Get one or None
+    - get_or_create(): Get existing object or create a new one
+    - update_or_create(): Get existing object and update it, or create a new one
+    - count(), exists(): Aggregate queries
+    - create(), bulk_create(): Insert objects
+    - update(), delete(): Modify/remove objects
+
+Query Expressions:
+    F: Database-side field reference (F("price") * F("quantity")).
+    Q: Boolean expression combinator (Q(a=1) | Q(b=2), ~Q(deleted=True)).
+
+Aggregates:
+    Count, Sum, Avg, Max, Min: SQL aggregate functions.
+    Concat: String concatenation.
+    Coalesce: NULL handling (COALESCE(a, b, c)).
+    RawSQL: Escape hatch for raw SQL expressions.
+
+Example:
+    # Get active adult users
+    users = await User.objects.filter(age__gte=18, status="active").all()
+
+    # Complex query
+    users = await (
+        User.objects
+        .filter(Q(role="admin") | Q(is_superuser=True))
+        .exclude(deleted=True)
+        .order_by("-created_at")
+        .limit(10)
+        .all()
+    )
+"""
+
+from .aggregates import Aggregate, Avg, Coalesce, Concat, Count, Max, Min, RawSQL, Sum
+from .base import SupportsExecute
+from .expressions import F
+from .manager import QueryManager
+from .q import Q
+from .raw import execute_raw
+from .select import Query
+from .typed import FlatValuesListQuery, ValuesListQuery, ValuesQuery
+
+__all__ = [
+    "Query",
+    "F",
+    "Q",
+    "SupportsExecute",
+    "QueryManager",
+    "Aggregate",
+    "Count",
+    "Sum",
+    "Avg",
+    "Max",
+    "Min",
+    "Concat",
+    "Coalesce",
+    "RawSQL",
+    "execute_raw",
+    "ValuesQuery",
+    "ValuesListQuery",
+    "FlatValuesListQuery",
+]