rich/README.pt-br.md

English readme • 中文 readme • Lengua española readme • Deutsche readme • Läs på svenska • 日本語 readme • 한국어 readme • Français readme • Schwizerdütsch readme • हिन्दी readme • Português brasileiro readme

Rich é uma biblioteca Python para rich text e formatação de estilos no terminal.

A API do Rich permite adicionar cores e estilos no output do terminal de forma fácil. Rich também permite formataçao de tabelas, barra de progresso, markdown, highlight de sintaxe de código fonte, rastreio de erros (traceback) e muito mais.

Para mais detalhes, veja um vídeo de introdução so Rich em calmcode.io por @fishnets88.

Veja aqui o que estão falando sobre o Rich.

Compatibilidade

Rich funciona no Linux, OSX e Windows. True color / emoji funciona no novo Terminal do Windows, o terminal classico é limitado a 16 cores. Rich requer Python 3.6.1 ou superior.

Rich funciona com Jupyter notebooks sem a necessidade de configurações adicionais.

Instalação

Instale usando pip ou seu gerenciador de pacotes PyPi favorito.

pip install rich

Execute o seguinte comando para testar o output do Rich no seu terminal:

python -m rich

Print do Rich

Para adicionar as as funções de formatação do rich na sua aplicação de forma fácil, simplesmente importe o metodo rich print que tem a mesma assinatura da função nativa do Python. Por exemplo:

from rich import print

print("Hello, [bold magenta]World[/bold magenta]!", ":vampire:", locals())

REPL do Rich

O Rich pode ser instalado no REPL do Python fazendo com que qualquer estrutura de dados seja exibida formatada e com highlights.

>>> from rich import pretty
>>> pretty.install()

Usando o Console

Para ter mais controle sobre a formatação do conteudo no terminal, importe e instancie um objeto do Console.

from rich.console import Console

console = Console()

Objetos do tipo Console tem um metodo print que tem a interface intencionalmente similar à função print nativa. Veja a seguir um exeplo de uso:

console.print("Hello", "World!")

Como esperado, este comando vai imprimir "Hello World!" no terminal. Porém, observe que, diferente da função print nativa, o Rich vai quebrar a linha entre palavras (word-wrap) no seu texto para caber na largura do terminal.

Existem algumas formas de adicionar cores e estilos nos outputs. É possivel aplicar um estilo para todo output adicionando o argumento nomeado style. Por exemplo:

console.print("Hello", "World!", style="bold red")

O resultado vai ser algo como:

Isso funciona bem para formatar cada linha do texto individualmente. Para maior controle sobre a formatação, o Rich renderiza um markup especial com uma sintaxe similar ao bbcode. Veja o exemplo a seguir:

console.print("Where there is a [bold cyan]Will[/bold cyan] there [u]is[/u] a [i]way[/i].")

Voce pode usar o objeto do Console para gerar facilmente uma saída para o terminal sofisticada. Veja a documentação da API do Console para mais detalhes.

Inspect do Rich

O Rich tem uma função inspect que gera um relatório de qualquer objeto no Python, como classes, instâncias ou funções nativas.

>>> my_list = ["foo", "bar"]
>>> from rich import inspect
>>> inspect(my_list, methods=True)

Confira a documentação do inspect para mais detalhes.

A biblioteca Rich

O Rich possui vários renderizaveis nativos que podem ser usados para criar outputs elegantes no seu CLI e ajudar a debugar o código.

Clique nos itens a seguir para expandir os detalhes:

Log

O objeto Console tem um método log() com uma interface similar ao print() mas que também imprime uma coluna com a hora atual, nome do arquivo e linha onde foi executado. Por padrão, o Rich vai fazer highlight de sintaxe para extruturas do Python e para repr strings. Se você usar o log() para imprimir uma collection (por exemplo um dicionário ou uma lista), o Rich vai imprimir formatado de uma forma que caiba no espaço disponível. Veja a seguir alguns exemplos dessas funções:

from rich.console import Console
console = Console()

test_data = [
    {"jsonrpc": "2.0", "method": "sum", "params": [None, 1, 2, 4, False, True], "id": "1",},
    {"jsonrpc": "2.0", "method": "notify_hello", "params": [7]},
    {"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": "2"},
]

def test_log():
    enabled = False
    context = {
        "foo": "bar",
    }
    movies = ["Deadpool", "Rise of the Skywalker"]
    console.log("Hello from", console, "!")
    console.log(test_data, log_locals=True)


