duckview 0.1.0__py3-none-any.whl

duckview-0.1.0.dist-info/METADATA

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: duckview
+Version: 0.1.0
+Author-email: laq12345 <laq12345@stu.zzu.edu.cn>
+Requires-Python: >=3.11
+Requires-Dist: build<2,>=1.5.0
+Provides-Extra: vd
+Requires-Dist: visidata; extra == 'vd'

duckview-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+dv/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dv/display.py,sha256=IqdAMJNSNj0oljSvrRAkO6pYfACw_cYNGZRwj9WFvek,5502
+dv/main.py,sha256=e-IeXvc8ARkZucsC6IirxzbqqV4x46eqm4TjAxUUlS8,26917
+dv/reader.py,sha256=U7PtrkDViDv35sbPL5ku9-jPyyDMjDtqy7jn59YG2Bg,3184
+dv/utils.py,sha256=pVvAXW3p8y08TItIebRjbCHvNMP8ZvqjcuQ_xqTx-0I,599
+duckview-0.1.0.dist-info/METADATA,sha256=qeEca2JBQNCOh0ZwlqdaJ69zjxrQH2QaJCTL2dtbYcs,214
+duckview-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+duckview-0.1.0.dist-info/entry_points.txt,sha256=83QZEcuNHO-VyYn01932bVLklrdX6utqDgB0Hiq4XMg,40
+duckview-0.1.0.dist-info/RECORD,,

duckview-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

duckview-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dv = dv.main:main_cli

dv/display.py

@@ -0,0 +1,181 @@
+"""Rich-based display functions for dv output."""
+
+from typing import Any
+import duckdb
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from loguru import logger
+
+
+def _create_console() -> Console:
+    """Create a Rich Console instance."""
+    return Console()
+
+
+def _results_to_table(
+    columns: list[str],
+    rows: list[tuple[Any, ...]],
+    title: str = "",
+    column_types: list[str] | None = None,
+) -> Table:
+    """Convert query results to a Rich Table.
+
+    Args:
+        columns: Column names.
+        rows: Row data as tuples.
+        title: Optional table title.
+        column_types: Optional column type strings, shown below column names.
+    """
+    table = Table(title=title, expand=False)
+
+    if column_types and len(column_types) == len(columns):
+        for name, dtype in zip(columns, column_types):
+            header = f"{name}\n[dim italic]{dtype}[/dim italic]"
+            table.add_column(header, overflow="ellipsis", no_wrap=False)
+    else:
+        for col_name in columns:
+            table.add_column(str(col_name), overflow="ellipsis", no_wrap=False)
+
+    for row in rows:
+        table.add_row(*[str(v) if v is not None else "" for v in row])
+
+    return table
+
+
+def display_structure(
+    con: duckdb.DuckDBPyConnection,
+    file_name: str,
+    format_name: str,
+    file_size: str,
+) -> None:
+    """Display file structure overview: columns, types, row count.
+
+    Args:
+        con: Active DuckDB connection with 'data' table registered.
+        file_name: Name of the source file.
+        format_name: Detected format (csv, parquet, etc.).
+        file_size: Human-readable file size string.
+    """
+    console = _create_console()
+
+    # Get column info via DESCRIBE
+    desc_result = con.sql("DESCRIBE SELECT * FROM data").fetchall()
+    # Get row count
+    count_result = con.sql("SELECT COUNT(*) AS cnt FROM data").fetchone()
+    row_count = count_result[0] if count_result else 0
+
+    # Build column info table
+    col_table = Table(expand=False, show_header=True, header_style="bold cyan")
+    col_table.add_column("Column", style="cyan")
+    col_table.add_column("Type")
+    col_table.add_column("Nullable")
+    col_table.add_column("NULLs")
+
+    # Build single null-count query for all columns
+    null_parts = [
+        f"COUNT(CASE WHEN \"{row[0]}\" IS NULL THEN 1 END)" for row in desc_result
+    ]
+    null_counts = con.sql(
+        f"SELECT {', '.join(null_parts)} FROM data"
+    ).fetchone() if null_parts else []
+
+    for i, row in enumerate(desc_result):
+        col_name, col_type, nullable = row[0], row[1], row[2]
+        null_count = null_counts[i] if null_counts else 0
+        null_pct = (null_count / row_count * 100) if row_count > 0 else 0
+        null_str = f"{null_count} ({null_pct:.1f}%)" if null_count > 0 else "0"
+        col_table.add_row(str(col_name), str(col_type), str(nullable), null_str)
+
+    # Summary stats in subtitle
+    col_count = len(desc_result)
+
+    # Build panel
+    panel = Panel(
+        col_table,
+        title=f"[bold]{file_name}[/bold]",
+        subtitle=(
+            f"{format_name.upper()} | {file_size} | "
+            f"{row_count} rows × {col_count} columns"
+        ),
+        border_style="green",
+        expand=False,
+    )
+
+    console.print(panel)
+    logger.debug("Displayed structure: {} cols, {} rows", col_count, row_count)
+
+
+def display_preview(
+    con: duckdb.DuckDBPyConnection,
+    n_rows: int = 10,
+) -> None:
+    """Display first N rows of the registered table.
+
+    Args:
+        con: Active DuckDB connection with 'data' table registered.
+        n_rows: Number of rows to display.
+    """
+    console = _create_console()
+
+    result = con.sql(f"SELECT * FROM data LIMIT {n_rows}")
+    columns = [desc[0] for desc in result.description]
+    types = [desc[1] for desc in result.description]
+    rows = result.fetchall()
+
+    table = _results_to_table(
+        columns, rows,
+        title=f"预览（前 {len(rows)} 行）",
+        column_types=types,
+    )
+    console.print(table)
+    logger.debug("Displayed preview: {} rows", len(rows))
+
+
+def display_stats(con: duckdb.DuckDBPyConnection) -> None:
+    """Display column statistics using DuckDB SUMMARIZE.
+
+    Args:
+        con: Active DuckDB connection with 'data' table registered.
+    """
+    console = _create_console()
+
+    try:
+        result = con.sql("SUMMARIZE SELECT * FROM data")
+    except Exception:
+        # SUMMARIZE may fail for some formats; fall back to DESCRIBE
+        logger.warning("SUMMARIZE not supported; falling back to DESCRIBE")
+        result = con.sql("DESCRIBE SELECT * FROM data")
+
+    columns = [desc[0] for desc in result.description]
+    rows = result.fetchall()
+
+    table = _results_to_table(columns, rows, title="列统计")
+    console.print(table)
+    logger.debug("Displayed stats: {} columns", len(columns))
+
+
+def display_query_result(
+    con: duckdb.DuckDBPyConnection,
+    query: str,
+) -> None:
+    """Execute a SQL query and display results.
+
+    Args:
+        con: Active DuckDB connection.
+        query: SQL query string.
+    """
+    console = _create_console()
+
+    result = con.sql(query)
+    columns = [desc[0] for desc in result.description]
+    types = [desc[1] for desc in result.description]
+    rows = result.fetchall()
+
+    table = _results_to_table(
+        columns, rows,
+        title="查询结果",
+        column_types=types,
+    )
+    console.print(table)
+    logger.debug("Displayed query result: {} rows", len(rows))

