Skip to content

Latest commit

 

History

History
460 lines (310 loc) · 18.7 KB

README.it.md

File metadata and controls

460 lines (310 loc) · 18.7 KB
Raw

Downloads codecov Rich blog Twitter Follow

Logo

English readme • 简体中文 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 • Italian readme • Русский readme • فارسی readme • Türkçe readme • Polskie readme

Rich è una libreria Python per un testo rich e con una piacevole formattazione nel terminale.

Le Rich API permettono di aggiungere facilmente colore e stile all'output del terminale. Rich permette di visualizzare tabelle, barre di avanzamento, markdown, evidenziazione della sintassi, tracebacks, e molto altro ancora — tutto già pronto all'uso.

Features

Per una video-introduzione di Rich puoi vedere calmcode.io by @fishnets88.

Guarda cosa le persone dicono su Rich.

Compatibilità

Rich funziona su Linux, OSX, e Windows. True color / emoji funzionano con il nuovo Windows Terminal, il terminale classico è limitato a 16 colori. Rich richiede Python 3.6.3 o superiore.

Rich funziona con i Jupyter notebooks senza configurazioni aggiuntive.

Installazione

Installa con pip o il tuo PyPI package manager preferito.

python -m pip install rich

Esegui il seguente comando per testare l'output di Rich sul tuo terminale:

python -m rich

Rich Print

Utilizzare rich è semplicissimo, ti basta importare il metodo rich print, che ha la stessa signature della funzione builtin in Python. Prova:

from rich import print

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

Hello World

Rich REPL

Rich può essere installo in Python REPL, in questo modo ogni struttura dati sarà visualizzata in modo gradevole ed evidenziato.

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

REPL

Utilizzo di Console

Per un maggiore personalizzazione dei contenuti puoi importare ed instanziare un oggetto Console.

from rich.console import Console

console = Console()

L'oggetto Console ha il metodo print che utilizza volutamente un interfaccia simile a quella del print originale. Ad esempio:

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

Come puoi immaginare, questo stamperà "Hello World!" sul terminale. Nota che diversamente dalla funzione builtin print, Rich potrebbe portare a capo il testo per rispettare le dimensioni del terminale.

Ci sono diversi modi di aggiungere stile e colore al tuo output. Puoi impostare uno stile per l'intero output utilizzando l'argomento keyword style. Ad esempio:

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

L'output sarà qualcosa tipo:

Hello World

Questo va bene per applicare uno stile ad una linea di testo alla volta. Per uno stile più ricercato, puoi utilizzare uno speciale linguaggio di markup che è simile nella sintassi a bbcode. Ad esempio:

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

Console Markup

Puoi utilizzare l'oggetto Console per generare output sofisticati con il minimo sforzo. Vedi la docs di Console API per ulteriori dettagli.

Rich Inspect

Rich ha una funzione inspect che può produrre un report per un qualsiasi oggetto Python, come una classe, un instanza, o un builtin.

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

Log

Vedi inspect docs per ulteriori dettagli.

Rich Library

Rich contiene alcuni builtin renderables che puoi utilizzare per creare eleganti output nella tua CLI e aiutarti nel debug del tuo codice.

Fai click sulle seguenti intestazioni per ulteriori dettagli:

Log

L'oggetto Console ha un metodo log() che utilizza un'interfaccia simile a print(), ma visualizza anche una colonna con l'ora corrente, il file e la linea che hanno generato la chiamata. Di default Rich evidenzierà le strutture Python e le stringhe repr. Se logghi un oggetto di tipo collection (e.s. un dict o una lista) Rich automaticamente abbellirà l'output in modo che possa entrare nello spazio disponibile. Ecco qui un esempio di alcune delle feature discusse:

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

Il codice appena mostrato produce il seguente output:

Log

Nota l'argomento log_locals, che visualizza una tabella contenente le variabili locali dove il metodo log è stato chiamato.

Il metodo log può essere usato per il logging su terminale di applicazioni che solitamente girano su server, ma ha anche uno scopo orientato al debugging.

Logging Handler

Puoi anche utilizzare la classe builtin Handler per formattare e colorare l'output dal modulo logging di Python. Ecco un esempio dell'output:

Logging

Emoji

Per inserire un emoji nell'output della console inseriscine il nome in mezzo a due ':'. Ad esempio:

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

Usa questa feature saggiamente.

Tables

Rich può visualizzare tabelle flessibili con caratteri unicode. C'è una vasta gamma di opzioni per la formattazione di bordi, stili, allineamenti di celle etc.

table movie

