Permalink
Browse files

Doc updates for the options module

  • Loading branch information...
1 parent 9229d59 commit 2aab06ba1a4311142d806b88a945c86c599866b4 @bdarnell bdarnell committed Sep 30, 2012
Showing with 96 additions and 56 deletions.
  1. +81 −52 tornado/options.py
  2. +15 −4 website/sphinx/options.rst
View
@@ -16,7 +16,8 @@
"""A command line parsing module that lets modules define their own options.
-Each module defines its own options, e.g.::
+Each module defines its own options which are added to the global
+option namespace, e.g.::
from tornado.options import define, options
@@ -30,12 +31,15 @@ def connect():
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. Your main() method can parse the command line
-or parse a config file with::
+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::
- import tornado.options
- tornado.options.parse_config_file("/etc/server.conf")
tornado.options.parse_command_line()
+ # or
+ tornado.options.parse_config_file("/etc/server.conf")
Command line formats are what you would expect ("--myoption=myvalue").
Config files are just Python files. Global names become options, e.g.::
@@ -46,6 +50,11 @@ def connect():
We support datetimes, timedeltas, ints, and floats (just pass a 'type'
kwarg to define). We also accept multi-value options. See the documentation
for define() below.
+
+`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.
"""
from __future__ import absolute_import, division, with_statement
@@ -90,6 +99,40 @@ def __setattr__(self, name, value):
def define(self, name, default=None, type=None, help=None, metavar=None,
multiple=False, group=None, callback=None):
+ """Defines a new command line option.
+
+ If type is given (one of str, float, int, datetime, or timedelta)
+ or can be inferred from the default, we parse the command line
+ arguments based on the given type. If multiple is True, we accept
+ comma-separated values, and the option value is always a list.
+
+ For multi-value integers, we also accept the syntax x:y, which
+ turns into range(x, y) - very useful for long integer ranges.
+
+ 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. They can be parsed
+ from the command line with parse_command_line() or parsed from a
+ config file with parse_config_file.
+
+ 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.
+ """
if name in self:
raise Error("Option %r already defined in %s", name,
self[name].file_name)
@@ -113,6 +156,16 @@ def define(self, name, default=None, type=None, help=None, metavar=None,
callback=callback)
def parse_command_line(self, args=None, final=True):
+ """Parses all options given on the command line (defaults to sys.argv).
+
+ 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.
+ """
if args is None:
args = sys.argv
remaining = []
@@ -144,6 +197,12 @@ def parse_command_line(self, args=None, final=True):
return remaining
def parse_config_file(self, path, final=True):
+ """Parses and loads the Python config file at the given path.
+
+ If ``final`` is ``False``, parse callbacks will not be run.
+ This is useful for applications that wish to combine configurations
+ from multiple sources.
+ """
config = {}
execfile(path, config, config)
for name in config:
@@ -188,6 +247,7 @@ def _help_callback(self, value):
sys.exit(0)
def add_parse_callback(self, callback):
+ """Adds a parse callback, to be invoked when option parsing is done."""
self._parse_callbacks.append(stack_context.wrap(callback))
def run_parse_callbacks(self):
@@ -322,82 +382,51 @@ def _parse_string(self, value):
options = OptionParser()
-"""Global options dictionary.
+"""Global options object.
-Supports both attribute-style and dict-style access.
+All defined options are available as attributes on this object.
"""
def define(name, default=None, type=None, help=None, metavar=None,
multiple=False, group=None, callback=None):
- """Defines a new command line option.
-
- If type is given (one of str, float, int, datetime, or timedelta)
- or can be inferred from the default, we parse the command line
- arguments based on the given type. If multiple is True, we accept
- comma-separated values, and the option value is always a list.
-
- For multi-value integers, we also accept the syntax x:y, which
- turns into range(x, y) - very useful for long integer ranges.
-
- 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 defined file.
-
- Command line option names must be unique globally. They can be parsed
- from the command line with parse_command_line() or parsed from a
- config file with parse_config_file.
-
- 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::
+ """Defines an option in the global namespace.
- 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.
+ See `OptionParser.define`.
"""
return options.define(name, default=default, type=type, help=help,
metavar=metavar, multiple=multiple, group=group,
callback=callback)
def parse_command_line(args=None, final=True):
- """Parses all options given on the command line (defaults to sys.argv).
-
- Note that args[0] is ignored since it is the program name in sys.argv.
+ """Parses global options from the command line.
- 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.
+ See `OptionParser.parse_command_line`.
"""
return options.parse_command_line(args, final=final)
def parse_config_file(path, final=True):
- """Parses and loads the Python config file at the given path.
+ """Parses global options from a config file.
- If ``final`` is ``False``, parse callbacks will not be run.
- This is useful for applications that wish to combine configurations
- from multiple sources.
+ See `OptionParser.parse_config_file`.
"""
return options.parse_config_file(path, final=final)
def print_help(file=None):
- """Prints all the command line options to stdout."""
+ """Prints all the command line options to stderr (or another file).
+
+ See `OptionParser.print_help`.
+ """
return options.print_help(file)
def add_parse_callback(callback):
- """Adds a parse callback, to be invoked when option parsing is done."""
+ """Adds a parse callback, to be invoked when option parsing is done.
+
+ See `OptionParser.add_parse_callback`
+ """
options.add_parse_callback(callback)
View
@@ -3,15 +3,26 @@
.. automodule:: tornado.options
+
+
+ Global functions
+ ----------------
+
.. autofunction:: define
.. py:data:: options
- Global options dictionary. Supports both attribute-style and
- dict-style access.
+ Global options object. All defined options are available as attributes
+ on this object.
.. autofunction:: parse_command_line
.. autofunction:: parse_config_file
- .. autofunction:: print_help(file=sys.stdout)
- .. autofunction:: enable_pretty_logging()
+ .. autofunction:: print_help(file=sys.stderr)
+ .. autofunction:: add_parse_callback
.. autoexception:: Error
+
+ OptionParser class
+ ------------------
+
+ .. autoclass:: OptionParser
+ :members:

0 comments on commit 2aab06b

Please sign in to comment.