dv/main.py

@@ -0,0 +1,747 @@
+"""dv - Terminal data file preview, exploration, and conversion tool."""
+
+import re
+import sys
+from pathlib import Path
+import duckdb
+import typer
+from loguru import logger
+
+from dv.utils import setup_logging
+from dv.reader import register_file, init_excel_support
+from dv.display import (
+    display_structure,
+    display_preview,
+    display_stats,
+    display_query_result,
+)
+
+app = typer.Typer(
+    name="dv",
+    help="在终端快速预览、探查、转换表格数据文件。",
+)
+
+COPY_FORMATS: dict[str, str] = {
+    ".csv": "FORMAT csv, HEADER true",
+    ".tsv": "FORMAT csv, HEADER true, DELIMITER '\\t'",
+    ".txt": "FORMAT csv, HEADER true, DELIMITER '\\t'",
+    ".tab": "FORMAT csv, HEADER true, DELIMITER '\\t'",
+    ".parquet": "FORMAT parquet",
+    ".json": "FORMAT json",
+    ".jsonl": "FORMAT json, ARRAY false",
+    ".xls": "FORMAT xlsx, HEADER true",
+    ".xlsx": "FORMAT xlsx, HEADER true",
+}
+
+FILE_PATH_PATTERN = re.compile(
+    r"""['"]([^'"]+\.(?:csv|tsv|txt|tab|parquet|jsonl?|xlsx?))['"]""",
+    re.IGNORECASE,
+)
+
+VALID_JOIN_HOW = {"inner", "left", "right", "outer"}
+
+
+def _format_size(size_bytes: int) -> str:
+    for unit in ("B", "KB", "MB", "GB"):
+        if size_bytes < 1024:
+            return f"{size_bytes:.1f} {unit}"
+        size_bytes /= 1024
+    return f"{size_bytes:.1f} TB"
+
+
+def _resolve_output(path: str, con: duckdb.DuckDBPyConnection | None = None, force: bool = False) -> tuple[Path, str]:
+    """Validate output path and return (resolved_path, copy_opts_string)."""
+    dst_path = Path(path)
+    dst_ext = dst_path.suffix.lower()
+    copy_opts = COPY_FORMATS.get(dst_ext)
+    if copy_opts is None:
+        logger.error(
+            "Unsupported output format: '{}'. Supported: {}",
+            dst_ext,
+            ", ".join(sorted(COPY_FORMATS.keys())),
+        )
+        raise typer.Exit(code=1)
+    if con and dst_ext in (".xls", ".xlsx"):
+        init_excel_support(con)
+    if dst_path.exists() and not force:
+        response = input(f"Overwrite '{dst_path.name}'? [y/N] ")
+        if response.lower() not in ("y", "yes"):
+            logger.info("Aborted.")
+            raise typer.Exit(code=0)
+    dst_path.parent.mkdir(parents=True, exist_ok=True)
+    return dst_path, copy_opts
+
+
+def _find_and_register_files(con: duckdb.DuckDBPyConnection, query: str) -> None:
+    seen = set()
+    for match in FILE_PATH_PATTERN.finditer(query):
+        file_str = match.group(1)
+        if file_str in seen:
+            continue
+        seen.add(file_str)
+        file_path = Path(file_str)
+        if file_path.exists():
+            table_name = file_path.stem.replace(".", "_")
+            register_file(con, file_path, table_name)
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    verbose: bool = typer.Option(False, "-v", "--verbose", help="启用调试日志"),
+    preview: int = typer.Option(10, "-p", "--preview", help="显示前 N 行"),
+    stats: bool = typer.Option(False, "-s", "--stats", help="显示列统计"),
+    columns: str = typer.Option(None, "-c", "--columns", help="逗号分隔的列名"),
+    sort: str = typer.Option(None, "--sort", help="按列排序（ASC/DESC）"),
+    info: bool = typer.Option(False, "-I", "--info", help="显示结构概览，替代默认预览"),
+):
+    """dv - 终端表格数据工具，基于 DuckDB。
+
+    示例：
+        dv data.csv                 查看文件结构（自动 peek）
+        dv peek data.csv -p 10      显示前 10 行
+        dv convert a.csv b.parquet  CSV 转 Parquet
+        dv sql "FROM 'data.csv' SELECT * LIMIT 5"
+        cat data.csv | dv           管道数据自动预览
+        cat data.csv | dv -p 10     管道 + 预览
+    """
+    setup_logging(verbose)
+    if ctx.invoked_subcommand is None and not sys.stdin.isatty():
+        ctx.invoke(peek, file=None, preview=preview, stats=stats, columns=columns, sort=sort, info=info)
+
+
+@app.command()
+def peek(
+    file: str = typer.Argument(None, help="数据文件路径（省略时从 stdin 读取）"),
+    preview: int = typer.Option(10, "-p", "--preview", help="显示前 N 行"),
+    stats: bool = typer.Option(False, "-s", "--stats", help="显示列统计"),
+    columns: str = typer.Option(None, "-c", "--columns", help="逗号分隔的列名"),
+    sort: str = typer.Option(None, "--sort", help="按列排序（可加 ASC/DESC）"),
+    info: bool = typer.Option(False, "-I", "--info", help="显示结构概览（列名、类型、NULL 数）"),
+):
+    """预览和探查数据文件。
+
+    默认显示前 10 行。用 -I/--info 查看结构概览。
+    用 -p/--preview 指定行数（0 = 显示结构）。
+    用 -s/--stats 查看列统计。
+    用 -c/--columns 选列显示。
+    用 --sort 排序。
+
+    省略文件路径时从 stdin 读取。
+    """
+    import tempfile
+
+    tmp_file = None
+    if file is None:
+        if sys.stdin.isatty():
+            logger.error("No file specified and stdin is a terminal. Pipe data or provide a file.")
+            raise typer.Exit(code=1)
+        data = sys.stdin.buffer.read()
+        tmp_file = tempfile.NamedTemporaryFile(suffix=".csv", delete=False)
+        tmp_file.write(data)
+        tmp_file.close()
+        file_path = Path(tmp_file.name)
+        file_size = _format_size(len(data))
+        display_name = "stdin"
+    else:
+        file_path = Path(file)
+        display_name = file_path.name
+        try:
+            file_size = _format_size(file_path.stat().st_size)
+        except FileNotFoundError:
+            logger.error("File not found: {}", file_path)
+            raise typer.Exit(code=1)
+
+    con = duckdb.connect()
+    try:
+        if preview < 0:
+            logger.error("Preview count must be >= 0, got {}", preview)
+            raise typer.Exit(code=1)
+        fmt = register_file(con, file_path, "_src")
+        if sort or columns:
+            select = "SELECT *" if not columns else f"SELECT {', '.join(c.strip() for c in columns.split(','))}"
+            order = f" ORDER BY {sort}" if sort else ""
+            con.sql(f"CREATE OR REPLACE VIEW data AS {select} FROM _src{order}")
+        else:
+            con.sql("CREATE OR REPLACE VIEW data AS SELECT * FROM _src")
+        if info or preview == 0:
+            display_structure(con, display_name, fmt, file_size)
+        elif stats:
+            display_stats(con)
+        else:
+            display_preview(con, n_rows=preview)
+    except ValueError as e:
+        logger.error(str(e))
+        raise typer.Exit(code=1)
+    except typer.Exit:
+        raise
+    except Exception as e:
+        logger.error("Failed to process file: {}", e)
+        raise typer.Exit(code=1)
+    finally:
+        con.close()
+        if tmp_file:
+            Path(tmp_file.name).unlink(missing_ok=True)
+
+
+@app.command()
+def convert(
+    src: str = typer.Argument(..., help="源文件路径"),
+    dst: str = typer.Argument(..., help="目标文件路径"),
+    where: str = typer.Option(None, "--where", help="SQL 过滤条件（WHERE 子句）"),
+    yes: bool = typer.Option(False, "-y", "--yes", help="跳过覆盖确认"),
+):
+    """转换数据文件格式。
+
+    输出格式由目标文件扩展名自动推断。
+    支持的格式：.csv、.tsv、.parquet、.json、.jsonl、.xlsx
+    """
+    src_path = Path(src)
+
+    if not src_path.exists():
+        logger.error("Source file not found: {}", src_path)
+        raise typer.Exit(code=1)
+
+    con = duckdb.connect()
+    try:
+        dst_path, copy_opts = _resolve_output(dst, con, force=yes)
+        register_file(con, src_path)
+        dst_abs = str(dst_path.resolve())
+        query = (
+            f"COPY (SELECT * FROM data WHERE {where}) TO '{dst_abs}' ({copy_opts})"
+            if where
+            else f"COPY (SELECT * FROM data) TO '{dst_abs}' ({copy_opts})"
+        )
+        con.sql(query)
+        logger.info("Converted {} -> {}", src_path.name, dst_path.name)
+    except typer.Exit:
+        raise
+    except Exception as e:
+        logger.error("Conversion failed: {}", e)
+        raise typer.Exit(code=1)
+    finally:
+        con.close()
+
+
+@app.command()
+def sql(
+    query: str = typer.Argument(
+        ..., help="SQL 查询语句（用单引号引用文件路径）"
+    ),
+    output: str = typer.Option(
+        None, "-o", "--output", help="保存结果到文件（格式由扩展名推断）"
+    ),
+    yes: bool = typer.Option(False, "-y", "--yes", help="跳过覆盖确认"),
+):
+    """对数据文件执行 SQL 查询。
+
+    查询中引用的文件（如 'data.csv'）会自动注册为临时表。
+
+    不加 -o 时显示结果，加 -o 时保存到文件。
+
+    示例：
+        dv sql "FROM 'data.csv' SELECT * WHERE age > 30"
+        dv sql "SELECT * FROM 'data.csv'" -o result.parquet
+    """
+    con = duckdb.connect()
+    tmp_path = None
+    try:
+        if not sys.stdin.isatty():
+            data = sys.stdin.buffer.read()
+            if data:
+                import tempfile
+                tmp = tempfile.NamedTemporaryFile(suffix=".csv", delete=False)
+                tmp.write(data)
+                tmp.close()
+                tmp_path = tmp.name
+                register_file(con, Path(tmp_path), "stdin")
+        _find_and_register_files(con, query)
+        if output:
+            dst_path, copy_opts = _resolve_output(output, con, force=yes)
+            dst_abs = str(dst_path.resolve())
+            con.sql(f"CREATE OR REPLACE TABLE _copy_tmp AS {query}")
+            con.sql(f"COPY (SELECT * FROM _copy_tmp) TO '{dst_abs}' ({copy_opts})")
+            con.sql("DROP TABLE IF EXISTS _copy_tmp")
+            logger.info("Saved to {}", dst_path.name)
+        else:
+            display_query_result(con, query)
+    except typer.Exit:
+        raise
+    except Exception as e:
+        logger.error("SQL execution failed: {}", e)
+        raise typer.Exit(code=1)
+    finally:
+        con.close()
+        if tmp_path:
+            Path(tmp_path).unlink(missing_ok=True)
+
+
+@app.command()
+def cat(
+    files: list[str] = typer.Argument(..., help="待拼接的文件路径（至少 2 个）"),
+    preview: int = typer.Option(10, "-p", "--preview", help="显示前 N 行"),
+    stats: bool = typer.Option(False, "-s", "--stats", help="显示列统计"),
+    output: str = typer.Option(
+        None, "-o", "--output", help="保存到文件（格式由扩展名推断）"
+    ),
+    yes: bool = typer.Option(False, "-y", "--yes", help="跳过覆盖确认"),
+):
+    """按行拼接多个数据文件（UNION ALL BY NAME）。
+
+    按列名自动对齐，各文件列数不同时缺失列自动填 NULL。
+
+    示例：
+        dv cat a.csv b.csv               拼接并预览结构
+        dv cat a.csv b.csv -p 10         拼接后预览 10 行
+        dv cat part*.csv -o merged.parquet
+    """
+    if len(files) < 2:
+        logger.error("Need at least 2 files to concatenate, got {}", len(files))
+        raise typer.Exit(code=1)
+
+    con = duckdb.connect()
+    try:
+        if preview < 0:
+            logger.error("Preview count must be >= 0, got {}", preview)
+            raise typer.Exit(code=1)
+        for i, f in enumerate(files):
+            fp = Path(f)
+            if not fp.exists():
+                logger.error("File not found: {}", fp)
+                raise typer.Exit(code=1)
+            register_file(con, fp, f"src_{i}")
+
+        unions = "\n  UNION ALL BY NAME\n".join(
+            f"SELECT * FROM src_{i}" for i in range(len(files))
+        )
+        con.sql(f"CREATE OR REPLACE VIEW data AS {unions}")
+
+        first_name = Path(files[0]).name
+        total_size = _format_size(sum(Path(f).stat().st_size for f in files))
+
+        if output:
+            dst_path, copy_opts = _resolve_output(output, con, force=yes)
+            dst_abs = str(dst_path.resolve())
+            con.sql(f"COPY (SELECT * FROM data) TO '{dst_abs}' ({copy_opts})")
+            logger.info("Saved to {}", dst_path.name)
+        elif preview == 0:
+            count = con.sql("SELECT COUNT(*) FROM data").fetchone()[0]
+            display_structure(
+                con, f"{first_name} + {len(files) - 1} more", "CONCAT", total_size
+            )
+            logger.debug("Concatenated {} files: {} rows", len(files), count)
+        elif stats:
+            display_stats(con)
+        else:
+            display_preview(con, n_rows=preview)
+    except typer.Exit:
+        raise
+    except Exception as e:
+        logger.error("Concatenation failed: {}", e)
+        raise typer.Exit(code=1)
+    finally:
+        con.close()
+
+
+@app.command()
+def join(
+    a: str = typer.Argument(..., help="左表文件路径"),
+    b: str = typer.Argument(..., help="右表文件路径"),
+    on: str = typer.Option(
+        None, "--on", help="JOIN 列名。同名列用 'gene'；不同名用 'probe=gene'。省略时自动检测。"
+    ),
+    how: str = typer.Option(
+        "inner", "--how", help="JOIN 方式：inner、left、right、outer"
+    ),
+    preview: int = typer.Option(10, "-p", "--preview", help="显示前 N 行"),
+    stats: bool = typer.Option(False, "-s", "--stats", help="显示列统计"),
+    output: str = typer.Option(
+        None, "-o", "--output", help="保存到文件（格式由扩展名推断）"
+    ),
+    yes: bool = typer.Option(False, "-y", "--yes", help="跳过覆盖确认"),
+):
+    """按公共列合并两个数据文件。
+
+    不指定 --on 时自动检测唯一共有列。
+    用 --how 选择合并方式（默认 inner）。
+
+    示例：
+        dv join deg.csv meta.csv                    自动检测合并列
+        dv join deg.csv meta.csv --on gene          同名列合并
+        dv join expr.csv meta.csv --on probe=gene   不同名列合并
+        dv join a.csv b.csv --on id --how left -o joined.parquet
+    """
+    a_path, b_path = Path(a), Path(b)
+
+    for p, label in [(a_path, "Left"), (b_path, "Right")]:
+        if not p.exists():
+            logger.error("{} file not found: {}", label, p)
+            raise typer.Exit(code=1)
+
+    how_lower = how.lower()
+    if how_lower not in VALID_JOIN_HOW:
+        logger.error(
+            "Invalid --how '{}'. Must be one of: {}",
+            how,
+            ", ".join(sorted(VALID_JOIN_HOW)),
+        )
+        raise typer.Exit(code=1)
+
+    how_sql = {"inner": "INNER", "left": "LEFT", "right": "RIGHT", "outer": "FULL"}[how_lower]
+
+    con = duckdb.connect()
+    try:
+        if preview < 0:
+            logger.error("Preview count must be >= 0, got {}", preview)
+            raise typer.Exit(code=1)
+        register_file(con, a_path, "a")
+        register_file(con, b_path, "b")
+
+        on_clause = _resolve_join_on(con, on)
+        a_cols = _get_column_names(con, "a")
+        b_cols = _get_column_names(con, "b")
+        join_col_raw = _get_join_column(on, a_cols, b_cols)
+
+        # Build explicit column list to avoid duplicate column errors
+        def _q(col, tbl):
+            """Quote col with tbl prefix, handling special chars."""
+            c = f'"{col}"' if "." in col else col
+            return f"{tbl}.{c}"
+
+        select_cols = [_q(c, "a") for c in a_cols]
+        for c in b_cols:
+            if c != join_col_raw:
+                select_cols.append(f"{_q(c, 'b')} AS \"{c}_2\"" if c in a_cols else _q(c, "b"))
+
+        col_list = ", ".join(select_cols)
+        con.sql(
+            f"CREATE OR REPLACE VIEW data AS "
+            f"SELECT {col_list} FROM a {how_sql} JOIN b {on_clause}"
+        )
+
+        total_size = _format_size(a_path.stat().st_size + b_path.stat().st_size)
+        count = con.sql("SELECT COUNT(*) FROM data").fetchone()[0]
+
+        if output:
+            dst_path, copy_opts = _resolve_output(output, con, force=yes)
+            dst_abs = str(dst_path.resolve())
+            con.sql(f"COPY (SELECT * FROM data) TO '{dst_abs}' ({copy_opts})")
+            logger.info("Saved to {}", dst_path.name)
+        elif preview == 0:
+            display_structure(
+                con,
+                f"{a_path.name} ⋈ {b_path.name}",
+                f"JOIN ({how_lower})",
+                total_size,
+            )
+            logger.debug("Joined: {} rows ({} JOIN)", count, how_lower)
+        elif stats:
+            display_stats(con)
+        else:
+            display_preview(con, n_rows=preview)
+    except typer.Exit:
+        raise
+    except Exception as e:
+        logger.error("Join failed: {}", e)
+        raise typer.Exit(code=1)
+    finally:
+        con.close()
+
+
+@app.command()
+def search(
+    pattern: str = typer.Argument(..., help="正则表达式"),
+    file: str = typer.Argument(..., help="数据文件路径"),
+    column: str = typer.Option(None, "--in", help="限定搜索某一列"),
+    ignore_case: bool = typer.Option(False, "-i", "--ignore-case", help="忽略大小写"),
+    literal: bool = typer.Option(False, "-l", "--literal", help="字面量搜索（非正则）"),
+    preview: int = typer.Option(10, "-p", "--preview", help="显示前 N 条匹配行"),
+    output: str = typer.Option(None, "-o", "--output", help="保存结果到文件"),
+    yes: bool = typer.Option(False, "-y", "--yes", help="跳过覆盖确认"),
+):
+    """正则搜索数据行。
+
+    搜索所有文本列，除非用 --in 指定某列。
+    用 -i 忽略大小写。
+
+    示例：
+        dv search "TP53" data.csv
+        dv search "TP53|BRCA1" data.csv --in gene -i
+    """
+    file_path = Path(file)
+    if not file_path.exists():
+        logger.error("File not found: {}", file_path)
+        raise typer.Exit(code=1)
+
+    con = duckdb.connect()
+    try:
+        if preview < 0:
+            logger.error("Preview count must be >= 0, got {}", preview)
+            raise typer.Exit(code=1)
+        register_file(con, file_path, "_src")
+        flags = "'i'" if ignore_case else ""
+        safe_pattern = pattern.replace("'", "''")
+        if literal:
+            safe_pattern = re.escape(safe_pattern)
+        col_info = con.sql("DESCRIBE SELECT * FROM _src").fetchall()
+        col_names = [r[0] for r in col_info]
+        col_types = [r[1] for r in col_info]
+
+        if column:
+            if column not in col_names:
+                logger.error("Column '{}' not found. Available: {}", column, ", ".join(col_names))
+                raise typer.Exit(code=1)
+            col_type = col_types[col_names.index(column)]
+            if "VARCHAR" not in str(col_type).upper():
+                logger.error(
+                    "Column '{}' is type {}, not text — cannot regex search.",
+                    column, col_type
+                )
+                raise typer.Exit(code=1)
+            where = f"WHERE regexp_matches(\"{column}\", '{safe_pattern}'{',' + flags if flags else ''})"
+        else:
+            str_cols = [c for c, t in zip(col_names, col_types) if "VARCHAR" in str(t).upper()]
+            if not str_cols:
+                logger.error("No text columns found to search in.")
+                raise typer.Exit(code=1)
+            conditions = " OR ".join(
+                f"regexp_matches(\"{c}\", '{safe_pattern}'{',' + flags if flags else ''})"
+                for c in str_cols
+            )
+            where = f"WHERE {conditions}"
+
+        con.sql(f"CREATE OR REPLACE VIEW data AS SELECT * FROM _src {where}")
+
+        if output:
+            dst_path, copy_opts = _resolve_output(output, con, force=yes)
+            dst_abs = str(dst_path.resolve())
+            con.sql(f"COPY (SELECT * FROM data) TO '{dst_abs}' ({copy_opts})")
+            logger.info("Saved to {}", dst_path.name)
+        elif preview > 0:
+            display_preview(con, n_rows=preview)
+        else:
+            display_structure(con, file_path.name, "FILTERED", _format_size(file_path.stat().st_size))
+    except typer.Exit:
+        raise
+    except Exception as e:
+        logger.error("Search failed: {}", e)
+        raise typer.Exit(code=1)
+    finally:
+        con.close()
+
+
+@app.command()
+def rename(
+    file: str = typer.Argument(..., help="数据文件路径"),
+    mapping: str = typer.Argument(..., help="重命名规则：old=new 或 old1=new1,old2=new2"),
+    output: str = typer.Option(None, "-o", "--output", help="保存到文件"),
+    info: bool = typer.Option(False, "-I", "--info", help="显示结构概览，替代默认预览"),
+    yes: bool = typer.Option(False, "-y", "--yes", help="跳过覆盖确认"),
+):
+    """重命名数据文件中的列名。
+
+    示例：
+        dv rename data.csv column0=gene
+        dv rename data.csv "id=gene_id,name=symbol"
+        dv rename data.csv p_val_adj=padj -o cleaned.csv
+    """
+    file_path = Path(file)
+    if not file_path.exists():
+        logger.error("File not found: {}", file_path)
+        raise typer.Exit(code=1)
+
+    pairs = []
+    for part in mapping.split(","):
+        if "=" not in part:
+            logger.error("Invalid mapping '{}'. Use old=new format.", part.strip())
+            raise typer.Exit(code=1)
+        old, new = part.split("=", 1)
+        pairs.append((old.strip(), new.strip()))
+
+    con = duckdb.connect()
+    try:
+        fmt = register_file(con, file_path, "_src")
+        col_names = [r[0] for r in con.sql("DESCRIBE SELECT * FROM _src").fetchall()]
+
+        select_parts = []
+        for old, new in pairs:
+            if old not in col_names:
+                logger.error("Column '{}' not found. Available: {}", old, ", ".join(col_names))
+                raise typer.Exit(code=1)
+            select_parts.append(f'"{old}" AS "{new}"')
+
+        renamed = set(old for old, _ in pairs)
+        for c in col_names:
+            if c not in renamed:
+                select_parts.append(f'"{c}"')
+
+        select_str = ", ".join(select_parts)
+        con.sql(f"CREATE OR REPLACE VIEW data AS SELECT {select_str} FROM _src")
+
+        if output:
+            dst_path, copy_opts = _resolve_output(output, con, force=yes)
+            dst_abs = str(dst_path.resolve())
+            con.sql(f"COPY (SELECT * FROM data) TO '{dst_abs}' ({copy_opts})")
+            logger.info("Saved to {}", dst_path.name)
+        else:
+            display_structure(con, file_path.name, fmt.upper(), _format_size(file_path.stat().st_size))
+    except typer.Exit:
+        raise
+    except Exception as e:
+        logger.error("Rename failed: {}", e)
+        raise typer.Exit(code=1)
+    finally:
+        con.close()
+
+
+@app.command()
+def vd(
+    file: str = typer.Argument(..., help="数据文件路径"),
+    where: str = typer.Option(None, "--where", help="过滤条件"),
+    columns: str = typer.Option(None, "-c", "--columns", help="逗号分隔的列名"),
+    sort: str = typer.Option(None, "--sort", help="排序列（ASC/DESC）"),
+    preview: int = typer.Option(0, "-p", "--preview", help="限制行数，0=不限"),
+):
+    """用 VisiData 交互式探索数据文件。
+
+    可先用 --where/-c/--sort/-p 过滤数据，再自动打开 VisiData。
+    """
+    import shutil
+    import subprocess
+    import tempfile
+
+    if not shutil.which("vd"):
+        logger.error("vd not found. Install: pip install \"dv[vd]\" or pip install visidata")
+        raise typer.Exit(code=1)
+
+    file_path = Path(file)
+    if not file_path.exists():
+        logger.error("File not found: {}", file_path)
+        raise typer.Exit(code=1)
+
+    # 无过滤参数：直接打开
+    if not (where or columns or sort or preview):
+        subprocess.run(["vd", str(file_path)])
+        return
+
+    # 有过滤参数：DuckDB 过滤 → 临时文件 → vd
+    con = duckdb.connect()
+    tmp_path = None
+    try:
+        register_file(con, file_path, "_src")
+
+        select = "SELECT *"
+        if columns:
+            col_list = ", ".join(c.strip() for c in columns.split(","))
+            select = f"SELECT {col_list}"
+
+        clauses = []
+        if where:
+            clauses.append(f"WHERE {where}")
+        if sort:
+            clauses.append(f"ORDER BY {sort}")
+        if preview > 0:
+            clauses.append(f"LIMIT {preview}")
+
+        sql = f"{select} FROM _src {' '.join(clauses)}"
+        tmp = tempfile.NamedTemporaryFile(suffix=".csv", delete=False)
+        tmp.close()
+        tmp_path = tmp.name
+        con.sql(f"COPY ({sql}) TO '{tmp_path}' (FORMAT csv, HEADER true)")
+        subprocess.run(["vd", tmp_path])
+    except typer.Exit:
+        raise
+    except Exception as e:
+        logger.error("vd open failed: {}", e)
+        raise typer.Exit(code=1)
+    finally:
+        con.close()
+        if tmp_path:
+            Path(tmp_path).unlink(missing_ok=True)
+
+
+def _get_column_names(con: duckdb.DuckDBPyConnection, table: str) -> list[str]:
+    return [
+        r[0]
+        for r in con.sql(
+            f"SELECT column_name FROM information_schema.columns WHERE table_name='{table}'"
+        ).fetchall()
+    ]
+
+
+def _get_join_column(on: str | None, a_cols: list[str], b_cols: list[str]) -> str | None:
+    if on is None:
+        common = sorted(set(a_cols) & set(b_cols))
+        return common[0] if len(common) == 1 else None
+    if "=" in on:
+        return on.split("=", 1)[0].strip()
+    return on
+
+
+def _resolve_join_on(con: duckdb.DuckDBPyConnection, on: str | None) -> str:
+    """Resolve the ON/USING clause for a JOIN.
+
+    Returns a SQL fragment like 'USING ("col.1")' or 'ON a."col.1" = b."gene"'.
+    """
+    def qc(col: str) -> str:
+        return f'"{col}"' if "." in col else col
+
+    if on is not None and "=" in on:
+        parts = on.split("=", 1)
+        left_col, right_col = parts[0].strip(), parts[1].strip()
+        return f"ON a.{qc(left_col)} = b.{qc(right_col)}"
+
+    if on is not None:
+        return f"USING ({qc(on)})"
+
+    a_cols = {
+        r[0]
+        for r in con.sql(
+            "SELECT column_name FROM information_schema.columns WHERE table_name='a'"
+        ).fetchall()
+    }
+    b_cols = {
+        r[0]
+        for r in con.sql(
+            "SELECT column_name FROM information_schema.columns WHERE table_name='b'"
+        ).fetchall()
+    }
+    common = sorted(a_cols & b_cols)
+
+    if len(common) == 0:
+        logger.error("No common columns found between the two files. Use --on to specify the join columns.")
+        raise typer.Exit(code=1)
+    if len(common) == 1:
+        return f"USING ({qc(common[0])})"
+
+    logger.error(
+        "Multiple common columns found: {}. Use --on to specify which one to join on.",
+        ", ".join(common),
+    )
+    raise typer.Exit(code=1)
+
+
+def _patch_default_peek():
+    """If the first non-flag argument looks like a file path, insert 'peek' at position 1."""
+    known = {
+        "peek", "convert", "sql", "cat", "join", "search", "rename", "vd",
+        "--help", "-h", "--show-completion", "--install-completion",
+    }
+    if any(a in known for a in sys.argv[1:]):
+        return
+    for i, arg in enumerate(sys.argv[1:], start=1):
+        if arg.startswith("-") or "=" in arg:
+            continue
+        if "/" in arg or "\\" in arg or "." in arg:
+            sys.argv.insert(1, "peek")
+            return
+
+
+def main_cli():
+    """Entry point for console_scripts and __main__."""
+    _patch_default_peek()
+    app()
+
+
+if __name__ == "__main__":
+    main_cli()

