rich

Leiame em inglês • 简体中文 leiame • 正體中文 leiame • Leiame em língua espanhola • Leiame em alemão • Läs på svenska • Leiame em 日本語 • Leiame em 한국어 • Leiame em francês • Leiame em Schwizerdütsch • हिन्दी leia-me • Português brasileiro leia-me • italiano leia-me • Русский leia-me • indonésio leia-me • فارسی leia-me • Türkçe leia-me • Polskie leia-me

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

A API Rich facilita a adição de cor e estilo à saída do terminal. Rich também pode renderizar tabelas bonitas, barras de progresso, markdown, código-fonte com destaque de sintaxe, tracebacks e muito mais - prontos para uso.

Para um vídeo de introdução ao Rich, consulte calmcode.io de @fishnets88.

Veja o que as pessoas estão dizendo sobre Rico.

Compatibilidade

Rich funciona com Linux, macOS e Windows. True color / emoji funciona com o novo Terminal do Windows, o terminal clássico é limitado a 16 cores. Rich requer Python 3.8 ou posterior.

Rich funciona com notebooks Jupyter sem necessidade de configuração adicional.

Instalando

Instale com pip ou seu gerenciador de pacotes PyPI favorito.

python -m pip install rich

Execute o seguinte para testar a saída rica em seu terminal:

python -m rich

Impressão rica

Para adicionar facilmente uma saída rica ao seu aplicativo, você pode importar o método rich print, que tem a mesma assinatura da função Python integrada. Experimente isto:

 from rich import print

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

REPL rico

Rich pode ser instalado no Python REPL, para que qualquer estrutura de dados seja bem impressa e destacada.

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

Usando a Consola

Para obter mais controle sobre o conteúdo avançado do terminal, importe e construa um objeto Console.

 from rich . console import Console

console = Console ()

O objeto Console possui um método print que possui uma interface intencionalmente semelhante à função print integrada. Aqui está um exemplo de uso:

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

Como você pode esperar, isso imprimirá "Hello World!" para o terminal. Observe que, diferentemente da função print integrada, Rich irá quebrar o texto para caber na largura do terminal.

Existem algumas maneiras de adicionar cor e estilo à sua saída. Você pode definir um estilo para toda a saída adicionando um argumento de palavra-chave de style . Aqui está um exemplo:

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

A saída será algo como o seguinte:

Isso é bom para estilizar uma linha de texto por vez. Para um estilo mais refinado, Rich renderiza uma marcação especial que é semelhante em sintaxe ao bbcode. Aqui está um exemplo:

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

Você pode usar um objeto Console para gerar uma saída sofisticada com esforço mínimo. Consulte a documentação da API do console para obter detalhes.

Inspeção rica

Rich tem uma função de inspeção que pode produzir um relatório sobre qualquer objeto Python, como classe, instância ou interno.

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

Consulte os documentos de inspeção para obter detalhes.

Biblioteca rica

Rich contém vários renderizáveis ​​integrados que você pode usar para criar uma saída elegante em sua CLI e ajudá-lo a depurar seu código.

Clique nos seguintes títulos para obter detalhes:

Registro

O objeto Console possui um método log() que possui uma interface semelhante a print() , mas também renderiza uma coluna para a hora atual e o arquivo e linha que fez a chamada. Por padrão, Rich fará destaque de sintaxe para estruturas Python e para strings repr. Se você registrar uma coleção (ou seja, um ditado ou uma lista), o Rich irá imprimi-la para que caiba no espaço disponível. Aqui está um exemplo de alguns desses recursos.

 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 acima produz a seguinte saída:

Observe o argumento log_locals , que gera uma tabela contendo as variáveis ​​locais onde o método log foi chamado.

O método log pode ser usado para registrar no terminal aplicativos de longa execução, como servidores, mas também é um ótimo auxiliar de depuração.

Manipulador de registro

Você também pode usar a classe Handler integrada para formatar e colorir a saída do módulo de registro do Python. Aqui está um exemplo da saída:

Emoji

Para inserir um emoji na saída do console, coloque o nome entre dois pontos. Aqui está um exemplo:

 >> > console . print ( ":smiley: :vampire: :pile_of_poo: :thumbs_up: :raccoon:" )
? ? ? ? ?

Use esse recurso com sabedoria.

Tabelas

