Индикатор выполнения для модуля click в Python

Использование click.progressbar() в сценариях на click

Иногда есть сценарии командной строки, которые должны обрабатывать большой объем данных, при этом нужно быстро показать пользователю прогресс в том, сколько времени это займет. Модуль сlick поддерживает простую визуализацию индикатора выполнения с помощью функции click.progressbar().

Примечание: Если требования к прогресс-бару, выходят за рамки того, что поддерживает индикатор выполнения click.progressbar(), то попробуйте использовать сторонний модуль tqdm.

Базовое использование очень простое: идея состоит в том, что данные, с которыми предстоит работать, представляют из себя итерацию. Обработка каждого элемента в итерации может занять некоторое время. Скажем, есть такой цикл:

# псевдокод
for file in list_files:
    modify_file(file)

Чтобы подключить этот код к обновляемому индикатору выполнения, все, что нужно сделать, это изменить код на этот:

# псевдокод
with click.progressbar(list_files) as bar:
    for file in bar:
        modify_file(file)

После этого функция click.progressbar() автоматически покажет индикатор выполнения в терминале и рассчитает оставшееся время. Для вычисления оставшегося времени требуется, чтобы итерируемый объект имел длину (количество элементов). Если количество элементов не может быть вычислено функцией len(), то можно указать длину явно:

# псевдокод
with click.progressbar(list_files, length=num_files) as bar:
    for file in bar:
        modify_file(file)

Обратите внимание, что click.progressbar() обновляет полосу прогресс-бара после каждой итерации цикла. Таким образом, следующий код будет отображаться правильно:

import click, time

with click.progressbar(range(5)) as bar:
    for x in bar:
        time.sleep(0.1)

Еще одна полезная функциональность click.progressbar() - связать метку с индикатором выполнения, которая будет отображаться перед индикатором выполнения:

# псевдокод
with click.progressbar(list_files,
                       label='Modifying files',
                       length=num_files) as bar:
    for file in bar:
        modify_file(file)

Иногда может потребоваться выполнить итерацию по внешнему итератору и нерегулярно продвигать индикатор выполнения. Для этого необходимо указать длину внешней итерации и использовать метод bar.update для возвращаемого значения контекста:

# псевдокод
with click.progressbar(length=total_size,
                       label='Unzipping archive') as bar:
    for archive in zip_files:
        archive.extract()
        # обновляем индикатор выполнения
        bar.update(archive.size)

Примечание. Индикатор выполнения в настоящее время предназначен для случаев использования, когда общий прогресс займет не менее нескольких секунд. Объект класса ProgressBar не будет отображать прогресс, который считается слишком быстрым (меньше секунды).

Печать данных внутри контекста with click.progressbar() as bar: не должна выполняться, так как индикатор выполнения будет поврежден.

Синтаксис и описание принимаемых аргументов.

click.progressbar(iterable=None, length=None, label=None, 
                   show_eta=True, show_percent=None, show_pos=False, 
                   item_show_func=None, fill_char='#', empty_char='-', 
                   bar_template='%(label)s  [%(bar)s]  %(info)s', info_sep='  ', 
                   width=36, file=None, color=None, update_min_steps=1)

Описание принимаемых аргументов:

• iterable: итерация для перебора. Если этот аргумент не указан, то аргумент length обязателен.
• length: int, количество элементов для повторения. По умолчанию панель прогресса попытается вычислить длину сама, что может сработать, а может и не сработать. Если также указывается аргумент iterable, то этот аргумент переопределяется вычисленной длинной iterable. Если iterable не указан, то индикатор выполнения будет обновляться в диапазоне этой длины.
• label: str метка, которая будет отображаться рядом с индикатором выполнения.
• show_eta: bool, включает или отключает отображение расчетного времени. Автоматически отключается, если длина не может быть определена.
• show_percent: bool, включает или отключает отображение процентов. если итерируемый объект имеет длину, то True, если нет, тоFalse.
• show_pos: bool, включает или отключает отображение абсолютного положения. Значение по умолчанию False.
• item_show_func: функция, вызываемая с текущим элементом, которая может возвращать строку, отображаемую рядом с индикатором выполнения. Если функция возвращает None, ничего не отображается. Текущий элемент может иметь значение None, например, при входе в панель и выходе из нее.
• fill_char: str, символ, используемый для заполнения индикатора выполнения.
• empty_char: str, символ, используемый для незакрашенной части индикатора выполнения.
• bar_template: str, строка формата, используемая в качестве шаблона для панели. Параметры - это метка для метки, полоса для индикатора выполнения и информация для информационного раздела.
• info_sep: str, разделитель между несколькими информационными элементами.
• width: int, Ширина индикатора выполнения в символах, 0 означает полную ширину терминала
• file: TextIO, файл для записи. Если это не терминал, печатается только этикетка.
• color: bool контролирует, поддерживает ли терминал цвета ANSI или нет. По умолчанию это автоматическое определение. Необходим только в том случае, если коды ANSI включены где-нибудь в выводе индикатора выполнения.
• update_min_steps: int, выполнять обновление индикатора только после завершения такого количества итераций. Это позволяет настраивать очень быстрые итераторы.