Add optional native iterator accelerator: ~5 ns/iter, ~4x faster than rich

`ProgressBar.__iter__` now dispatches to `speedups.progressbar.FastBarIterator`
(the `progressbar2[fast]` extra) when it is importable, falling back to the
pure-Python generator otherwise. The native iterator counts items in a C field
and only calls back into Python at redraw crossings via a small protocol
(`_fast_begin`/`_fast_tick`/`_fast_end`/`_fast_end_dirty`), reusing the existing
gate/redraw/calibration machinery so the redraw cadence is identical. The only
behavioural difference is that `value`/`previous_value` are synced at crossings
rather than every iteration, so reads between redraws lag slightly (like
tqdm.n); `PROGRESSBAR_DISABLE_FASTPATH=1` forces the pure-Python path.

This makes progressbar2 the fastest progress bar measured: ~5 ns/iter vs rich
19, tqdm 55. Pure Python stays ~30 ns (no native build), still ~1.8x faster
than tqdm and 2nd to rich.

Also:
- hoist `_gate_enabled` to a local in the pure-Python iterator (free, no
  behaviour change), trimming the fallback hot path a few ns.
- conftest `disable_native_accelerator` autouse fixture forces the pure-Python
  path for the rest of the suite; native behaviour is covered explicitly in
  tests/test_native_accelerator.py (dispatch + hooks covered without the
  compiled package via a fake/direct calls, so CI stays at 100% coverage; real
  end-to-end equivalence + issue #212 break/exception cleanup tests run where
  speedups is installed).
- refresh benchmark artifacts + README performance section.

Author: wolph

README.rst

@@ -76,27 +76,37 @@ automatically enable features like auto-resizing when the system supports it.
 Performance
 ******************************************************************************
 
-Wrapping a loop with ``progressbar2`` is cheap. On the benchmark machine
-(CPython 3.13, macOS arm64) it adds only about **31 nanoseconds per
-iteration** over a bare loop -- roughly **1.8x faster than tqdm** and second
-only to ``rich``, while being far ahead of the rest:
-
-================  ==================
-Library           Overhead per iter
-================  ==================
-rich              19 ns
-progressbar2      31 ns
-tqdm              56 ns
-alive-progress    246 ns
-click             1919 ns
-================  ==================
-
-The per-iteration cost is dominated by deciding *whether* to redraw, not by
-drawing: ``progressbar2`` keeps an integer "next update" gate so the common
-iteration is just an increment and a couple of cheap stores, only entering the
-(rate-limited) redraw machinery a few times per second. Behaviour is unchanged
--- the same widgets, the same redraw cadence, and ``value``/``previous_value``
-stay byte-identical to the pre-gate implementation on every iteration.
+Wrapping a loop with ``progressbar2`` is cheap -- and with the optional native
+accelerator it is the **fastest** progress bar available. On the benchmark
+machine (CPython 3.13, macOS arm64) the per-iteration overhead over a bare loop
+is:
+
+================  ==================  ==================
+Library           Overhead per iter  vs progressbar2
+================  ==================  ==================
+**progressbar2**  **5 ns** *(fast)*  baseline
+rich              19 ns               ~4x slower
+tqdm              55 ns               ~11x slower
+alive-progress    249 ns              ~52x slower
+click             1885 ns             ~390x slower
+================  ==================  ==================
+
+Two tiers, same API:
+
+- **Pure Python (default):** ~30 ns/iter -- roughly **1.8x faster than tqdm**,
+  second only to ``rich``, with **no native build required**. An integer "next
+  update" gate keeps the common iteration to an increment, a compare and a
+  couple of cheap stores, only entering the (rate-limited) redraw machinery a
+  few times per second. Behaviour is unchanged: same widgets, same redraw
+  cadence, and ``value``/``previous_value`` stay byte-identical to the
+  pre-gate implementation on every iteration.
+- **Native accelerator (**\ ``pip install progressbar2[fast]``\ **):** ~5 ns/iter,
+  **~4x faster than rich**. A small compiled (Cython) iterator counts in a C
+  field and only calls back into Python at redraw crossings. It engages
+  automatically when installed; the only behavioural difference is that
+  ``bar.value`` is synced at redraw crossings rather than every iteration, so
+  reads between redraws lag slightly (like ``tqdm.n``). Set
+  ``PROGRESSBAR_DISABLE_FASTPATH=1`` to force the pure-Python path.
 
 The benchmark is fully reproducible and pits ``progressbar2`` against ``tqdm``,
 ``rich``, ``alive-progress`` and ``click`` across iteration overhead, forced

