sqlseed 0.1.0__py3-none-any.whl

sqlseed/__init__.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from typing import Any
+
+from sqlseed._version import __version__
+
+__all__ = [
+    "ColumnConfig",
+    "DataOrchestrator",
+    "GenerationResult",
+    "GeneratorConfig",
+    "ProviderType",
+    "TableConfig",
+    "__version__",
+    "connect",
+    "fill",
+    "fill_from_config",
+    "load_config",
+    "preview",
+]
+
+from sqlseed.config.loader import load_config
+from sqlseed.config.models import (
+    ColumnConfig,
+    GeneratorConfig,
+    ProviderType,
+    TableConfig,
+)
+from sqlseed.core.orchestrator import DataOrchestrator
+from sqlseed.core.result import GenerationResult
+
+
+def fill(
+    db_path: str,
+    *,
+    table: str,
+    count: int = 1000,
+    columns: dict[str, Any] | None = None,
+    provider: str = "mimesis",
+    locale: str = "en_US",
+    seed: int | None = None,
+    batch_size: int = 5000,
+    clear_before: bool = False,
+    optimize_pragma: bool = True,
+) -> GenerationResult:
+    with DataOrchestrator(
+        db_path=db_path,
+        provider_name=provider,
+        locale=locale,
+        optimize_pragma=optimize_pragma,
+    ) as orch:
+        return orch.fill_table(
+            table_name=table,
+            count=count,
+            columns=columns,
+            seed=seed,
+            batch_size=batch_size,
+            clear_before=clear_before,
+        )
+
+
+def connect(
+    db_path: str,
+    *,
+    provider: str = "mimesis",
+    locale: str = "en_US",
+    optimize_pragma: bool = True,
+) -> DataOrchestrator:
+    return DataOrchestrator(
+        db_path=db_path,
+        provider_name=provider,
+        locale=locale,
+        optimize_pragma=optimize_pragma,
+    )
+
+
+def fill_from_config(config_path: str) -> list[GenerationResult]:
+    config = load_config(config_path)
+    results: list[GenerationResult] = []
+    with DataOrchestrator(
+        db_path=config.db_path,
+        provider_name=config.provider.value,
+        locale=config.locale,
+        optimize_pragma=config.optimize_pragma,
+    ) as orch:
+        for table_config in config.tables:
+            result = orch.fill_table(
+                table_name=table_config.name,
+                count=table_config.count,
+                seed=table_config.seed,
+                batch_size=table_config.batch_size,
+                clear_before=table_config.clear_before,
+                column_configs=table_config.columns,
+                transform=table_config.transform,
+            )
+            results.append(result)
+    return results
+
+
+def preview(
+    db_path: str,
+    *,
+    table: str,
+    count: int = 5,
+    columns: dict[str, Any] | None = None,
+    provider: str = "mimesis",
+    locale: str = "en_US",
+    seed: int | None = None,
+) -> list[dict[str, Any]]:
+    with DataOrchestrator(
+        db_path=db_path,
+        provider_name=provider,
+        locale=locale,
+        optimize_pragma=False,
+    ) as orch:
+        return orch.preview_table(
+            table_name=table,
+            count=count,
+            columns=columns,
+            seed=seed,
+        )

sqlseed/_utils/__init__.py

@@ -0,0 +1,11 @@
+from sqlseed._utils.metrics import MetricsCollector
+from sqlseed._utils.progress import create_progress
+from sqlseed._utils.sql_safe import build_insert_sql, quote_identifier, validate_table_name
+
+__all__ = [
+    "MetricsCollector",
+    "build_insert_sql",
+    "create_progress",
+    "quote_identifier",
+    "validate_table_name",
+]

sqlseed/_utils/logger.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import logging
+import sys
+from typing import Any
+
+import structlog
+
+
+def configure_logging(level: str = "INFO") -> None:
+    structlog.configure(
+        processors=[
+            structlog.contextvars.merge_contextvars,
+            structlog.processors.add_log_level,
+            structlog.processors.StackInfoRenderer(),
+            structlog.dev.set_exc_info,
+            structlog.processors.TimeStamper(fmt="iso"),
+            structlog.dev.ConsoleRenderer(),
+        ],
+        wrapper_class=structlog.make_filtering_bound_logger(
+            getattr(logging, level.upper(), logging.INFO),
+        ),
+        context_class=dict,
+        logger_factory=structlog.PrintLoggerFactory(file=sys.stderr),
+        cache_logger_on_first_use=True,
+    )
+
+
+def get_logger(name: str | None = None) -> Any:
+    return structlog.get_logger(name)

