0 dní v řadě · 0 bodů

Užitečné knihovny · 26 min

rich a tqdm: hezký výstup a průběh

Vypíšeš tabulky, stromy a zvýrazněná hlášení přes rich a k dlouhým cyklům přidáš ukazatel průběhu z tqdm.

Hloubka
Úkoly
Lidsky řečeno

Auto by jelo i bez palubní desky. Jenže bys nevěděl, jakou máš rychlost, kolik zbývá benzinu a jestli nesvítí kontrolka motoru. Program s holým print je takové auto: buď z něj teče nepřehledný proud textu, nebo mlčí a ty nevíš, jestli pracuje, nebo zamrzl. rich z výpisu udělá čitelnou palubní desku a tqdm přidá ukazatel, kolik cesty ještě zbývá.

Instalace a první výpis

Obě knihovny jsou cizí balíčky, takže na vlastním počítači je jednou doinstaluješ:

bash
python -m pip install rich tqdm

Ukázky na téhle stránce běží rovnou v prohlížeči, tady instalovat nemusíš.

U rich je hlavní postavou konzole, objekt, který ví, kam a jak široce se vypisuje. Vytvoříš ji jednou a pak voláš její print.

from rich.console import Console

console = Console(width=60, force_terminal=False, color_system=None)

console.print("Záloha dokončena.")
console.print("[bold green]Hotovo:[/bold green] 12 souborů")
Výstup
Záloha dokončena.
Hotovo: 12 souborů

Ty tři parametry jsou tu kvůli lekci:

  • width=60 nastaví šířku výpisu na 60 znaků,
  • force_terminal=False říká, že výstup nejde do skutečného terminálu,
  • color_system=None vypne barvy.

Díky nim vypadá výstup pokaždé stejně, ale tučné písmo a zelenou tu neuvidíš. Na svém počítači napiš jen tohle a barvy se objeví samy:

python
from rich.console import Console

console = Console()
console.print("[bold green]Hotovo:[/bold green] 12 souborů")

Existuje i zkratka from rich import print, která přepíše vestavěný print verzí od rich. Do malého skriptu se hodí. Ve větším programu je čitelnější vlastní console, protože je hned vidět, který výpis je který.

Značky a past s hranatými závorkami

Styl se zapisuje do hranatých závorek, podobně jako značky v HTML. Říká se tomu markup.

ZápisVýznam
[bold]text[/bold]tučně
[italic]text[/italic]kurzíva
[red]text[/red]červené písmo
[white on red]text[/]bílé písmo na červeném pozadí
[/]zavře naposledy otevřenou značku

Hranaté závorky ale občas patří do samotných dat, a tam začíná problém. Podívej se, co se stane s názvem souboru.

from rich.console import Console
from rich.markup import escape

console = Console(width=60, force_terminal=False, color_system=None)
soubor = "zaloha[stara].zip"

console.print("Mažu", soubor)
console.print("Mažu", escape(soubor))
console.print("Mažu", soubor, markup=False)
Výstup
Mažu zaloha.zip
Mažu zaloha[stara].zip
Mažu zaloha[stara].zip

První řádek lže. [stara] považoval rich za značku a tiše ji zahodil. Funkce escape závorky v textu ochrání a markup=False vypne značky pro celé volání.

Ještě hůř dopadne text, který vypadá jako zavírací značka. Tady program spadne:

from rich.console import Console

console = Console(width=60, force_terminal=False, color_system=None)
slozka = "[/tmp/data]"
console.print("Pracuji ve složce", slozka)
Výstup
Úkol

Vrať názvu závorky

Program má vypsat přesně Uloženo: report[final].xlsx. Slovo Uloženo: zůstane se značkou [bold], název souboru se ale nesmí poškodit.

from rich.console import Console
from rich.markup import escape

console = Console(width=60, force_terminal=False, color_system=None)
nazev = "report[final].xlsx"

