bakprint 0.1.0

Fancy, efficient, highly customizable debug printing for Python objects, pandas, and numpy.

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

pip install -e .

With the data stack:

pip install -e ".[data]"

Quick Start

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.

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:

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:

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
• examples/marching_dashes_demo.py

VS Code extension scaffold:

• vscode-extension/README.md