rich/README.ja.md

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は、 リッチ なテキストや美しい書式設定をターミナルで行うためのPythonライブラリです。

Rich APIを使用すると、ターミナルの出力に色やスタイルを簡単に追加することができます。 Richはきれいなテーブル、プログレスバー、マークダウン、シンタックスハイライトされたソースコード、トレースバックなどをすぐに生成・表示することもできます。

Richの紹介動画はこちらをご覧ください。 calmcode.io by @fishnets88.

Richについての人々の感想を見る。

互換性

RichはLinux、OSX、Windowsに対応しています。True colorと絵文字は新しい Windows ターミナルで動作しますが、古いターミナルでは8色に制限されています。Richを使用するにはPythonのバージョンは3.6.3以降が必要です。

Richは追加の設定を行わずとも、Jupyter notebooksで動作します。

インストール

pip や、あなたのお気に入りのPyPIパッケージマネージャを使ってインストールしてください。

python -m pip install rich

以下のコマンドを実行して、ターミナルでリッチの出力をテストできます:

python -m rich

Richのprint関数

簡単にリッチな出力をアプリケーションに追加するには、Pythonの組み込み関数と同じ名前を持つ rich print メソッドをインポートすることで実現できます。こちらを試してみてください:

from rich import print

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

Rich REPL

RichはPythonのREPLでインストールすることができ、データ構造がきれいに表示され、ハイライトされます。

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

Rich Inspect

RichにはPythonオブジェクトやクラス、インスタンス、組み込み関数などに関するレポートを作成することができる、inspect関数があります。

>>> from rich import inspect
>>> inspect(str, methods=True)

Consoleの使い方

リッチなターミナルコンテンツをより制御していくには、Console オブジェクトをインポートして構築していきます。

from rich.console import Console

console = Console()

Console オブジェクトには print メソッドがあり、これは組み込み関数の print と意図的に似たインターフェイスを持っています。 以下に使用例を示します:

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

あなたが予想した通り、これは "Hello World!" をターミナルに表示します。組み込み関数の print とは異なり、Rich はターミナルの幅に合わせてテキストをワードラップすることに注意してください。

出力結果に色やスタイルを追加する方法はいくつかあります。キーワード引数に style を追加することで、出力結果全体のスタイルを設定することができます。以下に例を示します:

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

以下のように出力されます:

この方法は一行のテキストを一度にスタイリングするのに適しています。 より細かくスタイリングを行うために、Richはbbcodeに似た構文の特別なマークアップを表示することができます。 これはその例です:

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

Console logging

Consoleオブジェクトには log() メソッドがあり、これは print() と同じインターフェイスを持ちますが、現在の時刻と呼び出しを行ったファイルと行数についてもカラムに表示します。デフォルトでは、RichはPythonの構造体とrepr文字列のシンタックスハイライトを行います。もしコレクション(例: dictやlist)をログに記録した場合、Richはそれを利用可能なスペースに収まるようにきれいに表示します。以下に、これらの機能のいくつかの例を示します。

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

上の例では以下のような出力が得られます:

log_localsという引数についてですが、これは、logメソッドが呼び出されたローカル変数を含むテーブルを出力します。

logメソッドはサーバのような長時間稼働しているアプリケーションのターミナルへのloggingとして使用できますが、デバッグ時に非常に役に立つ手段でもあります。

Logging Handler

また、内蔵されているHandler classを用いて、Pythonのloggingモジュールからの出力をフォーマットしたり、色付けしたりすることもできます。以下に出力の例を示します。

絵文字(Emoji)

コンソールの出力に絵文字を挿入するには、2つのコロンの間に名前を入れます。例を示します:

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

この機能をうまく活用してみてください。

テーブル

Richはユニコードの枠を用いて柔軟にテーブルを表示することができます。 罫線、スタイル、セルの配置などの書式設定のためのオプションが豊富にあります。

上のアニメーションは、examplesディレクトリのtable_movie.pyで生成したものです。

もう少し簡単な表の例を示します:

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)

これにより、以下のような出力が得られます:

コンソール上でのマークアップはprint() や log() と同じように表示されることに注意してください。実際には、Rich が表示可能なものはすべてヘッダや行に含めることができます (それが他のテーブルであっても、です)。

Tableクラスは、ターミナルの利用可能な幅に合わせてカラムのサイズを変更したり、必要に応じてテキストを折り返したりするのに十分なスマートさを持っています。 これは先ほどと同じ例で、ターミナルを上のテーブルよりも小さくしたものです。

プログレスバー

Richでは複数のちらつきのないのプログレスバーを表示して、長時間のタスクを追跡することができます。

