クイックスタート—ドキュメントをクリックします
クイックスタート
ライブラリはPyPIから直接入手できます。
pip install click
virtualenv にインストールすることを強くお勧めします。
virtualenv
Virtualenvは、おそらくClickアプリケーションの開発に使用したいものです。
virtualenvはどのような問題を解決しますか? Clickスクリプト以外のプロジェクトにも使用したい場合があります。 ただし、プロジェクトが多ければ多いほど、異なるバージョンのPython自体、または少なくとも異なるバージョンのPythonライブラリを使用する可能性が高くなります。 それに直面しましょう。ライブラリは下位互換性を壊すことがよくあり、深刻なアプリケーションの依存関係がゼロになる可能性はほとんどありません。 では、2つ以上のプロジェクトの依存関係が競合している場合はどうしますか?
Virtualenvが救いの手を差し伸べます! Virtualenvを使用すると、プロジェクトごとに1つずつ、Pythonを複数並べてインストールできます。 実際にはPythonの個別のコピーをインストールしませんが、さまざまなプロジェクト環境を分離しておくための賢い方法を提供します。 virtualenvがどのように機能するか見てみましょう。
Mac OS XまたはLinuxを使用している場合は、次の2つのコマンドのいずれかが機能する可能性があります。
$ sudo easy_install virtualenv
またはさらに良い:
$ pip install virtualenv --user
これらの1つは、おそらくシステムにvirtualenvをインストールします。 多分それはあなたのパッケージマネージャーにもあります。 Ubuntuを使用している場合は、次を試してください。
$ sudo apt-get install python-virtualenv
Windowsを使用している場合(または上記の方法のいずれも機能しない場合)は、最初にpip
をインストールする必要があります。 詳細については、 pipのインストールを参照してください。 インストールしたら、上からpip
コマンドを実行しますが、 sudo プレフィックスは付けません。
virtualenvをインストールしたら、シェルを起動して独自の環境を作成します。 私は通常、プロジェクトフォルダと venv フォルダを次の場所に作成します。
$ mkdir myproject
$ cd myproject
$ virtualenv venv
New python executable in venv/bin/python
Installing setuptools, pip............done.
これで、プロジェクトで作業するときはいつでも、対応する環境をアクティブ化するだけで済みます。 OS XおよびLinuxでは、次の手順を実行します。
$ . venv/bin/activate
Windowsユーザーの場合、次のコマンドが適しています。
$ venv\scripts\activate
いずれにせよ、virtualenvを使用しているはずです(アクティブな環境を表示するためにシェルのプロンプトがどのように変更されたかに注意してください)。
また、現実の世界に戻りたい場合は、次のコマンドを使用します。
$ deactivate
これを行った後、シェルのプロンプトは以前と同じように馴染みがあるはずです。
それでは、次に進みましょう。 次のコマンドを入力して、virtualenvでクリックをアクティブにします。
$ pip install Click
数秒後、あなたは行ってもいいです。
スクリーンキャストと例
Clickの基本的なAPIと、それを使用して簡単なアプリケーションを構築する方法を示すスクリーンキャストが利用可能です。 また、サブコマンドを使用してコマンドを作成する方法についても説明します。
Clickアプリケーションの例は、ドキュメントとGitHubリポジトリにreadmeファイルとともにあります。
inout
:ファイルの入出力naval
: docopt海軍の例のポートaliases
:コマンドエイリアスの例repo
: Git- / Mercurialのようなコマンドラインインターフェイスcomplex
:プラグインをロードする複雑な例validation
:カスタムパラメータ検証の例colors
: ColoramaANSIカラーサポートtermui
:ターミナルUI関数のデモimagepipe
:マルチコマンドチェーンデモ
基本概念-コマンドの作成
クリックは、デコレータを介したコマンドの宣言に基づいています。 内部的には、高度なユースケース用の非デコレータインターフェイスがありますが、高レベルの使用にはお勧めしません。
関数は、 click.command()で装飾することにより、Clickコマンドラインツールになります。 最も単純な場合、このデコレータで関数をデコレートするだけで、呼び出し可能なスクリプトになります。
何が起こっているのかというと、デコレータは関数を Command に変換し、それを呼び出すことができます。
if __name__ == '__main__':
hello()
そしてそれはどのように見えるか:
および対応するヘルプページ:
エコー
この例では、通常のprint()
関数の代わりに echo()を使用するのはなぜですか? この質問に対する答えは、ClickがPython2とPython3の両方を同じ方法でサポートし、環境が正しく構成されていない場合でも非常に堅牢になるようにすることです。 Clickは、すべてが完全に壊れていても、少なくとも基本的なレベルで機能することを望んでいます。
これが意味するのは、 echo()関数は、UnicodeError
で死ぬのではなく、端末が正しく構成されていない場合にエラー訂正を適用するということです。
追加の利点として、Click 2.0以降、エコー機能はANSIカラーも適切にサポートしています。 出力ストリームがファイルの場合はANSIコードが自動的に削除され、coloramaがサポートされている場合は、ANSIカラーもWindowsで機能します。 Python 2では、 echo()関数はバイト配列からのカラーコード情報を解析しないことに注意してください。 詳細については、 ANSI Colors を参照してください。
これが必要ない場合は、 print()コンストラクト/関数を使用することもできます。
ネストコマンド
コマンドは、タイプ Group の他のコマンドに添付できます。 これにより、スクリプトを任意にネストできます。 例として、データベースを管理するための2つのコマンドを実装するスクリプトを次に示します。
ご覧のとおり、 group()デコレータは command()デコレータと同じように機能しますが、代わりに Group オブジェクトを作成します。 Group.add_command()でアタッチされます。
単純なスクリプトの場合、代わりに Group.command()デコレータを使用して、コマンドを自動的にアタッチおよび作成することもできます。 上記のスクリプトは、代わりに次のように記述できます。
次に、setuptoolsエントリポイントまたはその他の呼び出しで Group を呼び出します。
if __name__ == '__main__':
cli()
Setuptoolsへの切り替え
これまでに作成したコードでは、ファイルの最後にif __name__ == '__main__':
のようなブロックがあります。 これは伝統的にスタンドアロンのPythonファイルがどのように見えるかです。 Clickを使用すると、それを続行できますが、setuptoolsを使用するより良い方法があります。
これには2つの主な(そしてもっと多くの)理由があります:
1つ目は、setuptoolsがWindowsの実行可能ラッパーを自動的に生成するため、コマンドラインユーティリティがWindowsでも機能することです。
2番目の理由は、setuptoolsスクリプトがUnix上のvirtualenvで動作し、virtualenvをアクティブ化する必要がないことです。 これは、すべての要件を含むスクリプトをvirtualenvにバンドルできる非常に便利な概念です。
Clickはそれを操作するために完全に装備されており、実際、残りのドキュメントでは、setuptoolsを使用してアプリケーションを作成していることを前提としています。
例ではsetuptoolsを使用することを前提としているため、残りを読む前に Setuptools Integration の章を確認することを強くお勧めします。