benchmarks/chart.png

@@ -1,6 +1,6 @@
 # Python progress-bar library benchmark
 
-_Generated 2026-06-23 17:30. Subject: **progressbar2** (version 4.5.0)._
+_Generated 2026-06-24 00:53. Subject: **progressbar2** (version 4.5.0)._
 
 Compares `progressbar2` against the most common alternatives across three independent dimensions. All rendered output is written to a real pseudo-terminal (pty) that is continuously drained, so every library believes it is attached to a TTY and actually draws — the comparison is apples-to-apples, not "is output suppressed when piped".
 
@@ -27,47 +27,47 @@ Compares `progressbar2` against the most common alternatives across three indepe
 
 Idiomatic "wrap my loop" call with each library's **default** settings, over **1,000,000** iterations with a trivial body. This is the real-world cost of dropping a progress bar around a fast loop. Overhead = (wrapped time − bare-loop time) / iterations. Lower is faster.
 
-Bare loop baseline: **5.59 ms** for 1,000,000 iterations.
+Bare loop baseline: **5.53 ms** for 1,000,000 iterations.
 
 | Library | Total time | Overhead/iter | vs progressbar2 |
 |---|--:|--:|--:|
-| rich | 24.7 ms | 19.1 ns | 0.63x |
-| **progressbar2** | 36.1 ms | 30.5 ns | baseline |
-| tqdm | 61.4 ms | 55.8 ns | 1.83x |
-| alive-progress | 251.2 ms | 245.6 ns | 8.05x |
-| click | 1924.1 ms | 1918.5 ns | 62.84x |
+| **progressbar2** | 10.4 ms | 4.8 ns | baseline |
+| rich | 24.7 ms | 19.2 ns | 3.97x |
+| tqdm | 60.2 ms | 54.6 ns | 11.30x |
+| alive-progress | 254.9 ms | 249.4 ns | 51.58x |
+| click | 1890.7 ms | 1885.2 ns | 389.96x |
 
 ## B. Forced per-update render cost
 
 Rendering **forced on every single update** over **30,000** updates — i.e. the cost of one full bar redraw, throttling disabled. Lower is faster.
 
 | Library | Total time | Per rendered update | vs progressbar2 |
 |---|--:|--:|--:|
-| tqdm | 331.4 ms | 11.04 us | 0.43x |
-| **progressbar2** | 769.4 ms | 25.64 us | baseline |
-| rich | 5173.6 ms | 172.45 us | 6.73x |
+| tqdm | 318.1 ms | 10.60 us | 0.44x |
+| **progressbar2** | 717.3 ms | 23.91 us | baseline |
+| rich | 5142.4 ms | 171.41 us | 7.17x |
 
 Excluded from this panel (no per-update force-render API):
 - **alive-progress** — renders on a background timer thread; no per-update render API
 - **click** — self-throttles writes (renders only when the drawn line changes); no force-every-update API
 
 ## C. Cold import time
 
-Wall-clock cost of importing the library in a fresh interpreter (minimum of 9 runs), with bare-interpreter startup (17 ms) subtracted. Matters for short-lived CLIs. Lower is lighter.
+Wall-clock cost of importing the library in a fresh interpreter (minimum of 9 runs), with bare-interpreter startup (16 ms) subtracted. Matters for short-lived CLIs. Lower is lighter.
 
 | Library | Import time (net) |
 |---|--:|
-| alive-progress | 8.6 ms |
-| tqdm | 23.5 ms |
-| click | 24.1 ms |
-| **progressbar2** | 45.3 ms |
-| rich | 49.6 ms |
+| alive-progress | 8.3 ms |
+| tqdm | 21.6 ms |
+| click | 23.0 ms |
+| **progressbar2** | 46.0 ms |
+| rich | 47.0 ms |
 
 ## Takeaways
 