基本的な使い方としては、任意のシーケンスを track 関数でラップし、その結果を繰り返し処理します。以下に例を示します:

from rich.progress import track

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

複数のプログレスバーを追加するのはそれほど大変ではありません。以下はドキュメントから抜粋した例です:

カラムには任意の詳細を表示するように設定することができます。組み込まれているカラムには、完了率、ファイルサイズ、ファイル速度、残り時間が含まれています。ここでは、進行中のダウンロードを表示する別の例を示します:

こちらを自分で試して見るには、進捗状況を表示しながら複数のURLを同時にダウンロードできる examples/downloader.py を参照してみてください。

ステータス

進捗状況を計算するのが難しい場合は、statusメソッドを使用して、「スピナー」アニメーションとメッセージを表示させることができます。通常、アニメーションはコンソールの使用を妨げることはありません。ここに例を示します:

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

これにより、ターミナルには以下のような出力が生成されます。

スピナーのアニメーションは cli-spinners から拝借しました。spinnerパラメータを指定することでスピナーを選択することができます。以下のコマンドを実行して、利用可能な値を確認してください:

python -m rich.spinner

上記コマンドは、ターミナルで以下のような出力を生成します:

ツリー

Richはガイドライン付きのツリーを表示することができます。ツリーはファイル構造などの階層データを表示するのに適しています。

ツリーのラベルは、シンプルなテキストや、Richが表示できるものであれば何でも表示することができます。以下を実行してデモを行います:

python -m rich.tree

これにより、次のような出力が生成されます:

linuxの tree コマンドと同様に、任意のディレクトリのツリー表示を行うスクリプトについては、tree.pyの例を参照してください。

カラム

Rich は、コンテンツをきれいな カラム で等幅、または最適な幅で表示することができます。これは(MacOS / Linux) の ls コマンドのとても基本的なクローンで、ディレクトリ一覧をカラムで表示します。

import os
import sys

from rich import print
from rich.columns import Columns

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

以下のスクリーンショットは、APIから引っ張ってきたデータをカラムで表示するcolumns exampleによる出力です:

マークダウン

Richはマークダウンを使用することができ、フォーマットをターミナル向けに変換するための良い仕事をしてくれます。

マークダウンを使用するには、Markdownクラスをインポートし、マークダウンコードを含む文字列で構成します。そしてそれをコンソールに表示します。これは例です:

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)

これにより、以下のような出力が得られます:

シンタックスハイライト

Richは シンタックスハイライト を実装するために pygments ライブラリを使用しています。使い方はマークダウンを使用するのと似ています。 Syntax オブジェクトを構築してコンソールに表示します。以下にその例を示します:

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)

これにより、以下のような出力が得られます:

トレースバック

Rich は 美しいトレースバック を表示することができ、通常のPythonのトレースバックよりも読みやすく、より多くのコードを表示することができます。Richをデフォルトのトレースバックハンドラとして設定することで、捕捉されなかった例外はすべてRichによって表示されるようになります。

OSXではこのような表示となります（Linuxでも似たような表示になります）:

Richを使用したプロジェクト

ここでは、Richを使用したいくつかのプロジェクトを紹介します:

• BrancoLab/BrainRender 3次元の神経解剖学的データを可視化するpythonパッケージ
• Ciphey/Ciphey 自動化された復号化ツール
• emeryberger/scalene Python用の高性能・高精度 CPU/メモリプロファイラ
• hedythedev/StarCli コマンドラインから GitHub のトレンドプロジェクトを閲覧できます
• intel/cve-bin-tool このツールは、一般的な脆弱性のあるコンポーネント(openssl, libpng, libxml2, expat, その他いくつか)をスキャンし、お使いのシステムに既知の脆弱性のある一般的なライブラリが含まれているかどうかを知らせてくれます。
• nf-core/tools nf-core コミュニティのためのヘルパーツールを含む Python パッケージ。
• cansarigol/pdbr pdb + Richライブラリによる、強化されたデバッグツール。
• plant99/felicette ダミーのための衛星画像。
• seleniumbase/SeleniumBase Seleniumとpytestで10倍速の自動化とテスト。バッテリーも含まれています。
• smacke/ffsubsync 字幕を自動的にビデオと同期させます。
• tryolabs/norfair あらゆる検出器にリアルタイムの2Dオブジェクトトラッキングを追加するための軽量なPythonライブラリ。
• ansible/ansible-lint Ansible-lint がplaybooksをチェックして、改善できる可能性のあるプラクティスや動作を確認します。
• ansible-community/molecule Ansible Moleculeのテストフレームワーク
• +Many more!