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"):endis 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}inbar_format: python substitutesdatetime.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(pythonlen); bareIterators 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 (pythonbool(x): a non-empty string is true).- Giant intervals (> 1.7e38 s) in
format_intervalare 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.crreproduces the same scenarios with the port;make verifycompares them byte-for-byte.spec/— a port of the deterministic tests from the original'stests/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).
tqdm.cr
- 0
- 0
- 0
- 0
- 0
- 3 days ago
- November 16, 2026
Mon, 16 Nov 2026 10:12:08 GMT