console.print("[bold]Uloženo:[/bold]", nazev)
Výstup
Kvíz

Co vypíše console.print("Soubor [draft].txt") při vypnutých barvách?

Tabulky

Zarovnávat sloupce ručně přes f-stringy je otrava. Table spočítá šířky za tebe. Nejdřív nadefinuješ sloupce, potom přidáváš řádky.

from rich.console import Console
from rich.table import Table

console = Console(width=60, force_terminal=False, color_system=None)
sklad = [("Šroub M6", 120, 1.5), ("Matka M6", 7, 0.9), ("Podložka", 1500, 0.2)]

tabulka = Table(title="Sklad")
tabulka.add_column("Zboží")
tabulka.add_column("Kusů", justify="right")
tabulka.add_column("Cena", justify="right")

for nazev, kusy, cena in sklad:
    tabulka.add_row(nazev, str(kusy), f"{cena:.2f} Kč")

console.print(tabulka)
Výstup
            Sklad
┏━━━━━━━━━━┳━━━━━━┳━━━━━━━━━┓
┃ Zboží    ┃ Kusů ┃    Cena ┃
┡━━━━━━━━━━╇━━━━━━╇━━━━━━━━━┩
│ Šroub M6 │  120 │ 1.50 Kč │
│ Matka M6 │    7 │ 0.90 Kč │
│ Podložka │ 1500 │ 0.20 Kč │
└──────────┴──────┴─────────┘

Všimni si str(kusy). Buňka musí být text nebo něco, co rich umí vykreslit. Holé číslo neprojde:

from rich.table import Table

tabulka = Table()
tabulka.add_column("Kusů")
tabulka.add_row(120)
Výstup

Vzhled se mění parametry. box určuje rámeček, footer přidá patičku a show_header=False schová záhlaví. Když se text nevejde, rich ho zalomí uvnitř sloupce. Sloupec s no_wrap=True se lámat nebude.

from rich import box
from rich.console import Console
from rich.table import Table

console = Console(width=34, force_terminal=False, color_system=None)

tabulka = Table(box=box.SIMPLE, show_footer=True)
tabulka.add_column("Položka", footer="Celkem")
tabulka.add_column("Cena", justify="right", footer="1 450 Kč", no_wrap=True)
tabulka.add_row("Výměna oleje a filtrů u služebního auta", "1 200 Kč")
tabulka.add_row("Mytí", "250 Kč")

console.print(tabulka)
Výstup
  Položka                   Cena
 ────────────────────────────────
  Výměna oleje a        1 200 Kč
  filtrů u služebního
  auta
  Mytí                    250 Kč
 ────────────────────────────────
  Celkem                1 450 Kč
Úkol

Tabulka úkolů

Ze seznamu ukoly vytvoř tabulku tabulka se sloupci Úkol a Hodin. Sloupec Hodin zarovnej doprava, přidej všechny řádky a tabulku vypiš přes console.

from rich.console import Console
from rich.table import Table

console = Console(width=60, force_terminal=False, color_system=None)
ukoly = [("Faktury", 2), ("Web", 5), ("Porada", 1)]

tabulka = Table()
# doplň sloupce a řádky
Výstup

Panely, stromy a oddělovače

Tři drobnosti, které zpřehlední výpis skriptu. rule nakreslí nadpisovou čáru, Panel orámuje důležitou zprávu a Tree zobrazí cokoli, co se větví, například složky.

from rich.console import Console
from rich.panel import Panel
from rich.tree import Tree

console = Console(width=40, force_terminal=False, color_system=None)

console.rule("Záloha")
console.print(Panel("Zkopírováno 12 souborů.", title="Výsledek"))

strom = Tree("projekt/")
zdroje = strom.add("src/")
zdroje.add("main.py")
zdroje.add("utils.py")
strom.add("README.md")
console.print(strom)
Výstup
──────────────── Záloha ────────────────
╭────────────── Výsledek ──────────────╮
│ Zkopírováno 12 souborů.              │
╰──────────────────────────────────────╯
projekt/
├── src/
│   ├── main.py
│   └── utils.py
└── README.md