sqlseed/_utils/metrics.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class MetricEntry:
+    name: str
+    value: float
+    timestamp: float = field(default_factory=time.monotonic)
+
+
+class MetricsCollector:
+    def __init__(self) -> None:
+        self._entries: list[MetricEntry] = []
+
+    def record(self, name: str, value: float) -> None:
+        self._entries.append(MetricEntry(name=name, value=value))
+
+    def get_entries(self, name: str | None = None) -> list[MetricEntry]:
+        if name is None:
+            return list(self._entries)
+        return [e for e in self._entries if e.name == name]
+
+    def summary(self) -> dict[str, Any]:
+        if not self._entries:
+            return {}
+        by_name: dict[str, list[float]] = {}
+        for entry in self._entries:
+            by_name.setdefault(entry.name, []).append(entry.value)
+        result: dict[str, Any] = {}
+        for name, values in by_name.items():
+            result[name] = {
+                "count": len(values),
+                "total": sum(values),
+                "avg": sum(values) / len(values),
+                "min": min(values),
+                "max": max(values),
+            }
+        return result
+
+    def clear(self) -> None:
+        self._entries.clear()

sqlseed/_utils/progress.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from rich.progress import BarColumn, Progress, SpinnerColumn, TextColumn, TimeElapsedColumn
+
+
+def create_progress() -> Progress:
+    return Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        BarColumn(),
+        TextColumn("[progress.percentage]{task.percentage:>3.0f}%"),
+        TimeElapsedColumn(),
+        transient=True,
+    )

sqlseed/_utils/schema_helpers.py

