tornado.options — Command-line parsing

命令行解析模块,可让模块定义自己的选项.

这个模块的灵感来自于Google的gflags . 与argparse库的主要区别在于,使用了全局注册表,因此可以在任何模块中定义选项(默认情况下,它还会启用tornado.log ). Tornado的其余部分不依赖于此模块,因此,如果愿意,可以随意使用argparse或其他配置库.

在使用之前,必须使用tornado.options.define定义选项,通常在模块的顶层. 然后,可以将这些选项作为tornado.options.options属性进行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_lineparse_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")

Note

当使用多个parse_*函数时,将final=False传递给除最后一个函数以外的所有函数,否则可能发生两次副作用(特别是,这可能导致日志消息加倍).

tornado.options.options is a singleton instance of OptionParser, and the top-level functions in this module (define, parse_command_line, etc) simply call methods on it. You may create additional OptionParser instances to define isolated sets of options, such as for subcommands.

Note

默认情况下,定义了几个选项,这些选项将在parse_command_lineparse_config_file时配置标准logging模块. 如果希望Tornado保留日志记录配置以便您自己进行管理,请在命令行中传递--logging=none或执行以下操作以在代码中禁用它:

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

在版本4.3中更改:短划线和下划线在选项名称中可以完全互换; 可以定义,设置和读取选项,并且可以将两者结合使用. 短划线通常用于命令行,而配置文件需要下划线.

Global functions

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

在全局名称空间中定义一个选项.

See OptionParser.define.

tornado.options.options

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

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

从命令行解析全局选项.

See OptionParser.parse_command_line.

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

解析配置文件中的全局选项.

See OptionParser.parse_config_file.

tornado.options.print_help(file=sys.stderr)[source]

将所有命令行选项打印到stderr(或另一个文件).

See OptionParser.print_help.

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

添加一个解析回调,在完成选项解析后将被调用.

See OptionParser.add_parse_callback

exception tornado.options.Error[source]

选项模块中的错误引起的异常.

OptionParser class

class tornado.options.OptionParser[source]

选项的集合,是具有类对象访问权限的字典.

通常通过tornado.options模块中的静态函数访问,该函数引用了全局实例.

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

定义一个新的命令行选项.

type可以是strintfloatbooldatetimetimedelta . 如果没有type被赋予但default是, type为类型default . 否则,将默认typestr .

如果multiple为True,则选项值的列表type ,而不是实例type .

helpmetavar用于构造自动生成的命令行帮助字符串. 帮助消息的格式如下:

--name=METAVAR      help string

group用于将定义的选项分为逻辑组. 默认情况下,命令行选项按定义它们的文件分组.

命令行选项名称必须在全局范围内唯一.

如果给出了callback ,则更改选项时将使用新值运行该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: List[str] = None, final: bool = True) → List[str][source]

解析命令行上给定的所有选项(默认为sys.argv ).

选项类似于--option=value ,并根据其type进行分析. 对于布尔选项,-- --option等效于--option=true

如果选项具有multiple=True ,则接受逗号分隔的值. 对于多值整数选项,还接受语法x:y ,它等效于range(x, y) .

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

我们返回未解析为选项的所有参数的列表.

如果finalFalse ,则不会运行解析回调. 这对于希望合并多个来源的配置的应用程序很有用.

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

解析并加载给定路径下的配置文件.

配置文件包含将要执行的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'

如果finalFalse ,则不会运行解析回调. 这对于希望合并多个来源的配置的应用程序很有用.

Note

tornado.options主要是一个命令行库. 为希望使用配置文件的应用程序提供了配置文件支持,但是更喜欢配置文件的应用程序可能希望查看其他库.

在版本4.1中进行了更改:配置文件现在始终被解释为utf-8,而不是系统默认编码.

在版本4.4中进行了更改:特殊变量__file__在配置文件中可用,用于指定配置文件本身的绝对路径.

在5.1版中进行了更改:添加了通过配置文件中的字符串设置选项的功能.

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

将所有命令行选项打印到stderr(或另一个文件).

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

添加一个解析回调,在完成选项解析后将被调用.

OptionParser.mockable() → tornado.options._Mockable[source]

返回与mock.patch兼容的包装,该包装与mock.patch兼容.

The 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__ and __setattr__. This function returns an object that can be used with mock.patch.object to modify option values:

with mock.patch.object(options.mockable(), 'name', value):
    assert options.name == value
OptionParser.items() → Iterable[Tuple[str, Any]][source]

(名称,值)对的可迭代.

3.1版中的新功能.

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

所有选项的名称和值.

3.1版中的新功能.

OptionParser.groups() → Set[str][source]

define创建的一组选项组.

3.1版中的新功能.

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

组中选项的名称和值.

将选项复制到应用程序设置中很有用:

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