localql 1.0.0__py3-none-any.whl

csvql/__init__.py

@@ -0,0 +1,23 @@
+"""CSVQL public package interface."""
+
+from csvql.api import CSVQLSession
+from csvql.engine import CSVQLEngine
+from csvql.export import ExportFormat
+from csvql.models import InspectResult, ProfileResult, QueryResult, SampleResult, TableSource
+from csvql.project_config import ProjectTablesResult
+from csvql.quality import CheckRunResult
+
+__all__ = [
+    "CSVQLEngine",
+    "CSVQLSession",
+    "CheckRunResult",
+    "ExportFormat",
+    "InspectResult",
+    "ProfileResult",
+    "ProjectTablesResult",
+    "QueryResult",
+    "SampleResult",
+    "TableSource",
+]
+
+__version__ = "1.0.0"

csvql/__main__.py

@@ -0,0 +1,6 @@
+"""Run CSVQL as `python -m csvql`."""
+
+from csvql.cli import main
+
+if __name__ == "__main__":
+    main()

csvql/api.py

@@ -0,0 +1,154 @@
+"""Small public Python API for project-backed CSVQL workflows."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from csvql.checks import run_configured_checks
+from csvql.engine import CSVQLEngine
+from csvql.exceptions import ExportError, ProjectConfigError
+from csvql.export import (
+    ExportFormat,
+    format_query_result_for_export,
+    resolve_export_path,
+    write_export_file,
+)
+from csvql.inspection import inspect_csv_source, sample_csv_source
+from csvql.models import InspectResult, ProfileResult, QueryResult, SampleResult
+from csvql.profiling import profile_csv_source
+from csvql.project_config import (
+    ProjectContext,
+    ProjectTable,
+    ProjectTablesResult,
+    build_project_tables_result,
+    load_project,
+    project_tables_to_sources,
+    resolve_catalog_path,
+)
+from csvql.quality import CheckRunResult
+from csvql.source import CSVSource, source_from_path
+from csvql.sql_file import load_sql_file
+
+
+@dataclass(frozen=True, slots=True)
+class CSVQLSession:
+    """Thin project-backed API over existing CSVQL services."""
+
+    _context: ProjectContext
+
+    @classmethod
+    def from_config(cls, start_dir: str | Path = ".") -> CSVQLSession:
+        """Create a session from the nearest project config at or above ``start_dir``."""
+
+        return cls(load_project(Path(start_dir)))
+
+    def tables(self) -> ProjectTablesResult:
+        """Return the configured project table aliases and resolved paths."""
+
+        return build_project_tables_result(self._context)
+
+    def query(self, sql: str) -> QueryResult:
+        """Run trusted local SQL against the configured project tables."""
+
+        with CSVQLEngine() as engine:
+            engine.register_tables(project_tables_to_sources(self._context))
+            return engine.query(sql)
+
+    def run_file(self, path: str | Path) -> QueryResult:
+        """Load and run a saved SQL file resolved from the project root."""
+
+        sql_file = load_sql_file(str(path), base_dir=self._context.project_root)
+        return self.query(sql_file.sql)
+
+    def inspect(self, table: str, *, exact: bool = False) -> InspectResult:
+        """Inspect a configured table alias."""
+
+        return inspect_csv_source(_catalog_source(self._context, table), exact=exact)
+
+    def sample(self, table: str, *, limit: int = 10) -> SampleResult:
+        """Return a bounded sample from a configured table alias."""
+
+        return sample_csv_source(_catalog_source(self._context, table), limit=limit)
+
+    def profile(self, table: str) -> ProfileResult:
+        """Profile a configured table alias."""
+
+        return profile_csv_source(_catalog_source(self._context, table))
+
+    def check(
+        self,
+        table: str | None = None,
+        *,
+        show_failures: bool = False,
+        failure_limit: int = 5,
+    ) -> CheckRunResult:
+        """Run configured data-quality checks for the project or one table alias."""
+
+        return run_configured_checks(
+            self._context,
+            table_name=table,
+            show_failures=show_failures,
+            failure_limit=failure_limit,
+        )
+
+    def export(
+        self,
+        sql_file: str | Path,
+        out: str | Path,
+        *,
+        format: ExportFormat | str = ExportFormat.json,
+        force: bool = False,
+    ) -> Path:
+        """Run a saved SQL file and export the result, defaulting to JSON output."""
+
+        export_format = _export_format(format)
+        output_path = resolve_export_path(
+            str(out),
+            base_dir=self._context.project_root,
+            force=force,
+        )
+        result = self.run_file(sql_file)
+        content = format_query_result_for_export(result, export_format)
+        write_export_file(output_path, content, overwrite=force)
+        return output_path
+
+
+def _catalog_source(context: ProjectContext, table_name: str) -> CSVSource:
+    project_table = _project_table(context, table_name)
+    resolved_path = resolve_catalog_path(project_table, context)
+    resolved_source = source_from_path(
+        str(resolved_path),
+        base_dir=context.project_root,
+    )
+    return CSVSource(
+        path=resolved_source.path,
+        display_path=table_name,
+        fingerprint=resolved_source.fingerprint,
+    )
+
+
+def _project_table(context: ProjectContext, table_name: str) -> ProjectTable:
+    normalized = table_name.strip().lower()
+    match = next(
+        (table for table in context.config.tables if table.name.lower() == normalized),
+        None,
+    )
+    if match is None:
+        raise ProjectConfigError(
+            f"Project catalog table '{table_name}' was not found in {context.config_path}.",
+            suggestion="Run csvql tables to list configured table aliases.",
+        )
+    return match
+
+
+def _export_format(value: ExportFormat | str) -> ExportFormat:
+    if isinstance(value, ExportFormat):
+        return value
+    try:
+        return ExportFormat(value)
+    except ValueError as exc:
+        raise ExportError(
+            f"Unsupported export format: {value}",
+            suggestion="Use csv, json, or markdown.",
+        ) from exc

csvql/atomic_write.py

@@ -0,0 +1,81 @@
+"""Atomic local text writes for CSVQL user-visible outputs."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+import threading
+from pathlib import Path
+
+
+class OperationCancelled(Exception):
+    """Raised when a cancellable local operation is cancelled before commit."""
+
+
+class OperationToken:
+    """Thread-safe cancellation token for local TUI/file operations."""
+
+    def __init__(self) -> None:
+        self._cancelled = threading.Event()
+
+    def cancel(self) -> None:
+        """Mark the operation as cancelled."""
+
+        self._cancelled.set()
+
+    @property
+    def is_cancelled(self) -> bool:
+        """Return whether cancellation has been requested."""
+
+        return self._cancelled.is_set()
+
+    def raise_if_cancelled(self) -> None:
+        """Raise :class:`OperationCancelled` when the token is cancelled."""
+
+        if self.is_cancelled:
+            raise OperationCancelled("Operation cancelled.")
+
+
+def write_text_atomic(
+    path: Path,
+    content: str,
+    *,
+    encoding: str = "utf-8",
+    newline: str | None = None,
+    overwrite: bool = True,
+    token: OperationToken | None = None,
+) -> None:
+    """Write text through a temp sibling file and atomically publish the target.
+
+    When ``overwrite`` is ``False``, the final path is only created if it does
+    not already exist.
+    """
+
+    if token is not None:
+        token.raise_if_cancelled()
+
+    fd, temp_name = tempfile.mkstemp(
+        prefix=f".{path.name}.",
+        suffix=".tmp",
+        dir=path.parent,
+        text=True,
+    )
+    temp_path = Path(temp_name)
+    try:
+        with os.fdopen(fd, "w", encoding=encoding, newline=newline) as file:
+            file.write(content)
+            file.flush()
+            os.fsync(file.fileno())
+        if token is not None:
+            token.raise_if_cancelled()
+        if overwrite:
+            os.replace(temp_path, path)
+        else:
+            os.link(temp_path, path)
+            temp_path.unlink(missing_ok=True)
+    except BaseException:
+        try:
+            temp_path.unlink(missing_ok=True)
+        except OSError:
+            pass
+        raise