test_log()

O código acima vai produzir algo parecido com:

Note o argumento log_locals que imprime uma tabela com as variáveis locais no contexto em que o método log() foi chamado.

O método log() pode ser usado para logar no terminal em aplicações de processos longos como servidores, mas é também uma ferramenta ótima para debugar.

Logging Handler

Você também pode usar a classe Handler nativa para formatar e colorir o output do módulo logging do Python. Veja aqui um exemplo do output:

Emoji

Para imprimir um emoji no console, coloque o nome do emoji entre dois ":" (dois pontos). Por exemplo:

>>> console.print(":smiley: :vampire: :pile_of_poo: :thumbs_up: :raccoon:")
😃 🧛 💩 👍 🦝

Por favor use esse recurso com sabedoria.

Tabelas

O Rich pode imprimir tables flexíveis usando caracteres unicode como bordas. Existem várias opções de formatação de bordas, estilos, alinhamento das celulas, etc.

A animação acima foi gerada com o arquivo table_movie.py da pasta de exemplos.

Veja um exemplo mais simple:

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

console = Console()

table = Table(show_header=True, header_style="bold magenta")
table.add_column("Date", style="dim", width=12)
table.add_column("Title")
table.add_column("Production Budget", justify="right")
table.add_column("Box Office", justify="right")
table.add_row(
    "Dec 20, 2019", "Star Wars: The Rise of Skywalker", "$275,000,000", "$375,126,118"
)
table.add_row(
    "May 25, 2018",
    "[red]Solo[/red]: A Star Wars Story",
    "$275,000,000",
    "$393,151,347",
)
table.add_row(
    "Dec 15, 2017",
    "Star Wars Ep. VIII: The Last Jedi",
    "$262,000,000",
    "[bold]$1,332,539,889[/bold]",
)

console.print(table)

Que gera o seguinte resultado:

Observe que o markup é renderizado da mesma for que em print() e log(). De fato, tudo que é renderizável pelo Rich pode ser incluído nos cabeçalhos ou linhas (até mesmo outras tabelas).

A classe Table é inteligente o suficiente para ajustar o tamanho das colunas para caber na largura do terminal, quebrando o texto em novas linhas quando necessário. Veja a seguir o mesmo exemplo, só que desta vez com um terminal menor do que o tamanho original da tabela:

Barra de Progresso

O Rich consegue renderizar de forma eficiente multiplas barras de progresso que podem ser usadas para rastrear o estado de processos longos.

Uma forma simples de usar é passando o iterável para a função track e iterar normalmente sobre o retorno. Veja o exemplo a seguir:

from rich.progress import track

for step in track(range(100)):
    do_step(step)

Adicionar multiplas barras de progresso também é simples. Veja outro exemplo que existe na documentação:

As colunas podem ser configuradas pra mostrar qualquer detalho necessário. As colunas nativas incluem a porcentagem completa, tamanho de arquivo, velocidade do arquivo e tempo restante. O exemplo a seguir mostra o progresso de um download:

Para testar isso no seu terminal, use o arquivo examples/downloader.py para fazer o download de multiplas URLs simultaneamente, exibindo o progresso de cada download.

Status

Em casos em que é dificil de calcular o progresso da tarefa, você pode usar o método status que exibe uma animação de um "spinner" e a mensagem. A animação não impede em nada o uso do console. Veja o exemplo a seguir:

from time import sleep
from rich.console import Console

console = Console()
tasks = [f"task {n}" for n in range(1, 11)]

with console.status("[bold green]Working on tasks...") as status:
    while tasks:
        task = tasks.pop(0)
        sleep(1)
        console.log(f"{task} complete")

Este código resultará no seguinte output no terminal:

As animações do "spinner" foram emprestadas do cli-spinners. É possível escolher um estilo de "spinner" usando o parametro spinner. Execute o comando a seguir para ver todos os tipos de "spinner" disponíveis.

python -m rich.spinner

O comando acima deve exibir o seguinte no seu terminal:

Árvore

O Rich pode renderizar árvores com linhas de identação. Uma árvore é a forma ideal de exibir uma extrutura de arquivos ou qualquer outra apresentação hierárquica de dados.

Os titulos dos itens da árvore podem ser textos simples ou qualquer coisa que o Rich pode renderizar. Execute o comando a seguir para uma demonstração:

