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

傳回一個包裝自我的物件，該物件與 mock.patch 相容。

mock.patch 函式（自 Python 3.3 起包含在標準函式庫 unittest.mock 套件中，或是在較舊版本的 Python 中包含在第三方 mock 套件中）與覆寫了 __getattr__ 和 __setattr__ 的物件（例如 options）不相容。此函式會傳回一個可以用 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]

一個群組中選項的名稱和值。

適用於將選項複製到 Application 設定中。

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