duo-orm 0.1.0__py3-none-any.whl

duo_orm/executor.py

@@ -0,0 +1,282 @@
+# duo_orm/executor.py
+
+from sqlalchemy import func, select, literal
+from sqlalchemy import delete as sa_delete
+from sqlalchemy import update as sa_update
+
+from .exceptions import ObjectNotFoundError, MultipleObjectsFoundError
+from .session import active_session_var, is_async_context
+
+
+def _get_db_from_query(query_builder):
+    """Internal helper to get the db object from a QueryBuilder."""
+    if not hasattr(query_builder, "db") or not query_builder.db:
+        raise RuntimeError("Database not configured for this query.")
+    return query_builder.db
+
+
+def _get_db_from_instance(instance):
+    """Internal helper to get the db object from a model instance."""
+    if not hasattr(instance.__class__, "_db") or not instance.__class__._db:
+        raise RuntimeError(
+            "Database not configured for this model. "
+            "Ensure your model inherits from a db.Model class."
+        )
+    return instance.__class__._db
+
+
+def _get_db_from_class(cls):
+    """Internal helper to get the db object from a model class."""
+    if not hasattr(cls, "_db") or not cls._db:
+        raise RuntimeError(
+            "Database not configured for this model. "
+            "Ensure your model inherits from a db.Model class."
+        )
+    return cls._db
+
+def _resolve_db_target(*, query_builder=None, instance=None, cls=None):
+    if query_builder is not None:
+        return _get_db_from_query(query_builder)
+    if instance is not None:
+        return _get_db_from_instance(instance)
+    if cls is not None:
+        return _get_db_from_class(cls)
+    raise RuntimeError("Missing context for resolving database target.")
+
+
+def _run_with_session(
+    *,
+    query_builder=None,
+    instance=None,
+    cls=None,
+    transactional: bool = False,
+    work_sync,
+    work_async,
+):
+    active_session = active_session_var.get(None)
+
+    if is_async_context():
+
+        async def _execute_async():
+            if active_session is not None:
+                return await work_async(active_session)
+            db = _resolve_db_target(query_builder=query_builder, instance=instance, cls=cls)
+            async with db.async_session_factory() as session:
+                if transactional:
+                    async with session.begin():
+                        return await work_async(session)
+                return await work_async(session)
+
+        return _execute_async()
+
+    if active_session is not None:
+        return work_sync(active_session)
+
+    db = _resolve_db_target(query_builder=query_builder, instance=instance, cls=cls)
+    with db.sync_session_factory() as session:
+        if transactional:
+            with session.begin():
+                return work_sync(session)
+        return work_sync(session)
+
+
+# --- READ OPERATIONS ---
+
+def _first(query_builder):
+    """Handles fetching the first record."""
+    stmt = query_builder._statement
+
+    def _sync(session):
+        result = session.execute(stmt)
+        return result.unique().scalars().first()
+
+    async def _async(session):
+        result = await session.execute(stmt)
+        return result.unique().scalars().first()
+
+    return _run_with_session(
+        query_builder=query_builder,
+        work_sync=_sync,
+        work_async=_async,
+    )
+
+def _all(query_builder):
+    """Handles fetching all records."""
+    stmt = query_builder._statement
+
+    def _sync(session):
+        result = session.execute(stmt)
+        return result.unique().scalars().all()
+
+    async def _async(session):
+        result = await session.execute(stmt)
+        return result.unique().scalars().all()
+
+    return _run_with_session(
+        query_builder=query_builder,
+        work_sync=_sync,
+        work_async=_async,
+    )
+
+def _count(query_builder):
+    """Handles counting the number of records for a query."""
+    count_stmt = func.count().select().select_from(query_builder._statement.alias("subquery"))
+
+    def _sync(session):
+        result = session.execute(count_stmt)
+        return result.scalar_one()
+
+    async def _async(session):
+        result = await session.execute(count_stmt)
+        return result.scalar_one()
+
+    return _run_with_session(
+        query_builder=query_builder,
+        work_sync=_sync,
+        work_async=_async,
+    )
+
+def _one(query_builder):
+    """Fetches exactly one record, raising if zero or multiple are found."""
+    stmt = query_builder._statement.limit(2)
+
+    def _handle_rows(rows):
+        if not rows:
+            raise ObjectNotFoundError(f"No {query_builder._model_cls.__name__} matches the query.")
+        if len(rows) > 1:
+            raise MultipleObjectsFoundError(
+                f"Multiple {query_builder._model_cls.__name__} instances match the query."
+            )
+        return rows[0]
+
+    def _sync(session):
+        result = session.execute(stmt)
+        rows = result.unique().scalars().all()
+        return _handle_rows(rows)
+
+    async def _async(session):
+        result = await session.execute(stmt)
+        rows = result.unique().scalars().all()
+        return _handle_rows(rows)
+
+    return _run_with_session(
+        query_builder=query_builder,
+        work_sync=_sync,
+        work_async=_async,
+    )
+
+def _exists(query_builder):
+    """Returns True if the query matches at least one record."""
+    exists_expr = query_builder._statement.exists()
+    # SQL Server (and some dialects) do not support `SELECT EXISTS (...)` directly.
+    # Use `SELECT 1 WHERE EXISTS (...)` which is portable.
+    exists_stmt = select(literal(True)).where(exists_expr).limit(1)
+    def _sync(session):
+        result = session.execute(exists_stmt)
+        return bool(result.scalar())
+
+    async def _async(session):
+        result = await session.execute(exists_stmt)
+        return bool(result.scalar())
+
+    return _run_with_session(
+        query_builder=query_builder,
+        work_sync=_sync,
+        work_async=_async,
+    )
+
+
+# --- WRITE OPERATIONS (Refactored) ---
+
+def _save(instance):
+    """Handles saving (INSERT/UPDATE) a model instance."""
+    def _sync(session):
+        session.add(instance)
+        session.flush()
+
+    async def _async(session):
+        session.add(instance)
+        await session.flush()
+
+    return _run_with_session(
+        instance=instance,
+        transactional=True,
+        work_sync=_sync,
+        work_async=_async,
+    )
+
+def _delete_instance(instance):
+    """Handles deleting a model instance."""
+    def _sync(session):
+        session.delete(instance)
+        session.flush()
+
+    async def _async(session):
+        session.delete(instance)
+        await session.flush()
+
+    return _run_with_session(
+        instance=instance,
+        transactional=True,
+        work_sync=_sync,
+        work_async=_async,
+    )
+
+def _bulk_create(cls, instances):
+    """Handles bulk creating model instances."""
+    def _sync(session):
+        session.add_all(instances)
+        session.flush()
+
+    async def _async(session):
+        session.add_all(instances)
+        await session.flush()
+
+    return _run_with_session(
+        cls=cls,
+        transactional=True,
+        work_sync=_sync,
+        work_async=_async,
+    )
+
+def _update(query_builder, **values):
+    """Handles bulk updates for a query."""
+    update_stmt = sa_update(query_builder._model_cls).values(**values)
+    where_clause = query_builder._statement.whereclause
+    if where_clause is not None:
+        update_stmt = update_stmt.where(where_clause)
+    def _sync(session):
+        session.execute(update_stmt)
+        session.flush()
+
+    async def _async(session):
+        await session.execute(update_stmt)
+        await session.flush()
+
+    return _run_with_session(
+        query_builder=query_builder,
+        transactional=True,
+        work_sync=_sync,
+        work_async=_async,
+    )
+
+def _delete(query_builder):
+    """Handles bulk deletes for a query."""
+    delete_stmt = sa_delete(query_builder._model_cls)
+    where_clause = query_builder._statement.whereclause
+    if where_clause is not None:
+        delete_stmt = delete_stmt.where(where_clause)
+    def _sync(session):
+        session.execute(delete_stmt)
+        session.flush()
+
+    async def _async(session):
+        await session.execute(delete_stmt)
+        await session.flush()
+
+    return _run_with_session(
+        query_builder=query_builder,
+        transactional=True,
+        work_sync=_sync,
+        work_async=_async,
+    )

