コンソール API¶

ターミナルの書式設定を完全に制御するために、Rich は Console クラスを提供します。ほとんどのアプリケーションでは、単一の Console インスタンスが必要となるため、モジュールレベルまたは最上位オブジェクトの属性として作成することをお勧めします。たとえば、「console.py」というファイルを作成してプロジェクトに追加できます。

from rich.console import Console
console = Console()

その後、次のようにプロジェクトのどこからでもコンソールをインポートできます。

from my_project.console import console

コンソールオブジェクトは、色とスタイルの ANSI エスケープシーケンスを生成するメカニズムを処理します。ターミナルの機能を自動検出し、必要に応じて色を変換します。

属性¶

コンソールは、レンダリングに必要な多くのプロパティを自動的に検出します。

size は、ターミナルの現在の寸法です（ウィンドウのサイズを変更すると変わる可能性があります）。
encoding は、デフォルトのエンコーディングです（通常は「utf-8」）。
is_terminal は、Console インスタンスがターミナルに出力しているかどうかを示すブール値です。
color_system は、コンソールのカラースキームを含む文字列です（下記参照）。

カラースキーム¶

ターミナルへの色の出力にはいくつかの「標準」がありますが、すべてが普遍的にサポートされているわけではありません。Rich は適切なカラースキームを自動的に検出するか、Console コンストラクタに color_system の値を指定することで手動で設定できます。

color_system は、次のいずれかの値に設定できます。

None 色を完全に無効にします。
"auto" カラースキームを自動検出します。
"standard" 通常と明るいバリエーションで 8 色を表示し、合計 16 色を表示できます。
"256" 「standard」の 16 色と、240 色の固定パレットを表示できます。
"truecolor" 1670 万色を表示できます。これは、おそらくモニターで表示できるすべての色です。
"windows" 従来の Windows ターミナルでは 8 色を表示できます。新しい Windows ターミナルでは「truecolor」を表示できます。

警告

カラースキームの設定には注意してください。ターミナルがサポートするよりも高いカラースキームを設定すると、テキストが読めなくなる可能性があります。

出力¶

リッチコンテンツをターミナルに書き込むには、print() メソッドを使用します。Rich は、オブジェクトの (__str__) メソッドを使用して任意のオブジェクトを文字列に変換し、簡単な構文強調表示を実行します。辞書やリストなど、任意のコンテナの整形済み出力も行います。文字列を出力すると、コンソールマークアップがレンダリングされます。いくつかの例を以下に示します。

console.print([1, 2, 3])
console.print("[blue underline]Looks like a link")
console.print(locals())
console.print("FOO", style="white on blue")

print() を使用して、コンソールプロトコルをサポートするオブジェクト（Text、Table、Syntax など、Rich の組み込みオブジェクトを含む）またはその他のカスタムオブジェクトをレンダリングすることもできます。

ログ出力¶

log() メソッドは print と同じ機能を提供しますが、実行中のアプリケーションのデバッグに役立つ機能が追加されています。ログ出力は、左側に現在の時刻を列として、右側にメソッドが呼び出されたファイルと行を列として書き込みます。例を以下に示します。

>>> console.log("Hello, World!")

[16:32:08] Hello, World!                                         <stdin>:1

デバッグを支援するために、log() メソッドには log_locals パラメータがあります。これを True に設定すると、Rich はメソッドが呼び出された場所のローカル変数のテーブルを表示します。

JSON の出力¶

print_json() メソッドは、JSON を含む文字列の整形済み出力（フォーマットとスタイル）を行います。簡単な例を以下に示します。

console.print_json('[false, true, null, "foo"]')

JSON オブジェクトをログ出力することで、JSON をログ出力することもできます。

from rich.json import JSON
console.log(JSON('["foo", "bar"]'))

JSON の出力は一般的な要件であるため、メイン名前空間から print_json をインポートできます。

from rich import print_json

コマンドラインで次のようにして JSON の整形済み出力を行うこともできます。

python -m rich.json cats.json

低レベル出力¶

print() と log()に加えて、Rich には out() メソッドがあり、ターミナルへのより低レベルな書き込み方法を提供します。out() メソッドは、すべて的位置引数を文字列に変換し、整形済み出力、折り返し、またはマークアップを適用しませんが、基本的なスタイルを適用でき、オプションで強調表示を行います。

例を以下に示します。

>>> console.out("Locals", locals())

ルール¶

rule() メソッドは、オプションのタイトル付きの水平線を描き、ターミナル出力をセクションに分割するのに適した方法です。

>>> console.rule("[bold red]Chapter 2")

─────────────────────────────── Chapter 2 ───────────────────────────────

