parqx 0.1.0__py3-none-any.whl

parqx/__init__.py

@@ -0,0 +1 @@
+"""The Parqx package."""

parqx/__main__.py

@@ -0,0 +1,5 @@
+"""Parqx: A Parquet TUI inspector."""
+
+from parqx.cli import app
+
+app(prog_name="parqx")

parqx/cli.py

@@ -0,0 +1,63 @@
+"""The Parqx CLI entrypoint."""
+
+import logging
+from importlib import metadata
+from pathlib import Path
+from typing import Annotated
+
+import pyarrow.parquet as pq
+import typer
+
+from parqx.logger import setup_logging
+from parqx.tui.app import ParqxApp
+
+logger = logging.getLogger(__name__)
+
+app = typer.Typer(help="Parqx: A Parquet TUI inspector.")
+
+
+def version_callback(value: bool) -> None:
+    """Parqx version callback."""
+    if value:
+        print(f"parqx {metadata.version('parqx')}")
+        raise typer.Exit()
+
+
+@app.command()
+def main(
+    path: Annotated[
+        Path,
+        typer.Argument(
+            exists=True,
+            file_okay=True,
+            dir_okay=False,
+            readable=True,
+            help="Parquet file to inspect.",
+        ),
+    ],
+    verbose: Annotated[
+        int,
+        typer.Option(
+            "--verbose",
+            "-v",
+            count=True,
+            help="Enable verbose logging (or `-vv` for more verbose output).",
+        ),
+    ] = 0,
+    version: Annotated[
+        bool | None,
+        typer.Option(
+            "--version",
+            callback=version_callback,
+            is_eager=True,
+            help="Show the version and exit.",
+        ),
+    ] = None,
+) -> None:
+    """Parqx: A Parquet TUI inspector."""
+    _ = version
+
+    setup_logging(verbose)
+
+    table = pq.read_table(path)  # type: ignore
+    ParqxApp(table).run()

parqx/logger.py

@@ -0,0 +1,76 @@
+"""The Parqx logging configuration."""
+
+import logging
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+
+from platformdirs import user_log_dir
+from textual.logging import TextualHandler
+
+_LOGGER_NAME = "parqx"
+_LOG_FILE_NAME = "parqx.log"
+_LOG_FILE_MAX_BYTES = 5 * 1024 * 1024  # 5 MiB
+_LOG_FILE_BACKUP_COUNT = 3
+_FILE_FORMAT = "%(asctime)s %(levelname)-8s %(name)s:%(lineno)d  %(message)s"
+_DATE_FORMAT = "%Y-%m-%d %H:%M:%S"
+
+
+def _verbosity_to_level(verbose: int) -> int:
+    """Map the `--verbose` count to a `logging` level."""
+    if verbose <= 0:
+        return logging.WARNING
+    if verbose == 1:
+        return logging.INFO
+    return logging.DEBUG
+
+
+def _log_file_path() -> Path:
+    """Return the rotating log file path under the platform user log directory."""
+    log_dir = Path(user_log_dir("parqx", appauthor=False, ensure_exists=True))
+    return log_dir / _LOG_FILE_NAME
+
+
+def setup_logging(verbose: int = 0) -> None:
+    r"""Configure logging for the Parqx application.
+
+    A TUI takes over the terminal, so log records must never reach `stdout` or
+    `stderr` while the app is running. This function installs two handlers on
+    the `parqx` logger:
+
+    - A `RotatingFileHandler` writing detailed records to a log file under
+    the platform user log directory (e.g. `%LOCALAPPDATA%\\parqx\\Logs\\parqx.log`
+    on Windows, `~/.local/state/parqx/log/parqx.log` on Linux).
+    - A `TextualHandler` so `logger.*` calls are also visible in `textual console`
+    during development.
+
+    Propagation to the root logger is disabled so records can't accidentally
+    leak to `stderr` and corrupt the TUI. The function is idempotent - calling
+    it again replaces the previously installed handlers.
+
+    Args:
+        verbose: Verbosity count from the CLI (`-v` once, `-vv` twice, ...).
+            0 maps to `WARNING`, 1 to `INFO`, 2+ to `DEBUG`.
+    """
+    level = _verbosity_to_level(verbose)
+    log_file = _log_file_path()
+
+    logger = logging.getLogger(_LOGGER_NAME)
+    logger.setLevel(level)
+    logger.propagate = False
+
+    for existing in logger.handlers:
+        logger.removeHandler(existing)
+        existing.close()
+
+    file_handler = RotatingFileHandler(
+        log_file,
+        maxBytes=_LOG_FILE_MAX_BYTES,
+        backupCount=_LOG_FILE_BACKUP_COUNT,
+        encoding="utf-8",
+        delay=True,
+    )
+    file_handler.setLevel(level)
+    file_handler.setFormatter(logging.Formatter(_FILE_FORMAT, datefmt=_DATE_FORMAT))
+    logger.addHandler(file_handler)
+
+    logger.addHandler(TextualHandler())

parqx/tui/__init__.py

@@ -0,0 +1 @@
+"""The Parqx TUI package."""

parqx/tui/app.py

@@ -0,0 +1,25 @@
+"""The Parqx Textual App."""
+
+from typing import Any
+
+import pyarrow as pa
+from textual.app import App, ComposeResult
+
+from parqx.tui.widgets import ArrowTable
+
+
+class ParqxApp(App[Any]):
+    """A Textual App for Parqx."""
+
+    def __init__(self, table: pa.Table) -> None:
+        """Initialize the app with an Arrow table to inspect.
+
+        Args:
+            table: Arrow table displayed by the main table widget.
+        """
+        super().__init__()
+        self._table = table
+
+    def compose(self) -> ComposeResult:
+        """Yield child widgets for the app."""
+        yield ArrowTable(self._table)

parqx/tui/widgets/__init__.py

@@ -0,0 +1,5 @@
+"""The TUI widgets package."""
+
+from parqx.tui.widgets.arrow_table import ArrowTable
+
+__all__ = ["ArrowTable"]