@@ -0,0 +1,51 @@
+"""
+Shared database schema helper utilities.
+
+Extracted from adapter implementations to avoid code duplication (DRY principle).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def detect_autoincrement(
+    execute_fn: Any,
+    table_name: str,
+    column_name: str,
+) -> bool:
+    """
+    Detect whether a column is AUTOINCREMENT by inspecting the CREATE TABLE SQL.
+
+    Works with both sqlite-utils Database.execute() and raw sqlite3 Connection.execute().
+
+    Args:
+        execute_fn: A callable that executes SQL and returns a cursor-like object
+                    with a .fetchone() method.
+        table_name: Name of the table.
+        column_name: Name of the column to check.
+
+    Returns:
+        True if the column is declared as INTEGER PRIMARY KEY AUTOINCREMENT.
+    """
+    try:
+        result = execute_fn(
+            "SELECT sql FROM sqlite_master WHERE type='table' AND name=?",
+            [table_name],
+        )
+        row = result.fetchone() if hasattr(result, "fetchone") else result
+        if row and row[0]:
+            sql_upper = row[0].upper()
+            if "AUTOINCREMENT" not in sql_upper:
+                return False
+            col_upper = column_name.upper()
+            for part in sql_upper.split(","):
+                stripped = part.strip()
+                if col_upper in stripped and "INTEGER" in stripped and "PRIMARY" in stripped:
+                    return True
+    except Exception:
+        logger.debug("Failed to detect autoincrement", extra={"table": table_name, "column": column_name})
+    return False

sqlseed/_utils/sql_safe.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import logging
+import re
+
+logger = logging.getLogger(__name__)
+
+
+def quote_identifier(name: str) -> str:
+    """
+    Safely escape a SQL identifier (table name, column name).
+
+    Uses SQLite's double-quote escaping rules:
+    - Wrap the identifier in double quotes
+    - Replace internal double quotes with two double quotes
+    """
+    if not name or not name.strip():
+        raise ValueError("SQL identifier cannot be empty")
+    escaped = name.replace('"', '""')
+    return f'"{escaped}"'
+
+
+def validate_table_name(name: str) -> str:
+    """
+    Validate and escape a table name.
+
+    Performs basic legality checks in addition to escaping.
+    Warns about table names containing special characters.
+    """
+    if not re.match(r"^[a-zA-Z_][a-zA-Z0-9_]*$", name):
+        logger.warning("Table name '%s' contains special characters and will be quoted", name)
+    return quote_identifier(name)
+
+
+def build_insert_sql(table_name: str, column_names: list[str]) -> str:
+    """
+    构建安全的 INSERT SQL 语句。
+
+    Returns:
+        INSERT INTO "table" ("col1", "col2") VALUES (?, ?)
+    """
+    safe_table = quote_identifier(table_name)
+    safe_columns = ", ".join(quote_identifier(col) for col in column_names)
+    placeholders = ", ".join(["?"] * len(column_names))
+    return f"INSERT INTO {safe_table} ({safe_columns}) VALUES ({placeholders})"

sqlseed/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

sqlseed/cli/__init__.py

@@ -0,0 +1,3 @@
+from sqlseed.cli.main import cli
+
+__all__ = ["cli"]

sqlseed/cli/main.py

@@ -0,0 +1,316 @@
+from __future__ import annotations
+
+import click
+
+from sqlseed._version import __version__
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="sqlseed")
+def cli() -> None:
+    """sqlseed - Declarative SQLite test data generation toolkit."""
+    pass
+
+
+@cli.command()
+@click.argument("db_path", required=False)
+@click.option("--table", "-t", default=None, help="Target table name")
+@click.option("--count", "-n", default=1000, type=int, help="Number of rows to generate")
+@click.option("--provider", "-p", default="mimesis", help="Data provider (mimesis|faker|base)")
+@click.option("--locale", "-l", default="en_US", help="Locale for data generation")
+@click.option("--seed", "-s", default=None, type=int, help="Random seed for reproducibility")
+@click.option("--batch-size", "-b", default=5000, type=int, help="Batch size for insertion")
+@click.option("--clear", is_flag=True, help="Clear table before generating")
+@click.option("--config", "-c", "config_path", default=None, help="YAML/JSON config file path")
+@click.option("--transform", "transform_path", default=None, help="Python transform script path")
+@click.option("--snapshot", is_flag=True, help="Save generation snapshot for replay")
+def fill(
+    db_path: str | None,
+    table: str | None,
+    count: int,
+    provider: str,
+    locale: str,
+    seed: int | None,
+    batch_size: int,
+    clear: bool,
+    config_path: str | None,
+    transform_path: str | None,
+    snapshot: bool,
+) -> None:
+    """Fill a table with generated test data.
+
+    Use --config for config-driven generation, or provide db_path + --table
+    for direct generation.
+    """
+    if config_path:
+        from sqlseed import fill_from_config
+
+        results = fill_from_config(config_path)
+        for result in results:
+            click.echo(str(result))
+        return
+
+    if not db_path:
+        raise click.UsageError("db_path is required when not using --config")
+    if not table:
+        raise click.UsageError("--table is required when not using --config")
+
+    from sqlseed import fill as api_fill
+
+    transform_fn = None
+    if transform_path:
+        from sqlseed.core.transform import load_transform
+
+        transform_fn = load_transform(transform_path)
+        click.echo(f"Transform script loaded: {transform_path}")
+
+    result = api_fill(
+        db_path,
+        table=table,
+        count=count,
+        provider=provider,
+        locale=locale,
+        seed=seed,
+        batch_size=batch_size,
+        clear_before=clear,
+    )
+    click.echo(str(result))
+
+    if transform_fn:
+        click.echo(f"Transform applied: {transform_path}")
+
+    if snapshot:
+        from sqlseed.config.models import GeneratorConfig, ProviderType, TableConfig
+        from sqlseed.config.snapshot import SnapshotManager
+
+        config = GeneratorConfig(
+            db_path=db_path,
+            provider=ProviderType(provider),
+            locale=locale,
+            tables=[
+                TableConfig(
+                    name=table,
+                    count=count,
+                    batch_size=batch_size,
+                    clear_before=clear,
+                    seed=seed,
+                )
+            ],
+        )
+        manager = SnapshotManager()
+        snapshot_path = manager.save(config, table, count, seed)
+        click.echo(f"Snapshot saved: {snapshot_path}")
+
+
+@cli.command()
+@click.argument("db_path")
+@click.option("--table", "-t", required=True, help="Target table name")
+@click.option("--count", "-n", default=5, type=int, help="Number of rows to preview")
+@click.option("--provider", "-p", default="mimesis", help="Data provider")
+@click.option("--locale", "-l", default="en_US", help="Locale")
+@click.option("--seed", "-s", default=None, type=int, help="Random seed")
+def preview(
+    db_path: str,
+    table: str,
+    count: int,
+    provider: str,
+    locale: str,
+    seed: int | None,
+) -> None:
+    """Preview generated data without writing to database."""
+    from rich.console import Console
+    from rich.table import Table as RichTable
+
+    from sqlseed import preview as api_preview
+
+    rows = api_preview(
+        db_path,
+        table=table,
+        count=count,
+        provider=provider,
+        locale=locale,
+        seed=seed,
+    )
+
+    if not rows:
+        click.echo("No data generated.")
+        return
+
+    console = Console()
+    rich_table = RichTable(title=f"Preview: {table} ({count} rows)")
+
+    for col_name in rows[0]:
+        rich_table.add_column(col_name)
+
+    for row in rows:
+        rich_table.add_row(*[str(v) for v in row.values()])
+
+    console.print(rich_table)
+
+
+@cli.command()
+@click.argument("db_path")
+@click.option("--table", "-t", default=None, help="Specific table to inspect")
+@click.option("--show-mapping", is_flag=True, help="Show column mapping strategy")
+def inspect(db_path: str, table: str | None, show_mapping: bool) -> None:
+    """Inspect database schema and column mapping strategies."""
+    from rich.console import Console
+    from rich.table import Table as RichTable
+
+    from sqlseed.core.orchestrator import DataOrchestrator
+
+    with DataOrchestrator(db_path) as orch:
+        console = Console()
+
+        tables = [table] if table else orch._db.get_table_names()
+
+        for tbl in tables:
+            count = orch._db.get_row_count(tbl)
+            columns = orch._schema.get_column_info(tbl)
+            fks = orch._db.get_foreign_keys(tbl)
+
+            rich_table = RichTable(title=f"Table: {tbl} ({count} rows)")
+            rich_table.add_column("Column")
+            rich_table.add_column("Type")
+            rich_table.add_column("Nullable")
+            rich_table.add_column("PK")
+            rich_table.add_column("Auto")
+
+            if show_mapping:
+                rich_table.add_column("Generator")
+                rich_table.add_column("Params")
+
+            for col in columns:
+                row_data = [
+                    col.name,
+                    col.type,
+                    "✓" if col.nullable else "✗",
+                    "✓" if col.is_primary_key else "",
+                    "✓" if col.is_autoincrement else "",
+                ]
+                if show_mapping:
+                    spec = orch._mapper.map_column(col)
+                    row_data.extend([spec.generator_name, str(spec.params)])
+                rich_table.add_row(*row_data)
+
+            console.print(rich_table)
+
+            if fks:
+                fk_table = RichTable(title=f"Foreign Keys: {tbl}")
+                fk_table.add_column("Column")
+                fk_table.add_column("Ref Table")
+                fk_table.add_column("Ref Column")
+                for fk in fks:
+                    fk_table.add_row(fk.column, fk.ref_table, fk.ref_column)
+                console.print(fk_table)
+
+
+@cli.command()
+@click.argument("config_path")
+@click.option("--db", default="test.db", help="Database path for template")
+def init(config_path: str, db: str) -> None:
+    """Generate a YAML configuration template."""
+    from sqlseed.config.loader import generate_template, save_config
+
+    config = generate_template(db)
+    save_config(config, config_path)
+    click.echo(f"Configuration template saved to: {config_path}")
+
+
+@cli.command()
+@click.argument("snapshot_path")
+def replay(snapshot_path: str) -> None:
+    """Replay a previously saved snapshot."""
+    from sqlseed.config.snapshot import SnapshotManager
+
+    manager = SnapshotManager()
+    result = manager.replay(snapshot_path)
+    click.echo(str(result))
+
+
+@cli.command("ai-suggest")
+@click.argument("db_path")
+@click.option("--table", "-t", required=True, help="Target table name")
+@click.option("--output", "-o", required=True, help="Output YAML file path")
+@click.option("--model", "-m", default=None, help="AI model name (default: qwen3-coder-plus)")
+@click.option("--api-key", envvar="SQLSEED_AI_API_KEY", default=None, help="AI API key")
+@click.option("--base-url", envvar="SQLSEED_AI_BASE_URL", default=None, help="AI API base URL")
+@click.option("--max-retries", default=3, type=int, help="Max refinement retries (0=disable)")
+@click.option("--verify/--no-verify", default=True, help="Enable AI config self-correction")
+@click.option("--no-cache", is_flag=True, help="Skip cached AI configs")
+def ai_suggest(
+    db_path: str,
+    table: str,
+    output: str,
+    model: str | None,
+    api_key: str | None,
+    base_url: str | None,
+    max_retries: int,
+    verify: bool,
+    no_cache: bool,
+) -> None:
+    """Analyze table schema and suggest generation rules via AI."""
+    import yaml
+    from sqlseed_ai.analyzer import SchemaAnalyzer
+    from sqlseed_ai.config import AIConfig
+
+    ai_config = AIConfig(api_key=api_key, base_url=base_url)
+    if model:
+        ai_config.model = model
+
+    analyzer = SchemaAnalyzer(config=ai_config)
+
+    if verify and max_retries > 0:
+        from sqlseed_ai.refiner import AiConfigRefiner, AISuggestionFailedError
+
+        refiner = AiConfigRefiner(analyzer, db_path)
+        try:
+            result = refiner.generate_and_refine(
+                table_name=table,
+                max_retries=max_retries,
+                no_cache=no_cache,
+            )
+        except AISuggestionFailedError as e:
+            click.echo(f"AI suggestion failed: {e}", err=True)
+            return
+    else:
+        from sqlseed.core.orchestrator import DataOrchestrator
+
+        with DataOrchestrator(db_path) as orch:
+            schema_ctx = orch.get_schema_context(table)
+            messages = analyzer.build_initial_messages(
+                table_name=schema_ctx["table_name"],
+                columns=schema_ctx["columns"],
+                indexes=schema_ctx["indexes"],
+                sample_data=schema_ctx["sample_data"],
+                foreign_keys=schema_ctx["foreign_keys"],
+                all_table_names=schema_ctx["all_table_names"],
+                distribution_profiles=schema_ctx.get("distribution"),
+            )
+            try:
+                result = analyzer.call_llm(messages)
+            except (ValueError, RuntimeError) as e:
+                click.echo(f"AI suggestion failed: {e}", err=True)
+                return
+
+    if result:
+        output_data = {
+            "db_path": db_path,
+            "provider": "mimesis",
+            "locale": "zh_CN",
+            "tables": [result],
+        }
+        with open(output, "w", encoding="utf-8") as f:
+            yaml.dump(output_data, f, allow_unicode=True, sort_keys=False, default_flow_style=False)
+        click.echo(f"AI suggestions saved to {output}")
+    else:
+        click.echo("No suggestions received. Ensure sqlseed-ai plugin is installed and API key is configured.")
+        click.echo("Set SQLSEED_AI_API_KEY environment variable or use --api-key option.")
+
+
+def main() -> None:
+    cli()
+
+
+if __name__ == "__main__":
+    main()

sqlseed/config/__init__.py

@@ -0,0 +1,14 @@
+from sqlseed.config.loader import generate_template, load_config, save_config
+from sqlseed.config.models import ColumnConfig, GeneratorConfig, ProviderType, TableConfig
+from sqlseed.config.snapshot import SnapshotManager
+
+__all__ = [
+    "ColumnConfig",
+    "GeneratorConfig",
+    "ProviderType",
+    "SnapshotManager",
+    "TableConfig",
+    "generate_template",
+    "load_config",
+    "save_config",
+]