rule メソッドは、線のスタイルを設定するための style パラメータと、タイトルを配置するための align パラメータ（「left」、「center」、「right」）も受け付けます。

ステータス表示¶

Rich は、通常のコンソール出力に干渉しない「スピナー」アニメーション付きのステータスメッセージを表示できます。この機能のデモを実行するには、次のコマンドを実行します。

python -m rich.status

ステータスメッセージを表示するには、ステータスメッセージ（文字列、Text、またはその他のレンダリング可能なもの）を使用して status() を呼び出します。結果は、コードブロックの周囲でステータス表示を開始および停止するコンテキストマネージャーです。例を以下に示します。

with console.status("Working..."):
    do_work()

spinner パラメータを使用してスピナーアニメーションを変更できます。

with console.status("Monkeying around...", spinner="monkey"):
    do_work()

spinner の利用可能な選択肢を確認するには、次のコマンドを実行します。

python -m rich.spinner

左右揃え / 配置¶

print と log の両方で、justify 引数をサポートしています。設定されている場合、「default」、「left」、「right」、「center」、「full」のいずれかでなければなりません。「left」の場合、出力される（またはログ出力される）テキストは左揃えになり、「right」の場合はターミナルの右揃えになり、「center」の場合は中央揃えになり、「full」の場合はターミナルの左右両方の端に合わせて揃えられます（本の印刷されたテキストのようになります）。

justify のデフォルトは "default" で、一般的には "left" と同じように見えますが、微妙な違いがあります。左揃えはテキストの右側にスペースを追加しますが、デフォルトの揃えは追加しません。style 引数で背景色を設定した場合にのみ、違いに気付くでしょう。次の例は、その違いを示しています。

from rich.console import Console

console = Console(width=20)

style = "bold white on blue"
console.print("Rich", style=style)
console.print("Rich", style=style, justify="left")
console.print("Rich", style=style, justify="center")
console.print("Rich", style=style, justify="right")

これは、次の出力を生成します。

Rich
Rich                
        Rich        
                Rich

オーバーフロー¶

オーバーフローは、出力するテキストが使用可能なスペースよりも大きい場合に発生します。たとえば、長い「単語」（URL など）を出力する場合、またはスペースが制限されたパネルやテーブルセル内のテキストがある場合に、オーバーフローが発生する可能性があります。

Richがオーバーフローをどのように処理するかを指定するには、overflow引数をprint()に渡します。この引数は、"fold"、"crop"、"ellipsis"、"ignore"のいずれかの文字列でなければなりません。デフォルトは"fold"で、余分な文字を次の行に折り返し、テキストに合うように必要な数の改行を作成します。

"crop"メソッドは、テキストを行末で切り捨て、オーバーフローする文字を破棄します。

"ellipsis"メソッドは"crop"と似ていますが、切り捨てられたテキストの最後に省略記号（"..."）を挿入します。

以下のコードは、基本的なオーバーフローメソッドを示しています。

from typing import List
from rich.console import Console, OverflowMethod

console = Console(width=14)
supercali = "supercalifragilisticexpialidocious"

overflow_methods: List[OverflowMethod] = ["fold", "crop", "ellipsis"]
for overflow in overflow_methods:
    console.rule(overflow)
    console.print(supercali, overflow=overflow, style="bold blue")
    console.print()

これは、次の出力を生成します。

──── fold ────
supercalifragi
listicexpialid
ocious

──── crop ────
supercalifragi

── ellipsis ──
supercalifrag…

"ignore"に設定することもできます。これにより、テキストが次の行に継続されます。実際には、print()を呼び出す際にcrop=Falseを設定しない限り、"crop"と同じように見えます。

コンソールスタイル¶

Consoleにはstyle属性があり、これを使用して印刷するすべてのものにスタイルを適用できます。デフォルトではstyleはNoneで、追加のスタイルは適用されませんが、有効なスタイルであれば何でも設定できます。以下は、style属性が設定されたConsoleの例です。

from rich.console import Console
blue_console = Console(style="white on blue")
blue_console.print("I'm blue. Da ba dee da ba di.")

ソフトラッピング¶

Richは、改行を挿入することで、印刷するテキストを折り返します。この動作を無効にするには、print()を呼び出す際にsoft_wrap=Trueを設定します。_ソフトラッピング_が有効になっている場合、収まらないテキストは組み込みのprintと同様に、次の行に継続されます。

クロッピング¶

print()メソッドには、ブール型のcrop引数があります。cropのデフォルト値はTrueで、これにより、次の行に継続する可能性のあるコンテンツを切り捨てるようにRichに指示します。Richは利用可能な幅に合わせてコンテンツのサイズを変更するため、通常はクロッピングについて考える必要はありません。

