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")
Note
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.
Note
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()
Changed in version 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)[source]
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)[source]
Parses global options from the command line.
tornado.options.parse_config_file(path, final=True)[source]
Parses global options from a config file.
tornado.options.print_help(file=sys.stderr)[source]
Prints all the command line options to stderr (or another file).
tornado.options.add_parse_callback(callback)[source]
Adds a parse callback, to be invoked when option parsing is done.
exception tornado.options.Error[source]
Exception raised by errors in the options module.
OptionParser class
class tornado.options.OptionParser[source]
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)[source]
Defines a new command line option.
type can be any of str, int, float, bool,
datetime, or timedelta. If no type
is given but a default is, type is the type of
default. Otherwise, type defaults to str.
If multiple is True, the option value is a list of type
instead of an instance of type.
help and metavar 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)[source]
Parses all options given on the command line (defaults to
sys.argv).
Options look like --option=value and are parsed according
to their type. 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 syntax
x:y is also accepted and equivalent to range(x, y).
Note that args[0] is ignored since it is the program name
in sys.argv.
We return a list of all arguments that are not parsed as options.
If final is False, 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)[source]
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 are not parsed from strings as they would be on the
command line; they should be set to the correct type (this
means if you have datetime or timedelta options you
will need to import those modules in the config file.
Example (using the options defined in the top-level docs of this module):
port = 80
mysql_host = 'mydb.example.com:3306'
memcache_hosts = ['cache1.example.com:11011',
'cache2.example.com:11011']
If final is False, parse callbacks will not be run.
This is useful for applications that wish to combine configurations
from multiple sources.
Note
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.
Changed in version 4.1: Config files are now always interpreted as utf-8 instead of the system default encoding.
Changed in version 4.4: The special variable __file__ is available inside config
files, specifying the absolute path to the config file itself.
OptionParser.print_help(file=None)[source]
Prints all the command line options to stderr (or another file).
OptionParser.add_parse_callback(callback)[source]
Adds a parse callback, to be invoked when option parsing is done.
OptionParser.mockable()[source]
Returns a wrapper around self that is compatible with
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()[source]
A sequence of (name, value) pairs.
New in version 3.1.
OptionParser.as_dict()[source]
The names and values of all options.
New in version 3.1.
OptionParser.groups()[source]
The set of option-groups created by define.
New in version 3.1.
OptionParser.group_dict(group)[source]
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'))
New in version 3.1.