Crate kdam

Expand description

A console progress bar library for Rust. (inspired by tqdm & rich.progress)

§Optional Features

The following are a list of Cargo features that can be enabled or disabled:

derive: Adds a derive macro for deriving BarExt trait.
notebook: Enables support for jupyter notebooks. It can be useful when you are building pyo3 python extension modules. Also, make sure that you have ipython and ipywidgets python libraries installed on your system.
gradient: Enables gradient colours support for progress bars and printing text.
rayon: Adds support for rayon’s parallel iterators.
rich: Enables rich style progress bar.
spinner: Enables support for using spinners.
template: Enables templating capabilities for Bar.
unicode: Enables unicode support.

§Usage

§Iterator Based

use kdam::tqdm;

fn main() {
    let chars = ["a", "b", "c", "d"];
    let mut charset = String::new();

    for i in tqdm!(chars.iter()) {
        charset += i;
    }

    eprintln!();
    assert_eq!(charset, "abcd");
}

§Manual

use kdam::{tqdm, BarExt};
use std::io::Result;

fn main() -> Result<()> {
    let mut pb = tqdm!(total = 100);

    for _ in 0..100 {
        pb.update(1)?;
    }

    eprintln!();
    Ok(())
}

Another example without a total value. This only shows basic stats.

use kdam::{tqdm, BarExt};
use std::io::Result;

fn main() -> Result<()> {
    let mut pb = tqdm!();

    for _ in 0..10000000 {
        pb.update(1)?;
    }

    pb.refresh()?;
    eprintln!();

    Ok(())
}

10000000 [00:03, 2998660.35it/s]

§Examples

§Description And Additional Stats

Custom information can be displayed and updated dynamically on kdam bars with the desc and postfix.

use kdam::{tqdm, BarExt};
use std::io::Result;

fn main() -> Result<()> {
    let mut pb = tqdm!(total = 10);
    pb.set_postfix(format!("str={}, lst={:?}", "h", [1, 2]));
    pb.refresh()?;

    for i in 0..10 {
        std::thread::sleep(std::time::Duration::from_secs_f32(0.5));
        pb.set_description(format!("GEN {}", i));
        pb.update(1)?;
    }
    
    eprintln!();
    Ok(())
}

GEN 4:  50%|█████████▎        | 5/10 [00:02<00:02, 1.95it/s, str=h, lst=[1, 2]]

§Nested Progress Bars

kdam supports nested progress bars. For manual control over positioning (e.g. for multi-processing use), you may specify position=n where n=0 for the outermost bar, n=1 for the next, and so on.

use kdam::{term, tqdm};
use std::io::Result;

fn main() -> Result<()> {
    term::init(false);
    term::hide_cursor()?;

    for _ in tqdm!(0..4, desc = "1st loop", position = 0) {
        for _ in tqdm!(0..5, desc = "2nd loop", position = 1) {
            for _ in tqdm!(0..50, desc = "3rd loop", position = 2) {
                std::thread::sleep(std::time::Duration::from_secs_f32(0.0001));
            }
        }
    }

    eprint!("{}", "\n".repeat(3));
    println!("completed!");

    Ok(())
}

1st loop:  50%|███████▎      | 2/4 [00:08<00:08, 0.25it/s]
2nd loop:  60%|████████▌     | 3/5 [00:02<00:01, 1.25it/s]
3rd loop:   0%|▎               | 0/50 [00:00<00:00, ?it/s]

§Writing Messages And Inputs

Since kdam uses a simple printing mechanism to display progress bars, you should not write any message in the terminal using println!() while a progressbar is open.

To write messages in the terminal without any collision with kdam bar display, a .write() method is provided. This message will print at bar output location, which is stderr by default.

use kdam::{tqdm, BarExt};
use std::io::Result;

fn main() -> Result<()> {
    let mut pb = tqdm!(total = 10);

    for i in 0..10 {
        std::thread::sleep(std::time::Duration::from_secs_f32(0.1));

        pb.update(1)?;
        pb.write(format!("Done task {}", i))?;
    }

    eprintln!();
    Ok(())
}

Done task 0
Done task 1
Done task 2
Done task 3
Done task 4
Done task 5
Done task 6
Done task 7
Done task 8
Done task 9
100%|███████████████████████████| 10/10 [00:02<00:00, 4.31it/s]

Similarly .input() method can be called to store an user input.

use kdam::{tqdm, BarExt};
use std::io::Result;

fn main() -> Result<()> {
    let mut pb = tqdm!(total = 10);

    for i in 0..10 {
        if i == 5 {
            if pb.input("Break Loop [y/n]: ")?.trim() == "y" {
                break;
            }
        }

        pb.update(1);
    }

    eprintln!();
    Ok(())
}

Break Loop [y/n]: y
 50%|███████████████▎              | 5/10 [00:01<00:01, 3.83it/s]

§Terminal Colorization

kdam also provides a text colorization trait for printing coloured text in terminal. It can be used as an alternative to existing colored crate.

use kdam::term::Colorizer;

kdam::term::init(true);

println!("{}", "hello world!".colorize("bold red"));
println!("{}", "hello world!".colorize("bright white on blue"));

Re-exports§

pub use rayon;rayon

Modules§

format: Functions for formatting values.
monitor: Monitor mode for progress bars.
term: Terminal related utilities.

Macros§

par_tqdmrayon: Parallel version of tqdm macro.
tqdm: tqdm like macro for creating Bar and BarIter.

Structs§

Bar: Core implemention of console progress bar.
BarBuilder: Create Bar with custom configurations.
BarIter: Iterable version of Bar.
RichProgressrich: An implementation rich.progress using Bar.
RowManager: RowManager allows to store and update many progress bars.
Spinnerspinner: Generic spinner for rendering spinner animations.

Enums§

Animation: Animation styles for Bar.
Colour: Colour applicable to text.
Columnrich: Renderable columns for RichProgress.

Traits§

BarExt: Comman progress bar functionalities shared between different types of progress bars.
TqdmIterator: Iterators decoration with BarIter.
TqdmParallelIteratorrayon: Parallel iterators decoration with BarIter.

Functions§

set_notebooknotebook: Set whether kdam is running inside a jupyter notebook or not.

Derive Macros§

BarExtderive: Derive BarExt trait for a struct.

Crate kdamCopy item path