注記

soft_wrap=Trueで印刷する場合、クロッピングは自動的に無効になります。

入力¶

consoleクラスにはinput()メソッドがあり、Pythonの組み込みのinput()関数と同じように動作しますが、Richで印刷できるものをプロンプトとして使用できます。たとえば、絵文字付きの色付きプロンプトを以下に示します。

from rich.console import Console
console = Console()
console.input("What is [i]your[/i] [bold red]name[/]? :smiley: ")

Pythonの組み込みreadlineモジュールが事前に読み込まれている場合、高度な行編集と履歴機能が利用可能になります。

エクスポート¶

Consoleクラスは、書き込まれた内容をテキスト、SVG、HTMLのいずれかとしてエクスポートできます。エクスポートを有効にするには、まずコンストラクタでrecord=Trueを設定します。これにより、print()またはlog()したデータのコピーが保存されます。例を以下に示します。

from rich.console import Console
console = Console(record=True)

コンテンツを書き込んだ後、export_text()、export_svg()、またはexport_html()を呼び出して、コンソール出力を文字列として取得できます。save_text()、save_svg()、またはsave_html()を呼び出して、コンテンツを直接ディスクに書き込むこともできます。

Rich Consoleによって生成されるHTML出力の例については、標準色を参照してください。

SVGのエクスポート¶

export_svg()またはsave_svg()を使用する場合、SVGの幅はターミナルウィンドウの幅（文字数で表す）と一致し、高さはコンソール出力に合わせて自動的に調整されます。

SVGをWebブラウザで開くことができます。<img>タグを使用してWebページに挿入したり、マークアップをHTMLにコピーすることもできます。

以下の画像は、RichによってエクスポートされたSVGの例を示しています。

rich.terminal_themeモジュールから目的のテーマをインポートし、themeパラメータを介してexport_svg()またはsave_svg()に渡すことで、SVGエクスポート時に使用するテーマをカスタマイズできます。

from rich.console import Console
from rich.terminal_theme import MONOKAI

console = Console(record=True)
console.save_svg("example.svg", theme=MONOKAI)

または、rich.terminal_theme.TerminalThemeインスタンスを自分で作成して渡すことで、独自のテーマを作成することもできます。

注記

SVGはFira Codeフォントを参照しています。Rich SVGをページに埋め込む場合は、Fira Code CSSへのリンクを追加することも検討してください。

エラーコンソール¶

Consoleオブジェクトはデフォルトでsys.stdoutに書き込みます（そのため、ターミナルに出力が表示されます）。stderr=TrueでConsoleを構築すると、Richはsys.stderrに書き込みます。これを使用して_エラーコンソール_を作成し、エラーメッセージと通常の出力を分離することができます。例を以下に示します。

from rich.console import Console
error_console = Console(stderr=True)

Consoleのstyleパラメータを設定して、エラーメッセージを視覚的に区別することもできます。方法は次のとおりです。

error_console = Console(stderr=True, style="bold red")

ファイル出力¶

コンストラクタのfile引数（テキスト書き込み用に開かれたファイルのようなオブジェクトである必要があります）を設定することで、Consoleオブジェクトにファイルへの書き込みを指示できます。これを使用して、出力がターミナルに表示されることなくファイルに書き込むことができます。例を以下に示します。

import sys
from rich.console import Console
from datetime import datetime

with open("report.txt", "wt") as report_file:
    console = Console(file=report_file)
    console.rule(f"Report Generated {datetime.now().ctime()}")

ファイルに書き込む場合、出力を現在のコンソールの幅に折り返したくない場合は、width引数を明示的に設定することをお勧めします。

出力のキャプチャ¶

出力をターミナルに直接書き込むのではなく、Consoleからの出力を_キャプチャ_したい場合があります。これはcapture()メソッドを使用して行うことができます。このメソッドはコンテキストマネージャーを返します。このコンテキストマネージャーから終了すると、get()を呼び出して、ターミナルに書き込まれたであろう文字列を返します。例を以下に示します。

from rich.console import Console
console = Console()
with console.capture() as capture:
    console.print("[bold red]Hello[/] World")
str_output = capture.get()

出力のキャプチャの別の方法は、Consoleファイルにio.StringIOを設定することです。これは、単体テストでコンソール出力をテストする場合に推奨される方法です。例を以下に示します。

from io import StringIO
from rich.console import Console
console = Console(file=StringIO())
console.print("[bold red]Hello[/] World")
str_output = console.file.getvalue()

ページング¶