Rich pode renderizar tabelas flexíveis com caracteres de caixa Unicode. Há uma grande variedade de opções de formatação para bordas, estilos, alinhamento de células, etc.

A animação acima foi gerada com table_movie.py no diretório de exemplos.

Aqui está um exemplo de tabela mais simples:

 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 )

Isso produz a seguinte saída:

Observe que a marcação do console é renderizada da mesma forma que print() e log() . Na verdade, qualquer coisa que seja renderizável por Rich pode ser incluída nos cabeçalhos/linhas (até mesmo em outras tabelas).

A classe Table é inteligente o suficiente para redimensionar colunas para caber na largura disponível do terminal, quebrando o texto conforme necessário. Aqui está o mesmo exemplo, com o terminal menor que a tabela acima:

Barras de progresso

Rich pode renderizar várias barras de progresso sem oscilações para rastrear tarefas de longa duração.

Para uso básico, envolva qualquer sequência na função track e repita o resultado. Aqui está um exemplo:

 from rich . progress import track

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

Não é muito mais difícil adicionar várias barras de progresso. Aqui está um exemplo retirado dos documentos:

As colunas podem ser configuradas para mostrar os detalhes que você desejar. As colunas integradas incluem porcentagem concluída, tamanho do arquivo, velocidade do arquivo e tempo restante. Aqui está outro exemplo mostrando um download em andamento:

Para experimentar você mesmo, consulte exemplos/downloader.py que pode baixar vários URLs simultaneamente enquanto exibe o progresso.

Status

Para situações em que é difícil calcular o progresso, você pode usar o método de status que exibirá uma animação e uma mensagem de 'spinner'. A animação não impedirá que você use o console normalmente. Aqui está um exemplo:

 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" )

Isso gera a seguinte saída no terminal.

As animações do spinner foram emprestadas dos cli-spinners. Você pode selecionar um controle giratório especificando o parâmetro spinner . Execute o seguinte comando para ver os valores disponíveis:

 python -m rich.spinner

O comando acima gera a seguinte saída no terminal:

Árvore

Rich pode renderizar uma árvore com linhas-guia. Uma árvore é ideal para exibir uma estrutura de arquivo ou qualquer outro dado hierárquico.

Os rótulos da árvore podem ser texto simples ou qualquer outra coisa que o Rich possa renderizar. Execute o seguinte para uma demonstração:

 python -m rich.tree

Isso gera a seguinte saída:

Veja o exemplo tree.py para um script que exibe uma visualização em árvore de qualquer diretório, semelhante ao comando linux tree .

Colunas

Rich pode renderizar conteúdo em colunas organizadas com largura igual ou ideal. Aqui está um clone muito básico do comando ls (MacOS/Linux) que exibe uma listagem de diretórios em colunas:

 import os
import sys

from rich import print
from rich . columns import Columns

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

A captura de tela a seguir é a saída do exemplo de colunas que exibe dados extraídos de uma API em colunas:

Remarcação

Rich pode renderizar descontos e faz um trabalho razoável ao traduzir a formatação para o terminal.

Para renderizar o markdown, importe a classe Markdown e construa-a com uma string contendo o código do markdown. Em seguida, imprima-o no console. Aqui está um 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á uma saída semelhante à seguinte:

Destaque de sintaxe

Rich usa a biblioteca pygments para implementar o realce de sintaxe. O uso é semelhante ao markdown de renderização; construa um objeto Syntax e imprima-o no console. Aqui está um 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 )

Isso produzirá a seguinte saída:

Rastreamentos

Rich pode renderizar lindos tracebacks que são mais fáceis de ler e mostram mais código do que os tracebacks padrão do Python. Você pode definir Rich como o manipulador de traceback padrão para que todas as exceções não detectadas sejam renderizadas por Rich.

Aqui está o que parece no OSX (semelhante no Linux):

Todos os renderizáveis ​​Rich fazem uso do Protocolo de Console, que você também pode usar para implementar seu próprio conteúdo Rich.

CLI rico

Consulte também Rich CLI para um aplicativo de linha de comando desenvolvido pela Rich. Código de realce de sintaxe, redução de renderização, exibição de CSVs em tabelas e muito mais, diretamente do prompt de comando.

Textual

Veja também o projeto irmão de Rich, Textual, que você pode usar para construir interfaces de usuário sofisticadas no terminal.