一個(gè)命令行解析模塊，讓模塊定義自己的選項(xiàng)。

這個(gè)模塊的靈感來(lái)自谷歌的 gflags。 與 ?argparse等庫(kù)的主要區(qū)別在于使用了全局注冊(cè)表，以便可以在任何模塊中定義選項(xiàng)（默認(rèn)情況下它還啟用 ?tornado.log?）。 Tornado 的其余部分不依賴于該模塊，因此如果您愿意，請(qǐng)隨意使用 ?argparse或其他配置庫(kù)。

選項(xiàng)必須在使用前用 ?tornado.options.define 定義，通常在模塊的頂層。 然后這些選項(xiàng)可以作為 ?tornado.options.options 的屬性訪問(wèn)：

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

應(yīng)用程序的 ?main()? 方法不需要了解整個(gè)程序中使用的所有選項(xiàng)； 它們都是在加載模塊時(shí)自動(dòng)加載的。 但是，所有定義選項(xiàng)的模塊都必須在解析命令行之前導(dǎo)入。

您的 ?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")

注意：

當(dāng)使用多個(gè) ?parse_*? 函數(shù)時(shí)，將 ?final=False? 傳遞給除最后一個(gè)之外的所有函數(shù)，否則可能會(huì)出現(xiàn)兩次副作用（特別是，這可能導(dǎo)致日志消息加倍）。

?tornado.options.options? 是 ?OptionParser的單例實(shí)例，該模塊中的頂級(jí)函數(shù)（?define、?parse_command_line等）只是在其上調(diào)用方法。 您可以創(chuàng)建額外的 ?OptionParser實(shí)例來(lái)定義隔離的選項(xiàng)集，例如子命令。

注意：

默認(rèn)情況下，定義了幾個(gè)選項(xiàng)，用于在調(diào)用 ?parse_command_line或 ?parse_config_file時(shí)配置標(biāo)準(zhǔn)日志記錄模塊。 如果您希望 Tornado 單獨(dú)保留日志記錄配置以便您可以自己管理它，請(qǐng)?jiān)诿钚猩蟼鬟f ?--logging=none 或執(zhí)行以下操作以在代碼中禁用它：

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

在 4.3 版更改: 破折號(hào)和下劃線在選項(xiàng)名稱中完全可以互換； 可以使用兩者的任意組合來(lái)定義、設(shè)置和讀取選項(xiàng)。 破折號(hào)通常用于命令行，而配置文件需要下劃線。

全局函數(shù)

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

在全局命名空間中定義一個(gè)選項(xiàng)。

tornado.options.options

全局選項(xiàng)對(duì)象。 所有定義的選項(xiàng)都可用作此對(duì)象的屬性。

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

從命令行解析全局選項(xiàng)。

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

從配置文件中解析全局選項(xiàng)。

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

將所有命令行選項(xiàng)打印到 stderr（或另一個(gè)文件）。

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

添加一個(gè)解析回調(diào)，在選項(xiàng)解析完成時(shí)調(diào)用。

exception tornado.options.Error

選項(xiàng)模塊中的錯(cuò)誤引發(fā)的異常。

選項(xiàng)解析器類

class tornado.options.OptionParser

選項(xiàng)的集合，具有類似對(duì)象訪問(wèn)權(quán)限的字典。

通常通過(guò) ?tornado.options? 模塊中的靜態(tài)函數(shù)訪問(wèn)，這些函數(shù)引用全局實(shí)例。

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

定義一個(gè)新的命令行選項(xiàng)。

?type可以是 ?str、?int、?float?、?bool?、?datetime或 ?timedelta中的任何一種。 如果沒(méi)有給出類型但給出了默認(rèn)值，則 ?type是默認(rèn)值的類型。 否則，類型默認(rèn)為 ?str?。

如果 ?multiple為 ?True，則選項(xiàng)值是類型列表而不是類型實(shí)例。

?help和 ?metavar用于構(gòu)造自動(dòng)生成的命令行幫助字符串。 幫助消息的格式如下：

--name=METAVAR      help string

