tornado.options — コマンドライン解析

モジュールが独自のオプションを定義できるようにするコマンドライン解析モジュール。

このモジュールは、Googleのgflagsに触発されています。argparseなどのライブラリとの主な違いは、グローバルレジストリが使用されるため、どのモジュールでもオプションを定義できることです（デフォルトでtornado.logも有効になります）。Tornadoの残りの部分は、このモジュールに依存していないため、必要に応じてargparseまたは他の構成ライブラリを自由に使用してください。

オプションは、使用前にtornado.options.defineで定義する必要があります。一般的には、モジュールのトップレベルで定義します。オプションは、tornado.options.optionsの属性としてアクセスできます。

# myapp/db.py
from tornado.options import define, options

define("mysql_host", default="127.0.0.1:3306", help="Main user DB")
define("memcache_hosts", default="127.0.0.1:11011", multiple=True,
       help="Main user memcache servers")

def connect():
    db = database.Connection(options.mysql_host)
    ...

# myapp/server.py
from tornado.options import define, options

define("port", default=8080, help="port to listen on")

def start_server():
    app = make_app()
    app.listen(options.port)

アプリケーションのmain()メソッドは、プログラム全体で使用されるすべてのオプションを認識する必要はありません。それらは、モジュールがロードされるときにすべて自動的にロードされます。ただし、オプションを定義するすべてのモジュールは、コマンドラインが解析される前にインポートされている必要があります。

main()メソッドでは、parse_command_lineまたはparse_config_fileのいずれかで、コマンドラインまたは設定ファイルを解析できます。

import myapp.db, myapp.server
import tornado

if __name__ == '__main__':
    tornado.options.parse_command_line()
    # or
    tornado.options.parse_config_file("/etc/server.conf")

注

複数のparse_*関数を使用する場合は、最後の関数以外はすべてfinal=Falseを渡してください。そうしないと、副作用が2回発生する可能性があります（特に、ログメッセージが2倍になる可能性があります）。

tornado.options.optionsはOptionParserのシングルトンインスタンスであり、このモジュールのトップレベル関数（define、parse_command_lineなど）は、単にそのメソッドを呼び出すだけです。サブコマンドなど、分離されたオプションのセットを定義するために、追加のOptionParserインスタンスを作成できます。

注

デフォルトでは、parse_command_lineまたはparse_config_fileが呼び出されると、標準のloggingモジュールを構成するいくつかのオプションが定義されています。Tornadoにログ構成をそのままにして自分で管理する場合は、コマンドラインで--logging=noneを渡すか、次のコードを実行して無効にします。

from tornado.options import options, parse_command_line
options.logging = None
parse_command_line()

注

parse_command_lineまたはparse_config_file関数は、callbackオプション定義を使用して、ログ構成とユーザー定義のコマンドラインフラグを設定した後で呼び出す必要があります。そうしないと、これらの構成は有効になりません。

バージョン 4.3 で変更: オプション名では、ダッシュとアンダースコアは完全に交換可能です。オプションは、両方を混在させて定義、設定、読み取りできます。ダッシュはコマンドラインでの使用に一般的ですが、設定ファイルにはアンダースコアが必要です。

グローバル関数

tornado.options.define(name: str, default: Optional[Any] = None, type: Optional[type] = None, help: Optional[str] = None, metavar: Optional[str] = None, multiple: bool = False, group: Optional[str] = None, callback: Optional[Callable[[Any], None]] = None) → None

グローバル名前空間にオプションを定義します。

OptionParser.defineを参照してください。

tornado.options.options

グローバルなオプションオブジェクト。定義されたすべてのオプションは、このオブジェクトの属性として利用可能です。

tornado.options.parse_command_line(args: Optional[List[str]] = None, final: bool = True) → List[str]

コマンドラインからグローバルオプションを解析します。

OptionParser.parse_command_lineを参照してください。

tornado.options.parse_config_file(path: str, final: bool = True) → None

設定ファイルからグローバルオプションを解析します。

OptionParser.parse_config_fileを参照してください。

tornado.options.print_help(file=sys.stderr)

すべてのコマンドラインオプションを stderr（または別のファイル）に出力します。

OptionParser.print_helpを参照してください。

tornado.options.add_parse_callback(callback: Callable[[], None]) → None

オプションの解析が完了したときに呼び出される解析コールバックを追加します。

OptionParser.add_parse_callbackを参照してください

exception tornado.options.Error

オプションモジュールでのエラーによって発生する例外。

OptionParser クラス

class tornado.options.OptionParser

オプションのコレクションで、オブジェクトのようなアクセスを持つ辞書です。

通常は、グローバルインスタンスを参照するtornado.optionsモジュールの静的関数を介してアクセスされます。

OptionParser.define(name: str, default: Optional[Any] = None, type: Optional[type] = None, help: Optional[str] = None, metavar: Optional[str] = None, multiple: bool = False, group: Optional[str] = None, callback: Optional[Callable[[Any], None]] = None) → None

新しいコマンドラインオプションを定義します。

type は、str、int、float、bool、datetime、または timedelta のいずれかになります。type が指定されていないが、default が指定されている場合、type は default の型になります。それ以外の場合、type のデフォルトは str です。