python -m rich.tree

Isso gera o seguinte resultado:

Veja o exemplo em tree.py de um código que gera uma árvore de exibição de um dicionário, semelhante ao comando tree do linux.

Colunas

O Rich pode renderizar conteúdos em colunas bem formatadas com tamanhos iguais ou otimizados. O exemplo a seguir é uma cópia básica do comando ls (presente no MacOS / Linux) que mostra o conteúdo de uma pasta organizado em colunas:

import os
import sys

from rich import print
from rich.columns import Columns

directory = os.listdir(sys.argv[1])
print(Columns(directory))

O screenshot a seguir é do resultado do exemplo de colunas formatando em colunas os dados extraidos de uma API:

Markdown

O Rich pode renderizar markdown e faz um bom trabalho de conversão do formato para o terminal.

Para renderizar markdowm, importe a classe Markdown e instancie com a string que contem o código markdown. Depois, imprima o objeto no console. Por exemplo:

from rich.console import Console
from rich.markdown import Markdown

console = Console()
with open("README.md") as readme:
    markdown = Markdown(readme.read())
console.print(markdown)

Isso produzirá um resultado como:

Highlight de Sintaxe

O Rich usa a biblioteca pygments para implementar o highlight de sintaxe. O uso é similar à renderização de markdown, instancie um objeto da classe Syntax imprima no console. Por exemplo:

from rich.console import Console
from rich.syntax import Syntax

my_code = '''
def iter_first_last(values: Iterable[T]) -> Iterable[Tuple[bool, bool, T]]:
    """Iterate and generate a tuple with a flag for first and last value."""
    iter_values = iter(values)
    try:
        previous_value = next(iter_values)
    except StopIteration:
        return
    first = True
    for value in iter_values:
        yield first, False, previous_value
        first = False
        previous_value = value
    yield first, True, previous_value
'''
syntax = Syntax(my_code, "python", theme="monokai", line_numbers=True)
console = Console()
console.print(syntax)

Este código gerará o seguinte resultado:

Rastreio de Erros (tracebacks)

O Rich renderiza tracebacks formatados que são fáceis de ler e mostra mais código do que os tracebacks padrão do Python. É possivel configurar o Rich como o gerenciador padrão de tracebacks para que todas as excessões inesperadas sejam renderizadas pelo Rich.

Veja o resultado disso no OSX (resultados semelhantes no Linux):

Todos os renderizaveis do Rich usam o Protocolo do Console, que você pode usar para implementar o seu próprio conteúdo Rich.

Rich para empresas

Disponível como parte da assinatura Tidelift.

Os mantenedores do Rich e milhares de outros pacotes estão trabalhando com o Tidelift para disponibilizar suporte comercial e manutenção de projetos de código aberto usados nas suas aplicações. Economise tempo, reduza riscos e melhore a saúde do código enquanto paga os mantenedores dos pacotes exatos que você usa. Mais detalhes.

Projetos usando Rich

Aqui estão alguns projetos que usam o Rich:

• BrancoLab/BrainRender a python package for the visualization of three dimensional neuro-anatomical data um pacote python para visualisação tridimensional de dados neuro-atômicos.
• Ciphey/Ciphey ferramenta de descriptografia autoatizada.
• emeryberger/scalene um analisador de CPU e memória de alta performance e alta precisão para Python
• hedythedev/StarCli Explore projetos de destaque no GitHub pela linha de comando do terminal
• intel/cve-bin-tool Essa ferramenta verifica a vulnerabilidade de diversos componentes populares (openssl, libpng, libxml2, expat e outros) presentes no seu sistema e alerta para possíveis vulnerabilidades conhecidas.
• nf-core/tools pacote Python com ferramentas auxiliares par a comunidade nf-core.
• cansarigol/pdbr pdb + Rich para auxiliar no debug
• plant99/felicette Imagem de satélites para iniciantes.
• seleniumbase/SeleniumBase Automatize & teste 10x mais rápido com Selenium & pytest. Baterias inclusas.
• smacke/ffsubsync Automagicamente sincronize legendas com vídeos.
• tryolabs/norfair Biblioteca Python para adicionar rastreio em tempo real de objetos 2D em qualquer detector.
• ansible/ansible-lint Ansible-lint verifica boas práticas e comportamento que podem ser melhorados.
• ansible-community/molecule Framework de test para Ansible Molecule
• +Muitos outros!