swiftpy-framework 0.1.0__py3-none-any.whl

swiftpy/database/migrations/schema.py

@@ -0,0 +1,435 @@
+from __future__ import annotations
+
+import json
+import math
+import warnings
+from collections.abc import Callable
+from datetime import datetime
+from typing import Any
+
+import asyncpg
+
+from swiftpy.core.container import get_container
+from swiftpy.database.identifiers import validate_identifier
+from swiftpy.database.migrations.blueprint import (
+    _UNSET,
+    ALLOWED_COLUMN_TYPES,
+    Blueprint,
+    ColumnDefinition,
+    DefaultRaw,
+    _validate_column_length,
+    _validate_decimal_params,
+    raw,
+)
+from swiftpy.database.pool import DatabasePool
+from swiftpy.database.transaction import get_active_connection
+
+
+class SchemaGrammar:
+    """Translates a Blueprint into PostgreSQL Data Definition Language (DDL) statements."""
+
+    @classmethod
+    def compile_create(cls, blueprint: Blueprint) -> list[str]:
+        table = validate_identifier(blueprint.table)
+        columns_sql: list[str] = []
+        constraints_sql: list[str] = []
+        post_statements: list[str] = []
+
+        # 1. Compile columns
+        for col in blueprint.columns:
+            col_sql = cls._compile_column(col)
+            columns_sql.append(col_sql)
+
+            # Standalone index on column
+            if col.is_index:
+                idx_name = validate_identifier(
+                    col.index_name or f"idx_{table}_{col.name}"
+                )
+                post_statements.append(
+                    f'CREATE INDEX "{idx_name}" ON "{table}" ("{col.name}");'
+                )
+
+            # Standalone named unique constraint on column
+            if col.is_unique and col.index_name:
+                uq_col_name = validate_identifier(col.index_name)
+                constraints_sql.append(
+                    f'CONSTRAINT "{uq_col_name}" UNIQUE ("{col.name}")'
+                )
+
+            # Column comments
+            post_statements.extend(cls._compile_comment(table, col))
+
+        # 2. Compile table-level primary key (e.g. composite primary key)
+        if blueprint.primary_columns:
+            pk_name = validate_identifier(blueprint.primary_key_name or f"pk_{table}")
+            cols_joined = ", ".join(f'"{c}"' for c in blueprint.primary_columns)
+            constraints_sql.append(
+                f'CONSTRAINT "{pk_name}" PRIMARY KEY ({cols_joined})'
+            )
+
+        # 3. Compile table-level unique constraints and indexes
+        for idx in blueprint.indexes:
+            cols_joined = ", ".join(f'"{c}"' for c in idx.columns)
+            name_suffix = "_".join(idx.columns)
+
+            if idx.is_unique:
+                uq_name = validate_identifier(idx.name or f"uq_{table}_{name_suffix}")
+                constraints_sql.append(f'CONSTRAINT "{uq_name}" UNIQUE ({cols_joined})')
+            else:
+                idx_name = validate_identifier(idx.name or f"idx_{table}_{name_suffix}")
+                post_statements.append(
+                    f'CREATE INDEX "{idx_name}" ON "{table}" ({cols_joined});'
+                )
+
+        # 4. Compile foreign key constraints
+        for fk in blueprint.foreign_keys:
+            if not fk.ref_table:
+                raise ValueError(
+                    f"Foreign key on {table}.{fk.column} must specify a referenced table via .on('table_name')"
+                )
+            fk_name = validate_identifier(
+                fk.name or f"fk_{table}_{fk.column}_{fk.ref_table}"
+            )
+            constraints_sql.append(
+                f'CONSTRAINT "{fk_name}" FOREIGN KEY ("{fk.column}") '
+                f'REFERENCES "{fk.ref_table}" ("{fk.ref_column}") '
+                f"ON DELETE {fk.on_delete_action} ON UPDATE {fk.on_update_action}"
+            )
+
+        definitions = columns_sql + constraints_sql
+        create_sql = f'CREATE TABLE "{table}" (\n    '
+        create_sql += ",\n    ".join(definitions)
+        create_sql += "\n);"
+
+        return [create_sql, *post_statements]
+
+    @classmethod
+    def compile_table(cls, blueprint: Blueprint) -> list[str]:
+        table = validate_identifier(blueprint.table)
+        statements: list[str] = []
+
+        # 1. Drops first, so one blueprint can replace what it removes
+        for name in blueprint.drop_foreign_list:
+            safe_name = validate_identifier(name)
+            statements.append(
+                f'ALTER TABLE "{table}" DROP CONSTRAINT IF EXISTS "{safe_name}";'
+            )
+        for name in blueprint.drop_unique_list:
+            safe_name = validate_identifier(name)
+            statements.append(
+                f'ALTER TABLE "{table}" DROP CONSTRAINT IF EXISTS "{safe_name}";'
+            )
+        for name in blueprint.drop_indexes_list:
+            safe_name = validate_identifier(name)
+            statements.append(f'DROP INDEX IF EXISTS "{safe_name}";')
+        for name in blueprint.drop_columns_list:
+            safe_name = validate_identifier(name)
+            statements.append(
+                f'ALTER TABLE "{table}" DROP COLUMN IF EXISTS "{safe_name}";'
+            )
+
+        # 2. Renames
+        for old_name, new_name in blueprint.rename_columns_map.items():
+            safe_old = validate_identifier(old_name)
+            safe_new = validate_identifier(new_name)
+            statements.append(
+                f'ALTER TABLE "{table}" RENAME COLUMN "{safe_old}" TO "{safe_new}";'
+            )
+
+        # 3. Adds
+        for col in blueprint.columns:
+            statements.append(
+                f'ALTER TABLE "{table}" ADD COLUMN {cls._compile_column(col)};'
+            )
+            if col.is_index:
+                idx_name = validate_identifier(
+                    col.index_name or f"idx_{table}_{col.name}"
+                )
+                statements.append(
+                    f'CREATE INDEX "{idx_name}" ON "{table}" ("{col.name}");'
+                )
+            statements.extend(cls._compile_comment(table, col))
+
+        for idx in blueprint.indexes:
+            cols_joined = ", ".join(f'"{c}"' for c in idx.columns)
+            suffix = "_".join(idx.columns)
+            if idx.is_unique:
+                name = validate_identifier(idx.name or f"uq_{table}_{suffix}")
+                statements.append(
+                    f'ALTER TABLE "{table}" ADD CONSTRAINT "{name}" UNIQUE ({cols_joined});'
+                )
+            else:
+                name = validate_identifier(idx.name or f"idx_{table}_{suffix}")
+                statements.append(
+                    f'CREATE INDEX "{name}" ON "{table}" ({cols_joined});'
+                )
+
+        for fk in blueprint.foreign_keys:
+            if not fk.ref_table:
+                raise ValueError(
+                    f"Foreign key on {table}.{fk.column} must specify a referenced table via .on('table_name')"
+                )
+            fk_name = validate_identifier(
+                fk.name or f"fk_{table}_{fk.column}_{fk.ref_table}"
+            )
+            statements.append(
+                f'ALTER TABLE "{table}" ADD CONSTRAINT "{fk_name}" '
+                f'FOREIGN KEY ("{fk.column}") REFERENCES "{fk.ref_table}" ("{fk.ref_column}") '
+                f"ON DELETE {fk.on_delete_action} ON UPDATE {fk.on_update_action};"
+            )
+
+        return statements
+
+    @classmethod
+    def compile_drop(cls, table: str) -> str:
+        return f'DROP TABLE "{validate_identifier(table)}";'
+
+    @classmethod
+    def compile_drop_if_exists(cls, table: str) -> str:
+        return f'DROP TABLE IF EXISTS "{validate_identifier(table)}";'
+
+    @classmethod
+    def _compile_column(cls, col: ColumnDefinition) -> str:
+        col_name = validate_identifier(col.name)
+        parts: list[str] = [f'"{col_name}"']
+        t = col.type_name.strip().lower() if isinstance(col.type_name, str) else ""
+        if t not in ALLOWED_COLUMN_TYPES:
+            raise ValueError(f"Unsupported column type: {col.type_name!r}")
+
+        # Type mapping
+        if t == "id" or t == "big_increments":
+            parts.append("BIGSERIAL PRIMARY KEY")
+            return " ".join(parts)
+        elif t == "increments":
+            parts.append("SERIAL PRIMARY KEY")
+            return " ".join(parts)
+        elif t == "uuid":
+            parts.append("UUID")
+        elif t == "string":
+            validated_length = _validate_column_length(col.length)
+            parts.append(
+                f"VARCHAR({validated_length})"
+                if validated_length is not None
+                else "VARCHAR"
+            )
+        elif t == "text":
+            parts.append("TEXT")
+        elif t == "integer":
+            parts.append("INTEGER")
+        elif t == "big_integer":
+            parts.append("BIGINT")
+        elif t == "small_integer":
+            parts.append("SMALLINT")
+        elif t == "boolean":
+            parts.append("BOOLEAN")
+        elif t == "decimal":
+            raw_precision = 8 if col.precision is None else col.precision
+            raw_scale = 2 if col.scale is None else col.scale
+            precision, scale = _validate_decimal_params(raw_precision, raw_scale)
+            parts.append(f"NUMERIC({precision}, {scale})")
+        elif t == "float":
+            parts.append("DOUBLE PRECISION")
+        elif t == "json":
+            parts.append("JSON")
+        elif t == "jsonb":
+            parts.append("JSONB")
+        elif t == "date":
+            parts.append("DATE")
+        elif t == "time":
+            parts.append("TIME")
+        elif t == "timestamp":
+            parts.append("TIMESTAMP")
+        elif t == "timestamptz":
+            parts.append("TIMESTAMPTZ")
+        elif t == "vector":
+            raw_dim = getattr(col, "dimensions", None)
+            dim = 1536 if raw_dim is None else raw_dim
+            if isinstance(dim, bool) or not isinstance(dim, int) or dim <= 0:
+                raise ValueError(
+                    f"Vector dimensions must be a positive integer, got {raw_dim!r}"
+                )
+            parts.append(f"vector({dim})")
+
+        # Primary key
+        if col.is_primary:
+            parts.append("PRIMARY KEY")
+
+        # Nullability
+        if col.is_nullable:
+            parts.append("NULL")
+        elif not col.is_primary:
+            parts.append("NOT NULL")
+
+        # Default value
+        if col.default_val is not _UNSET:
+            default_expr = cls._format_default_value(col.default_val)
+            parts.append(f"DEFAULT {default_expr}")
+
+        # Unique (if not named; named unique is emitted in constraints_sql)
+        if col.is_unique and not col.index_name:
+            parts.append("UNIQUE")
+
+        # Unsigned check
+        if col.is_unsigned:
+            parts.append(f'CHECK ("{col_name}" >= 0)')
+
+        return " ".join(parts)
+
+    @staticmethod
+    def _compile_comment(table: str, col: ColumnDefinition) -> list[str]:
+        if col.comment_text is None:
+            return []
+        escaped = col.comment_text.replace("'", "''")
+        return [f'COMMENT ON COLUMN "{table}"."{col.name}" IS \'{escaped}\';']
+
+    @classmethod
+    def _format_default_value(cls, val: Any) -> str:
+        if val is None:
+            return "NULL"
+        if isinstance(val, bool):
+            return "TRUE" if val else "FALSE"
+        if isinstance(val, int):
+            return str(val)
+        if isinstance(val, float):
+            if not math.isfinite(val):
+                raise ValueError(f"Default float value must be finite, got {val!r}")
+            return str(val)
+        if isinstance(val, DefaultRaw):
+            return val.sql
+        if hasattr(val, "sql") and isinstance(val.sql, str):
+            return str(val.sql).strip()
+        if isinstance(val, (dict, list)):
+            json_escaped = json.dumps(val).replace("'", "''")
+            return f"'{json_escaped}'"
+        if isinstance(val, datetime):
+            iso_escaped = val.isoformat().replace("'", "''")
+            return f"'{iso_escaped}'"
+        if isinstance(val, str):
+            # Legacy magic PostgreSQL functions/keywords (deprecated in favor of raw(...))
+            upper = val.strip().upper()
+            if upper in {
+                "CURRENT_TIMESTAMP",
+                "CURRENT_DATE",
+                "CURRENT_TIME",
+                "NOW()",
+                "GEN_RANDOM_UUID()",
+                "TRUE",
+                "FALSE",
+                "NULL",
+            }:
+                warnings.warn(
+                    f"Passing SQL expression {val!r} as a string to .default() is deprecated; "
+                    f"use raw({val!r}) instead.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+                return val.strip()
+            # String literal: escape single quotes
+            escaped = val.replace("'", "''")
+            return f"'{escaped}'"
+        escaped = str(val).replace("'", "''")
+        return f"'{escaped}'"
+
+
+class Schema:
+    """Schema builder facade for defining and altering database tables."""
+
+    @classmethod
+    async def _get_connection(cls) -> tuple[asyncpg.Connection, bool]:
+        """Returns the active transaction connection or acquires a new one from the pool."""
+        tx_conn = get_active_connection()
+        if tx_conn is not None:
+            return tx_conn, False
+
+        container = get_container()
+        pool = container.resolve(DatabasePool).get_pool()
+        conn = await pool.acquire()
+        return conn, True
+
+    @classmethod
+    async def _execute_statements(cls, statements: list[str]) -> None:
+        conn, should_release = await cls._get_connection()
+        try:
+            async with conn.transaction():
+                for sql in statements:
+                    if sql.strip():
+                        await conn.execute(sql)
+        finally:
+            if should_release:
+                container = get_container()
+                await container.resolve(DatabasePool).get_pool().release(conn)
+
+    @classmethod
+    async def create(cls, table: str, callback: Callable[[Blueprint], Any]) -> None:
+        """Create a new database table using a fluent Blueprint."""
+        blueprint = Blueprint(table, is_create=True)
+        callback(blueprint)
+        statements = SchemaGrammar.compile_create(blueprint)
+        await cls._execute_statements(statements)
+
+    @classmethod
+    async def table(cls, table: str, callback: Callable[[Blueprint], Any]) -> None:
+        """Modify an existing database table using a fluent Blueprint."""
+        blueprint = Blueprint(table, is_create=False)
+        callback(blueprint)
+        statements = SchemaGrammar.compile_table(blueprint)
+        await cls._execute_statements(statements)
+
+    @classmethod
+    async def drop(cls, table: str) -> None:
+        """Drop a database table."""
+        sql = SchemaGrammar.compile_drop(table)
+        await cls._execute_statements([sql])
+
+    @classmethod
+    async def drop_if_exists(cls, table: str) -> None:
+        """Drop a database table if it exists."""
+        sql = SchemaGrammar.compile_drop_if_exists(table)
+        await cls._execute_statements([sql])
+
+    @classmethod
+    async def has_table(cls, table: str) -> bool:
+        """Determine whether the given table exists in the database."""
+        safe_table = validate_identifier(table)
+        conn, should_release = await cls._get_connection()
+        try:
+            query = """
+                SELECT EXISTS (
+                    SELECT 1
+                    FROM information_schema.tables
+                    WHERE table_name = $1
+                    AND table_schema = current_schema()
+                );
+            """
+            result = await conn.fetchval(query, safe_table)
+            return bool(result)
+        finally:
+            if should_release:
+                container = get_container()
+                await container.resolve(DatabasePool).get_pool().release(conn)
+
+    @classmethod
+    async def has_column(cls, table: str, column: str) -> bool:
+        """Determine whether the given column exists on the specified table."""
+        safe_table = validate_identifier(table)
+        safe_column = validate_identifier(column)
+        conn, should_release = await cls._get_connection()
+        try:
+            query = """
+                SELECT EXISTS (
+                    SELECT 1
+                    FROM information_schema.columns
+                    WHERE table_name = $1
+                    AND column_name = $2
+                    AND table_schema = current_schema()
+                );
+            """
+            result = await conn.fetchval(query, safe_table, safe_column)
+            return bool(result)
+        finally:
+            if should_release:
+                container = get_container()
+                await container.resolve(DatabasePool).get_pool().release(conn)
+
+
+__all__ = ["Schema", "SchemaGrammar", "raw"]

swiftpy/database/orm/__init__.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from swiftpy.database.orm.fields import Field, FieldInfo, Vector, VectorFieldInfo
+from swiftpy.database.orm.model import Model, ModelQueryBuilder
+from swiftpy.database.orm.relationships import (
+    BelongsTo,
+    BelongsToMany,
+    HasMany,
+    HasOne,
+    LazyLoadingDisabledError,
+    Relation,
+    RelationDescriptor,
+    RelationNotLoadedError,
+    RelationshipQueryBuilder,
+)
+
+__all__ = [
+    "BelongsTo",
+    "BelongsToMany",
+    "Field",
+    "FieldInfo",
+    "HasMany",
+    "HasOne",
+    "LazyLoadingDisabledError",
+    "Model",
+    "ModelQueryBuilder",
+    "Relation",
+    "RelationDescriptor",
+    "RelationNotLoadedError",
+    "RelationshipQueryBuilder",
+    "Vector",
+    "VectorFieldInfo",
+]

swiftpy/database/orm/fields.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+_MISSING = object()
+
+
+class FieldInfo:
+    """Represents column metadata and configuration on an Active Record Model."""
+
+    def __init__(
+        self,
+        default: Any = _MISSING,
+        *,
+        default_factory: Callable[[], Any] | None = None,
+        primary_key: bool = False,
+        nullable: bool = True,
+    ) -> None:
+        self.default = default
+        self.default_factory = default_factory
+        self.primary_key = primary_key
+        self.nullable = nullable
+
+
+class VectorFieldInfo(FieldInfo):
+    """Represents a vector column for semantic search and embeddings on an Active Record Model."""
+
+    def __init__(
+        self,
+        dimensions: int,
+        default: Any = _MISSING,
+        *,
+        metric: str = "cosine",
+        default_factory: Callable[[], Any] | None = None,
+        primary_key: bool = False,
+        nullable: bool = True,
+    ) -> None:
+        if isinstance(dimensions, bool) or not isinstance(dimensions, int) or dimensions <= 0:
+            raise ValueError(f"Vector dimensions must be a positive integer, got {dimensions}")
+        allowed_metrics = {"cosine", "l2", "inner_product"}
+        if metric not in allowed_metrics:
+            raise ValueError(
+                f"Unsupported vector distance metric '{metric}'. Expected one of {allowed_metrics}."
+            )
+        super().__init__(
+            default=default,
+            default_factory=default_factory,
+            primary_key=primary_key,
+            nullable=nullable,
+        )
+        self.dimensions = dimensions
+        self.metric = metric
+
+
+def Field(
+    default: Any = _MISSING,
+    *,
+    default_factory: Callable[[], Any] | None = None,
+    primary_key: bool = False,
+    nullable: bool = True,
+) -> Any:
+    """Declare column metadata, default value, or default_factory on an Active Record Model."""
+    return FieldInfo(
+        default=default,
+        default_factory=default_factory,
+        primary_key=primary_key,
+        nullable=nullable,
+    )
+
+
+def Vector(
+    dimensions: int,
+    default: Any = _MISSING,
+    *,
+    metric: str = "cosine",
+    default_factory: Callable[[], Any] | None = None,
+    primary_key: bool = False,
+    nullable: bool = True,
+) -> Any:
+    """Declare a vector embedding column with fixed dimensionality on an Active Record Model."""
+    return VectorFieldInfo(
+        dimensions=dimensions,
+        default=default,
+        metric=metric,
+        default_factory=default_factory,
+        primary_key=primary_key,
+        nullable=nullable,
+    )
+
+
+__all__ = ["Field", "FieldInfo", "Vector", "VectorFieldInfo"]