Tornado 命令行解析

一个命令行解析模块，让模块定义自己的选项。

这个模块的灵感来自谷歌的 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实例来定义隔离的选项集，例如子命令。

注意：

默认情况下，定义了几个选项，用于在调用 ​parse_command_line或 ​parse_config_file时配置标准日志记录模块。 如果您希望 Tornado 单独保留日志记录配置以便您可以自己管理它，请在命令行上传递 ​--logging=none 或执行以下操作以在代码中禁用它：

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

在 4.3 版更改: 破折号和下划线在选项名称中完全可以互换； 可以使用两者的任意组合来定义、设置和读取选项。 破折号通常用于命令行，而配置文件需要下划线。

全局函数

tornado.options.define(name: str, default: 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

在全局命名空间中定义一个选项。

tornado.options.options

全局选项对象。 所有定义的选项都可用作此对象的属性。

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

从命令行解析全局选项。

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

从配置文件中解析全局选项。

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

将所有命令行选项打印到 stderr（或另一个文件）。

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

添加一个解析回调，在选项解析完成时调用。

exception tornado.options.Error

选项模块中的错误引发的异常。

选项解析器类

class tornado.options.OptionParser

选项的集合，具有类似对象访问权限的字典。

通常通过 ​tornado.options​ 模块中的静态函数访问，这些函数引用全局实例。

OptionParser.define(name: str, default: 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是默认值的类型。 否则，类型默认为 ​str​。

如果 ​multiple为 ​True，则选项值是类型列表而不是类型实例。

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

返回与 ​mock.patch​ 兼容的 self 包装器。

​mock.patch​ 函数（自 Python 3.3 起包含在标准库 ​unittest.mock​ 包中，或包含在旧版 Python 的第三方模拟包中）与覆盖 ​__getattr__​ 和 ​__setattr__​ 的选项等对象不兼容。 此函数返回一个对象，该对象可与 ​mock.patch.object​ 一起使用以修改选项值：

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

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

可迭代的(name,value)键值对。

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

所有选项的名称和值。

OptionParser.groups() → Set[str]

​define​创建的选项组集。

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