ユーザーに提示する長い出力がある場合は、_ページャ_を使用して表示できます。ページャは通常、オペレーティングシステム上のアプリケーションで、少なくともキーを押してスクロールすることをサポートしますが、多くの場合、テキストの上下スクロールやその他の機能をサポートします。

pager()を呼び出すことで、Consoleからの出力をページングできます。これはコンテキストマネージャーを返します。ページャが終了すると、印刷されたものはすべてページャに送信されます。例を以下に示します。

from rich.__main__ import make_test_card
from rich.console import Console

console = Console()
with console.pager():
    console.print(make_test_card())

ほとんどのプラットフォームのデフォルトのページャは色をサポートしていないため、Richは出力から色を削除します。ページャが色をサポートしていることがわかっている場合は、pager() メソッドを呼び出す際にstyles=Trueを設定できます。

注記

Richは、ページャコマンドを取得するために、MANPAGER、次にPAGER環境変数を確認します（MANPAGERが優先されます）。LinuxとmacOSでは、これらのいずれかをless -rに設定して、ANSIスタイルによるページングを有効にできます。

代替スクリーン¶

警告

この機能は現在実験段階です。本番環境で使用する場合、しばらくお待ちいただくことをお勧めします。

端末は、通常の端末とは別に「代替スクリーン」モードをサポートしており、入力とコマンドのストリームをそのまま維持できるフルスクリーンアプリケーションを可能にします。Richはset_alt_screen()メソッドを介してこのモードをサポートしていますが、終了時に代替モードを無効にするコンテキストマネージャーを返すscreen()を使用することをお勧めします。

代替スクリーンの例を以下に示します。

from time import sleep
from rich.console import Console

console = Console()
with console.screen():
    console.print(locals())
    sleep(5)

上記のコードは、5秒後にコマンドプロンプトに戻る前に、整形された辞書を代替スクリーンに表示します。

screen()にレンダリング可能なオブジェクトを提供することもできます。これは、update()を呼び出すと、代替スクリーンに表示されます。

例を以下に示します。

from time import sleep

from rich.console import Console
from rich.align import Align
from rich.text import Text
from rich.panel import Panel

console = Console()

with console.screen(style="bold white on red") as screen:
    for count in range(5, 0, -1):
        text = Align.center(
            Text.from_markup(f"[blink]Don't Panic![/blink]\n{count}", justify="center"),
            vertical="middle",
        )
        screen.update(Panel(text))
        sleep(1)

レンダリング可能なオブジェクトを使用してスクリーンを更新すると、スクロールせずに画面に収まるようにコンテンツをトリミングできます。

Richでフルスクリーンインターフェースを構築するためのより強力な方法については、ライブ表示を参照してください。

注記

Pythonコードの終了後に代替モードで行き詰まった場合は、端末にresetと入力してください。

端末の検出¶

Richは、端末に書き込んでいないことを検出すると、出力から制御コードを削除します。制御コードを通常のファイルに書き込む場合は、コンストラクタでforce_terminal=Trueを設定します。

Richによる端末の自動検出は便利です。出力をファイルや他のアプリケーションにパイプすると、プレーンテキストが書き込まれるからです。

インタラクティブモード¶

端末に書き込んでいない場合、Richはプログレスバーやステータスインジケーターなどのアニメーションを削除します（たとえば、テキストファイルにこれらを書き込む必要がないためです）。コンストラクタのforce_interactive引数を設定して、この動作をオーバーライドできます。アニメーションを有効にするにはTrue、無効にするにはFalseに設定します。

注記

一部のCIシステムはANSIカラーとスタイルをサポートしますが、カーソルを移動したり、端末の一部を選択的に更新したりするものはサポートしていません。このような場合は、force_terminalをTrueに、force_interactiveをFalseに設定することをお勧めします。

環境変数¶

Richはいくつかの標準的な環境変数を尊重します。

環境変数TERMを"dumb"または"unknown"に設定すると、色/スタイルと、カーソルの移動を必要とする機能（プログレスバーなど）が無効になります。

環境変数FORCE_COLORが設定されている場合、TERMの値に関係なく、色/スタイルが有効になります。これは、端末ではないがANSIエスケープシーケンスを表示できるCIシステムで役立ちます。

環境変数NO_COLORが設定されている場合、Richは出力の色をすべて無効にします。これはFORCE_COLORよりも優先されます。no_colorの詳細を参照してください。

注記

NO_COLOR環境変数は、*色*のみを削除します。淡色、太字、斜体、下線などのスタイルは保持されます。

width / height引数がConsoleへの引数として明示的に提供されない場合、環境変数COLUMNS/LINESを使用してコンソールの幅/高さを設定できます。JUPYTER_COLUMNS/JUPYTER_LINESは同様に動作し、Jupyterで使用されます。