Tornado 命令行解析

一個命令行解析模塊，讓模塊定義自己的選項。

這個模塊的靈感來自谷歌的 gflags。 與 ?argparse等庫的主要區(qū)別在于使用了全局注冊表，以便可以在任何模塊中定義選項（默認情況下它還啟用 ?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)

應(yīng)用程序的 ?main()? 方法不需要了解整個程序中使用的所有選項； 它們都是在加載模塊時自動加載的。 但是，所有定義選項的模塊都必須在解析命令行之前導(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")

注意：

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

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

注意：

默認情況下，定義了幾個選項，用于在調(diào)用 ?parse_command_line或 ?parse_config_file時配置標準日志記錄模塊。 如果您希望 Tornado 單獨保留日志記錄配置以便您可以自己管理它，請在命令行上傳遞 ?--logging=none 或執(zhí)行以下操作以在代碼中禁用它：

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

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

全局函數(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

在全局命名空間中定義一個選項。

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

添加一個解析回調(diào)，在選項解析完成時調(diào)用。

exception tornado.options.Error

選項模塊中的錯誤引發(fā)的異常。

選項解析器類

class tornado.options.OptionParser

選項的集合，具有類似對象訪問權(quán)限的字典。

通常通過 ?tornado.options? 模塊中的靜態(tài)函數(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

定義一個新的命令行選項。

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

如果 ?multiple為 ?True，則選項值是類型列表而不是類型實例。

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

--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? 指定的文件中的選項將覆蓋先前在命令行上設(shè)置的選項，但可以被以后的標志覆蓋。

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

解析命令行上給出的所有選項（默認為 ?sys.argv?）。

選項看起來像 ?--option=value? 并根據(jù)它們的?type?進行解析。 對于布爾選項，?--option? 等效于?--option=true?

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

請注意，?args[0]? 被忽略，因為它是 ?sys.argv? 中的程序名稱。

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

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

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

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

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

選項可以是選項或字符串的指定類型（在這種情況下，它們的解析方式與 ?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?，解析回調(diào)將不會運行。 這對于希望組合來自多個來源的配置的應(yīng)用程序很有用。

注意：

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

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

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

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

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

將所有命令行選項打印到 stderr（或另一個文件）。

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

添加一個解析回調(diào)，在選項解析完成時調(diào)用。

OptionParser.mockable() → tornado.options._Mockable

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

?mock.patch? 函數(shù)（自 Python 3.3 起包含在標準庫 ?unittest.mock? 包中，或包含在舊版 Python 的第三方模擬包中）與覆蓋 ?__getattr__? 和 ?__setattr__? 的選項等對象不兼容。 此函數(shù)返回一個對象，該對象可與 ?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?創(chuàng)建的選項組集。

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

組中選項的名稱和值。

用于將選項復(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'))