Improve documentation

* document InvalidCommand error class
* re-raise the TypeError you get from handler() when the arguments do not
  match with the name of the actual failed procedure, since Python
  does not.

Author: smurfix

docs/index.rst

@@ -569,6 +569,35 @@ The commands will then be available::
       populate  Populate database with default data
       recreate  Recreates database tables (same as issuing 'drop' and then 'create')
 
+Error handling
+--------------
+
+Users do not like to see stack traces, but developers want them for bug reports.
+
+Therefore, ``flask.ext.script.command`` provides an `InvalidCommand` error
+class which is not supposed to print a stack trace when reported.
+
+In your command handler:
+
+	from flask.ext.script.command import InvalidCommand
+
+    [… if some command verification fails …]
+    class MyCommand(Command):
+        def run(self, foo=None,bar=None):
+            if foo and bar:
+	            raise InvalidCommand("Options foo and bar are incompatible")
+
+In your main loop:
+
+    try:
+        MyManager().run()
+    except InvalidCommand as err:
+        print(err, file=sys.stderr)
+        sys.exit(1)
+
+This way, you maintain interoperability if some plug-in code supplies
+Flask-Script hooks you'd like to use, or vice versa.
+
 Accessing local proxies
 -----------------------
 

flask_script/__init__.py

@@ -379,7 +379,12 @@ def handle(self, prog, args=None):
 
             if handle is last_func and getattr(last_func, 'capture_all_args', False):
                 args.append(remaining_args)
-            res = handle(*args, **config)
+            try:
+                res = handle(*args, **config)
+            except TypeError as err:
+                err.args = ("{}: {}".format(handle,str(err)),)
+                raise
+
             args = [res]
 
         assert not kwargs

flask_script/commands.py

@@ -16,9 +16,18 @@
 
 
 class InvalidCommand(Exception):
+    """\
+        This is a generic error for "bad" commands.
+        It is not used in Flask-Script itself, but you should throw
+		this error (or one derived from it) in your command handlers,
+        and your main code should display this error's message without
+        a stack trace.
+
+        This way, we maintain interoperability if some other plug-in code
+        supplies Flask-Script hooks.
+        """
     pass
 
-
 class Group(object):
     """
     Stores argument groups and mutually exclusive groups for

setup.py

@@ -27,7 +27,7 @@
 
 setup(
     name='Flask-Script',
-    version='2.0.2',
+    version='2.0.3',
     url='http://github.com/smurfix/flask-script',
     license='BSD',
     author='Dan Jacob',