ユーティリティ—ドキュメントをクリック

ユーティリティ

Clickが引数の解析と処理とのインターフェースとして提供する機能に加えて、コマンドラインユーティリティの作成に役立つ一連のアドオン機能も提供します。

Stdoutへの印刷

最も明白なヘルパーは echo（）関数であり、多くの点でPython printステートメントまたは関数のように機能します。 主な違いは、Python 2と3で同じように機能し、誤って構成された出力ストリームをインテリジェントに検出し、失敗することはないことです（Python 3を除く。詳細については、 Python 3の制限を参照してください）。

例：

import click

click.echo('Hello World!')

最も重要なことは、バイトを出力できないPython3の組み込みprint関数とは異なり、Unicodeデータとバイナリデータの両方を出力できることです。 ただし、デフォルトでは末尾の改行が出力されます。これは、nl=Falseを渡すことで抑制される必要があります。

click.echo(b'\xe2\x98\x83', nl=False)

最後になりましたが、 echo（）は、クリックのインテリジェントな内部出力ストリームを使用して、WindowsコンソールでのUnicode出力をサポートするstdoutおよびstderrを実行します。 これは、 click.echo を使用している限り、Unicode文字を出力できることを意味します（表示できる文字に関して、デフォルトのフォントにはいくつかの制限があります）。 この機能はClick6.0の新機能です。

バージョン6.0の新機能。

Clickは、Windowsで出力ストリームをエミュレートして、個別のAPIを介したWindowsコンソールへのUnicodeをサポートするようになりました。 詳細については、 Windowsコンソールノートを参照してください。

バージョン3.0の新機能。

Click 3.0以降では、err=Trueを渡すことで、標準エラーに簡単に印刷することもできます。

click.echo('Hello World!', err=True)

ANSIカラー

バージョン2.0の新機能。

Click 2.0以降、 echo（）関数は、ANSIの色とスタイルを処理するための追加機能を追加しました。 Windowsでは、この機能は colorama がインストールされている場合にのみ使用できることに注意してください。 インストールされている場合、ANSIコードはインテリジェントに処理されます。 Python 2では、echo関数はバイト配列からのカラーコード情報を解析しないことに注意してください。

主にこれは次のことを意味します。

• クリックの echo（）関数は、ストリームが端末に接続されていない場合、ANSIカラーコードを自動的に削除します。
• echo（）関数は、Windowsの端末に透過的に接続し、ANSIコードを端末API呼び出しに変換します。 これは、色が他のオペレーティングシステムと同じようにWindowsで機能することを意味します。

colorama サポートに関する注意：クリックすると、 colorama が使用可能になると自動的に検出され、使用されます。 しないでください colorama.init()に電話してください！

colorama をインストールするには、次のコマンドを実行します。

$ pip install colorama

文字列のスタイルを設定するには、 style（）関数を使用できます。

import click

click.echo(click.style('Hello World!', fg='green'))
click.echo(click.style('Some more text', bg='blue', fg='white'))
click.echo(click.style('ATTENTION', blink=True, bold=True))

echo（）と style（）の組み合わせは、 secho（）と呼ばれる単一の関数でも使用できます。

click.secho('Hello World!', fg='green')
click.secho('Some more text', bg='blue', fg='white')
click.secho('ATTENTION', blink=True, bold=True)

ポケットベルのサポート

状況によっては、端末に長いテキストを表示して、ユーザーにスクロールさせたい場合があります。 これは、 echo（）関数と同様に機能する echo_via_pager（）関数を使用して実現できますが、常にstdoutに書き込み、可能であればページャーを介して書き込みます。

例：

大量のテキストにページャーを使用する場合、特に事前にすべてを生成するのに時間がかかる場合は、文字列の代わりにジェネレーター（またはジェネレーター関数）を渡すことができます。

画面のクリア

バージョン2.0の新機能。

ターミナル画面をクリアするには、Click2.0以降で提供されている clear（）関数を使用できます。 名前が示すとおりに機能します。プラットフォームに依存しない方法で、表示されている画面全体をクリアします。

import click
click.clear()

ターミナルからのキャラクターの取得

バージョン2.0の新機能。

