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，否则可能会出现两次副作用（特别是，这可能会导致日志消息加倍）。

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)。

请注意，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() → _Mockable

返回一个围绕 self 的包装器，它与 mock.patch 兼容。

mock.patch 函数（包含在 Python 3.3 及更高版本中的标准库 unittest.mock 包中，或者在较早版本的 Python 中的第三方 mock 包中）与像 options 这样的对象不兼容，这些对象会覆盖 __getattr__ 和 __setattr__。此函数返回一个对象，该对象可以与 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 中新增。