Metadata-Version: 2.4
Name: hmm-viewer
Version: 2.1.3
Summary: View CSV, Parquet files and pandas/polars DataFrames in a terminal UI
Author: Stephen Sun
License-Expression: MIT
Project-URL: Homepage, https://github.com/suntianxun/hmm
Project-URL: Repository, https://github.com/suntianxun/hmm
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Provides-Extra: pandas
Requires-Dist: pandas; extra == "pandas"
Requires-Dist: pyarrow; extra == "pandas"
Provides-Extra: polars
Requires-Dist: polars; extra == "polars"

# hmm-viewer

Python package for [hmm](https://github.com/suntianxun/hmm) — a terminal UI for viewing CSV, Parquet, and Excel files.

The Go binary is automatically downloaded from GitHub releases on first use. No need to install Go.

## Installation

```bash
uv pip install hmm-viewer              # base install
uv pip install 'hmm-viewer[pandas]'    # with pandas support
uv pip install 'hmm-viewer[polars]'    # with polars support
```

## Usage

### CLI

After installing, the `hmm` command is available:

```bash
hmm data.csv
hmm data.parquet
hmm data.xlsx
```

### Python API

```python
from hmm_viewer import hmm

# Works with pandas DataFrames
import pandas as pd
df = pd.read_csv("data.csv")
hmm(df)

# Works with polars DataFrames
import polars as pl
df = pl.read_parquet("data.parquet")
hmm(df)

# Dict of DataFrames — each key becomes a sheet tab
sheets = pd.read_excel("data.xlsx", sheet_name=None)
hmm(sheets)
```

This is especially useful from a debugger (ipdb, pdb, ipython) to quickly
inspect a DataFrame in the terminal.

## How it works

- **CLI**: The `hmm` command is a thin wrapper that delegates to the Go binary.
- **Python API**: `hmm(df)` writes the DataFrame to a temporary Parquet file (or Excel file for a dict of DataFrames), launches the `hmm` binary, and cleans up the temp file when done. For dicts the TUI spinner shows immediately while the Excel file is being written.
- **Auto-download**: If the Go binary isn't found on `$PATH` or `~/go/bin`, it is automatically downloaded from GitHub releases and cached at `~/.cache/hmm/`.