duo_orm/migrations/__init__.py

@@ -0,0 +1 @@
+# This file makes the 'migrations' directory a Python sub-package.

duo_orm/migrations/cli.py

@@ -0,0 +1,164 @@
+# duo_orm/migrations/cli.py
+
+import click
+from alembic import command
+from alembic.util import CommandError
+from .config import (
+    _get_config,
+    _generate_files,
+    _resolve_layout,
+    _persist_pyproject_config,
+    get_alembic_config,
+    DB_OBJECT_NAME,
+    load_template,
+)
+from duo_orm.exceptions import ConfigurationError
+
+# 1. Main CLI group
+@click.group()
+def cli():
+    """The main entry point for the duo-orm CLI."""
+    pass
+
+# 2. New top-level 'init' command
+@cli.command()
+@click.option(
+    "--dir",
+    "orm_dir",
+    default=None,
+    help="Override the target directory for database/migrations/models (defaults to db/).",
+)
+def init(orm_dir):
+    """Initializes a complete, opinionated database structure."""
+    click.echo("-> Initializing complete database structure...")
+    try:
+        project_root, config = _get_config(override_dir=orm_dir)
+        relative_dir = config["duo_orm_dir"]
+        base_dir, migrations_dir, module_path = _resolve_layout(project_root, relative_dir)
+
+        # --- Scaffolding logic ---
+
+        base_dir.mkdir(parents=True, exist_ok=True)
+
+        # Ensure parent directories are packages
+        if base_dir != project_root:
+            for p in base_dir.parents:
+                if p == project_root:
+                    break
+                (p / "__init__.py").touch(exist_ok=True)
+
+        (base_dir / "__init__.py").touch(exist_ok=True)
+
+        # A. Scaffold migrations environment
+        if not migrations_dir.exists():
+            _generate_files(base_dir, module_path, DB_OBJECT_NAME, config["version_table"])
+            click.secho(f"✅ Created migration environment at: {migrations_dir}", fg="green")
+        else:
+            click.secho(f"Migration environment at {migrations_dir} already exists. Skipping.", fg="yellow")
+
+        # B. Scaffold database.py and models directory
+        db_file_path = base_dir / "database.py"
+        if not db_file_path.exists():
+            template = load_template("database.py.tpl")
+            db_file_path.write_text(template)
+            click.secho(f"✅ Created database entrypoint at: {db_file_path}", fg="green")
+        else:
+            click.secho(f"Database entrypoint at {db_file_path} already exists. Skipping.", fg="yellow")
+
+        models_dir = db_file_path.parent / "models"
+        models_dir.mkdir(exist_ok=True)
+        (models_dir / "__init__.py").touch(exist_ok=True)
+        click.secho(f"✅ Ensured models directory exists at: {models_dir}", fg="green")
+
+        # Persist the resolved directory so future commands can infer it without flags.
+        _persist_pyproject_config(project_root, relative_dir, config.get("version_table"))
+
+        click.secho("\nProject initialization complete!", fg="green")
+        click.echo("Next steps:")
+        click.echo(f"1. Define your models in the '{models_dir}' directory.")
+        click.echo("2. Run 'duo-orm migration create \"initial models\"' to create your first migration.")
+
+    except Exception as e:
+        raise click.ClickException(f"Error during initialization: {e}")
+
+
+# 3. 'migration' subcommand group
+@cli.group(name="migration")
+def migration_group():
+    """Manages database schema migrations."""
+    pass
+
+# 4. Add existing commands to the 'migration' group
+@migration_group.command()
+@click.argument("message")
+@click.option(
+    "--dir",
+    "orm_dir",
+    default=None,
+    help="Override the target directory (defaults to db/ or pyproject config).",
+)
+def create(message, orm_dir):
+    """Creates a new migration file with autogenerated changes."""
+    click.echo("-> Creating new migration...")
+    try:
+        alembic_cfg = get_alembic_config(override_dir=orm_dir)
+        command.revision(alembic_cfg, message=message, autogenerate=True)
+        click.secho("✅ New migration file created.", fg="green")
+    except (CommandError, ConfigurationError) as e:
+        raise click.ClickException(f"Error creating migration: {e}")
+
+
+@migration_group.command()
+@click.argument("revision", default="head")
+@click.option(
+    "--dir",
+    "orm_dir",
+    default=None,
+    help="Override the target directory (defaults to db/ or pyproject config).",
+)
+def upgrade(revision, orm_dir):
+    """Applies migrations to the database."""
+    click.echo(f"-> Applying migrations to revision: {revision}")
+    try:
+        alembic_cfg = get_alembic_config(override_dir=orm_dir)
+        command.upgrade(alembic_cfg, revision)
+        click.secho("✅ Migrations applied successfully.", fg="green")
+    except (CommandError, ConfigurationError) as e:
+        raise click.ClickException(f"Error applying migrations: {e}")
+
+
+@migration_group.command(context_settings={"ignore_unknown_options": True, "allow_extra_args": True})
+@click.argument("revision", default=None, required=False)
+@click.option(
+    "--dir",
+    "orm_dir",
+    default=None,
+    help="Override the target directory (defaults to db/ or pyproject config).",
+)
+@click.pass_context
+def downgrade(ctx, revision, orm_dir):
+    """Reverts migrations."""
+    revision = revision or (ctx.args[0] if ctx.args else "-1")
+    click.echo(f"-> Downgrading migrations to revision: {revision}")
+    try:
+        alembic_cfg = get_alembic_config(override_dir=orm_dir)
+        command.downgrade(alembic_cfg, revision)
+        click.secho("✅ Migrations reverted successfully.", fg="green")
+    except (CommandError, ConfigurationError) as e:
+        raise click.ClickException(f"Error reverting migrations: {e}")
+
+
+@migration_group.command()
+@click.option(
+    "--dir",
+    "orm_dir",
+    default=None,
+    help="Override the target directory (defaults to db/ or pyproject config).",
+)
+def history(orm_dir):
+    """Shows the migration history."""
+    try:
+        alembic_cfg = get_alembic_config(override_dir=orm_dir)
+        command.history(alembic_cfg)
+    except (CommandError, ConfigurationError) as e:
+        raise click.ClickException(f"Error showing history: {e}")