dv/reader.py

@@ -0,0 +1,110 @@
+"""Format detection and DuckDB file registration for dv."""
+
+from pathlib import Path
+import duckdb
+from loguru import logger
+
+
+# Extension -> format name mapping for DuckDB read functions
+FORMAT_MAP: dict[str, str] = {
+    ".csv": "csv",
+    ".tsv": "tsv",
+    ".txt": "tsv",
+    ".tab": "tsv",
+    ".parquet": "parquet",
+    ".json": "json",
+    ".jsonl": "json",
+    ".xlsx": "excel",
+    ".xls": "excel",
+}
+
+# Extension -> SQL read function template
+READ_SQL_TEMPLATES: dict[str, str] = {
+    "csv": "read_csv_auto('{path}')",
+    "tsv": "read_csv_auto('{path}')",
+    "parquet": "read_parquet('{path}')",
+    "json": "read_json_auto('{path}')",
+}
+
+
+def detect_format(file_path: Path) -> str:
+    """Detect data format from file extension.
+
+    Args:
+        file_path: Path to the data file.
+
+    Returns:
+        Format name string (e.g. 'csv', 'parquet', 'excel').
+
+    Raises:
+        ValueError: If the file extension is not supported.
+    """
+    ext = file_path.suffix.lower()
+    if not ext:
+        raise ValueError(
+            f"Cannot detect format: '{file_path}' has no file extension. "
+            f"Supported extensions: {', '.join(sorted(set(FORMAT_MAP.values())))}\n"
+            f"Supported file types: {', '.join(sorted(FORMAT_MAP.keys()))}"
+        )
+
+    fmt = FORMAT_MAP.get(ext)
+    if fmt is None:
+        raise ValueError(
+            f"Unsupported file format: '{ext}'. "
+            f"Supported extensions: {', '.join(sorted(FORMAT_MAP.keys()))}"
+        )
+    return fmt
+
+
+def init_excel_support(con: duckdb.DuckDBPyConnection) -> None:
+    """Install and load DuckDB excel and spatial extensions."""
+    for ext in ("excel", "spatial"):
+        try:
+            con.sql(f"LOAD {ext}")
+        except Exception:
+            logger.debug("Installing {} extension...", ext)
+            con.sql(f"INSTALL {ext}")
+            con.sql(f"LOAD {ext}")
+            logger.debug("{} extension installed and loaded", ext)
+
+
+def register_file(
+    con: duckdb.DuckDBPyConnection,
+    file_path: Path,
+    table_name: str = "data",
+) -> str:
+    """Register a data file as a DuckDB view.
+
+    Args:
+        con: Active DuckDB connection.
+        file_path: Path to the data file.
+        table_name: Name for the registered view (default: 'data').
+
+    Returns:
+        The format name used to read the file.
+
+    Raises:
+        FileNotFoundError: If the file does not exist.
+        ValueError: If the format is not supported.
+    """
+    if not file_path.exists():
+        raise FileNotFoundError(f"File not found: {file_path}")
+
+    fmt = detect_format(file_path)
+    path_str = str(file_path.resolve())
+    logger.debug("Registering {} as format={} table={}", path_str, fmt, table_name)
+
+    if fmt == "excel":
+        init_excel_support(con)
+        con.sql(
+            f"CREATE OR REPLACE VIEW {table_name} AS "
+            f"SELECT * FROM st_read('{path_str}')"
+        )
+    else:
+        read_fn = READ_SQL_TEMPLATES[fmt].format(path=path_str)
+        con.sql(f"CREATE OR REPLACE VIEW {table_name} AS SELECT * FROM {read_fn}")
+
+    logger.info(
+        "Registered '{}' as table '{}' (format: {})", file_path.name, table_name, fmt
+    )
+    return fmt

dv/utils.py

@@ -0,0 +1,24 @@
+"""Logging and utility functions for dv."""
+
+import sys
+from loguru import logger
+
+
+def setup_logging(verbose: bool = False) -> None:
+    """Configure loguru logging.
+
+    Args:
+        verbose: If True, set log level to DEBUG. Otherwise WARNING.
+    """
+    logger.remove()
+    level = "DEBUG" if verbose else "WARNING"
+    logger.add(
+        sys.stderr,
+        level=level,
+        format=(
+            "<level>{level: <8}</level> | "
+            "<cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - "
+            "<level>{message}</level>"
+        ),
+        colorize=True,
+    )