tornado.options ---命令行分析

命令行分析模块，允许模块定义自己的选项。

这个模块的灵感来自谷歌 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.options

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

注解

使用多个时 parse_* 功能、通行证 final=False 对于除最后一条以外的所有消息，或副作用可能会发生两次（特别是，这可能导致日志消息加倍）。

tornado.options.options 是的单实例 OptionParser 以及本模块中的顶级功能 (define ， parse_command_line 等）只需对其调用方法。您可以创建其他 OptionParser 用于定义独立选项集的实例，例如用于子命令的实例。

注解

默认情况下，将定义几个选项来配置标准 logging 模块时间 parse_command_line 或 parse_config_file 被称为。如果您希望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 除了A default 是， type 是什么类型 default . 否则， type 默认为 str .

如果 multiple 为真，选项值是 type 而不是 type .

help 和 metavar 用于构造自动生成的命令行帮助字符串。帮助消息的格式如下：

--name=METAVAR      help string

group 用于将定义的选项分组到逻辑组中。默认情况下，命令行选项按定义它们的文件分组。

命令行选项名称必须全局唯一。

如果A 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) .

注意 args[0] 被忽略，因为它是中的程序名 sys.argv .

我们返回一个未被解析为选项的所有参数的列表。

如果 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() → tornado.options._Mockable

返回与兼容的自我包装 mock.patch .

这个 mock.patch function (included in the standard library unittest.mock package since Python 3.3, or in the third-party mock package for older versions of Python) is incompatible with objects like options that override _ _ getattr_uuu``和 ``__setattr__ . 此函数返回一个可用于 mock.patch.object 要修改选项值：

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

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

（名称、值）对的可Itable。

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 新版功能.