duo_orm/migrations/config.py

@@ -0,0 +1,239 @@
+# duo_orm/migrations/config.py
+
+import importlib
+import importlib.resources
+import sys
+from importlib.util import module_from_spec, spec_from_file_location
+import re
+from pathlib import Path
+from typing import Any, Dict, Tuple, Optional
+
+import toml
+from alembic.config import Config
+
+from duo_orm.exceptions import ConfigurationError
+from duo_orm.db import Database
+
+DEFAULT_ORM_DIR = "db"
+DB_OBJECT_NAME = "db"
+DEFAULT_VERSION_TABLE = "alembic_version"
+_ENV_VERSION_TABLE_REGEX = re.compile(
+    r'version_table\s*=\s*config\.get_main_option\("version_table",\s*"(?P<name>[A-Za-z_][A-Za-z0-9_]*)"\)'
+)
+
+
+def _get_project_root() -> Path:
+    """Finds the project root by looking for pyproject.toml."""
+    current_dir = Path.cwd()
+    for parent in [current_dir] + list(current_dir.parents):
+        if (parent / "pyproject.toml").exists():
+            return parent
+    raise FileNotFoundError("Could not find project root (pyproject.toml).")
+
+
+def _normalize_dir(value: str | None) -> str:
+    raw = (value or DEFAULT_ORM_DIR).strip()
+    if not raw or raw == ".":
+        raw = DEFAULT_ORM_DIR
+    rel_path = Path(raw)
+    if rel_path.is_absolute():
+        raise ConfigurationError("duo_orm_dir must be a relative path within the project.")
+    parts = [part for part in rel_path.parts if part not in ("", ".")]
+    if not parts:
+        parts = [DEFAULT_ORM_DIR]
+    for part in parts:
+        if not part.isidentifier():
+            raise ConfigurationError(
+                f"Invalid path segment '{part}' in duo_orm_dir. Use valid Python identifiers."
+            )
+    return "/".join(parts)
+
+
+def _slugify_repo_name(path: Path) -> str:
+    """Convert a repository directory name to a snake_case-ish slug."""
+    name = path.name
+    slug = re.sub(r"[^0-9A-Za-z]+", "_", name).strip("_").lower()
+    return slug or "duo_orm"
+
+
+def _normalize_version_table(value: Optional[str], project_root: Path) -> str:
+    raw = (value or "").strip()
+    if not raw:
+        return DEFAULT_VERSION_TABLE
+    if not re.match(r"^[A-Za-z_][A-Za-z0-9_]*$", raw):
+        raise ConfigurationError(
+            "version_table must be a valid SQL identifier (letters, digits, underscore, not starting with a digit)."
+        )
+    return raw
+
+
+def _detect_version_table_from_env(migrations_dir: Path) -> Optional[str]:
+    env_path = migrations_dir / "env.py"
+    if not env_path.exists():
+        return None
+    match = _ENV_VERSION_TABLE_REGEX.search(env_path.read_text())
+    if match:
+        return match.group("name")
+    return None
+
+
+def _resolve_layout(project_root: Path, relative_dir: str) -> Tuple[Path, Path, str]:
+    rel_path = Path(relative_dir)
+    base_dir = (project_root / rel_path).resolve()
+    module_path = relative_dir.replace("/", ".")
+    migrations_dir = base_dir / "migrations"
+    return base_dir, migrations_dir, module_path
+
+
+def _get_config(found_root: Optional[Path] = None, override_dir: Optional[str] = None) -> Tuple[Path, Dict[str, Any]]:
+    """
+    Finds and parses the user's configuration from pyproject.toml, with optional
+    overrides from CLI flags/env vars.
+    """
+    root = found_root
+    raw_dir = override_dir
+    if root is None:
+        try:
+            root = _get_project_root()
+        except FileNotFoundError:
+            root = Path.cwd()
+    pyproject_path = root / "pyproject.toml"
+    orm_config: Dict[str, Any] = {}
+    if pyproject_path.exists():
+        config_data = toml.load(pyproject_path)
+        orm_config = config_data.get("tool", {}).get("duo-orm") or {}
+    if raw_dir is None:
+        raw_dir = orm_config.get("duo_orm_dir")
+    normalized_dir = _normalize_dir(raw_dir)
+    orm_config["duo_orm_dir"] = normalized_dir
+    orm_config["version_table"] = _normalize_version_table(orm_config.get("version_table"), root)
+    return root, orm_config
+
+
+def _persist_pyproject_config(project_root: Path, relative_dir: str, version_table: Optional[str] = None):
+    pyproject_path = project_root / "pyproject.toml"
+    data: Dict[str, Any] = {}
+    if pyproject_path.exists():
+        data = toml.load(pyproject_path)
+    tool_section = data.setdefault("tool", {})
+    orm_section = tool_section.setdefault("duo-orm", {})
+    orm_section["duo_orm_dir"] = relative_dir
+    if version_table:
+        orm_section["version_table"] = version_table
+    pyproject_path.write_text(toml.dumps(data))
+
+
+def load_template(filename: str) -> str:
+    template_path = importlib.resources.files("duo_orm.migrations").joinpath("templates", filename)
+    return template_path.read_text()
+
+
+def _generate_files(base_dir: Path, module_path: str, db_object_name: str, version_table: str):
+    """Creates the directories and files for the migration environment."""
+    migrations_dir = base_dir / "migrations"
+    versions_dir = migrations_dir / "versions"
+    versions_dir.mkdir(parents=True, exist_ok=True)
+
+    # 1. Read our internal templates
+    template_path = importlib.resources.files("duo_orm.migrations").joinpath(
+        "templates"
+    )
+    ini_template = (template_path / "alembic.ini.tpl").read_text()
+    env_template = (template_path / "env.py.tpl").read_text()
+
+    # 2. Write the managed alembic.ini
+    (migrations_dir / "alembic.ini").write_text(ini_template)
+
+    # 3. Customize and write the smart env.py
+    env_py_content = env_template.format(
+        db_object_module=f"{module_path}.database",
+        db_object_name=db_object_name,
+        version_table=version_table,
+    )
+    (migrations_dir / "env.py").write_text(env_py_content)
+
+    # 4. Copy the script.py.mako template from the installed Alembic package
+    try:
+        mako_content = (
+            importlib.resources.files("alembic")
+            .joinpath("templates/generic/script.py.mako")
+            .read_text()
+        )
+        (migrations_dir / "script.py.mako").write_text(mako_content)
+    except (ImportError, AttributeError):
+        # This is a fallback and should rarely happen.
+        raise RuntimeError("Could not locate the alembic package to copy templates.")
+
+
+def get_alembic_config(override_dir: Optional[str] = None) -> Config:
+    """
+    Creates a complete Alembic Config object programmatically.
+    This is used by all CLI commands to run Alembic.
+    """
+    project_root, user_config = _get_config(override_dir=override_dir)
+    base_dir, migrations_dir, module_path = _resolve_layout(project_root, user_config["duo_orm_dir"])
+
+    # If the user didn't specify a version_table, try to infer the default from an existing env.py
+    if user_config.get("version_table") == DEFAULT_VERSION_TABLE:
+        detected = _detect_version_table_from_env(migrations_dir)
+        if detected:
+            user_config["version_table"] = detected
+
+    # This is the path to the INI file inside the user's project
+    config_file_path = str(migrations_dir / "alembic.ini")
+
+    # Ensure project root is importable so db package can be found
+    project_root_str = str(project_root)
+    if project_root_str not in sys.path:
+        sys.path.insert(0, project_root_str)
+
+    # Alembic's Config object reads the INI file as a base
+    config = Config(config_file_path)
+
+    # Dynamically import the user's configured database object (fresh each time)
+    db_object = None
+    try:
+        module_name = f"{module_path}.database"
+        importlib.invalidate_caches()
+        if module_name in sys.modules:
+            sys.modules.pop(module_name)
+        module = importlib.import_module(module_name)
+        sys.modules[module_name] = module
+        db_object = getattr(module, DB_OBJECT_NAME)
+    except (ImportError, AttributeError):
+        db_file = base_dir / "database.py"
+        module_name = f"{module_path}.database"
+        spec = spec_from_file_location(module_name, db_file)
+        if spec and spec.loader:
+            module = module_from_spec(spec)
+            sys.modules[module_name] = module
+            spec.loader.exec_module(module)  # type: ignore[attr-defined]
+            db_object = getattr(module, DB_OBJECT_NAME, None)
+
+    if not isinstance(db_object, Database):
+        raise ConfigurationError(
+            f"Could not import Database instance from '{module_path}.database'."
+        )
+
+    if not isinstance(db_object, Database):
+        raise ConfigurationError(
+            f"The object '{DB_OBJECT_NAME}' in '{module_path}.database' is not a duo_orm.Database instance."
+        )
+
+    # Programmatically set the URL and metadata for Alembic's environment
+    config.set_main_option("sqlalchemy.url", str(db_object.url))
+    config.set_main_option("version_table", user_config["version_table"])
+    config.attributes["target_metadata"] = db_object.metadata
+
+    return config
+
+
+__all__ = [
+    "_get_config",
+    "_generate_files",
+    "_resolve_layout",
+    "_persist_pyproject_config",
+    "get_alembic_config",
+    "DEFAULT_ORM_DIR",
+    "DB_OBJECT_NAME",
+]