tornado.options
— Command-line parsing¶
A command line parsing module that lets modules define their own options.
This module is inspired by Google’s gflags. The primary difference
with libraries such as argparse
is that a global registry is used so
that options may be defined in any module (it also enables
tornado.log
by default). The rest of Tornado does not depend on this
module, so feel free to use argparse
or other configuration
libraries if you prefer them.
Options must be defined with tornado.options.define
before use,
generally at the top level of a module. The options are then
accessible as attributes of 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)
The main()
method of your application does not need to be aware of all of
the options used throughout your program; they are all automatically loaded
when the modules are loaded. However, all modules that define options
must have been imported before the command line is parsed.
Your main()
method can parse the command line or parse a config file with
either parse_command_line
or 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")
注解
When using multiple parse_*
functions, pass final=False
to all
but the last one, or side effects may occur twice (in particular,
this can result in log messages being doubled).
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.
注解
By default, several options are defined that will configure the
standard logging
module when parse_command_line
or parse_config_file
are called. If you want Tornado to leave the logging configuration
alone so you can manage it yourself, either pass --logging=none
on the command line or do the following to disable it in code:
from tornado.options import options, parse_command_line
options.logging = None
parse_command_line()
在 4.3 版更改: Dashes and underscores are fully interchangeable in option names; options can be defined, set, and read with any mix of the two. Dashes are typical for command-line usage while config files require underscores.
Global functions¶
-
tornado.options.
define
(name, default=None, type=None, help=None, metavar=None, multiple=False, group=None, callback=None)[源代码]¶ Defines an option in the global namespace.
See
OptionParser.define
.
-
tornado.options.
options
¶ Global options object. All defined options are available as attributes on this object.
-
tornado.options.
parse_command_line
(args=None, final=True)[源代码]¶ Parses global options from the command line.
-
tornado.options.
print_help
(file=sys.stderr)[源代码]¶ Prints all the command line options to stderr (or another file).
OptionParser class¶
-
class
tornado.options.
OptionParser
[源代码]¶ A collection of options, a dictionary with object-like access.
Normally accessed via static functions in the
tornado.options
module, which reference a global instance.
-
OptionParser.
define
(name, default=None, type=None, help=None, metavar=None, multiple=False, group=None, callback=None)[源代码]¶ Defines a new command line option.
type
can be any ofstr
,int
,float
,bool
,datetime
, ortimedelta
. If notype
is given but adefault
is,type
is the type ofdefault
. Otherwise,type
defaults tostr
.If
multiple
is True, the option value is a list oftype
instead of an instance oftype
.help
andmetavar
are used to construct the automatically generated command line help string. The help message is formatted like:--name=METAVAR help string
group
is used to group the defined options in logical groups. By default, command line options are grouped by the file in which they are defined.Command line option names must be unique globally.
If a
callback
is given, it will be run with the new value whenever the option is changed. This can be used to combine command-line and file-based options:define("config", type=str, help="path to config file", callback=lambda path: parse_config_file(path, final=False))
With this definition, options in the file specified by
--config
will override options set earlier on the command line, but can be overridden by later flags.
-
OptionParser.
parse_command_line
(args=None, final=True)[源代码]¶ Parses all options given on the command line (defaults to
sys.argv
).Options look like
--option=value
and are parsed according to theirtype
. For boolean options,--option
is equivalent to--option=true
If the option has
multiple=True
, comma-separated values are accepted. For multi-value integer options, the syntaxx:y
is also accepted and equivalent torange(x, y)
.Note that
args[0]
is ignored since it is the program name insys.argv
.We return a list of all arguments that are not parsed as options.
If
final
isFalse
, parse callbacks will not be run. This is useful for applications that wish to combine configurations from multiple sources.
-
OptionParser.
parse_config_file
(path, final=True)[源代码]¶ Parses and loads the config file at the given path.
The config file contains Python code that will be executed (so it is not safe to use untrusted config files). Anything in the global namespace that matches a defined option will be used to set that option’s value.
Options may either be the specified type for the option or strings (in which case they will be parsed the same way as in
parse_command_line
)Example (using the options defined in the top-level docs of this module):
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'
If
final
isFalse
, parse callbacks will not be run. This is useful for applications that wish to combine configurations from multiple sources.注解
tornado.options
is primarily a command-line library. Config file support is provided for applications that wish to use it, but applications that prefer config files may wish to look at other libraries instead.在 4.1 版更改: Config files are now always interpreted as utf-8 instead of the system default encoding.
在 4.4 版更改: The special variable
__file__
is available inside config files, specifying the absolute path to the config file itself.在 5.1 版更改: Added the ability to set options via strings in config files.
-
OptionParser.
print_help
(file=None)[源代码]¶ Prints all the command line options to stderr (or another file).
-
OptionParser.
add_parse_callback
(callback)[源代码]¶ Adds a parse callback, to be invoked when option parsing is done.
-
OptionParser.
mockable
()[源代码]¶ Returns a wrapper around self that is compatible with
mock.patch
.The
mock.patch
function (included in the standard libraryunittest.mock
package since Python 3.3, or in the third-partymock
package for older versions of Python) is incompatible with objects likeoptions
that override__getattr__
and__setattr__
. This function returns an object that can be used withmock.patch.object
to modify option values:with mock.patch.object(options.mockable(), 'name', value): assert options.name == value
-
OptionParser.
group_dict
(group)[源代码]¶ The names and values of options in a group.
Useful for copying options into Application settings:
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 新版功能.