pandas-tibble 0.2.3
R-style tibble() display for pandas DataFrames using Rich
License: MIT
Requires Python: <4.0.0,>=3.10.0
Keywords: pandas, tibble, R, dataframe, rich, terminal, display

# pandas-tibble [![PyPI Version](https://img.shields.io/pypi/v/pandas-tibble.svg)](https://pypi.org/project/pandas-tibble/)

![Downloads](https://img.shields.io/pypi/dm/pandas-tibble)

Display pandas DataFrames with R-style tibble formatting in the terminal.

## What it does

- `Tibble` class - a DataFrame subclass that preserves all pandas functionality with automatic tibble-style display
- Prints DataFrames with column type annotations (`<chr>`, `<int>`, `<dbl>`, `<date>`, `<datetime>`)
- Shows dimensions at the top
- Distinguishes between date and datetime types
- Provides glimpse() for quick column overview
- All pandas operations work: `.query()`, `.merge()`, `.groupby()`, etc.

## Installation

```bash
pip install pandas-tibble
```

For development:
```bash
git clone https://github.com/caspercrause/pandas-tibble.git
cd pandas-tibble
poetry install
```

## Requirements

- Python >= 3.10.0
- pandas >= 2.0.0
- rich >= 13.0.0

## Usage

### Tibble class (Recommended)

Create a DataFrame subclass with automatic beautiful display:

```python
from pandas_tibble import Tibble

# Create a Tibble - displays automatically!
tbl = Tibble({
    'product': ['A', 'B', 'A', 'B'],
    'revenue': [100, 150, 120, 180],
    'units': [10, 12, 11, 15]
})

# Just evaluate it - beautiful display
tbl

# All pandas operations work and return Tibbles!
tbl.query('revenue > 110')
tbl['profit'] = tbl['revenue'] * 0.2
tbl.groupby('product').sum()
tbl.merge(other_tbl, on='product')
```

Output:
```
# A DataFrame: 4 × 3

product  revenue  units
<chr>    <int>    <int>
A        100      10
B        150      12
A        120      11
B        180      15
```

### tibble() function (for printing purposes only)

Display any DataFrame with type annotations:

```python
import pandas as pd
from pandas_tibble import tibble
from datetime import date

df = pd.DataFrame({
    'start_date': [date(2024, 1, i) for i in range(1, 6)],
    'name': ['Alice', 'Bob', 'Charlie', 'Diana', 'Eve'],
    'value': [100, 200, 300, 400, 500]
})

tibble(df)
```

Output:
```
# A DataFrame: 5 × 3

start_date  name     value
<date>      <chr>    <int>
━━━━━━━━━━━━━━━━━━━━━━━━━━━
2024-01-01  Alice    100
2024-01-02  Bob      200
2024-01-03  Charlie  300
2024-01-04  Diana    400
2024-01-05  Eve      500
```

Options:
```python
tibble(df, max_rows=20)         # Show more rows
tibble(df, show_index=True)     # Include index column
```

### glimpse()

Quick column overview:

```python
glimpse(df)
```

Output:
```
Rows: 5
Columns: 3

start_date  <date>  2024-01-01, 2024-01-02, 2024-01-03...
name        <chr>   Alice, Bob, Charlie...
value       <int>   100, 200, 300...
```

## Type mapping

| pandas dtype | Display | Format |
|--------------|---------|---------|
| `object` (string) | `<chr>` | as-is |
| `int64` | `<int>` | as-is |
| `float64` | `<dbl>` | 2 decimals |
| `bool` | `<lgl>` | True/False |
| `datetime64[ns]` | `<datetime>` | YYYY-MM-DD HH:MM:SS |
| `object` (date) | `<date>` | YYYY-MM-DD |
| `category` | `<fctr>` | as-is |
| `timedelta64[ns]` | `<timedelta>` | as-is |

Missing values display as `NA`.

## Features

- ✅ Full pandas compatibility - all methods preserved
- ✅ Automatic beautiful display in terminal, Jupyter, VS Code
- ✅ Operations return Tibble objects (`.query()`, `.merge()`, `.groupby()`, etc.)
- ✅ Type annotations for all columns
- ✅ Works with existing DataFrames via `Tibble(df)` conversion

## What it doesn't do

- Does not replicate R tibble's subsetting rules
- Does not support tibble construction syntax (use dict or DataFrame syntax)
- Does not modify how pandas operations work (100% compatible)

## Similar Packages

Several packages provide enhanced DataFrame display or R-style functionality:

- **rich-dataframe**: Creates animated and pretty DataFrames using Rich, but is display-only and does not create a DataFrame subclass
- **skimpy**: Python port of R's skimr package, focuses on summary statistics rather than full tibble-style display
- **tabulate**: General table formatting library used by pandas' `to_markdown()`, provides formatting without DataFrame integration
- **rich-tools**: Helper functions to convert DataFrames to Rich tables for printing, not a DataFrame replacement
- **datar**: Full tidyverse port to Python with complete API replacement and heavy dependencies

## What Sets pandas-tibble Apart

pandas-tibble is the only package that combines all of the following:

- DataFrame subclass that preserves all pandas methods and operations
- Automatic R-style tibble display without explicit print calls
- Lightweight implementation with only two dependencies (pandas and Rich)
- All operations return Tibble objects, maintaining consistency throughout your workflow
- Drop-in replacement for pandas DataFrames with zero API changes

Most packages are either display-only utilities or complete pandas replacements. pandas-tibble provides the best of both worlds: beautiful R-style display with full pandas compatibility.

## License

MIT

## Author

Casper Crause