Questa animazione è stata realizzata con table_movie.py presente nella directory examples.

Ecco qui un semplice esempio di tabella:

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)

Questo produce il seguente output:

table

Nota che il console markup è visualizzato nello stesso modo di print() e log(). Infatti, tutto ciò che è visualizzabile da Rich può essere incluso nelle intestazioni / righe (anche altre tabelle).

La classe Table è abbastanza smart da ridimensionare le colonne per entrare nello spazio residuo del terminale, wrappando il testo come richiesto. Ad esempio, con il terminale reso più piccolo della tabella sopra:

table2

Barre di avanzamento

Rich può visualizzare, senza sfarfallio, multiple barre di avanzamento per tenere traccia di task di lunga durata.

Per un utilizzo base, wrappa ogni 'step' con la funzione track e itera sul risultato. Ad esempio:

from rich.progress import track

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

Non è difficile aggiungere barre di avanzamento multiple. Ecco un esempio dalla documentazione:

progress

Le colonne possono essere configurate per visualizzare qualsiasi dettaglio tu voglia. Le colonne built-in includono percentuale di completamente, dimensione del file, velocità, e tempo rimasto. Ecco un altro esempio che mostra un download in corso:

progress

Per testare tu stesso, vedi examples/downloader.py che può scaricare multipli URL simultaneamente mentre mostra lo stato di avanzamento.

Status

Per situazioni in cui è difficile calcolare l'avanzamento, puoi utilizzare il metodo status che mostrerà un animazione 'spinner' e un messaggio. L'animazione non ti impedisce di utilizzare la console normalmente. Ad esempio:

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

Questo produrrà il seguente output nel terminale.

status

L'animazione dello spinner è ispirata da cli-spinners. Puoi selezionarne uno specificando spinner tra i parametri. Esegui il seguente comando per visualizzare le possibili opzioni:

python -m rich.spinner

Questo produrrà il seguente output nel terminale.

spinners

Albero

Rich può visualizzare un albero con linee guida. Un albero è ideale per mostrare la struttura di un file, o altri dati gerarchici.

Le etichette dell'albero possono essere semplice testo o qualsiasi altra cosa che Rich può visualizzare. Esegui il seguente comando per una dimostrazione:

python -m rich.tree

Questo produrrà il seguente output:

markdown

Vedi l'esempio tree.py per uno script che mostra una vista ad albero di ogni directory, simile a quella del comando linux tree.

Colonne

Rich può visualizzare contenuti in colonne ordinate con larghezza uguale o ottimale. Ecco qui un clone base del comando (MacOS / Linux) ls che mostra il contenuto di una directory in colonna:

import os
import sys

from rich import print
from rich.columns import Columns

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

Il seguente screenshot è l'output dell'esempio di columns che visualizza i dati ottenuti da un API in colonna:

columns

Markdown

Rich può visualizzare markdown e tradurlo in modo da visualizzarlo su terminale.

Per visualizzare markdown importa la classe Markdown e instanziala con una stringa contenente codice markdown. Dopo stampala sulla console. Ad esempio:

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)

Questo produrrà un output simile al seguente:

markdown

Evidenziazione della sintassi

Rich utilizza la libreria pygments per implementare il syntax highlighting. L'utilizzo è simile a quello per visualizzare markdown; instanzia un oggetto Syntax e stampalo sulla console. Ad esempio:

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

my_code = '''
def iter_first_last(values: Iterable[T]) -> Iterable[Tuple[bool, bool, T]]:
    """Itera e genera una tupla con un flag per il primo e ultimo valore."""
    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)

Questo produrrà il seguente output:

syntax

Tracebacks

Rich può visualizzare gradevoli tracebacks che sono più semplici da leggere e che mostrano più codice rispetto ai Python tracebacks. Puoi impostare Rich come il traceback handler di default, in questo modo tutte le eccezioni non gestiti saranno visualizzate da Rich.

Ecco come appare su OSX (simile a Linux):

traceback

Tutti i Rich renderables utilizzano Console Protocol, che puoi utilizzare per implementare nuovi contenuti su Rich.

Rich per le aziende

Disponibile come parte dell'iscrizione a Tidelift.

Lo sviluppatore di Rich e migliaia di altri packages lavorano con Tidelift per garantire supporto commerciale e mantenimento per i pacchetti open source che utilizzi per costruire le tue applicazioni. Risparmia tempo, riduci i rischi, e migliora la vita del codice, pagando i mantenitori dello stesso package che utilizzi. Ulteriori informazioni.

Progetti che usano Rich

Ecco alcuni progetti che utilizzano Rich: