barflow 0.2.3__tar.gz → 0.3.1__tar.gz

{barflow-0.2.3/src/barflow.egg-info → barflow-0.3.1}/PKG-INFO

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

{barflow-0.2.3 → barflow-0.3.1}/examples/gallery.py

@@ -30,8 +30,10 @@ from __future__ import annotations
 
 import argparse
 import random
+import shutil
 import sys
 import time
+import unicodedata
 from pathlib import Path
 
 _REPO_SRC = Path(__file__).resolve().parent.parent / "src"
@@ -126,6 +128,29 @@ def extract(cols):
 
 # ----- Per-row renderer ---------------------------------------------------
 
+def cell_width(s):
+    """Display columns a glyph string occupies in a terminal.
+
+    Emoji and CJK render two columns wide; combining marks, ZWJ, and variation
+    selectors add none. Over-counting is safe here (the bar just ends a hair
+    short); under-counting is not (the row overflows and the percent clips), so
+    anything in the emoji planes is treated as width 2.
+    """
+    w = 0
+    prev = 0  # display width of the most recent base glyph
+    for ch in s:
+        cp = ord(ch)
+        if cp == 0xFE0F:  # emoji variation selector forces the base to 2 cols
+            w += 2 - prev
+            prev = 2
+            continue
+        if unicodedata.combining(ch) or cp in (0x200D, 0xFE0E):  # ZWJ, text VS
+            continue
+        prev = 2 if unicodedata.east_asian_width(ch) in ("W", "F") or cp >= 0x1F000 else 1
+        w += prev
+    return w
+
+
 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
@@ -173,23 +198,65 @@ def run_gallery(presets, *, duration=6.0, fps=24, seed=None):
         print("nothing to show.", file=sys.stderr)
         return
 
+    # Each preset is one terminal row; the redraw moves the cursor up
+    # exactly len(presets) rows every frame. If the block is taller than the
+    # rows actually free below the header, the cursor-up clamps at the top of
+    # the screen and the overflow scrolls into scrollback every frame — a wall
+    # of the duplicated top row(s). Reserve the header the caller already
+    # printed (title + blank = 2 lines), the trailing footer (1), plus a
+    # one-line safety margin, then trim to what's left.
+    HEADER_LINES, FOOTER_LINES, SAFETY = 2, 1, 1
+    term_lines = shutil.get_terminal_size().lines
+    avail = max(1, term_lines - HEADER_LINES - FOOTER_LINES - SAFETY)
+    if len(presets) > avail:
+        sys.stderr.write(
+            f"\x1b[1;93mTerminal is {term_lines} rows; showing first "
+            f"{avail} of {len(presets)} presets. Resize taller or use "
+            f"--section / --only to pick fewer.\x1b[0m\n\n"
+        )
+        presets = presets[:avail]
+
     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)
+
+    # Cap each bar so the whole row fits one terminal line. A cell costs as many
+    # columns as its fill glyph is wide, so emoji bars (lightning's ⚡, width 2)
+    # need half the cells of an ASCII bar to occupy the same space. Without this
+    # the row overflows the right margin and — now that autowrap is off — the
+    # trailing percent is clipped clean off ("lightning … ⚡⚡ %").
+    term_cols = shutil.get_terminal_size().columns
+    for p in parts.values():
+        fill, _empty, _partials, left, right = p["bar_glyphs"]
+        glyph_w = cell_width(fill) or 1
+        spinner_w = 2 if p["spinner_frames"] else 0
+        # spinner + name + " " + bar-brackets + " 100%" + 1-col margin
+        overhead = (spinner_w + name_width + 1 + cell_width(left)
+                    + cell_width(right) + 5 + 1)
+        max_cells = max(1, (term_cols - overhead) // glyph_w)
+        p["bar_width"] = min(p["bar_width"], max_cells)
     frame_delay = 1.0 / fps
     total_frames = max(1, int(duration * fps))
 
     out = sys.stdout
-    out.write("\x1b[?25l")  # hide cursor
+    # Hide cursor and turn OFF autowrap (DECAWM). Double-width glyphs (emoji
+    # bars like lightning's ⚡, fire 🔥) can push a row past the right margin;
+    # with autowrap on the terminal folds the overflow onto a second physical
+    # line, so the row occupies 2 lines while the redraw only climbs n_rows
+    # lines — a 1-line drift per frame that scrolls the top row off as a wall.
+    # With autowrap off the overflow is clipped at the margin instead, keeping
+    # every row exactly one physical line so the cursor-up math stays exact.
+    out.write("\x1b[?25l\x1b[?7l")
     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%
+            frame_start = time.perf_counter()
             for n in presets:
                 step = speeds[n] / total_frames
                 fractions[n] = min(1.0, fractions[n] + step)
@@ -209,9 +276,13 @@ def run_gallery(presets, *, duration=6.0, fps=24, seed=None):
 
             if all(f >= 1.0 for f in fractions.values()):
                 break
-            time.sleep(frame_delay)
+            # Subtract render+write+flush cost so the real frame rate tracks
+            # the target instead of (target_period + work) per frame.
+            slack = frame_delay - (time.perf_counter() - frame_start)
+            if slack > 0:
+                time.sleep(slack)
     finally:
-        out.write("\x1b[?25h")  # show cursor
+        out.write("\x1b[?7h\x1b[?25h")  # restore autowrap, show cursor
         out.flush()
 
     elapsed = time.perf_counter() - t_start
@@ -234,8 +305,8 @@ def main():
                     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("--fps", type=int, default=60,
+                    help="target frames per second (default 60)")
     ap.add_argument("--seed", type=int, default=None,
                     help="seed for per-preset speed randomness")
     ap.add_argument("--list", action="store_true",

{barflow-0.2.3 → barflow-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "barflow"
-version = "0.2.3"
+version = "0.3.1"
 description = "Fast Python progress bars with a C++ core. Windows-first."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -61,6 +61,7 @@ skip = ["*-musllinux_i686", "*-win32"]
 # The C++17 core uses aligned new/delete, which Clang only emits for a
 # deployment target of macOS 10.13+. CPython 3.12+ already defaults the
 # x86_64 target high enough, but 3.10/3.11 default to 10.9 and fail to
-# compile. Pin the floor to 10.13 for every macOS build (arm64 is always
-# 11.0+ regardless, so this only lifts the x86_64 leg).
-environment = { MACOSX_DEPLOYMENT_TARGET = "10.13" }
+# compile. cibuildwheel now enforces a 10.15 floor, so pin to that for
+# every macOS build (arm64 is always 11.0+ regardless, so this only lifts
+# the x86_64 leg). 10.15 still satisfies the aligned-new requirement.
+environment = { MACOSX_DEPLOYMENT_TARGET = "10.15" }

{barflow-0.2.3 → barflow-0.3.1}/src/barflow/__init__.py

@@ -8,7 +8,7 @@ asyncio wrapper are lazy-loaded via `__getattr__` on first access.
 from . import _core
 from ._core import Tracker
 
-__version__ = "0.2.3"
+__version__ = "0.3.1"
 __all__ = ["Progress", "Tracker", "track", "__version__"]
 
 

{barflow-0.2.3 → barflow-0.3.1}/src/barflow/_core.cpp

@@ -244,6 +244,14 @@ struct ProgressState {
     std::thread             render_thread;
     std::once_flag          close_once;
 
+    // pause()/resume() let an external writer (e.g. an output redirector)
+    // suspend the render thread, emit lines on the cleared bar area, and
+    // then have the bar repainted below. `paused` is checked by the render
+    // loop on every wakeup; `force_render` makes the first frame after
+    // resume repaint even if no counter moved while paused.
+    std::atomic<bool>       paused{false};
+    bool                    force_render{false};   // guarded by render_mtx
+
     double min_interval{0.05};
     bool   disable{false};
     bool   vt_enabled{false};
@@ -1273,6 +1281,49 @@ void render_frame(ProgressState* st) {
             if (pending_skip > 0) {
                 append_cursor_right(buf, pending_skip);
             }
+            // The cursor now sits at the end of this row's actual content
+            // (re-emitted columns end there; trailing matched columns were
+            // CUF-skipped to their end). Erase from here to end of line so a
+            // column that SHRANK since last frame — e.g. a variable-width
+            // callback/postfix going from "subprocess" to "sqlite3" — doesn't
+            // leave stale trailing characters ("sqlite3sses"). EL0 (\x1b[K)
+            // clears only rightward, so already-emitted columns are safe.
+            if (st->vt_enabled) {
+                buf.append("\x1b[K", 3);
+                // EL0 clears only the current physical row's tail. If this
+                // line wrapped across multiple rows last frame and shrank to
+                // fewer rows now, the surplus old wrapped row(s) below are
+                // left on screen — and once last_task_cells shrinks the next
+                // frame's cursor-up walk won't reach them, making the stale
+                // rows permanent. Erase each surplus row, then walk back up
+                // (vertical moves preserve the column) so the cursor stays at
+                // the end of this row's content for the downstream newline.
+                if (term_w > 0) {
+                    int cur_total = 0, prev_total = 0;
+                    for (size_t ci = 0; ci < ncols; ++ci) {
+                        if (!visible_cols[ci]) continue;
+                        cur_total  += this_cells[ci];
+                        prev_total += prev_cells[ci];
+                    }
+                    int cur_rows  = (cur_total  + term_w - 1) / term_w;
+                    int prev_rows = (prev_total + term_w - 1) / term_w;
+                    if (cur_rows  < 1) cur_rows  = 1;
+                    if (prev_rows < 1) prev_rows = 1;
+                    if (prev_rows > cur_rows) {
+                        int surplus = prev_rows - cur_rows;
+                        for (int k = 0; k < surplus; ++k) {
+                            buf.append("\x1b[1B", 4);   // down one row, no scroll
+                            buf.append("\x1b[2K", 4);   // erase that stale row
+                        }
+                        buf.append("\x1b[", 2);
+                        char tmp[20];
+                        size_t nn = u64_to_chars(
+                            tmp, static_cast<uint64_t>(surplus));
+                        buf.append(tmp, nn);
+                        buf.push_back('A');             // walk back up to content row
+                    }
+                }
+            }
         } else {
             // Full emit: concatenate every visible column's bytes.
             // When use_delta was true globally we skipped the up-front
@@ -1340,11 +1391,17 @@ void render_loop(ProgressState* st) {
         st->render_cv.wait_for(lock, interval);
         if (!st->running.load(std::memory_order_acquire)) break;
 
+        // Suspended for external writing: do not touch the terminal until
+        // resume() clears the flag. pause() already erased the bar area, so
+        // the external writer owns the screen meanwhile.
+        if (st->paused.load(std::memory_order_acquire)) continue;
+
         // Render unconditionally if there is a spinner (it animates even
-        // with no producer progress); otherwise only if counters moved.
-        // The spinner flag is cached at column setup so we don't re-scan
-        // the column vector on every wakeup (every `min_interval`).
-        bool any_dirty = st->has_spinner_col;
+        // with no producer progress) or if a resume forced a repaint;
+        // otherwise only if counters moved. The spinner flag is cached at
+        // column setup so we don't re-scan the column vector on every
+        // wakeup (every `min_interval`).
+        bool any_dirty = st->has_spinner_col || st->force_render;
         if (!any_dirty) {
             for (auto& t : st->tasks) {
                 if (t->completed.load(std::memory_order_acquire) != t->last_snapshot) {
@@ -1353,7 +1410,10 @@ void render_loop(ProgressState* st) {
                 }
             }
         }
-        if (any_dirty) render_frame(st);
+        if (any_dirty) {
+            render_frame(st);
+            st->force_render = false;
+        }
     }
     // Final frame, still under the lock.
     render_frame(st);
@@ -1735,15 +1795,26 @@ PyObject* Progress_update(PyProgress* self,
     if (nargs >= 2) {
         if (barflow_pylong_to_u64(args[1], &n) < 0) return nullptr;
     }
+    // Drop the GIL around render_mtx: render_frame holds the lock while a
+    // CallbackColumn re-enters Python, so a GIL-holding caller blocked here
+    // would deadlock. Defer the out-of-range error until the GIL is back.
     Task* target = nullptr;
+    bool  oob    = false;
+    auto* st     = self->state;
+    Py_BEGIN_ALLOW_THREADS
     {
-        std::lock_guard<std::mutex> lg(self->state->render_mtx);
+        std::lock_guard<std::mutex> lg(st->render_mtx);
         if (task_id < 0 ||
-            static_cast<size_t>(task_id) >= self->state->tasks.size()) {
-            PyErr_SetString(PyExc_IndexError, "task_id out of range");
-            return nullptr;
+            static_cast<size_t>(task_id) >= st->tasks.size()) {
+            oob = true;
+        } else {
+            target = st->tasks[static_cast<size_t>(task_id)].get();
         }
-        target = self->state->tasks[static_cast<size_t>(task_id)].get();
+    }
+    Py_END_ALLOW_THREADS
+    if (oob) {
+        PyErr_SetString(PyExc_IndexError, "task_id out of range");
+        return nullptr;
     }
     target->completed.fetch_add(n, std::memory_order_relaxed);
     Py_RETURN_NONE;
@@ -1766,19 +1837,26 @@ PyObject* Progress_add_task(PyProgress* self, PyObject* args, PyObject* kwds) {
     task->start_time_ns = now_ns();
     if (desc) task->description = desc;
     Task* raw = task.get();
-    int id;
+    int   id;
+    // Drop the GIL around render_mtx (see set_total): render_frame holds the
+    // lock while a CallbackColumn re-enters Python. The task is fully built
+    // above; only the vector push + task0 publish happen under the lock, none
+    // of which touch Python state, so they are safe with the GIL released.
+    auto* st = self->state;
+    Py_BEGIN_ALLOW_THREADS
     {
-        std::lock_guard<std::mutex> lg(self->state->render_mtx);
-        id = static_cast<int>(self->state->tasks.size());
+        std::lock_guard<std::mutex> lg(st->render_mtx);
+        id = static_cast<int>(st->tasks.size());
         task->id = id;
-        self->state->tasks.push_back(std::move(task));
+        st->tasks.push_back(std::move(task));
         // Publish task0 if this is the first task. CAS so concurrent
         // first-add races resolve to whichever wins.
         Task* expected = nullptr;
-        self->state->task0.compare_exchange_strong(
+        st->task0.compare_exchange_strong(
             expected, raw,
             std::memory_order_release, std::memory_order_relaxed);
     }
+    Py_END_ALLOW_THREADS
     return PyLong_FromLong(id);
 }
 
@@ -1796,16 +1874,27 @@ PyObject* Progress_set_total(PyProgress* self,
     if (PyErr_Occurred()) return nullptr;
     uint64_t total = 0;
     if (barflow_pylong_to_u64(args[1], &total) < 0) return nullptr;
+    // Drop the GIL around render_mtx: render_frame holds the lock while a
+    // CallbackColumn re-enters Python, so a GIL-holding caller blocked here
+    // would deadlock. Defer the out-of-range error until the GIL is back.
+    bool oob = false;
+    auto* st = self->state;
+    Py_BEGIN_ALLOW_THREADS
     {
-        std::lock_guard<std::mutex> lg(self->state->render_mtx);
+        std::lock_guard<std::mutex> lg(st->render_mtx);
         if (task_id < 0 ||
-            static_cast<size_t>(task_id) >= self->state->tasks.size()) {
-            PyErr_SetString(PyExc_IndexError, "task_id out of range");
-            return nullptr;
+            static_cast<size_t>(task_id) >= st->tasks.size()) {
+            oob = true;
+        } else {
+            st->tasks[static_cast<size_t>(task_id)]->total = total;
         }
-        self->state->tasks[static_cast<size_t>(task_id)]->total = total;
     }
-    self->state->render_cv.notify_one();
+    Py_END_ALLOW_THREADS
+    if (oob) {
+        PyErr_SetString(PyExc_IndexError, "task_id out of range");
+        return nullptr;
+    }
+    st->render_cv.notify_one();
     Py_RETURN_NONE;
 }
 
@@ -1830,17 +1919,27 @@ PyObject* Progress_set_task_description(PyProgress* self,
     Py_ssize_t dlen = 0;
     const char* ds = PyUnicode_AsUTF8AndSize(args[1], &dlen);
     if (!ds) return nullptr;
+    // ds points into args[1]'s cached UTF-8 buffer; args[1] is kept alive by
+    // the caller and not mutated, so reading it with the GIL dropped is safe.
+    bool oob = false;
+    auto* st = self->state;
+    Py_BEGIN_ALLOW_THREADS
     {
-        std::lock_guard<std::mutex> lg(self->state->render_mtx);
+        std::lock_guard<std::mutex> lg(st->render_mtx);
         if (task_id < 0 ||
-            static_cast<size_t>(task_id) >= self->state->tasks.size()) {
-            PyErr_SetString(PyExc_IndexError, "task_id out of range");
-            return nullptr;
+            static_cast<size_t>(task_id) >= st->tasks.size()) {
+            oob = true;
+        } else {
+            st->tasks[static_cast<size_t>(task_id)]->description.assign(
+                ds, static_cast<size_t>(dlen));
         }
-        self->state->tasks[static_cast<size_t>(task_id)]->description.assign(
-            ds, static_cast<size_t>(dlen));
     }
-    self->state->render_cv.notify_one();
+    Py_END_ALLOW_THREADS
+    if (oob) {
+        PyErr_SetString(PyExc_IndexError, "task_id out of range");
+        return nullptr;
+    }
+    st->render_cv.notify_one();
     Py_RETURN_NONE;
 }
 
@@ -1854,16 +1953,23 @@ PyObject* Progress_set_description(PyProgress* self, PyObject* desc_obj) {
     Py_ssize_t dlen = 0;
     const char* ds = PyUnicode_AsUTF8AndSize(desc_obj, &dlen);
     if (!ds) return nullptr;
+    bool empty = false;
+    auto* st = self->state;
+    Py_BEGIN_ALLOW_THREADS
     {
-        std::lock_guard<std::mutex> lg(self->state->render_mtx);
-        if (self->state->tasks.empty()) {
-            PyErr_SetString(PyExc_IndexError, "no tasks");
-            return nullptr;
+        std::lock_guard<std::mutex> lg(st->render_mtx);
+        if (st->tasks.empty()) {
+            empty = true;
+        } else {
+            st->tasks[0]->description.assign(ds, static_cast<size_t>(dlen));
         }
-        self->state->tasks[0]->description.assign(
-            ds, static_cast<size_t>(dlen));
     }
-    self->state->render_cv.notify_one();
+    Py_END_ALLOW_THREADS
+    if (empty) {
+        PyErr_SetString(PyExc_IndexError, "no tasks");
+        return nullptr;
+    }
+    st->render_cv.notify_one();
     Py_RETURN_NONE;
 }
 
@@ -1892,6 +1998,11 @@ PyObject* Progress_write_above(PyProgress* self, PyObject* text_obj) {
     const char* text = PyUnicode_AsUTF8AndSize(text_obj, &len);
     if (!text) return nullptr;
 
+    // Drop the GIL around render_mtx (see set_total): render_frame holds the
+    // lock while a CallbackColumn re-enters Python. `text` points into
+    // text_obj's cached UTF-8 buffer, which stays valid (caller holds a ref,
+    // no mutation) while the GIL is released.
+    Py_BEGIN_ALLOW_THREADS
     {
         std::lock_guard<std::mutex> lg(self->state->render_mtx);
         auto* st = self->state;
@@ -1944,10 +2055,83 @@ PyObject* Progress_write_above(PyProgress* self, PyObject* text_obj) {
         // — invalidate so the next render_frame does a full emit.
         st->delta_valid = false;
     }
+    Py_END_ALLOW_THREADS
     self->state->render_cv.notify_one();
     Py_RETURN_NONE;
 }
 
+// pause() — suspend the render thread and erase the bar area, leaving the
+// cursor at column 0 of the cleared region so an external writer can emit
+// lines there without the bar repainting on top. Mirrors the walk-back +
+// erase that write_above performs. Idempotent and safe to call when the bar
+// is disabled or closed (no-op). Pairs with resume().
+PyObject* Progress_pause(PyProgress* self, PyObject* /*args*/) {
+    auto* st = self->state;
+    if (st->disable || st->closed) Py_RETURN_NONE;
+    // Release the GIL before taking render_mtx. The render thread holds
+    // render_mtx across render_frame, which re-enters Python (PyGILState)
+    // for any CallbackColumn — so a GIL-holding caller that blocked on
+    // render_mtx here would deadlock against the render thread waiting on
+    // the GIL. Dropping the GIL lets the render thread finish and release
+    // the lock. write_bytes touches no Python state, so it is GIL-free safe.
+    Py_BEGIN_ALLOW_THREADS
+    {
+        std::lock_guard<std::mutex> lg(st->render_mtx);
+        // Acquiring render_mtx guarantees no frame is mid-flight: the render
+        // loop only holds the lock outside its cv wait, so once we hold it
+        // the last frame is fully written.
+        st->paused.store(true, std::memory_order_release);
+
+        if (st->vt_enabled) {
+            std::string& buf = st->scratch;
+            buf.clear();
+            int term_w = query_terminal_width(st);
+            if (!st->last_task_cells.empty()) {
+                int total_rows = 0;
+                for (int c : st->last_task_cells) {
+                    int r = (term_w > 0) ? ((c + term_w - 1) / term_w) : 1;
+                    if (r < 1) r = 1;
+                    total_rows += r;
+                }
+                if (total_rows > 0) {
+                    buf.append("\x1b[", 2);
+                    char tmp[20];
+                    size_t n = u64_to_chars(tmp, static_cast<uint64_t>(total_rows));
+                    buf.append(tmp, n);
+                    buf.push_back('A');
+                }
+            }
+            buf.push_back('\r');
+            buf.append("\x1b[J", 3);   // erase from cursor to end of screen
+            write_bytes(st, buf.data(), buf.size());
+            st->last_rendered_lines = 0;
+            st->last_task_cells.clear();
+            st->delta_valid = false;   // resume repaints from scratch
+        }
+    }
+    Py_END_ALLOW_THREADS
+    Py_RETURN_NONE;
+}
+
+// resume() — undo pause(): clear the suspend flag and force the next render
+// loop wakeup to repaint the bar below whatever the external writer emitted.
+PyObject* Progress_resume(PyProgress* self, PyObject* /*args*/) {
+    auto* st = self->state;
+    if (st->disable || st->closed) Py_RETURN_NONE;
+    // Drop the GIL before render_mtx for the same reason as pause(): the
+    // render thread may hold render_mtx while waiting on the GIL inside a
+    // CallbackColumn.
+    Py_BEGIN_ALLOW_THREADS
+    {
+        std::lock_guard<std::mutex> lg(st->render_mtx);
+        st->paused.store(false, std::memory_order_release);
+        st->force_render = true;
+    }
+    Py_END_ALLOW_THREADS
+    st->render_cv.notify_one();
+    Py_RETURN_NONE;
+}
+
 PyObject* Progress_get_completed(PyProgress* self, void* /*closure*/) {
     Task* t = self->state->task0.load(std::memory_order_acquire);
     uint64_t v = t ? t->completed.load(std::memory_order_relaxed) : 0;
@@ -1955,11 +2139,16 @@ PyObject* Progress_get_completed(PyProgress* self, void* /*closure*/) {
 }
 
 PyObject* Progress_get_n_tasks(PyProgress* self, void* /*closure*/) {
+    // Drop the GIL around render_mtx (see set_total): render_frame may hold
+    // the lock while a CallbackColumn re-enters Python and waits on the GIL.
     Py_ssize_t n;
+    auto* st = self->state;
+    Py_BEGIN_ALLOW_THREADS
     {
-        std::lock_guard<std::mutex> lg(self->state->render_mtx);
-        n = static_cast<Py_ssize_t>(self->state->tasks.size());
+        std::lock_guard<std::mutex> lg(st->render_mtx);
+        n = static_cast<Py_ssize_t>(st->tasks.size());
     }
+    Py_END_ALLOW_THREADS
     return PyLong_FromSsize_t(n);
 }
 
@@ -1989,6 +2178,10 @@ PyMethodDef Progress_methods[] = {
         "Force an immediate render frame."},
     {"write_above",reinterpret_cast<PyCFunction>(Progress_write_above),
         METH_O, "Emit text above the bar area without tearing."},
+    {"pause",      reinterpret_cast<PyCFunction>(Progress_pause),   METH_NOARGS,
+        "Suspend the render thread and clear the bar so external writes are clean."},
+    {"resume",     reinterpret_cast<PyCFunction>(Progress_resume),  METH_NOARGS,
+        "Resume rendering after pause(), repainting the bar."},
     {nullptr, nullptr, 0, nullptr}
 };
 
@@ -2045,21 +2238,34 @@ int Tracker_init(PyTracker* self, PyObject* args, PyObject* kwds) {
     Py_INCREF(progress);
     self->progress = reinterpret_cast<PyProgress*>(progress);
 
+    // Drop the GIL around render_mtx (see set_total): render_frame holds the
+    // lock while a CallbackColumn re-enters Python and waits on the GIL.
+    // Defer error reporting until the GIL is reacquired.
+    enum { LOOKUP_OK, LOOKUP_EMPTY, LOOKUP_OOB } lookup = LOOKUP_OK;
+    auto* st = self->progress->state;
+    Py_BEGIN_ALLOW_THREADS
     {
         // Lock the vector for the lookup. The Task* itself is heap-stable
         // (unique_ptr) so the cached pointer remains valid for the
         // lifetime of the Progress instance.
-        auto* st = self->progress->state;
         std::lock_guard<std::mutex> lg(st->render_mtx);
         if (st->tasks.empty()) {
-            PyErr_SetString(PyExc_RuntimeError, "progress has no tasks");
-            return -1;
-        }
-        if (task_id < 0 || static_cast<size_t>(task_id) >= st->tasks.size()) {
-            PyErr_SetString(PyExc_IndexError, "task_id out of range");
-            return -1;
+            lookup = LOOKUP_EMPTY;
+        } else if (task_id < 0 ||
+                   static_cast<size_t>(task_id) >= st->tasks.size()) {
+            lookup = LOOKUP_OOB;
+        } else {
+            self->task = st->tasks[static_cast<size_t>(task_id)].get();
         }
-        self->task = st->tasks[static_cast<size_t>(task_id)].get();
+    }
+    Py_END_ALLOW_THREADS
+    if (lookup == LOOKUP_EMPTY) {
+        PyErr_SetString(PyExc_RuntimeError, "progress has no tasks");
+        return -1;
+    }
+    if (lookup == LOOKUP_OOB) {
+        PyErr_SetString(PyExc_IndexError, "task_id out of range");
+        return -1;
     }
     self->closed = 0;
     self->owns_progress = owns;

{barflow-0.2.3 → barflow-0.3.1}/src/barflow/themes.py

@@ -21,6 +21,8 @@ matches their app's visual identity.
 
 from __future__ import annotations
 
+import random as _random
+
 from . import columns as c
 
 
@@ -778,6 +780,22 @@ def training():
     ]
 
 
+# ---------------------------------------------------------------------------
+# Meta
+# ---------------------------------------------------------------------------
+
+def random_theme():
+    """Pick a random theme each call and return its columns."""
+    # Collapse aliases, drop self, so every pick is a distinct real theme.
+    # dict.fromkeys de-dupes by identity while preserving THEMES' insertion
+    # order — a plain set would iterate in a hash-randomized order, defeating
+    # reproducibility under a seeded RNG.
+    pool = list(dict.fromkeys(
+        fn for fn in THEMES.values() if fn is not random_theme
+    ))
+    return _random.choice(pool)()
+
+
 # ---------------------------------------------------------------------------
 # Registry
 # ---------------------------------------------------------------------------
@@ -875,6 +893,9 @@ THEMES = {
     "downloading":  downloading,
     "building":     building,
     "training":     training,
+
+    # Meta
+    "random":       random_theme,
 }
 
 
@@ -922,4 +943,6 @@ __all__ = [
     "github_dark", "discord", "dracula", "solarized", "nord", "gruvbox",
     # Specialized
     "tiny", "detailed", "downloading", "building", "training",
+    # Meta
+    "random_theme",
 ]

{barflow-0.2.3 → barflow-0.3.1/src/barflow.egg-info}/PKG-INFO

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