-- **Default per-iteration overhead:** `progressbar2` is 31 ns/iter, ranking #2 of 5. `rich` is the lightest per iteration (19 ns), `click` the heaviest (1919 ns).
-  - `rich` and `tqdm` win here because their default settings do almost no per-iteration work (counter compare / background refresh thread); `progressbar2` calls a monotonic clock and evaluates its redraw predicate on every `update()`.
-- **Render cost:** when a redraw actually happens, `progressbar2` draws one update in 25.6 us — 2.32x the cheapest (`tqdm`) but 6.7x cheaper than rich's full-display re-render.
+- **Default per-iteration overhead:** `progressbar2` is 5 ns/iter, ranking #1 of 5. `progressbar2` is the lightest per iteration (5 ns), `click` the heaviest (1885 ns).
+  - `progressbar2` and `tqdm` win here because their default settings do almost no per-iteration work (counter compare / background refresh thread); `progressbar2` calls a monotonic clock and evaluates its redraw predicate on every `update()`.
+- **Render cost:** when a redraw actually happens, `progressbar2` draws one update in 23.9 us — 2.26x the cheapest (`tqdm`) but 7.2x cheaper than rich's full-display re-render.
 - **Why both numbers matter:** `progressbar2` caps redraws at ~20/sec by default (50 ms floor), so in practice the cheap render in B fires rarely and the per-iteration cost in A dominates real workloads.
 - **Import weight:** `progressbar2` is mid-pack to import; `alive-progress` is the lightest, `rich` the heaviest.
 

benchmarks/report.md

@@ -20,53 +20,53 @@
     "term": "80x24"
   },
   "scenario_a_default_overhead": {
-    "baseline_min_s": 0.00558699993416667,
-    "baseline_median_s": 0.005599833093583584,
+    "baseline_min_s": 0.005534708965569735,
+    "baseline_median_s": 0.005606417078524828,
     "libs": {
       "progressbar2": {
-        "total_min_s": 0.03611662518233061,
-        "total_median_s": 0.037002416793257,
-        "overhead_ns_per_iter": 30.52962524816394
+        "total_min_s": 0.010368958115577698,
+        "total_median_s": 0.010549040976911783,
+        "overhead_ns_per_iter": 4.834249150007963
       },
       "tqdm": {
-        "total_min_s": 0.061426167376339436,
-        "total_median_s": 0.06293316604569554,
-        "overhead_ns_per_iter": 55.839167442172766
+        "total_min_s": 0.06017666729167104,
+        "total_median_s": 0.061196332797408104,
+        "overhead_ns_per_iter": 54.6419583261013
       },
       "rich": {
-        "total_min_s": 0.024669166654348373,
-        "total_median_s": 0.02482037479057908,
-        "overhead_ns_per_iter": 19.082166720181704
+        "total_min_s": 0.02470291731879115,
+        "total_median_s": 0.024790583178400993,
+        "overhead_ns_per_iter": 19.168208353221416
       },
       "alive-progress": {
-        "total_min_s": 0.2512250836007297,
-        "total_median_s": 0.2683616247959435,
-        "overhead_ns_per_iter": 245.63808366656306
+        "total_min_s": 0.25490304082632065,
+        "total_median_s": 0.2645676671527326,
+        "overhead_ns_per_iter": 249.3683318607509
       },
       "click": {
-        "total_min_s": 1.9241157919168472,
-        "total_median_s": 1.9306053328327835,
-        "overhead_ns_per_iter": 1918.5287919826806
+        "total_min_s": 1.89069899963215,
+        "total_median_s": 1.907758583780378,
+        "overhead_ns_per_iter": 1885.1642906665802
       }
     }
   },
   "scenario_b_forced_render": {
-    "baseline_min_s": 0.0001589590683579445,
+    "baseline_min_s": 0.00016704201698303223,
     "libs": {
       "progressbar2": {
-        "total_min_s": 0.7693966659717262,
-        "total_median_s": 0.7766300840303302,
-        "per_update_us": 25.64125689677894
+        "total_min_s": 0.7173186247237027,
+        "total_median_s": 0.719321624841541,
+        "per_update_us": 23.905052756890655
       },
       "tqdm": {
-        "total_min_s": 0.33136308286339045,
-        "total_median_s": 0.3320189160294831,
-        "per_update_us": 11.040137459834416
+        "total_min_s": 0.3181296670809388,
+        "total_median_s": 0.31852462515234947,
+        "per_update_us": 10.598754168798527
       },
       "rich": {
-        "total_min_s": 5.17360516730696,
-        "total_median_s": 5.191705749835819,
-        "per_update_us": 172.4482069412867
+        "total_min_s": 5.1424090838991106,
+        "total_median_s": 5.166477249935269,
+        "per_update_us": 171.40806806273758
       }
     },
     "excluded": {
@@ -75,27 +75,27 @@
     }
   },
   "scenario_c_import_time": {
-    "interpreter_baseline_s": 0.016710625030100346,
+    "interpreter_baseline_s": 0.015609750058501959,
     "libs": {
       "progressbar2": {
-        "total_min_s": 0.06196920806542039,
-        "net_ms": 45.258583035320044
+        "total_min_s": 0.06156795937567949,
+        "net_ms": 45.958209317177534
       },
       "tqdm": {
-        "total_min_s": 0.04024833394214511,
-        "net_ms": 23.537708912044764
+        "total_min_s": 0.03719387482851744,
+        "net_ms": 21.584124770015478
       },
       "rich": {
-        "total_min_s": 0.06633466714993119,
-        "net_ms": 49.62404211983085
+        "total_min_s": 0.06259091570973396,
+        "net_ms": 46.981165651232004
       },
       "alive-progress": {
-        "total_min_s": 0.025270250160247087,
-        "net_ms": 8.559625130146742
+        "total_min_s": 0.023956042248755693,
+        "net_ms": 8.346292190253735
       },
       "click": {
-        "total_min_s": 0.04085325030609965,
-        "net_ms": 24.142625275999308
+        "total_min_s": 0.03865604242309928,
+        "net_ms": 23.04629236459732
       }
     }
   }