?group用于將定義的選項(xiàng)分組到邏輯組中。 默認(rèn)情況下，命令行選項(xiàng)按定義它們的文件分組。

命令行選項(xiàng)名稱必須全局唯一。

如果給出了?callback?，則只要更改選項(xiàng)，它將使用新值運(yùn)行。 這可用于組合命令行和基于文件的選項(xiàng)：

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

使用此定義，由 ?--config? 指定的文件中的選項(xiàng)將覆蓋先前在命令行上設(shè)置的選項(xiàng)，但可以被以后的標(biāo)志覆蓋。

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

解析命令行上給出的所有選項(xiàng)（默認(rèn)為 ?sys.argv?）。

選項(xiàng)看起來(lái)像 ?--option=value? 并根據(jù)它們的?type?進(jìn)行解析。 對(duì)于布爾選項(xiàng)，?--option? 等效于?--option=true?

如果選項(xiàng)有 ?multiple=True?，則接受逗號(hào)分隔的值。 對(duì)于多值整數(shù)選項(xiàng)，語(yǔ)法 ?x:y? 也被接受并等效于 ?range(x, y)?。

請(qǐng)注意，?args[0]? 被忽略，因?yàn)樗?nbsp;?sys.argv? 中的程序名稱。

我們返回所有未解析為選項(xiàng)的參數(shù)列表。

如果 ?final為 ?False，解析回調(diào)將不會(huì)運(yùn)行。 這對(duì)于希望組合來(lái)自多個(gè)來(lái)源的配置的應(yīng)用程序很有用。

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

解析并加載給定路徑的配置文件。

配置文件包含將被執(zhí)行的 Python 代碼（因此使用不受信任的配置文件是不安全的）。 全局命名空間中與已定義選項(xiàng)匹配的任何內(nèi)容都將用于設(shè)置該選項(xiàng)的值。

選項(xiàng)可以是選項(xiàng)或字符串的指定類型（在這種情況下，它們的解析方式與 ?parse_command_line相同）

示例（使用此模塊的頂級(jí)文檔中定義的選項(xiàng)）：

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?，解析回調(diào)將不會(huì)運(yùn)行。 這對(duì)于希望組合來(lái)自多個(gè)來(lái)源的配置的應(yīng)用程序很有用。

注意：

?tornado.options? 主要是一個(gè)命令行庫(kù)。 為希望使用它的應(yīng)用程序提供了配置文件支持，但更喜歡配置文件的應(yīng)用程序可能希望查看其他庫(kù)。

在 4.1 版更改: 配置文件現(xiàn)在總是被解釋為 utf-8 而不是系統(tǒng)默認(rèn)編碼。

在 4.4 版更改：特殊變量 ?__file__ ?在配置文件中可用，指定配置文件本身的絕對(duì)路徑。

在 5.1 版更改: 添加了通過(guò)配置文件中的字符串設(shè)置選項(xiàng)的功能。

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

將所有命令行選項(xiàng)打印到 stderr（或另一個(gè)文件）。

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

添加一個(gè)解析回調(diào)，在選項(xiàng)解析完成時(shí)調(diào)用。

OptionParser.mockable() → tornado.options._Mockable

返回與 ?mock.patch? 兼容的 self 包裝器。

?mock.patch? 函數(shù)（自 Python 3.3 起包含在標(biāo)準(zhǔn)庫(kù) ?unittest.mock? 包中，或包含在舊版 Python 的第三方模擬包中）與覆蓋 ?__getattr__? 和 ?__setattr__? 的選項(xiàng)等對(duì)象不兼容。 此函數(shù)返回一個(gè)對(duì)象，該對(duì)象可與 ?mock.patch.object? 一起使用以修改選項(xiàng)值：

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

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

可迭代的(name,value)鍵值對(duì)。

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

所有選項(xiàng)的名稱和值。

OptionParser.groups() → Set[str]

?define?創(chuàng)建的選項(xiàng)組集。

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

組中選項(xiàng)的名稱和值。

用于將選項(xiàng)復(fù)制到應(yīng)用程序設(shè)置中：

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