通常、端末から入力を読み取る場合は、標準入力から読み取ります。 ただし、これはバッファリングされた入力であり、回線が終了するまで表示されません。 特定の状況では、それを実行したくない場合があり、代わりに、書き込まれている個々の文字を読み取ります。

このために、Clickは getchar（）関数を提供します。この関数は、ターミナルバッファーから単一の文字を読み取り、それをUnicode文字として返します。

stdinが代わりにパイプである場合でも、この関数は常にターミナルから読み取ることに注意してください。

例：

import click

click.echo('Continue? [yn] ', nl=False)
c = click.getchar()
click.echo()
if c == 'y':
    click.echo('We will go on')
elif c == 'n':
    click.echo('Abort!')
else:
    click.echo('Invalid input :(')

これは生の入力を読み取ることに注意してください。つまり、矢印キーなどがプラットフォームのネイティブエスケープ形式で表示されます。 翻訳される文字は^Cと^Dのみで、それぞれキーボード割り込みとファイルの終わりの例外に変換されます。 そうしないと、それを忘れて、適切に終了できないスクリプトを作成するのが簡単すぎるためです。

キーが押されるのを待っています

バージョン2.0の新機能。

ユーザーがキーボードのいずれかのキーを押すまで一時停止すると便利な場合があります。 これは、cmd.exeがコマンド実行の終了時に待機する代わりにデフォルトでウィンドウを閉じるWindowsで特に役立ちます。

クリックすると、 pause（）関数を使用してこれを実行できます。 この機能は、端末（カスタマイズ可能）にクイックメッセージを出力し、ユーザーがキーを押すのを待ちます。 それに加えて、スクリプトがインタラクティブに実行されない場合は、NOP（操作命令なし）にもなります。

例：

import click
click.pause()

エディターの起動

バージョン2.0の新機能。

Clickは、 edit（）を介したエディターの自動起動をサポートしています。 これは、ユーザーに複数行の入力を求める場合に非常に便利です。 ユーザーが定義したエディターを自動的に開くか、適切なデフォルトにフォールバックします。 ユーザーが保存せずにエディターを閉じると、戻り値はNoneになります。それ以外の場合は、入力されたテキストになります。

使用例：

import click

def get_commit_message():
    MARKER = '# Everything below is ignored\n'
    message = click.edit('\n\n' + MARKER)
    if message is not None:
        return message.split(MARKER, 1)[0].rstrip('\n')

または、この関数を使用して、特定のファイル名でファイルのエディターを起動することもできます。 この場合、戻り値は常に None です。

使用例：

import click
click.edit(filename='/etc/passwd')

アプリケーションの起動

バージョン2.0の新機能。

Clickは、 launch（）を介したアプリケーションの起動をサポートしています。 これを使用して、URLまたはファイルタイプに関連付けられたデフォルトのアプリケーションを開くことができます。 これは、たとえば、Webブラウザや画像ビューアを起動するために使用できます。 これに加えて、ファイルマネージャを起動し、提供されたファイルを自動的に選択することもできます。

使用例：

click.launch("https://click.palletsprojects.com/")
click.launch("/my/downloaded/file.txt", locate=True)

ファイル名の印刷

ファイル名はUnicodeでない可能性があるため、フォーマットするのは少し難しい場合があります。 一般に、Python2ではprint関数を使用してstdoutにバイトを書き込むことができるため、これは3よりも簡単ですが、Python 3では、常にUnicodeで操作する必要があります。

これがクリックで機能する方法は、 format_filename（）関数を使用することです。 ファイル名からUnicodeへのベストエフォート変換を実行し、失敗することはありません。 これにより、これらのファイル名を完全なUnicode文字列のコンテキストで使用できるようになります。

例：

click.echo('Path: %s' % click.format_filename(b'foo.txt'))

標準ストリーム

コマンドラインユーティリティの場合、入力ストリームと出力ストリームに確実にアクセスすることが非常に重要です。 Pythonは通常、sys.stdoutやその仲間を介してこれらのストリームへのアクセスを提供しますが、残念ながら、特にこれらのストリームがUnicodeおよびバイナリデータにどのように応答するかに関して、2.xと3.xの間にはAPIの違いがあります。

このため、clickは get_binary_stream（）および get_text_stream（）関数を提供します。これらの関数は、さまざまなPythonバージョンおよびさまざまな端末構成で一貫した結果を生成します。