multiple が True の場合、オプションの値は type のインスタンスではなく、type のリストになります。

help および metavar は、自動生成されるコマンドラインヘルプ文字列の構築に使用されます。ヘルプメッセージは次のようにフォーマットされます。

--name=METAVAR      help string

group は、定義されたオプションを論理グループにグループ化するために使用されます。デフォルトでは、コマンドラインオプションは、それらが定義されているファイルによってグループ化されます。

コマンドラインオプションの名前は、グローバルに一意である必要があります。

callback が指定されている場合、オプションが変更されるたびに、新しい値を使用して実行されます。これは、コマンドラインオプションとファイルベースのオプションを組み合わせるために使用できます。

define("config", type=str, help="path to config file",
       callback=lambda path: parse_config_file(path, final=False))

この定義では、--config で指定されたファイル内のオプションは、コマンドラインで以前に設定されたオプションを上書きしますが、後続のフラグによって上書きされる可能性があります。

OptionParser.parse_command_line(args: Optional[List[str]] = None, final: bool = True) → List[str]

コマンドラインで指定されたすべてのオプションを解析します（デフォルトは sys.argv です）。

オプションは --option=value のようになり、それらの type に従って解析されます。ブールオプションの場合、--option は --option=true と同等です。

オプションに multiple=True がある場合、コンマ区切りの値が受け入れられます。複数値の整数オプションの場合、x:y の構文も受け入れられ、range(x, y) と同等です。

sys.argv のプログラム名であるため、args[0] は無視されることに注意してください。

オプションとして解析されなかったすべての引数のリストを返します。

final が False の場合、解析コールバックは実行されません。これは、複数のソースからの構成を組み合わせたいアプリケーションに役立ちます。

OptionParser.parse_config_file(path: str, final: bool = True) → None

指定されたパスにある設定ファイルを解析してロードします。

設定ファイルには、実行されるPythonコードが含まれています（したがって、信頼できない設定ファイルを使用するのは**安全ではありません**）。定義されたオプションと一致するグローバル名前空間のものは、そのオプションの値を設定するために使用されます。

オプションは、オプションに指定された型、または文字列のいずれかになります（この場合、parse_command_line と同じ方法で解析されます）。

例（このモジュールのトップレベルドキュメントで定義されたオプションを使用）：

port = 80
mysql_host = 'mydb.example.com:3306'
# Both lists and comma-separated strings are allowed for
# multiple=True.
memcache_hosts = ['cache1.example.com:11011',
                  'cache2.example.com:11011']
memcache_hosts = 'cache1.example.com:11011,cache2.example.com:11011'

final が False の場合、解析コールバックは実行されません。これは、複数のソースからの構成を組み合わせたいアプリケーションに役立ちます。

注

tornado.options は主にコマンドラインライブラリです。設定ファイルサポートは、それを使用したいアプリケーション向けに提供されていますが、設定ファイルを好むアプリケーションは、代わりに他のライブラリを調べることをお勧めします。

バージョン 4.1 で変更: 設定ファイルは、システムのデフォルトエンコーディングではなく、常に utf-8 として解釈されるようになりました。

バージョン 4.4 で変更: 特別な変数 __file__ は、設定ファイル自体の絶対パスを指定する設定ファイル内で使用できるようになりました。

バージョン 5.1 で変更: 設定ファイルで文字列を介してオプションを設定する機能が追加されました。

OptionParser.print_help(file: Optional[TextIO] = None) → None

すべてのコマンドラインオプションを stderr（または別のファイル）に出力します。

OptionParser.add_parse_callback(callback: Callable[[], None]) → None

オプションの解析が完了したときに呼び出される解析コールバックを追加します。

OptionParser.mockable() → _Mockable

mock.patch と互換性のある、自身のラッパーを返します。

標準ライブラリのmock.patch関数（Python 3.3以降ではunittest.mockパッケージに含まれており、古いバージョンのPythonではサードパーティのmockパッケージに含まれています）は、__getattr__と__setattr__をオーバーライドするoptionsのようなオブジェクトとは互換性がありません。この関数は、オプションの値を変更するためにmock.patch.objectで使用できるオブジェクトを返します。

with mock.patch.object(options.mockable(), 'name', value):
    assert options.name == value

OptionParser.items() → Iterable[Tuple[str, Any]]

(名前, 値) ペアのイテラブル。

バージョン 3.1 で新規追加。

OptionParser.as_dict() → Dict[str, Any]

すべてのオプションの名前と値。

バージョン 3.1 で新規追加。

OptionParser.groups() → Set[str]

defineによって作成されたオプショングループのセット。

バージョン 3.1 で新規追加。

OptionParser.group_dict(group: str) → Dict[str, Any]

グループ内のオプションの名前と値。

オプションをアプリケーション設定にコピーするのに役立ちます。

from tornado.options import define, parse_command_line, options

define('template_path', group='application')
define('static_path', group='application')

parse_command_line()

application = Application(
    handlers, **options.group_dict('application'))

バージョン 3.1 で新規追加。