benchmarks/results.json

@@ -2,6 +2,7 @@
 
 import abc
 import contextlib
+import importlib
 import itertools
 import logging
 import math
@@ -30,6 +31,18 @@
 )
 from .terminal import os_specific
 
+try:
+    # Optional native accelerator, shipped as the ``progressbar2[fast]`` extra
+    # (the separate ``speedups`` package). When importable, the iterator path
+    # uses it automatically; otherwise we fall back to the pure-Python gate.
+    # Loaded via importlib so type checkers don't try to resolve the optional
+    # compiled module when it is absent.
+    _FastBarIterator = importlib.import_module(
+        'speedups.progressbar',
+    ).FastBarIterator
+except Exception:  # pragma: no cover - environmental (absent / ABI mismatch)
+    _FastBarIterator = None
+
 logger = logging.getLogger(__name__)
 
 # float also accepts integers and longs but we don't want an explicit union
@@ -928,6 +941,20 @@ def __call__(self, iterable, max_value=None):
         return self
 
     def __iter__(self):
+        # Dispatch to the optional native iterator when available, else the
+        # pure-Python generator. The native path counts in C and syncs
+        # `value`/`previous_value` only at redraw crossings (so they lag
+        # mid-loop, like `tqdm.n`), beating the per-iteration attribute writes
+        # the pure-Python path pays to keep them live every iteration.
+        if (
+            _FastBarIterator is not None
+            and self._iterable is not None
+            and not os.environ.get('PROGRESSBAR_DISABLE_FASTPATH')
+        ):
+            return _FastBarIterator(self, self._iterable)
+        return self._iter_python()
+
+    def _iter_python(self):
         # Single generator (see issue #212): a `break`/exception in the loop
         # body triggers `GeneratorExit`, letting us finish and restore any
         # redirected streams. The integer gate keeps the common iteration to
@@ -953,6 +980,10 @@ def __iter__(self):
             value = self.value
             next_update = value
             update = self.update