最終的な結果として、これらの関数は常に機能ストリームオブジェクトを返します（Python 3の非常に奇妙な場合を除き、 Python 3の制限を参照）。

例：

import click

stdin_text = click.get_text_stream('stdin')
stdout_binary = click.get_binary_stream('stdout')

バージョン6.0の新機能。

Clickは、Windowsで出力ストリームをエミュレートして、個別のAPIを介したWindowsコンソールへのUnicodeをサポートするようになりました。 詳細については、 Windowsコンソールノートを参照してください。

インテリジェントなファイルを開く

バージョン3.0の新機能。

Click 3.0以降、 File タイプからファイルを開くためのロジックは、 open_file（）関数を介して公開されます。 stdin / stdoutやその他のファイルをインテリジェントに開くことができます。

例：

import click

stdout = click.open_file('-', 'w')
test_file = click.open_file('test.txt', 'w')

stdinまたはstdoutが返される場合、戻り値は特別なファイルにラップされ、コンテキストマネージャーがファイルを閉じるのを防ぎます。 これにより、標準ストリームの処理が透過的になり、いつでも次のように使用できます。

with click.open_file(filename, 'w') as f:
    f.write('Hello World!\n')

アプリケーションフォルダの検索

バージョン2.0の新機能。

多くの場合、アプリケーションに属する構成ファイルを開きたいと思うでしょう。 ただし、オペレーティングシステムが異なれば、これらの構成ファイルは標準に応じてさまざまな場所に保存されます。 Clickは、 get_app_dir（）関数を提供します。この関数は、OSに応じて、アプリケーションのユーザーごとの構成ファイルの最適な場所を返します。

使用例：

import os
import click
import ConfigParser

APP_NAME = 'My Application'

def read_config():
    cfg = os.path.join(click.get_app_dir(APP_NAME), 'config.ini')
    parser = ConfigParser.RawConfigParser()
    parser.read([cfg])
    rv = {}
    for section in parser.sections():
        for key, value in parser.items(section):
            rv['%s.%s' % (section, key)] = value
    return rv

プログレスバーの表示

バージョン2.0の新機能。

場合によっては、大量のデータを処理する必要のあるコマンドラインスクリプトがありますが、その所要時間に関する進捗状況をユーザーにすばやく表示したい場合があります。 Clickは、 progressbar（）関数を介した単純なプログレスバーレンダリングをサポートしています。

基本的な使用法は非常に単純です。つまり、操作したい反復可能オブジェクトがあるということです。 iterable内のアイテムごとに、処理に時間がかかる場合があります。 したがって、次のようなループがあるとします。

for user in all_the_users_to_process:
    modify_the_user(user)

自動的に更新されるプログレスバーにこれを接続するには、コードを次のように変更するだけです。

import click

with click.progressbar(all_the_users_to_process) as bar:
    for user in bar:
        modify_the_user(user)

クリックすると、プログレスバーが端末に自動的に印刷され、残り時間が計算されます。 残り時間の計算には、iterableに長さが必要です。 長さがないが長さがわかっている場合は、明示的に指定できます。

with click.progressbar(all_the_users_to_process,
                       length=number_of_users) as bar:
    for user in bar:
        modify_the_user(user)

progressbar（）は、ループの各反復の後に後にバーを更新することに注意してください。 したがって、このようなコードは正しくレンダリングされます。

import time

with click.progressbar([1, 2, 3]) as bar:
    for x in bar:
        print('sleep({})...'.format(x))
        time.sleep(x)

もう1つの便利な機能は、進行状況バーの前に表示される進行状況バーにラベルを関連付けることです。

with click.progressbar(all_the_users_to_process,
                       label='Modifying user accounts',
                       length=number_of_users) as bar:
    for user in bar:
        modify_the_user(user)

場合によっては、外部イテレータを繰り返し処理し、プログレスバーを不規則に進める必要があります。 これを行うには、長さを指定し（反復可能ではなく）、コンテキストの戻り値を直接反復するのではなく、更新メソッドを使用する必要があります。

with click.progressbar(length=total_size,
                       label='Unzipping archive') as bar:
    for archive in zip_file:
        archive.extract()
        bar.update(archive.size)