Metadata-Version: 2.2
Name: bakprint
Version: 0.1.0
Summary: Fancy, efficient, highly customizable debug printing for Python objects, pandas, and numpy.
Author: Maroun
License: MIT
Keywords: debugging,printing,rich,pandas,numpy
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.7.0
Provides-Extra: data
Requires-Dist: numpy>=1.24.0; extra == "data"
Requires-Dist: pandas>=2.0.0; extra == "data"
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == "dev"
Requires-Dist: numpy>=1.24.0; extra == "dev"
Requires-Dist: pandas>=2.0.0; extra == "dev"
Requires-Dist: twine>=5.1.1; extra == "dev"

# bakprint

`bakprint` is a terminal-first debug printing package built for clarity and showmanship.
It aims to be the thing you reach for when `print()` is too plain and a full debugger is too slow.

Highlights:

- Fancy boxed output powered by `rich`
- Strong previews for `pandas.DataFrame`, `pandas.Series`, and `numpy.ndarray`
- Summary mode for schema-first and stats-first debugging
- Built-in diffs for mappings, arrays, series, and dataframes
- Optional caller trace metadata for fast “where did this print come from?” debugging
- Efficient truncation for huge payloads
- Configurable themes, limits, metadata, and summary statistics
- Friendly API for one-off debugging or reusable printer instances

## Install

```bash
pip install -e .
```

With the data stack:

```bash
pip install -e ".[data]"
```

## Quick Start

```python
import pandas as pd
import numpy as np

from bakprint import PrintConfig, bak_diffx, bak_printx, bak_summaryx

config = PrintConfig(
    theme="aurora",
    max_array_rows=8,
    max_array_cols=6,
    max_dataframe_rows=12,
    max_dataframe_cols=8,
    show_summary=True,
)

df = pd.DataFrame(
    {
        "city": ["Beirut", "Paris", "Cairo", "Tokyo"],
        "orders": [12, 7, 18, 14],
        "revenue": [1250.5, 910.2, 1833.8, 1660.0],
    }
)

array = np.arange(36).reshape(6, 6)

bak_printx(df, title="DataFrame Preview", config=config)
bak_printx(array, title="Array Preview", config=config)
bak_printx({"active": True, "threshold": 0.91, "payload": ["a", "b", "c"]})
bak_summaryx(df, title="DataFrame Summary", config=config)
bak_diffx({"status": "draft", "rows": 10}, {"status": "ready", "rows": 12}, title="Payload Diff", config=config)
```

## API

### `bak_printx(*objects, title=None, labels=None, config=None, console=None, **overrides)`

Print one or more objects using a temporary or provided `DebugPrinter`.

### `bak_formatx(obj, label=None, config=None, **overrides)`

Return a rich renderable for integration into another `rich` console workflow.

### `bak_inspectx(obj, label=None, config=None, console=None, **overrides)`

Print a single object and return it, so it can be inserted into debug pipelines.

### `bak_animatex(obj, label=None, title=None, config=None, console=None, duration=None, fps=None, **overrides)`

Animate an object using the configured border effect.

### `bak_summaryx(obj, label=None, title=None, config=None, console=None, **overrides)`

Print a summary-oriented view of an object.

### `bak_diffx(before, after, labels=("before", "after"), title=None, config=None, console=None, **overrides)`

Print a focused diff between two objects.

### `DebugPrinter`

Reusable printer instance with stable console + configuration.

```python
from rich.text import Text

from bakprint import DebugPrinter, PrintConfig


class QueryPlan:
    def __init__(self, steps: list[str]) -> None:
        self.steps = steps


printer = DebugPrinter(PrintConfig(theme="matrix"))
printer.register(
    QueryPlan,
    lambda plan, config: Text(
        " -> ".join(plan.steps),
        style=config.resolve_style("accent"),
    ),
)

printer.print(QueryPlan(["scan", "join", "aggregate"]), title="Custom Type")
```

### `PrintConfig`

Configuration dataclass for themes, truncation, summary display, and styling.

Useful debug-oriented options:

- `display_mode="summary"` for stats and schema instead of row previews
- `border_effect="marching_dashes"` for an opt-in animated dashed border
- automatic fallback to a static frame when output is not a real TTY
- ASCII-safe dashed borders when the terminal can't reliably render Unicode boxes
- `animation_duration=1.6` to control how long the animation runs
- `animation_fps=10` to control animation speed
- `show_trace=True` to include caller file, line, and function
- `show_timestamp=True` to timestamp each print
- `diff_sample_size=20` to expand sampled diff output

Example:

```python
from bakprint import DebugPrinter, PrintConfig

printer = DebugPrinter(
    PrintConfig(
        theme="matrix",
        show_trace=True,
        show_timestamp=True,
    )
)

printer.print({"status": "live", "rows": 128}, title="Trace Example")
printer.summarize(df, title="Summary Example")
printer.diff(old_df, new_df, title="DataFrame Diff")
```

Marching dashes example:

```python
from bakprint import PrintConfig, bak_animatex

config = PrintConfig(
    theme="noir",
    border_effect="marching_dashes",
    animation_duration=1.6,
    animation_fps=10,
)

bak_animatex({"status": "ok", "rows": 128}, title="Marching Border", config=config)
```

## Theme Presets

- `aurora`: saturated, colorful, presentation-friendly
- `paper`: cleaner, softer output for daytime terminals
- `matrix`: neon green cyber-debug vibe
- `noir`: restrained and contrast-heavy

## Design Notes

`bakprint` keeps heavy objects fast by previewing slices instead of materializing full text dumps.
For arrays and dataframes, it reports shape and dtype information first, then renders only the configured visible window.

Full feature reference:

- [FEATURES.md](/home/maroun/bakprint/FEATURES.md:1)
- [examples/marching_dashes_demo.py](/home/maroun/bakprint/examples/marching_dashes_demo.py:1)

VS Code extension scaffold:

- [vscode-extension/README.md](/home/maroun/bakprint/vscode-extension/README.md:1)
