Permalink
Browse files

Separate usage into usage/help/description

This commit implements a clear distinction between usage, help, and
description as in the argparse module. usage shows how the command
might be executed on the command line. help is a short description
for a command. description is a longer description for a command.

Before this commit, we didn't have a way to change description without
changing usage. This could be a nuisance for someone who wanted to see
the generate usage. For instance, if we ran `manage.py somecommand -h`,
we've seen something like this so far:

    usage: Some descriptions for the command.

    optional arguments:
      -h, --help            show this help message and exit
      ...

If we added usage manually to the docstring of the command, then the
output of `manage.py -h` would become ugly. The only way to get around
these problems is to use diffrent variables, namely help and description.
  • Loading branch information...
1 parent 72b5a3b commit b3e2536799c48cf5485d9c11ffabd22a88b2d299 @clee704 clee704 committed Oct 8, 2013
Showing with 31 additions and 7 deletions.
  1. +9 −3 flask_script/__init__.py
  2. +2 −2 flask_script/commands.py
  3. +20 −2 tests.py
@@ -64,7 +64,7 @@ def run(self):
"""
def __init__(self, app=None, with_default_commands=None, usage=None,
- disable_argcomplete=False):
+ help=None, description=None, disable_argcomplete=False):
self.app = app
@@ -76,7 +76,9 @@ def __init__(self, app=None, with_default_commands=None, usage=None,
if with_default_commands or (app and with_default_commands is None):
self.add_default_commands()
- self.usage = self.description = usage
+ self.usage = usage
+ self.help = help if help is not None else usage
+ self.description = description if description is not None else usage
self.disable_argcomplete = disable_argcomplete
self.parent = None
@@ -149,14 +151,18 @@ def create_parser(self, prog, parents=None):
# parser_parents = [options_parser]
parser = argparse.ArgumentParser(prog=prog, usage=self.usage,
+ description=self.description,
parents=[options_parser])
subparsers = parser.add_subparsers()
for name, command in self._commands.items():
+ usage = getattr(command, 'usage', None)
+ help = getattr(command, 'help', command.__doc__)
description = getattr(command, 'description', command.__doc__)
command_parser = command.create_parser(name, parents=[options_parser])
- subparser = subparsers.add_parser(name, usage=description, help=description,
+ subparser = subparsers.add_parser(name, usage=usage, help=help,
+ description=description,
parents=[command_parser], add_help=False)
@@ -197,7 +197,7 @@ class Shell(Command):
banner = ''
- description = 'Runs a Python shell inside Flask application context.'
+ help = description = 'Runs a Python shell inside Flask application context.'
def __init__(self, banner=None, make_context=None, use_ipython=True,
use_bpython=True):
@@ -286,7 +286,7 @@ class Server(Command):
:param options: :func:`werkzeug.run_simple` options.
"""
- description = 'Runs the Flask development server i.e. app.run()'
+ help = description = 'Runs the Flask development server i.e. app.run()'
def __init__(self, host='127.0.0.1', port=5000, use_debugger=True,
use_reloader=True, threaded=False, processes=1,
View
@@ -641,14 +641,23 @@ def test_manager_usage_with_submanager(self, capsys):
assert code == 0
assert 'Example sub-manager' in out
- def test_submanager_usage(self, capsys):
+ def test_submanager_usage_and_help_and_description(self, capsys):
- sub_manager = Manager(usage='Example sub-manager')
+ sub_manager = Manager(usage='sub_manager [--foo]',
+ help='shorter desc for submanager',
+ description='longer desc for submanager')
sub_manager.add_command('simple', SimpleCommand())
manager = Manager(self.app)
manager.add_command('sub_manager', sub_manager)
+ code = run('manage.py -h', lambda: manager.run())
+ out, err = capsys.readouterr()
+ assert code == 0
+ assert 'sub_manager [--foo]' not in out
+ assert 'shorter desc for submanager' in out
+ assert 'longer desc for submanager' not in out
+
code = run('manage.py sub_manager', lambda: manager.run())
out, err = capsys.readouterr()
assert code == 2
@@ -657,6 +666,15 @@ def test_submanager_usage(self, capsys):
code = run('manage.py sub_manager -h', lambda: manager.run())
out, err = capsys.readouterr()
assert code == 0
+ assert 'sub_manager [--foo]' in out
+ assert 'shorter desc for submanager' not in out
+ assert 'longer desc for submanager' in out
+ assert 'simple command' in out
+
+ code = run('manage.py sub_manager simple -h', lambda: manager.run())
+ out, err = capsys.readouterr()
+ assert code == 0
+ assert 'sub_manager [--foo] simple [-h]' in out
assert 'simple command' in out
def test_submanager_has_no_default_commands(self):

1 comment on commit b3e2536

@suiwenfeng

what about description for command or option? Is it supported?

Please sign in to comment.