barflow 0.2.1__tar.gz → 0.2.2__tar.gz

{barflow-0.2.1/src/barflow.egg-info → barflow-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: barflow
-Version: 0.2.1
+Version: 0.2.2
 Summary: Fast Python progress bars with a C++ core. Windows-first.
 Author: NevermindNilas
 License-Expression: MIT

barflow-0.2.2/benchmarks/bench_import_to_iter.py

@@ -0,0 +1,187 @@
+"""Benchmark: total ms from zero to first iteration body.
+
+Measures the *end-to-end* cost a user actually pays:
+    1. import the library
+    2. construct a progress bar around a range
+    3. enter the first iteration
+
+All three phases run inside a subprocess so the import is genuinely cold.
+The subprocess prints a single perf_counter_ns timestamp; the driver
+subtracts the interpreter-startup baseline to isolate library cost.
+
+Usage:
+    python benchmarks/bench_import_to_iter.py
+    python benchmarks/bench_import_to_iter.py --runs 21
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import statistics
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parent.parent
+SRC = REPO / "src"
+
+# ---------- snippets ----------------------------------------------------------
+# Each snippet must print exactly ONE integer: perf_counter_ns elapsed from
+# the top of the script to the moment the first iteration body executes.
+
+SNIPPETS: dict[str, str] = {
+    "rich": """\
+import time, sys, os
+_t0 = time.perf_counter_ns()
+from rich.console import Console
+from rich.progress import Progress
+import io
+_sink = io.StringIO()
+_console = Console(file=_sink, force_terminal=True)
+with Progress(console=_console, transient=True) as _p:
+    _task = _p.add_task("work", total=100)
+    for _i in range(100):
+        # === first iteration body reached ===
+        _elapsed = time.perf_counter_ns() - _t0
+        break
+# print outside the context manager so rich doesn't capture it
+os.write(1, (str(_elapsed) + "\\n").encode())
+""",
+    "tqdm": """\
+import time, os
+_t0 = time.perf_counter_ns()
+from tqdm import tqdm
+import io
+_sink = io.StringIO()
+for _i in tqdm(range(100), file=_sink, total=100):
+    _elapsed = time.perf_counter_ns() - _t0
+    break
+os.write(1, (str(_elapsed) + "\\n").encode())
+""",
+    "barflow": """\
+import time, sys, os
+sys.path.insert(0, {src!r})
+_t0 = time.perf_counter_ns()
+# redirect fd 2 so the C renderer doesn't write to console
+_devnull = os.open(os.devnull, os.O_WRONLY)
+_saved = os.dup(2)
+os.dup2(_devnull, 2)
+from barflow import track
+for _i in track(range(100), total=100):
+    _elapsed = time.perf_counter_ns() - _t0
+    break
+os.dup2(_saved, 2)
+os.close(_saved)
+os.close(_devnull)
+os.write(1, (str(_elapsed) + "\\n").encode())
+""",
+    "alive-progress": """\
+import time, os
+_t0 = time.perf_counter_ns()
+from alive_progress import alive_bar
+import io
+_sink = io.StringIO()
+with alive_bar(100, file=_sink, force_tty=True) as _bar:
+    for _i in range(100):
+        _elapsed = time.perf_counter_ns() - _t0
+        break
+os.write(1, (str(_elapsed) + "\\n").encode())
+""",
+}
+
+
+# ---------- driver ------------------------------------------------------------
+
+def _run_snippet(label: str, snippet: str, runs: int) -> list[int]:
+    """Return list of elapsed-ns values, one per successful run."""
+    env = os.environ.copy()
+    env["PYTHONPATH"] = str(SRC) + os.pathsep + env.get("PYTHONPATH", "")
+    env["PYTHONDONTWRITEBYTECODE"] = "1"
+
+    results: list[int] = []
+    for _ in range(runs):
+        proc = subprocess.run(
+            [sys.executable, "-c", snippet],
+            env=env,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            text=True,
+            timeout=30,
+        )
+        if proc.returncode != 0:
+            continue
+        line = proc.stdout.strip().splitlines()[0] if proc.stdout.strip() else ""
+        try:
+            results.append(int(line))
+        except ValueError:
+            pass
+    return results
+
+
+def _baseline(runs: int) -> float:
+    """Median wall-ns of a bare `python -c pass` — interpreter startup only."""
+    env = os.environ.copy()
+    env["PYTHONDONTWRITEBYTECODE"] = "1"
+    times: list[float] = []
+    for _ in range(runs):
+        t0 = time.perf_counter()
+        subprocess.run(
+            [sys.executable, "-c", "pass"],
+            env=env,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            check=True,
+        )
+        times.append(time.perf_counter() - t0)
+    return statistics.median(times) * 1e9  # -> ns
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="Import-to-first-iteration benchmark")
+    ap.add_argument("--runs", type=int, default=11,
+                    help="trials per library (default 11)")
+    args = ap.parse_args()
+
+    print(f"=== Import -> show bar -> first iteration (runs={args.runs}) ===")
+    print(f"    Python {sys.version}")
+    print()
+
+    # The snippet already measures elapsed time internally (perf_counter_ns),
+    # so it captures import + construction + first iter. No baseline subtraction
+    # needed — the timer starts AFTER the interpreter is already running.
+
+    header = f"  {'library':<18s} {'median':>10s} {'min':>10s} {'p90':>10s} {'max':>10s}"
+    print(header)
+    print("  " + "-" * (len(header) - 2))
+
+    for label, snippet in SNIPPETS.items():
+        if label == "barflow":
+            snippet = snippet.format(src=str(SRC))
+        samples = _run_snippet(label, snippet, args.runs)
+        if not samples:
+            print(f"  {label:<18s} {'SKIP (not installed or error)':>10s}")
+            continue
+        samples.sort()
+        median = statistics.median(samples)
+        mn = samples[0]
+        p90 = samples[int(round(0.90 * (len(samples) - 1)))]
+        mx = samples[-1]
+        print(
+            f"  {label:<18s} "
+            f"{median / 1e6:>9.1f}ms "
+            f"{mn / 1e6:>9.1f}ms "
+            f"{p90 / 1e6:>9.1f}ms "
+            f"{mx / 1e6:>9.1f}ms"
+        )
+
+    print()
+    print("Timer starts AFTER interpreter boot (inside the subprocess).")
+    print("Measures: import lib + construct progress bar + reach first iteration body.")
+    print()
+    print("Lower is better.")
+
+
+if __name__ == "__main__":
+    main()

barflow-0.2.2/examples/gallery.py

@@ -0,0 +1,271 @@
+"""Gallery — every preset rendering at once, side-by-side.
+
+Inspired by alive-progress's `showtime`. Every selected preset gets
+its own row; all rows redraw in the same animation frame so the
+terminal looks like a wall of bars all racing simultaneously.
+
+Each row pulls the preset's bar glyphs, color style, spinner frames,
+and description style straight from `barflow.themes` so what you see
+matches `barflow.Progress(theme=name)` exactly.
+
+Run from any cwd:
+    python examples/gallery.py
+    python examples/gallery.py --section neon
+    python examples/gallery.py --section emoji --fps 30
+    python examples/gallery.py --only vaporwave hacker rocket_emoji
+    python examples/gallery.py --list
+    python examples/gallery.py --duration 8 --fps 24
+
+Record as a GIF (requires `vhs` from charm.sh):
+    vhs examples/gallery.tape   # → examples/gallery.gif
+
+Tips:
+    - Resize your terminal tall enough to fit every row.
+    - 24-bit truecolor terminal recommended for the neon palette.
+    - Emoji presets need an emoji-capable font (Win Terminal, iTerm2,
+      modern gnome-terminal, kitty, alacritty + Noto Emoji, etc.).
+"""
+
+from __future__ import annotations
+
+import argparse
+import random
+import sys
+import time
+from pathlib import Path
+
+_REPO_SRC = Path(__file__).resolve().parent.parent / "src"
+if _REPO_SRC.is_dir() and str(_REPO_SRC) not in sys.path:
+    sys.path.insert(0, str(_REPO_SRC))
+
+# Force UTF-8 on Windows so emoji + box-drawing glyphs don't crash cp1252.
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, ValueError):
+        pass
+
+from barflow import themes  # noqa: E402
+from barflow._core import (  # noqa: E402
+    COL_BAR, COL_SPINNER, COL_DESCRIPTION, COL_PERCENT, COL_TEXT,
+)
+
+
+RESET = "\x1b[0m"
+
+
+# Curated lineups per section. Skip themes that need rate/eta columns to
+# look right (classic, downloading, etc.) — gallery is bar-focused.
+SECTIONS: dict[str, list[str]] = {
+    "neon": [
+        "vaporwave", "synthwave", "lightning", "plasma", "acid",
+        "midnight", "ember", "amber_crt", "miami", "gold_rush",
+        "alien", "deep_sea", "magma", "void", "chevron",
+        "rail_neon", "slash", "neon", "cyberpunk",
+    ],
+    "ascii": [
+        "hacker", "binary", "curly", "march", "wave", "rail_ascii",
+        "ascii", "equals", "brackets",
+    ],
+    "emoji": [
+        "fire_emoji", "rocket", "sakura", "storm",
+        "sparkle", "pacman", "heart_emoji", "moon", "weather",
+    ],
+    "brand": [
+        "github_dark", "discord", "dracula", "solarized", "nord", "gruvbox",
+    ],
+    "playful": [
+        "hearts", "stars", "arrows", "pipes", "shade",
+        "line", "double", "round", "matrix",
+        "fire", "ocean", "ice", "sunset", "forest",
+    ],
+    "all": [],  # filled below
+}
+SECTIONS["all"] = (
+    SECTIONS["neon"] + SECTIONS["ascii"] + SECTIONS["emoji"]
+    + SECTIONS["brand"] + SECTIONS["playful"]
+)
+
+
+# ----- Column extraction --------------------------------------------------
+
+def extract(cols):
+    """Pull bar glyphs, bar style, spinner frames + style, desc style.
+
+    Returns dict with keys: bar_width, bar_ansi, bar_glyphs (5-tuple),
+    spinner_frames (list[str]|None), spinner_ansi (str), desc_ansi (str),
+    prefix_text (str), prefix_ansi (str).
+    """
+    out = {
+        "bar_width": 30,
+        "bar_ansi": "",
+        "bar_glyphs": ("█", " ", [], "", ""),
+        "spinner_frames": None,
+        "spinner_ansi": "",
+        "desc_ansi": "",
+        "prefix_text": "",
+        "prefix_ansi": "",
+    }
+    for col in cols:
+        kind = col[0]
+        if kind == COL_BAR:
+            w = col[2]
+            out["bar_width"] = 30 if w is None or w < 0 else w
+            out["bar_ansi"] = col[4] or ""
+            out["bar_glyphs"] = col[5]
+        elif kind == COL_SPINNER:
+            out["spinner_frames"] = col[3]
+            out["spinner_ansi"] = col[4] or ""
+        elif kind == COL_DESCRIPTION:
+            out["desc_ansi"] = col[4] or ""
+        elif kind == COL_TEXT and not out["prefix_text"]:
+            out["prefix_text"] = col[1] or ""
+            out["prefix_ansi"] = col[4] or ""
+    return out
+
+
+# ----- Per-row renderer ---------------------------------------------------
+
+def build_bar(glyphs, width, fraction):
+    """Build one bar string from a 5-tuple glyphs spec at given fill fraction."""
+    fill, empty, partials, left, right = glyphs
+    cells = max(1, width)
+    levels = len(partials) + 1
+    total = cells * levels
+    filled = int(fraction * total + 0.5)
+    full_cells = filled // levels
+    partial_idx = filled % levels
+
+    body = fill * full_cells
+    remaining = cells - full_cells
+    if partial_idx > 0 and remaining > 0:
+        body += partials[partial_idx - 1]
+        remaining -= 1
+    body += empty * remaining
+    return f"{left}{body}{right}"
+
+
+def render_row(name, parts, fraction, frame_tick, name_width):
+    """Render a single preset row at this frame."""
+    name_label = f"\x1b[1;97m{name:<{name_width}}{RESET}"
+
+    spinner = ""
+    frames = parts["spinner_frames"]
+    if frames:
+        glyph = frames[frame_tick % len(frames)]
+        ansi = parts["spinner_ansi"]
+        spinner = f"{ansi}{glyph}{RESET} " if ansi else f"{glyph} "
+
+    bar_str = build_bar(parts["bar_glyphs"], parts["bar_width"], fraction)
+    bar_part = f"{parts['bar_ansi']}{bar_str}{RESET}" if parts["bar_ansi"] else bar_str
+
+    pct = f"{int(fraction * 100):3d}%"
+    pct_color = "\x1b[1m" if fraction < 1.0 else "\x1b[1;92m"
+    pct_part = f"{pct_color}{pct}{RESET}"
+
+    return f"{spinner}{name_label} {bar_part} {pct_part}"
+
+
+# ----- Showtime loop ------------------------------------------------------
+
+def run_gallery(presets, *, duration=6.0, fps=24, seed=None):
+    if not presets:
+        print("nothing to show.", file=sys.stderr)
+        return
+
+    rng = random.Random(seed)
+    parts = {n: extract(themes.get(n)) for n in presets}
+    speeds = {n: rng.uniform(0.6, 1.6) for n in presets}  # finish-time multiplier
+    fractions = {n: 0.0 for n in presets}
+    name_width = max(len(n) for n in presets)
+    n_rows = len(presets)
+    frame_delay = 1.0 / fps
+    total_frames = max(1, int(duration * fps))
+
+    out = sys.stdout
+    out.write("\x1b[?25l")  # hide cursor
+    out.flush()
+
+    drew_once = False
+    t_start = time.perf_counter()
+    try:
+        for frame in range(total_frames + fps):  # extra slack so all bars hit 100%
+            for n in presets:
+                step = speeds[n] / total_frames
+                fractions[n] = min(1.0, fractions[n] + step)
+
+            lines = [
+                render_row(n, parts[n], fractions[n], frame, name_width)
+                for n in presets
+            ]
+
+            if drew_once:
+                out.write(f"\x1b[{n_rows}A")  # cursor up N rows
+            out.write("\r")
+            out.write("\n".join(f"\x1b[2K{l}" for l in lines))
+            out.write("\n")
+            out.flush()
+            drew_once = True
+
+            if all(f >= 1.0 for f in fractions.values()):
+                break
+            time.sleep(frame_delay)
+    finally:
+        out.write("\x1b[?25h")  # show cursor
+        out.flush()
+
+    elapsed = time.perf_counter() - t_start
+    sys.stderr.write(
+        f"\n\x1b[1;92m{len(presets)} presets, {elapsed:.2f}s, "
+        f"{fps} fps target.\x1b[0m\n"
+    )
+
+
+# ----- CLI ----------------------------------------------------------------
+
+def main():
+    ap = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    ap.add_argument("--section", choices=sorted(SECTIONS), default="all",
+                    help="which lineup to show (default: all)")
+    ap.add_argument("--only", nargs="+", default=None,
+                    help="explicit preset list (overrides --section)")
+    ap.add_argument("--duration", type=float, default=6.0,
+                    help="approximate seconds for fastest bar to finish (default 6)")
+    ap.add_argument("--fps", type=int, default=24,
+                    help="target frames per second (default 24)")
+    ap.add_argument("--seed", type=int, default=None,
+                    help="seed for per-preset speed randomness")
+    ap.add_argument("--list", action="store_true",
+                    help="list section lineups and exit")
+    args = ap.parse_args()
+
+    if args.list:
+        for sec, names in SECTIONS.items():
+            valid = [n for n in names if n in themes.THEMES]
+            print(f"\n[{sec}]  ({len(valid)} presets)")
+            for n in valid:
+                print(f"  {n}")
+        return
+
+    if args.only:
+        unknown = [n for n in args.only if n not in themes.THEMES]
+        if unknown:
+            print(f"unknown preset(s): {', '.join(unknown)}", file=sys.stderr)
+            sys.exit(2)
+        picks = args.only
+    else:
+        picks = [n for n in SECTIONS[args.section] if n in themes.THEMES]
+
+    sys.stderr.write(
+        f"\x1b[1;97mBarFlow gallery\x1b[0m — "
+        f"{len(picks)} presets, ~{args.duration:.1f}s, {args.fps} fps\n\n"
+    )
+
+    run_gallery(picks, duration=args.duration, fps=args.fps, seed=args.seed)
+
+
+if __name__ == "__main__":
+    main()

barflow-0.2.2/examples/presets_gallery.py

@@ -0,0 +1,145 @@
+"""Preset & template gallery — neon, ASCII art, emoji, brand palettes.
+
+Run from anywhere:
+    python examples/presets_gallery.py
+    python examples/presets_gallery.py --section neon
+    python examples/presets_gallery.py --only vaporwave hacker rocket_emoji
+    python examples/presets_gallery.py --list
+
+Each preset runs a short animated demo. The header above each bar
+prints the preset name in bright white so you can match what you like.
+
+Sections:
+    neon       — vaporwave, synthwave, lightning, plasma, acid, midnight, ...
+    ascii      — hacker, binary, curly, march, wave, rail_ascii
+    emoji      — rocket, sakura, storm, sparkle, pacman, heart, moon, ...
+    brand      — github_dark, discord, dracula, solarized, nord, gruvbox
+    specialized — tiny, detailed, downloading, building, training
+    classic    — original 27 themes (utilitarian, colorful, playful)
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+from pathlib import Path
+
+_REPO_SRC = Path(__file__).resolve().parent.parent / "src"
+if _REPO_SRC.is_dir() and str(_REPO_SRC) not in sys.path:
+    sys.path.insert(0, str(_REPO_SRC))
+
+import barflow
+from barflow import themes
+
+
+SECTIONS: dict[str, list[str]] = {
+    "neon": [
+        "vaporwave", "synthwave", "lightning", "plasma", "acid",
+        "midnight", "ember", "amber_crt", "miami", "gold_rush",
+        "alien", "deep_sea", "magma", "void", "chevron",
+        "rail_neon", "slash_neon",
+    ],
+    "ascii": [
+        "hacker", "binary", "curly", "march", "wave_ascii", "rail_ascii",
+    ],
+    "emoji": [
+        "fire_emoji", "rocket_emoji", "sakura_emoji", "storm_emoji",
+        "sparkle_emoji", "pacman_emoji", "heart_emoji", "moon_emoji",
+        "weather_emoji",
+    ],
+    "brand": [
+        "github_dark", "discord", "dracula", "solarized", "nord", "gruvbox",
+    ],
+    "specialized": [
+        "tiny", "detailed", "downloading", "building", "training",
+    ],
+    "classic": [
+        "classic", "minimal", "rich_like", "spinner", "mono", "ghost",
+        "ascii", "equals", "brackets",
+        "neon", "pastel", "retro", "matrix", "fire", "ocean", "ice",
+        "sunset", "forest", "cyberpunk",
+        "hearts", "stars", "arrows_march", "pipes", "shade_cool",
+        "line_clean", "double_frame", "round_retro",
+    ],
+}
+
+
+def hdr(name: str):
+    sys.stderr.write(
+        f"\n\x1b[1;97m{name}\x1b[0m  "
+        f"\x1b[90m{'─' * max(2, 40 - len(name))}\x1b[0m\n"
+    )
+    sys.stderr.flush()
+
+
+def section_hdr(name: str):
+    sys.stderr.write(
+        f"\n\x1b[1;95m━━━ {name.upper()} ━━━\x1b[0m\n"
+    )
+    sys.stderr.flush()
+
+
+def run_preset(name: str, *, n: int = 100, delay: float = 0.012,
+               desc: str | None = None):
+    hdr(name)
+    cols = themes.get(name)
+    with barflow.Progress(*cols, total=n, desc=desc or "demo") as p:
+        for _ in range(n):
+            p.tick()
+            time.sleep(delay)
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--section", choices=sorted(SECTIONS), default=None,
+                    help="show only one section")
+    ap.add_argument("--only", nargs="+", default=None,
+                    help="subset of preset names to show")
+    ap.add_argument("--list", action="store_true",
+                    help="print every preset name (grouped by section) and exit")
+    ap.add_argument("--n", type=int, default=100,
+                    help="iterations per preset (default 100)")
+    ap.add_argument("--delay", type=float, default=0.012,
+                    help="sleep per iter in seconds (default 0.012)")
+    args = ap.parse_args()
+
+    if args.list:
+        for sec, names in SECTIONS.items():
+            print(f"\n[{sec}]")
+            for n in names:
+                if n in themes.THEMES:
+                    print(f"  {n}")
+        return
+
+    if args.only:
+        unknown = [n for n in args.only if n not in themes.THEMES]
+        if unknown:
+            print(f"Unknown preset(s): {', '.join(unknown)}", file=sys.stderr)
+            print(f"Run with --list to see all names.", file=sys.stderr)
+            sys.exit(2)
+        for name in args.only:
+            run_preset(name, n=args.n, delay=args.delay)
+        return
+
+    sections = [args.section] if args.section else list(SECTIONS)
+    total = sum(len(SECTIONS[s]) for s in sections)
+    sys.stderr.write(
+        f"\x1b[1;97mBarFlow preset gallery\x1b[0m — "
+        f"{total} presets across {len(sections)} sections, "
+        f"~{args.n * args.delay:.1f}s each\n"
+    )
+
+    for sec in sections:
+        section_hdr(sec)
+        for name in SECTIONS[sec]:
+            if name not in themes.THEMES:
+                continue
+            run_preset(name, n=args.n, delay=args.delay, desc=name)
+
+    sys.stderr.write("\n\x1b[1;92mdone.\x1b[0m\n")
+
+
+if __name__ == "__main__":
+    main()

{barflow-0.2.1 → barflow-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "barflow"
-version = "0.2.1"
+version = "0.2.2"
 description = "Fast Python progress bars with a C++ core. Windows-first."
 readme = "README.md"
 requires-python = ">=3.13"