Metoda add vrací novou větev. Proto si ji ulož do proměnné, když do ní chceš přidávat další položky.

Úkol

Strom ze slovníku

Do stromu strom přidej pro každou složku ze slovníku slozky jednu větev a do ní její soubory. Strom nakonec vypiš.

from rich.console import Console
from rich.tree import Tree

console = Console(width=60, force_terminal=False, color_system=None)
slozky = {"fotky": ["leto.jpg", "zima.jpg"], "texty": ["poznamky.txt"]}

strom = Tree("disk/")
# doplň
Výstup

Kdy rich nepoužívat

rich píše pro lidi. Zalamuje text podle šířky okna a tím může rozbít data, která čte jiný program.

from rich.console import Console

console = Console(width=30, force_terminal=False, color_system=None)
adresa = "https://example.com/faktury/2026/brezen/souhrn.pdf"

console.print(adresa)
console.print(adresa, soft_wrap=True)
print(adresa)
Výstup
https://example.com/faktury/20
26/brezen/souhrn.pdf
https://example.com/faktury/2026/brezen/souhrn.pdf
https://example.com/faktury/2026/brezen/souhrn.pdf

První výpis rozsekal adresu na dva řádky a v tomhle stavu ji už nikdo nezkopíruje. soft_wrap=True zalamování vypne a obyčejný print o žádné šířce ani neví.

Dobré pravidlo: data posílej přes print na standardní výstup, hlášení pro člověka přes Console(stderr=True). Když pak někdo spustí python skript.py > data.txt, do souboru půjdou jen data a hlášení zůstanou na obrazovce.

K tomu rich přidává pár věcí, které v prohlížeči nemají smysl, ale ve skriptech se hodí:

python
import logging
import time

from rich.console import Console
from rich.logging import RichHandler
from rich.traceback import install

install()  # readable colored tracebacks for uncaught errors

logging.basicConfig(level="INFO", format="%(message)s", handlers=[RichHandler()])
logging.getLogger("app").info("Spouštím import")

console = Console(stderr=True)
with console.status("Čekám na server..."):  # spinner while the block runs
    time.sleep(2)
console.log("Hotovo")  # adds time and source line
Pod kapotou · jak rich vykresluje a jak ho testovat

Každý objekt, který jde vypsat, implementuje protokol: __rich__ vrátí jiný vykreslitelný objekt, __rich_console__(self, console, options) postupně vydává Segmenty (text + styl) a nepovinné __rich_measure__ hlásí minimální a maximální šířku. Tabulka je tak jen skladatel cizích objektů a do buňky můžeš vložit další tabulku, panel nebo strom.

Šířka se neměří ve znacích, ale v buňkách terminálu: rich.cells.cell_len("日本") je 4 a většina emoji zabírá 2 buňky. Právě proto f"{text:<10}" s emoji rozhodí sloupce a Table ne.

Chování řídí prostředí: NO_COLOR vypne barvy, FORCE_COLOR zapne terminálový režim i bez TTY, TTY_COMPATIBLE=1 se hodí pro CI, které umí escape sekvence, a COLUMNS určuje šířku. Bez TTY rich barvy zahodí, a když nenajde žádný terminál, počítá se šířkou 80. To je typický důvod, proč výpis v Dockeru vypadá jinak než na notebooku.

Výstup testuj přes Console(file=io.StringIO(), width=80), případně přes with console.capture() as c:. Volba record=True uchová výpis pro export_text(), export_html() a export_svg(), takže ze skriptu snadno vznikne příloha do CI.

tqdm: kolik ještě zbývá

Název tqdm vychází z arabského slova pro pokrok. Použití je skoro drze jednoduché: to, přes co cyklus prochází, obalíš do tqdm(...).

