公共事業.

Clickが提供するパラメータ解析や処理インタフェースとの機能に加えて，コマンドライン実用プログラムの作成に有用な一連の付加機能を提供している.

標準出力に印刷する

最も明らかな助っ人は echo() 関数、この関数は多くの点でPythonと類似している print 文や関数。主な違いは，多くの異なる端末環境で同じように動作することである.

例：：

import click

click.echo('Hello World!')

これは，テキストデータを出力することも可能であるし，バイナリデータを出力することも可能である.デフォルトでは、転送する必要がある尾行変換子を発行します nl=False **

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

最後に重要でないことではありません echo() Clickを用いたスマート内部出力は，Windowsコンソール上のUnicode出力をサポートするstdoutとstderrに流れる.つまりあなたが使っている限り click.echo Unicode文字を出力することができます(表示可能な文字については、デフォルトフォントに制限があります)。

Changelog

バージョン 6.0 で追加.

Windows上のアナログ出力ストリームをクリックして、別個のAPIを介してWindowsコンソールへのUnicodeをサポートします。より多くの情報については、参照されたい Windowsコンソール備考 それがそうです。

Changelog

バージョン 3.0 で追加.

また、以下のパラメータを渡すことで、標準エラーに簡単に印刷することができます err=True **

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

ANSI色

Changelog

バージョン 2.0 で追加.

♪the echo() 関数はANSIの色とパターンを扱う余分な機能を獲得した.Windows上では、この機能は以下の場合にのみ利用可能であることに注意されたい colorama もう設置しました。これを実装すると，ANSIコードを知的に処理する.

これは主に

• クリックの echo() ストリームが端末に接続されていなければ，関数はANSIカラーコードを自動的に剥離する.

• ♪the echo() 関数はWindows上の端末に透過的に接続し，ANSIコードを端末API呼び出しに変換する.これは，色のWindows上での動作方式が他のオペレーティングシステム上での動作方式と同じであることを意味する.

メモ： colorama サポート：クリックがいつ自動的に検出されますか colorama 利用可能であり、それを使用することができる。vt.やって、やる not 呼び出し 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))

この2つの技術の結合は echo() そして style() 1つの名前で secho() **

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

ポケベル支持

場合によっては、端末上に長いテキストを表示し、ユーザにスクロール閲覧させることを望むことができる。これは使用することで echo_via_pager() 関数、この関数の動作方法は echo() 関数は，つねに標準出力を書き込み，可能であればページャを介して書き込まれる.

例：

@click.command()
def less():
    click.echo_via_pager("\n".join(f"Line {idx}" for idx in range(200)))

大量のテキストをページプログラムを用いて処理する場合、特に、すべてのコンテンツを予め生成しておくのに時間がかかる場合、文字列ではなく、生成器(または生成器関数)を渡すことができる：

def _generate_output():
    for idx in range(50000):
        yield f"Line {idx}\n"

@click.command()
def less():
    click.echo_via_pager(_generate_output())

スクリーンが空になる

Changelog

バージョン 2.0 で追加.

端末画面をクリアするためには、ご利用いただけます clear() Click 2.0から提供される機能.その機能はその名の通りですプラットフォームとは無関係な方法で可視画面全体をクリアします

import click
click.clear()

端末から文字を取得する

Changelog

バージョン 2.0 で追加.

一般に、端末から入力を読み取ると、標準入力から読み出される。しかし，これはバッファ入力であり，ラインが終了するまで表示されない.場合によっては、あなたはそうしたくなくて、単一の文字を書く時にそれらを読むことができるかもしれない。

そのためClickは getchar() 関数は、終端バッファから単一文字を読み出し、Unicode文字として返す関数である。

この関数は，標準入力がパイプラインであってもつねに端末から読み出されることに注意されたい.

例：：

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 これらはそれぞれキーボード割込みとファイル終了異常に変換される.このようにしたのは，そうでなければそれを忘れやすく，正しく脱退できないスクリプトを作成しやすいからである.

