tqdm.cr

tqdm.cr

A 1:1 Crystal port of the python library tqdm 4.67.3. Bar rendering is byte-identical to the original — verified by the oracle parity tests (make verify).

Usage

require "tqdm"

# iteration (python: for i in tqdm(range(100)):)
Tqdm.each(1..100) { |i| work(i) }
t = Tqdm.new(array).each { |x| ... }          # or explicitly

# python: with tqdm(total=100) as t:
Tqdm.new(total: 100) do |t|
  t.update(10)
end

t = Tqdm.new(total: 100, desc: "download",    # manual mode
             unit: "B", unit_scale: true,
             unit_divisor: 1024, colour: "green")
100.times { t.update(1) }
t.close

# python: trange(100)
trange(100) { |i| work(i) }

Tqdm.write("message between bars")            # python tqdm.write(...)

The whole core of tqdm/std.py is supported: total/desc/leave/ncols/nrows/ mininterval/maxinterval/miniters/ascii/disable/unit/unit_scale/dynamic_ncols/ smoothing/bar_format/initial/position/postfix/unit_divisor/lock_args/colour/ delay, update/close/clear/refresh/unpause/reset/set_description(_str)/ set_postfix(_str)/format_dict/to_s (moveto, display), nested bars (position, nrows, ... (more hidden) ...), write/external_write_mode, wrapattr/CallbackIOWrapper, trange, the monitor fiber, locking (set_lock/get_lock), TQDM_* env overrides, Bar, EMA, format_meter/format_num/format_interval/format_sizeof, and the python subset of the format spec ({percentage:3.0f}, {bar:10}, {n_fmt} etc. in bar_format).

Differences from python (forced)

  • write(..., end=...) → Tqdm.write(s, end_str: "\n"): end is a Crystal keyword.
  • set_postfix(loss=1, ...) (kwargs) → set_postfix({loss: 1, ...}) (Hash/NamedTuple); keys are sorted alphabetically, just like python sorts kwargs.
  • bool(t) → t.empty?; len(t) → t.size (nil = python TypeError); str(t) → t.to_s.
  • Discrete "python numbers": int-ness is preserved ("10", not "10.0"); float repr is reproduced exactly (py_float_str).
  • {eta} in bar_format: python substitutes datetime.now()+remaining (wall clock) — here it is a best-effort string; the deterministic {remaining}/{remaining_s} fields are available.
  • The total is auto-detected for Indexable/Range/Hash (python len); bare Iterators are treated as generators (unknown total), like python.
  • TQDM_* env vars are read once at load time (like python's envwrap at import), converted according to the parameter default's type (python bool(x): a non-empty string is true).
  • Giant intervals (> 1.7e38 s) in format_interval are not supported (python bignum); up to 1e27 s is covered (Int128) and oracle-tested.
  • The original's gui/notebook/keras/pandas modules are outside the core and not ported.

Known Crystal issue

Casting structs to module types ((1..10).as(Enumerable(Int32))) crashes on Crystal 1.21 — therefore iterables are converted to an Iterator at the Tqdm.new boundary, without module casts.

Parity tests (per AGENTS.md)

  • oracle/golden/ — dumps of 17 deterministic scenarios (fake clock + IO::Memory) taken from the real python-tqdm 4.67.3 (bin/oracle_dump.py).
  • bin/oracle_dump.cr reproduces the same scenarios with the port; make verify compares them byte-for-byte.
  • spec/ — a port of the deterministic tests from the original's tests/tests_tqdm.py (test_format_interval, test_format_num, test_format_meter, test_bar_formatspec, test_si_format, live-bar behaviour).
make verify   # oracle/golden == oracle/current (byte-exact)
make spec     # 18 tests
make golden   # re-dump golden from python-tqdm (requires tqdm==4.67.3)
make test     # verify + spec

Original sources: tmp/tqdm-4.67.3/ (sdist, for reference).

Repository

tqdm.cr

Owner
Statistic
  • 0
  • 0
  • 0
  • 0
  • 0
  • 3 days ago
  • November 16, 2026
License

Links
Synced at

Mon, 16 Nov 2026 10:12:08 GMT

Languages