python
from time import sleep
from tqdm import tqdm

for fotka in tqdm(range(200), desc="Fotky", unit="ks"):
    sleep(0.01)  # real work goes here

V terminálu se jeden řádek průběžně přepisuje:

text
Fotky:  30%|███       | 60/200 [00:00<00:01, 97.21ks/s]

Skutečný ukazatel by tu při každém spuštění ukázal jiné časy, takže si jeho podobu necháme vyrobit z pevných čísel. Metoda format_meter je přesně ta, kterou tqdm používá pro vykreslení.

from tqdm import tqdm

print(tqdm.format_meter(n=30, total=100, elapsed=12.0, ncols=50, ascii=True))
print(tqdm.format_meter(n=30, total=None, elapsed=12.0))
Výstup
 30%|###6        | 30/100 [00:12<00:28,  2.50it/s]
30it [00:12,  2.50it/s]

Jak ten první řádek číst:

ČástVýznam
30%hotová část práce
###6totéž jako pruh, poslední znak ukazuje rozdělaný dílek
30/100kolik průchodů proběhlo z kolika
00:12kolik času už uběhlo
00:28odhad, kolik času ještě zbývá
2.50it/srychlost

it/s znamená „iterací za sekundu“, tedy kolik průchodů cyklem stihne za sekundu. Druhý řádek ukazuje, co se stane bez celkového počtu: žádná procenta, žádný odhad, jen počítadlo.

To nastává u generátorů. Generátor hodnoty vyrábí za pochodu a předem neví, kolik jich bude, takže len() na něm nefunguje. Když počet znáš, řekni ho sám přes total.

python
from tqdm import tqdm

def read_lines(path):
    with open(path, encoding="utf-8") as f:
        for line in f:
            yield line.strip()

with open("data.txt", encoding="utf-8") as f:
    count = sum(1 for _ in f)

for line in tqdm(read_lines("data.txt"), total=count, unit="řádek"):
    ...
Kvíz

Proč for x in tqdm(moje_generatorova_funkce()): neukáže procenta?

Ruční posun, výpisy a vypnutí

Někdy se nepočítají průchody, ale třeba bajty. Pak vytvoříš ukazatel s total a posouváš ho metodou update. Blok with ho na konci správně ukončí.

import io
from tqdm import tqdm

bloky = [b"a" * 400, b"b" * 250, b"c" * 350]

with tqdm(total=1000, unit="B", file=io.StringIO()) as pruh:
    for blok in bloky:
        pruh.update(len(blok))
        print("hotovo bajtů:", pruh.n)
Výstup
hotovo bajtů: 400
hotovo bajtů: 650
hotovo bajtů: 1000

file=io.StringIO() posílá pruh do neviditelného poznámkového bloku, aby tu nepřekážel. U sebe ho vynech. Takhle vypadá typické použití při stahování většího souboru:

python
import requests
from tqdm import tqdm

url = "https://example.com/data.zip"
with requests.get(url, stream=True, timeout=30) as r:
    r.raise_for_status()
    total = int(r.headers.get("content-length", 0)) or None
    with open("data.zip", "wb") as f, tqdm(
        total=total, unit="B", unit_scale=True, unit_divisor=1024
    ) as bar:
        for chunk in r.iter_content(chunk_size=64 * 1024):
            f.write(chunk)
            bar.update(len(chunk))

Obyčejný print uprostřed cyklu pruh rozseká na kusy. Místo něj použij tqdm.write, který pruh na okamžik uklidí a pak ho vykreslí znovu.

from tqdm import tqdm

for cislo in tqdm(range(1, 6), disable=True):
    if cislo % 2 == 0:
        tqdm.write(f"sudé číslo: {cislo}")
Výstup
sudé číslo: 2
sudé číslo: 4

Parametr disable=True pruh úplně vypne. Hodí se pro přepínač --quiet. Hodnota disable=None ho vypne jen tehdy, když výstup nejde do terminálu, což ocení logy na serveru.

