Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Separate usage into usage/help/description #79

Merged
merged 1 commit into from

2 participants

Choongmin Lee Sean Lynch
Choongmin Lee

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.

Choongmin Lee clee704 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.
b3e2536
Sean Lynch techniq merged commit 62c4176 into from
Sean Lynch
Collaborator

Looks like a reasonable change. Thanks.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Oct 8, 2013
  1. Choongmin Lee

    Separate usage into usage/help/description

    clee704 authored
    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.
This page is out of date. Refresh to see the latest.
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
12 flask_script/__init__.py
View
@@ -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)
4 flask_script/commands.py
View
@@ -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,
22 tests.py
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):
Something went wrong with that request. Please try again.