ボタンを待つ

Changelog

バージョン 2.0 で追加.

ユーザがキーボード上の任意のキーを押す前に一時停止することが有用である場合がある.これはWindows上で特に有用です cmd.exe デフォルトの場合、待つのではなく、コマンドの実行終了時にウィンドウを閉じる。

Clickではこれは pause() 機能します。この機能は、端末(カスタマイズ可能)に高速メッセージを印刷し、ユーザが次のキーを押すのを待つ。また，スクリプトが交互に実行されていなければ，NOP(操作命令なし)となる.

例：：

import click
click.pause()

エディタを起動する

Changelog

バージョン 2.0 で追加.

エディタを自動起動することで、サポートをクリックします 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')

アプリケーションを起動する

Changelog

バージョン 2.0 で追加.

クリックサポートは、以下のようにアプリケーションを起動します。 launch() それがそうです。これは、URLまたはファイルタイプに関連するデフォルトアプリケーションを開くために使用することができる。例えば、これは、ウェブブラウザまたは画像ビューアを起動するために使用されてもよい。それに加えて、ファイルマネージャを起動し、提供されたファイルを自動的に選択することができる。

例示的な用法：

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

ファイル名を印刷する

ファイル名はUnicodeではないかもしれないので、それらをフォーマットするのはちょっと難しいかもしれません。

クリックする方法は format_filename() 機能します。それはファイル名をUnicodeに変換するために最善を尽くし、決して失敗しないだろう。これにより，これらのファイル名を完全なUnicode文字列のコンテキストで使用することが可能となる.

例：：

click.echo(f"Path: {click.format_filename(b'foo.txt')}")

標準流.

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

だからこそClickは get_binary_stream() そして get_text_stream() 関数は、異なるPythonバージョンと様々な端末構成で一致した結果を生成する。

最終的な結果は、これらの関数は、常に関数フローオブジェクトに戻る(非常に奇妙な場合は除く；参照されたい。 Unicodeサポート ）。

例：：

import click

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

Changelog

バージョン 6.0 で追加.

現在Windows上で出力ストリームをシミュレートして、別個のAPIを介してWindowsコンソールにUnicodeをサポートしています。より多くの情報については、参照されたい Windowsコンソール備考 それがそうです。

スマートファイルが開きます

Changelog

バージョン 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')

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

Changelog

バージョン 2.0 で追加.

一般的に、あなたはあなたのアプリケーションに属する構成ファイルを開きたいです。しかし、異なるオペレーティングシステムは、その基準に従って、これらのプロファイルを異なる位置に格納する。クリックして提供できます get_app_dir() 関数は、オペレーティングシステムに従ってアプリケーションの各ユーザプロファイルの最適な位置を返す。

例示的な用法：

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[f"{section}.{key}"] = value
    return rv

プログレスバーを表示する

Changelog

バージョン 2.0 で追加.

大量のデータを処理する必要があるコマンドラインスクリプトがある場合もありますが、どのくらいの時間がかかるかをユーザに迅速に表示したいと思います。簡単なプログレスバーの提示をクリックしてサポートします(通過 progressbar() 機能します。

基本的な使い方は非常に簡単です：その思想はあなたが操作したい反復器を持っているということです。反復器の各々については、処理のためにいくつかの時間が必要となる場合がある。次のようなサイクルがあると仮定してください。

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)

クリックすると、プログレスバーが自動的に端末に印刷され、残りの時間が計算されます。残り時間の計算には，反復器の長さが要求される.長さがないが、長さを知っている場合、それを明示的に提供することができる：

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(f"sleep({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)

時々、ユーザは、外部反復器を必要とし、プログレスバーを不規則に進める必要がある場合がある。そのためには、長さを指定し(反復することができません)、コンテキストの返り値にupdate方法を使用する必要があります：

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