parqx 0.1.0__tar.gz

parqx-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Senyu Xie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

parqx-0.1.0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: parqx
+Version: 0.1.0
+Summary: Parquet TUI inspector
+Author: Senyu Xie
+Author-email: Senyu Xie <senyuxie@qq.com>
+License-File: LICENSE
+Requires-Dist: pyarrow>=24.0.0
+Requires-Dist: textual>=8.2.7
+Requires-Dist: typer>=0.26.7
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Parqx
+
+Parqx is a lightweight terminal UI for inspecting Apache Parquet files.
+
+It opens a local Parquet file directly in your terminal and displays it as an interactive, scrollable table backed by PyArrow and Textual.
+
+## Installation
+
+Parqx requires Python 3.12 or newer.
+
+```bash
+pip install parqx
+```
+
+## Usage
+
+Open a Parquet file:
+
+```bash
+parqx data/weather.parquet
+```
+
+## Navigation
+
+| Key                   | Action                        |
+| ---                   | ---                           |
+| `↑` / `↓`             | Move the cursor up or down    |
+| `←` / `→`             | Move the cursor left or right |
+| `PageUp` / `PageDown` | Move one page up or down      |
+| `Home`                | Move to the leftmost column   |
+| `End`                 | Move to the rightmost column  |
+| `Ctrl+Home`           | Move to the first row         |
+| `Ctrl+End`            | Move to the last row          |
+| `Enter`               | Select the current cell       |
+| `Ctrl+Q`              | Quit                          |
+
+## License
+
+Parqx is licensed under the MIT License. See [LICENSE](LICENSE) for details.

parqx-0.1.0/README.md

@@ -0,0 +1,39 @@
+# Parqx
+
+Parqx is a lightweight terminal UI for inspecting Apache Parquet files.
+
+It opens a local Parquet file directly in your terminal and displays it as an interactive, scrollable table backed by PyArrow and Textual.
+
+## Installation
+
+Parqx requires Python 3.12 or newer.
+
+```bash
+pip install parqx
+```
+
+## Usage
+
+Open a Parquet file:
+
+```bash
+parqx data/weather.parquet
+```
+
+## Navigation
+
+| Key                   | Action                        |
+| ---                   | ---                           |
+| `↑` / `↓`             | Move the cursor up or down    |
+| `←` / `→`             | Move the cursor left or right |
+| `PageUp` / `PageDown` | Move one page up or down      |
+| `Home`                | Move to the leftmost column   |
+| `End`                 | Move to the rightmost column  |
+| `Ctrl+Home`           | Move to the first row         |
+| `Ctrl+End`            | Move to the last row          |
+| `Enter`               | Select the current cell       |
+| `Ctrl+Q`              | Quit                          |
+
+## License
+
+Parqx is licensed under the MIT License. See [LICENSE](LICENSE) for details.

parqx-0.1.0/pyproject.toml

@@ -0,0 +1,78 @@
+[project]
+name = "parqx"
+version = "0.1.0"
+description = "Parquet TUI inspector"
+readme = "README.md"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Senyu Xie", email = "senyuxie@qq.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "pyarrow>=24.0.0",
+    "textual>=8.2.7",
+    "typer>=0.26.7",
+]
+
+[project.scripts]
+parqx = "parqx.cli:app"
+
+[build-system]
+requires = ["uv_build>=0.11.21,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "mypy>=2.1.0",
+    "pyright>=1.1.410",
+    "pytest>=9.1.0",
+    "ruff>=0.15.17",
+    "textual-dev>=1.8.0",
+]
+
+[tool.mypy]
+strict = true
+python_version = "3.12"
+
+[tool.pyright]
+typeCheckingMode = "strict"
+
+[tool.ruff]
+target-version = "py312"
+
+[tool.ruff.format]
+docstring-code-format = true
+skip-magic-trailing-comma = true
+
+[tool.ruff.lint]
+select = [
+    "B",
+    "C4",
+    "D",
+    "E4",
+    "E7",
+    "E9",
+    "F",
+    "G",
+    "I",
+    "LOG",
+    "N",
+    "PERF",
+    "PT",
+    "PTH",
+    "RET",
+    "RUF",
+    "S",
+    "SIM",
+    "TID",
+    "UP",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S", "D"]
+
+[tool.ruff.lint.isort]
+split-on-trailing-comma = false
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"

parqx-0.1.0/src/parqx/__init__.py

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

parqx-0.1.0/src/parqx/__main__.py

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

parqx-0.1.0/src/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-0.1.0/src/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-0.1.0/src/parqx/tui/__init__.py

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

parqx-0.1.0/src/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-0.1.0/src/parqx/tui/widgets/__init__.py

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