tab-cli 0.1.1__py3-none-any.whl

tab_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Tab CLI - A CLI tool for tabular data."""
+
+__version__ = "0.1.0"

tab_cli/cli.py

@@ -0,0 +1,171 @@
+"""Main CLI entry point using Typer."""
+
+import sys
+from typing import Annotated, Optional
+
+from loguru import logger
+import polars as pl
+import typer
+from rich.console import Console
+from rich.logging import RichHandler
+
+from tab_cli import config
+from tab_cli.handlers import TableWriter, infer_reader, infer_writer
+
+app = typer.Typer(
+    help="A CLI tool for viewing and manipulating tabular data.",
+    no_args_is_help=True,
+)
+
+
+@app.callback()
+def main_callback(
+    az_url_authority_is_account: Annotated[
+        bool,
+        typer.Option(
+            "--az-url-authority-is-account",
+            help="Interpret az:// URL authority as storage account name instead of container name",
+        ),
+    ] = False,
+    log_level: Annotated[
+        str,
+        typer.Option("--log-level", help="Log level from {DEBUG, INFO, WARNING, ERROR, CRITICAL}"),
+    ] = "INFO",
+) -> None:
+    """Global options for tab_cli CLI."""
+    config.config.az_url_authority_is_account = az_url_authority_is_account
+    logger.remove()
+    logger.add(
+        RichHandler(
+            rich_tracebacks=True,
+            tracebacks_show_locals=True,
+            markup=True,
+        ),
+        format="{message}",
+        level=log_level.upper(),
+    )
+
+
+def _output(
+    lf: pl.LazyFrame,
+    limit: int | None,
+    skip: int,
+    output: str | None,
+) -> None:
+    show_truncation = limit is None and output is None
+    actual_limit = 20 if show_truncation else limit
+
+    if show_truncation:
+        assert actual_limit is not None
+        lf = lf.slice(skip, length=actual_limit + 1)
+        df = lf.collect()
+        truncated = len(df) > actual_limit
+        if truncated:
+            df = df.head(actual_limit)
+        lf = df.lazy()
+    else:
+        if skip > 0 or actual_limit is not None:
+            lf = lf.slice(skip, length=actual_limit)
+        truncated = False
+
+    writer = infer_writer(output, truncated=show_truncation and truncated)
+
+    for chunk in writer.write(lf):
+        sys.stdout.buffer.write(chunk)
+
+
+@app.command()
+def view(
+    path: Annotated[str, typer.Argument(help="Path to the data file or directory")],
+    limit: Annotated[Optional[int], typer.Option("--limit", help="Maximum number of rows to display")] = None,
+    skip: Annotated[int, typer.Option("--skip", help="Number of rows to skip")] = 0,
+    input: Annotated[Optional[str], typer.Option("-i", "--input-format", help="Input format")] = None,
+    output: Annotated[Optional[str], typer.Option("-o", "--output-format", help="Output format")] = None,
+) -> None:
+    """View tabular data from a file."""
+    reader = infer_reader(path, format=input)
+    lf = reader.read(path)
+    _output(lf, limit=limit, skip=skip, output=output)
+
+@app.command()
+def schema(
+    path: Annotated[str, typer.Argument(help="Path to the data file or directory")],
+    input: Annotated[Optional[str], typer.Option("-i", "--input-format", help="Input format")] = None,
+) -> None:
+    """Display the schema of a tabular data file."""
+    reader = infer_reader(path, format=input)
+    table_schema = reader.schema(path)
+    console = Console(force_terminal=True)
+    console.print(table_schema)
+
+
+@app.command()
+def sql(
+    query: Annotated[str, typer.Argument(help="SQL query to execute (table is available as 't')")],
+    path: Annotated[str, typer.Argument(help="Path to the data file or directory")],
+    limit: Annotated[Optional[int], typer.Option("--limit", help="Maximum number of rows to display")] = None,
+    skip: Annotated[int, typer.Option("--skip", help="Number of rows to skip")] = 0,
+    input: Annotated[Optional[str], typer.Option("-i", "--input-format", help="Input format")] = None,
+    output: Annotated[Optional[str], typer.Option("-o", "--output-format", help="Output format")] = None,
+) -> None:
+    """Run a SQL query on tabular data. The table is available as 't'."""
+    reader = infer_reader(path, format=input)
+    lf = reader.read(path)
+    ctx = pl.SQLContext(t=lf, eager=False)
+    result_lf = ctx.execute(query)
+    _output(result_lf, limit=limit, skip=skip, output=output)
+
+
+@app.command()
+def summary(
+    path: Annotated[str, typer.Argument(help="Path to the data file or directory")],
+    input: Annotated[Optional[str], typer.Option("-i", "--input-format", help="Input format")] = None,
+) -> None:
+    """Display summary information about a tabular data file."""
+    handler = infer_reader(path, format=input)
+    table_summary = handler.summary(path)
+    console = Console(force_terminal=True)
+    console.print(table_summary)
+
+
+@app.command()
+def convert(
+    src: Annotated[str, typer.Argument(help="Path to the source file or directory")],
+    dst: Annotated[str, typer.Argument(help="Path to the destination file or directory")],
+    input: Annotated[Optional[str], typer.Option("-i", "--input-format", help="Input format")] = None,
+    output: Annotated[Optional[str], typer.Option("-o", "--output-format", help="Output format")] = None,
+    num_partitions: Annotated[Optional[int], typer.Option("-n", "--num-partitions", help="Number of output partitions")] = None,
+) -> None:
+    """Convert tabular data from one format to another."""
+    reader = infer_reader(src, format=input)
+    # Determine output format: use -o if specified, else inherit from input
+    if output is not None:
+        writer = infer_writer(format=output)
+    elif input is not None:
+        writer = infer_writer(format=input)
+    else:
+        writer = reader
+        assert isinstance(writer, TableWriter)
+    lf = reader.read(src)
+    writer.write_to_path(lf, dst, partitions=num_partitions)
+
+
+@app.command()
+def cat(
+    paths: Annotated[list[str], typer.Argument(help="Paths to the data files or directories")],
+    input: Annotated[Optional[str], typer.Option("-i", "--input-format", help="Input format")] = None,
+    output: Annotated[Optional[str], typer.Option("-o", "--output-format", help="Output format")] = None,
+) -> None:
+    """Concatenate tabular data from multiple files."""
+    reader = infer_reader(paths[0], format=input)
+    files = [reader.read(path) for path in paths]
+    lf = pl.concat(files, how="vertical")
+    _output(lf, limit=None, skip=0, output=output)
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

tab_cli/config.py

@@ -0,0 +1,14 @@
+"""Global configuration for tab_cli-cli."""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Config:
+    """Global configuration settings."""
+
+    az_url_authority_is_account: bool = False
+
+
+# Global config instance
+config: Config = Config()

tab_cli/formats/__init__.py

@@ -0,0 +1,15 @@
+"""Format handlers for reading and writing tabular data."""
+
+from tab_cli.formats.base import FormatHandler
+from tab_cli.formats.avro import AvroFormat
+from tab_cli.formats.csv import CsvFormat
+from tab_cli.formats.jsonl import JsonlFormat
+from tab_cli.formats.parquet import ParquetFormat
+
+__all__ = [
+    "FormatHandler",
+    "AvroFormat",
+    "CsvFormat",
+    "JsonlFormat",
+    "ParquetFormat",
+]

tab_cli/formats/avro.py

@@ -0,0 +1,47 @@
+"""Avro format handler using polars-fastavro."""
+
+from collections.abc import Iterable
+from io import BytesIO
+from typing import BinaryIO
+
+import polars as pl
+import polars_fastavro
+
+from tab_cli.formats.base import FormatHandler
+
+
+class AvroFormat(FormatHandler):
+    """Handler for Avro files."""
+
+    def extension(self) -> str:
+        return ".avro"
+
+    def supports_glob(self) -> bool:
+        # polars_fastavro doesn't support glob patterns
+        return False
+
+    def scan(self, url: str, storage_options: dict[str, str] | None = None) -> pl.LazyFrame:
+        # polars_fastavro doesn't support storage_options, so cloud URIs
+        # need to be accessed through fsspec first
+        return polars_fastavro.scan_avro(url)
+
+    def read_stream(self, stream: BinaryIO) -> pl.DataFrame:
+        return polars_fastavro.read_avro(stream)
+
+    def collect_schema(self, url: str, storage_options: dict[str, str] | None = None) -> list[tuple[str, pl.DataType]]:
+        # polars_fastavro doesn't support storage_options
+        return list(polars_fastavro.scan_avro(url).collect_schema().items())
+
+    def count_rows(self, url: str, storage_options: dict[str, str] | None = None) -> int:
+        # polars_fastavro doesn't support storage_options
+        return polars_fastavro.scan_avro(url).select(pl.len()).collect().item()
+
+    def write(self, lf: pl.LazyFrame) -> Iterable[bytes]:
+        output = BytesIO()
+        df = lf.collect()
+        polars_fastavro.write_avro(df, output)
+        yield output.getvalue()
+
+    def write_to_single_file(self, lf: pl.LazyFrame, path: str) -> None:
+        df = lf.collect()
+        polars_fastavro.write_avro(df, path)

tab_cli/formats/base.py

@@ -0,0 +1,63 @@
+"""Base format handler interface."""
+
+from abc import ABC, abstractmethod
+from collections.abc import Iterable
+from typing import BinaryIO
+
+import polars as pl
+
+
+class FormatHandler(ABC):
+    """Handles reading and writing a specific tabular format."""
+
+    @abstractmethod
+    def extension(self) -> str:
+        """Return the file extension (e.g., '.parquet')."""
+        pass
+
+    def supports_glob(self) -> bool:
+        """Whether this format supports glob patterns in scan().
+
+        Formats with native Polars support (Parquet, CSV, JSONL) can scan
+        directories directly. Others (Avro) need manual file iteration.
+        """
+        return False
+
+    @abstractmethod
+    def scan(self, url: str, storage_options: dict[str, str] | None = None) -> pl.LazyFrame:
+        """Scan from a URL (local path or cloud URL).
+
+        Args:
+            url: The URL to scan from.
+            storage_options: Optional storage options for cloud access.
+        """
+        pass
+
+    @abstractmethod
+    def read_stream(self, stream: BinaryIO) -> pl.DataFrame:
+        """Read from a byte stream. Returns eager DataFrame."""
+        pass
+
+    @abstractmethod
+    def collect_schema(self, url: str, storage_options: dict[str, str] | None = None) -> list[tuple[str, pl.DataType]]:
+        """Get schema as list of (name, dtype) tuples."""
+        pass
+
+    @abstractmethod
+    def count_rows(self, url: str, storage_options: dict[str, str] | None = None) -> int:
+        """Count rows in the file."""
+        pass
+
+    def extra_summary(self, url: str) -> dict[str, str | int | float] | None:
+        """Return format-specific summary metadata, if any."""
+        return None
+
+    @abstractmethod
+    def write(self, lf: pl.LazyFrame) -> Iterable[bytes]:
+        """Write LazyFrame to bytes (for streaming output)."""
+        pass
+
+    @abstractmethod
+    def write_to_single_file(self, lf: pl.LazyFrame, path: str) -> None:
+        """Write LazyFrame to a single file."""
+        pass

tab_cli/formats/csv.py

@@ -0,0 +1,45 @@
+"""CSV/TSV format handler."""
+
+from collections.abc import Iterable
+from io import BytesIO
+from typing import BinaryIO
+
+import polars as pl
+
+from tab_cli.formats.base import FormatHandler
+
+
+class CsvFormat(FormatHandler):
+    """Handler for CSV/TSV files."""
+
+    def __init__(self, separator: str = ","):
+        self.separator = separator
+
+    def extension(self) -> str:
+        return ".csv" if self.separator == "," else ".tsv"
+
+    def supports_glob(self) -> bool:
+        return True
+
+    def scan(self, url: str, storage_options: dict[str, str] | None = None) -> pl.LazyFrame:
+        return pl.scan_csv(url, separator=self.separator, storage_options=storage_options)
+
+    def read_stream(self, stream: BinaryIO) -> pl.DataFrame:
+        return pl.read_csv(stream, separator=self.separator)
+
+    def collect_schema(self, url: str, storage_options: dict[str, str] | None = None) -> list[tuple[str, pl.DataType]]:
+        return list(pl.scan_csv(url, separator=self.separator, storage_options=storage_options).collect_schema().items())
+
+    def count_rows(self, url: str, storage_options: dict[str, str] | None = None) -> int:
+        return pl.scan_csv(url, separator=self.separator, storage_options=storage_options).select(pl.len()).collect().item()
+
+    def write(self, lf: pl.LazyFrame) -> Iterable[bytes]:
+        first = True
+        for batch in lf.collect_batches():
+            output = BytesIO()
+            batch.write_csv(output, separator=self.separator, include_header=first)
+            first = False
+            yield output.getvalue()
+
+    def write_to_single_file(self, lf: pl.LazyFrame, path: str) -> None:
+        lf.sink_csv(path, separator=self.separator)

tab_cli/formats/jsonl.py

@@ -0,0 +1,41 @@
+"""JSONL (newline-delimited JSON) format handler."""
+
+import json
+from collections.abc import Iterable
+from typing import BinaryIO
+
+import polars as pl
+
+from tab_cli.formats.base import FormatHandler
+
+
+class JsonlFormat(FormatHandler):
+    """Handler for JSONL files."""
+
+    def extension(self) -> str:
+        return ".jsonl"
+
+    def supports_glob(self) -> bool:
+        return True
+
+    def scan(self, url: str, storage_options: dict[str, str] | None = None) -> pl.LazyFrame:
+        return pl.scan_ndjson(url, storage_options=storage_options)
+
+    def read_stream(self, stream: BinaryIO) -> pl.DataFrame:
+        return pl.read_ndjson(stream)
+
+    def collect_schema(self, url: str, storage_options: dict[str, str] | None = None) -> list[tuple[str, pl.DataType]]:
+        return list(pl.scan_ndjson(url, storage_options=storage_options).collect_schema().items())
+
+    def count_rows(self, url: str, storage_options: dict[str, str] | None = None) -> int:
+        return pl.scan_ndjson(url, storage_options=storage_options).select(pl.len()).collect().item()
+
+    def write(self, lf: pl.LazyFrame) -> Iterable[bytes]:
+        for batch in lf.collect_batches():
+            for row in batch.iter_rows(named=True):
+                yield (json.dumps(row, default=str, ensure_ascii=False) + "\n").encode("utf-8")
+
+    def write_to_single_file(self, lf: pl.LazyFrame, path: str) -> None:
+        with open(path, "wb") as f:
+            for chunk in self.write(lf):
+                f.write(chunk)

tab_cli/formats/parquet.py

@@ -0,0 +1,57 @@
+"""Parquet format handler."""
+
+from collections.abc import Iterable
+from io import BytesIO
+from typing import BinaryIO
+
+import polars as pl
+
+from tab_cli.formats.base import FormatHandler
+
+
+class ParquetFormat(FormatHandler):
+    """Handler for Parquet files."""
+
+    def extension(self) -> str:
+        return ".parquet"
+
+    def supports_glob(self) -> bool:
+        return True
+
+    def scan(self, url: str, storage_options: dict[str, str] | None = None) -> pl.LazyFrame:
+        return pl.scan_parquet(url, storage_options=storage_options)
+
+    def read_stream(self, stream: BinaryIO) -> pl.DataFrame:
+        return pl.read_parquet(stream)
+
+    def collect_schema(self, url: str, storage_options: dict[str, str] | None = None) -> list[tuple[str, pl.DataType]]:
+        return list(pl.scan_parquet(url, storage_options=storage_options).collect_schema().items())
+
+    def count_rows(self, url: str, storage_options: dict[str, str] | None = None) -> int:
+        return pl.scan_parquet(url, storage_options=storage_options).select(pl.len()).collect().item()
+
+    def extra_summary(self, url: str) -> dict[str, str | int | float] | None:
+        import pyarrow.parquet as pq
+
+        pf = pq.ParquetFile(url)
+        metadata = pf.metadata
+
+        extra: dict[str, str | int | float] = {}
+        codecs: set[str] = set()
+        for rg_idx in range(metadata.num_row_groups):
+            rg = metadata.row_group(rg_idx)
+            for col_idx in range(rg.num_columns):
+                col = rg.column(col_idx)
+                codecs.add(col.compression)
+        extra["Row groups"] = metadata.num_row_groups
+        if codecs:
+            extra["Compression"] = ", ".join(sorted(codecs))
+        return extra
+
+    def write(self, lf: pl.LazyFrame) -> Iterable[bytes]:
+        output = BytesIO()
+        lf.sink_parquet(output)
+        yield output.getvalue()
+
+    def write_to_single_file(self, lf: pl.LazyFrame, path: str) -> None:
+        lf.sink_parquet(path)

tab_cli/handlers/__init__.py

@@ -0,0 +1,87 @@
+"""Handler registration and inference."""
+
+import os
+
+from tab_cli.formats import AvroFormat, CsvFormat, JsonlFormat, ParquetFormat
+from tab_cli.formats.base import FormatHandler
+from tab_cli.handlers.base import FormatWriter, TableReader, TableWriter
+from tab_cli.handlers.cli_table import CliTableFormatter
+from tab_cli.storage import get_backend
+
+# Format handlers
+_FORMAT_MAP: dict[str, FormatHandler] = {
+    "csv": CsvFormat(","),
+    "tsv": CsvFormat("\t"),
+    "parquet": ParquetFormat(),
+    "jsonl": JsonlFormat(),
+    "avro": AvroFormat(),
+}
+
+
+def _get_extension(path: str) -> str:
+    """Extract file extension from a path or URL."""
+    # Handle URIs by getting the path component
+    if "://" in path:
+        path = path.split("://", 1)[1]
+    # Get extension from basename
+    basename = os.path.basename(path.rstrip("/"))
+    return os.path.splitext(basename)[1][1:].lower()
+
+
+def infer_reader(path: str, format: str | None = None) -> TableReader:
+    """Infer the reader for a file.
+
+    Args:
+        path: Path to the file or directory (local or cloud URL).
+        format: Explicit format override. If None, inferred from extension.
+
+    Returns:
+        TableReader configured for the format and storage backend.
+    """
+    backend = get_backend(path)
+
+    if format is not None:
+        fmt = _FORMAT_MAP.get(format.lower())
+        if fmt is None:
+            raise ValueError(f"Unknown format: {format}. Supported: {', '.join(_FORMAT_MAP)}")
+        return TableReader(backend, fmt)
+
+    # Infer format from path
+    if backend.is_directory(path):
+        # Get extension from first file in directory
+        for file_info in backend.list_files(path, ""):
+            extension = _get_extension(file_info.url)
+            if extension:
+                break
+        else:
+            raise ValueError(f"No files found in directory: {path}")
+    else:
+        extension = _get_extension(path)
+
+    fmt = _FORMAT_MAP.get(extension)
+    if fmt is None:
+        raise ValueError(f"Unknown extension: {extension}. Supported: {', '.join(_FORMAT_MAP)}")
+
+    return TableReader(backend, fmt)
+
+
+def infer_writer(format: str | None = None, truncated: bool = False) -> TableWriter:
+    """Infer the writer for a format.
+
+    Args:
+        format: Output format. If None, returns CLI table formatter.
+        truncated: Whether the output is truncated (for CLI display).
+
+    Returns:
+        TableWriter for the format.
+    """
+    if format is None:
+        return CliTableFormatter(truncated=truncated)
+    if format == "table-svg":
+        return CliTableFormatter(truncated=truncated, svg_capture=True)
+
+    fmt = _FORMAT_MAP.get(format.lower())
+    if fmt is None:
+        raise ValueError(f"Unknown format: {format}. Supported: {', '.join(_FORMAT_MAP)}")
+
+    return FormatWriter(fmt)