+            # `_gate_enabled` is set once in `start()` and never mutated during
+            # iteration, so hoist it to a local and drop the per-iteration
+            # attribute load on the hot path.
+            gate_enabled = self._gate_enabled
             for item in iterator:
                 value += 1
                 # When the gate is disabled, call `update()` every iteration so
@@ -964,7 +995,7 @@ def __iter__(self):
                 # `update()` (rather than pre-setting `self.value`) lets it
                 # record the prior value in the public `previous_value`,
                 # preserving its original semantics.
-                if not self._gate_enabled or value >= next_update:
+                if not gate_enabled or value >= next_update:
                     update(value)
                     next_update = self._next_update
                 else:
@@ -981,6 +1012,28 @@ def __iter__(self):
             self.finish(dirty=True)
             raise
 
+    # --- Native accelerator protocol (used by speedups.FastBarIterator) ------
+    # The C iterator counts items itself and calls back here only at gate
+    # crossings, reusing the existing gate/redraw/calibration machinery so the
+    # redraw cadence is identical to `_iter_python`.
+
+    def _fast_begin(self) -> None:
+        """Start the bar (draws 0%, sets `_next_update`/`_gate_enabled`)."""
+        if self.start_time is None:
+            self.start()
+
+    def _fast_tick(self, value: int) -> None:
+        """Handle a redraw crossing: redraw-if-due and recompute the gate."""
+        self.update(value)
+
+    def _fast_end(self) -> None:
+        """Finish normally (draws 100%, restores streams) on exhaustion."""
+        self.finish()
+
+    def _fast_end_dirty(self) -> None:
+        """Finish dirty on early break/exception (restores streams)."""
+        self.finish(dirty=True)
+
     def __next__(self):
         value: typing.Any
         try:

progressbar/bar.py

@@ -112,6 +112,12 @@ repository = 'https://github.com/wolph/python-progressbar/'
 progressbar = 'progressbar.__main__:main'
 
 [project.optional-dependencies]
+# Optional native iterator accelerator. When installed it is detected and used
+# automatically (the iterator path drops to ~5 ns/iter); otherwise progressbar2
+# falls back to the pure-Python gate. See the Performance section in README.
+fast = [
+    'speedups>=2.1.0',
+]
 docs = [
     'sphinx>=1.8.5',
     'sphinx-autodoc-typehints>=1.6.0',

pyproject.toml

@@ -24,6 +24,18 @@ def pytest_configure(config) -> None:
     )
 
 
+@pytest.fixture(autouse=True)
+def disable_native_accelerator(monkeypatch):
+    # The optional native accelerator (speedups.FastBarIterator) is exercised
+    # explicitly in test_native_accelerator.py. Every other test targets the
+    # pure-Python iterator (`_iter_python`), so force that path by default when
+    # the compiled `speedups` package happens to be installed in the dev/bench
+    # environment. Native tests restore it via their own monkeypatch.
+    import progressbar.bar as bar_module
+
+    monkeypatch.setattr(bar_module, '_FastBarIterator', None)
+
+
 @pytest.fixture(autouse=True)
 def small_interval(monkeypatch, request) -> None:
     # Tests marked `no_freezegun` need real timing conditions (e.g. the perf

tests/conftest.py

@@ -525,9 +525,11 @@ def test_shortcut_has_single_generator_layer():
 
     gen = progressbar.progressbar(range(3), fd=RecordingTTY())
     assert isinstance(gen, types.GeneratorType)
-    # It is the bar's own __iter__ generator, not a wrapper: compare the
-    # generator's code object to ProgressBar.__iter__ (robust across versions).
-    assert gen.gi_code is progressbar.ProgressBar.__iter__.__code__
+    # It is the bar's own iterator generator, not a wrapper: compare the
+    # generator's code object to ProgressBar._iter_python (the pure-Python
+    # path `__iter__` dispatches to; robust across versions). The autouse
+    # `disable_native_accelerator` fixture forces this path here.
+    assert gen.gi_code is progressbar.ProgressBar._iter_python.__code__
 
 
 def test_env_disables_fastpath(monkeypatch):