Úkol

Pruh, který nelže

Ukazatel má jít od 0 do součtu všech velikostí v seznamu bloky. Oprav total tak, aby se spočítal ze seznamu, a v cyklu posouvej pruh o velikost bloku.

import io
from tqdm import tqdm

bloky = [120, 80, 300]

pruh = tqdm(total=100, file=io.StringIO())
for blok in bloky:
    pruh.update(1)
pruh.close()
Výstup
Úkol

Řekni mu, kolik toho bude

Funkce objednavky je generátor, takže tqdm nezná délku. Doplň parametr total podle délky seznamu CISLA a výsledek cyklu ulož do seznamu hotovo.

import io
from tqdm import tqdm

CISLA = [101, 102, 103, 104]

def objednavky():
    for cislo in CISLA:
        yield cislo

pruh = tqdm(objednavky(), file=io.StringIO())
hotovo = []
Výstup
Kvíz

Proč tqdm ve výchozím stavu kreslí na stderr, a ne na stdout?

Pod kapotou · tqdm v produkci

Kolik stojí. Překreslování je omezené: mininterval=0.1 s a miniters se dynamicky dolaďuje, takže tqdm většinu iterací jen přičte a čas ani neměří. Ve velmi těsné smyčce je i tak levnější aktualizovat po dávkách přes update(n).

Odhad času. Rychlost se vyhlazuje exponenciálním průměrem (smoothing=0.3). smoothing=0 dá průměr za celý běh, což je stabilnější u nerovnoměrných úloh. Vlákno TMonitor hlídá maxinterval (10 s), aby se pruh nezasekl, když iterace náhle zpomalí. V prostředí bez vláken ho vypne tqdm.monitor_interval = 0.

Logy. V kontejneru bez TTY se každý refresh zapíše jako další kus textu oddělený \r. Řešení je disable=None, nebo řídký refresh přes mininterval=30. S modulem logging spoj pruh přes tqdm.contrib.logging.logging_redirect_tqdm.

Souběh. tqdm.contrib.concurrent nabízí thread_map a process_map, tqdm.asyncio zase verzi pro asyncio a tqdm.auto vybere vhodnou variantu pro terminál nebo notebook. Více pruhů nad sebou řídí parametr position. U rich je obdobou rich.progress: track(...) nebo Progress s vlastními sloupci, který si překresluje vlastní vlákno. Když už v aplikaci rich máš, vyhneš se tím souboji dvou knihoven o stejný řádek terminálu.

Obě knihovny dohromady

Skutečný skript je typicky používá společně: tqdm ukazuje průběh, tqdm.write hlásí problémy a na závěr rich vypíše přehled.

from collections import Counter

from rich.console import Console
from rich.table import Table
from tqdm import tqdm

console = Console(width=40, force_terminal=False, color_system=None)
soubory = ["leto.jpg", "zima.png", "navod.pdf", "jaro.jpg", "rozbity", "more.jpg"]

pocty = Counter()
for nazev in tqdm(soubory, desc="Třídím", disable=True):  # remove disable at home
    if "." not in nazev:
        tqdm.write(f"Přeskakuji {nazev}: nemá příponu")
        continue
    pripona = nazev.rsplit(".", 1)[1]
    pocty[pripona] += 1

tabulka = Table(title="Přehled")
tabulka.add_column("Přípona")
tabulka.add_column("Počet", justify="right")
for pripona, pocet in pocty.most_common():
    tabulka.add_row(pripona, str(pocet))
console.print(tabulka)
Výstup
Přeskakuji rozbity: nemá příponu
      Přehled
┏━━━━━━━━━┳━━━━━━━┓
┃ Přípona ┃ Počet ┃
┡━━━━━━━━━╇━━━━━━━┩
│ jpg     │     3 │
│ png     │     1 │
│ pdf     │     1 │
└─────────┴───────┘