csvql/benchmark_data.py

@@ -0,0 +1,167 @@
+"""Deterministic synthetic sales-project generation for benchmarking."""
+
+from __future__ import annotations
+
+import random
+from csv import DictWriter
+from dataclasses import dataclass
+from datetime import date, timedelta
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import yaml  # type: ignore[import-untyped]
+
+if TYPE_CHECKING:
+    from csvql.benchmarking import BenchmarkDatasetRecord
+
+CONFIG_TEXT = {
+    "version": 1,
+    "tables": {
+        "customers": {
+            "path": "data/customers.csv",
+            "checks": [
+                {"name": "customer_id_required", "type": "not_null", "column": "customer_id"},
+                {"name": "customer_id_unique", "type": "unique", "column": "customer_id"},
+            ],
+        },
+        "orders": {
+            "path": "data/orders.csv",
+            "checks": [
+                {"name": "order_id_required", "type": "not_null", "column": "order_id"},
+                {"name": "order_id_unique", "type": "unique", "column": "order_id"},
+                {
+                    "name": "customer_exists",
+                    "type": "foreign_key",
+                    "column": "customer_id",
+                    "references": {"table": "customers", "column": "customer_id"},
+                },
+                {
+                    "name": "total_amount_nonnegative",
+                    "type": "min",
+                    "column": "total_amount",
+                    "value": 0,
+                },
+                {"name": "row_count_expected", "type": "row_count_between", "min": 1},
+            ],
+        },
+    },
+}
+
+REVENUE_BY_MONTH_SQL = """SELECT
+    date_trunc('month', order_date) AS order_month,
+    COUNT(*) AS order_count,
+    SUM(total_amount) AS revenue
+FROM orders
+GROUP BY 1
+ORDER BY 1;
+"""
+
+CUSTOMER_LTV_SQL = """SELECT
+    c.customer_id,
+    c.email,
+    COUNT(o.order_id) AS order_count,
+    SUM(o.total_amount) AS lifetime_value
+FROM customers c
+JOIN orders o USING (customer_id)
+GROUP BY c.customer_id, c.email
+ORDER BY lifetime_value DESC;
+"""
+
+
+@dataclass(frozen=True, slots=True)
+class SyntheticSalesSpec:
+    """Deterministic synthetic dataset sizing and seed inputs."""
+
+    dataset_id: str
+    seed: int
+    customer_count: int
+    orders_per_customer: int
+
+
+def write_synthetic_sales_project(root: Path, spec: SyntheticSalesSpec) -> None:
+    """Write a complete benchmark project fixture under ``root``."""
+
+    rng = random.Random(spec.seed)
+    data_dir = root / "data"
+    query_dir = root / "queries"
+    data_dir.mkdir(parents=True, exist_ok=True)
+    query_dir.mkdir(parents=True, exist_ok=True)
+
+    customers_path = data_dir / "customers.csv"
+    orders_path = data_dir / "orders.csv"
+
+    with customers_path.open("w", encoding="utf-8", newline="") as handle:
+        writer = DictWriter(handle, fieldnames=["customer_id", "email", "created_at"])
+        writer.writeheader()
+        for index in range(1, spec.customer_count + 1):
+            writer.writerow(
+                {
+                    "customer_id": f"CUST-{index:05d}",
+                    "email": f"customer{index:05d}@example.com",
+                    "created_at": (date(2025, 1, 1) + timedelta(days=index % 90)).isoformat(),
+                }
+            )
+
+    statuses = ("paid", "pending", "refunded")
+    with orders_path.open("w", encoding="utf-8", newline="") as handle:
+        writer = DictWriter(
+            handle,
+            fieldnames=["order_id", "customer_id", "order_date", "status", "total_amount"],
+        )
+        writer.writeheader()
+        order_index = 1
+        for customer_index in range(1, spec.customer_count + 1):
+            customer_id = f"CUST-{customer_index:05d}"
+            for _ in range(spec.orders_per_customer):
+                writer.writerow(
+                    {
+                        "order_id": f"ORD-{order_index:07d}",
+                        "customer_id": customer_id,
+                        "order_date": (
+                            date(2025, 3, 1) + timedelta(days=order_index % 120)
+                        ).isoformat(),
+                        "status": statuses[order_index % len(statuses)],
+                        "total_amount": f"{rng.uniform(10, 500):.2f}",
+                    }
+                )
+                order_index += 1
+
+    (root / ".csvql.yml").write_text(
+        yaml.safe_dump(CONFIG_TEXT, sort_keys=False),
+        encoding="utf-8",
+    )
+    (query_dir / "revenue_by_month.sql").write_text(REVENUE_BY_MONTH_SQL, encoding="utf-8")
+    (query_dir / "customer_ltv.sql").write_text(CUSTOMER_LTV_SQL, encoding="utf-8")
+
+
+def describe_sales_project(
+    root: Path,
+    *,
+    dataset_id: str,
+    seed: int | None,
+    project_path: str,
+) -> BenchmarkDatasetRecord:
+    """Return row-count and file-size facts for one generated project."""
+
+    from csvql.benchmarking import BenchmarkDatasetRecord
+
+    customers_path = root / "data" / "customers.csv"
+    orders_path = root / "data" / "orders.csv"
+    return BenchmarkDatasetRecord(
+        dataset_id=dataset_id,
+        project_path=project_path,
+        seed=seed,
+        customer_rows=_csv_row_count(customers_path),
+        order_rows=_csv_row_count(orders_path),
+        file_sizes={
+            "data/customers.csv": customers_path.stat().st_size,
+            "data/orders.csv": orders_path.stat().st_size,
+        },
+    )
+
+
+def _csv_row_count(path: Path) -> int:
+    """Return the number of data rows in a CSV file with one header row."""
+
+    with path.open(encoding="utf-8") as handle:
+        return max(sum(1 for _ in handle) - 1, 0)