diff --git a/examples/manage.py b/examples/manage.py index 5c0dc21..56438bf 100755 --- a/examples/manage.py +++ b/examples/manage.py @@ -1,6 +1,7 @@ #!/usr/bin/env python # PYTHON_ARGCOMPLETE_OK +from __future__ import print_function import pprint from flask import Flask, current_app @@ -11,7 +12,7 @@ def create_app(config=None): app = Flask(__name__) app.debug = False - print "CONFIG", config + print("CONFIG", config) app.config.from_envvar('APP_CONFIG', silent=True) @@ -34,14 +35,14 @@ def dumpconfig(): @manager.command def output(name): "print something" - print name - print type(name) + print(name) + print(type(name)) @manager.command def outputplus(name, url=None): "print name and url" - print name, url + print(name, url) @manager.command @@ -50,7 +51,7 @@ def getrolesimple(): choices = ("member", "moderator", "admin") role = prompt_choices("role", choices=choices, default="member") - print "ROLE:", role + print("ROLE:", role) @manager.command @@ -63,14 +64,14 @@ def getrole(): ) role = prompt_choices("role", choices=choices, resolve=int, default=1) - print "ROLE:", role + print("ROLE:", role) @manager.option('-n', '--name', dest='name', help="your name") @manager.option('-u', '--url', dest='url', help="your url") def optional(name, url): "print name and url" - print name, url + print(name, url) manager.add_option("-c", "--config", dest="config", diff --git a/flask_script/__init__.py b/flask_script/__init__.py index 306f522..022ef8b 100644 --- a/flask_script/__init__.py +++ b/flask_script/__init__.py @@ -29,19 +29,21 @@ argparse._AppendConstAction, argparse._CountAction) - try: import argcomplete + ARGCOMPLETE_IMPORTED = True except ImportError: ARGCOMPLETE_IMPORTED = False -def add_help(parser, help_args): + +def add_help(parser, help_args): if not help_args: return parser.add_argument(*help_args, action='help', default=argparse.SUPPRESS, help=_('show this help message and exit')) + class Manager(object): """ Controller class for handling a set of commands. @@ -72,13 +74,13 @@ def run(self): :param disable_argcomplete: disable automatic loading of argcomplete. """ - help_args = ('-?','--help') + help_args = ('-?', '--help') def __init__(self, app=None, with_default_commands=None, usage=None, help=None, description=None, disable_argcomplete=False): self.app = app - + self.subparser_kwargs = dict() self._commands = OrderedDict() @@ -162,7 +164,7 @@ def __call__(self, app=None, **kwargs): def create_app(self, *args, **kwargs): warnings.warn("create_app() is deprecated; use __call__().", warnings.DeprecationWarning) - return self(*args,**kwargs) + return self(*args, **kwargs) def create_parser(self, prog, func_stack=(), parent=None): """ @@ -170,7 +172,7 @@ def create_parser(self, prog, func_stack=(), parent=None): by get_options(), and subparser for the given commands. """ prog = os.path.basename(prog) - func_stack=func_stack+(self,) + func_stack += (self,) options_parser = argparse.ArgumentParser(add_help=False) for option in self.get_options(): @@ -233,7 +235,7 @@ def _parse_known_args(self, arg_strings, *args, **kw): def get_options(self): return self._options - def add_command(self, *args, **kwargs): + def add_command(self, command_or_name, command=None, namespace=None): """ Adds command to registry. @@ -242,20 +244,18 @@ def add_command(self, *args, **kwargs): :param namespace: Namespace of the command (optional; pass as kwarg) """ - if len(args) == 1: - command = args[0] - name = None - - else: - name, command = args - - if name is None: + if command is None: + # one positional arg -> command, guess for name + command = command_or_name if hasattr(command, 'name'): name = command.name else: name = type(command).__name__.lower() name = re.sub(r'command$', '', name) + else: + # two positional args -> command, name + name = command_or_name if isinstance(command, Manager): command.parent = self @@ -263,19 +263,18 @@ def add_command(self, *args, **kwargs): if isinstance(command, type): command = command() - namespace = kwargs.get('namespace') - if not namespace: + if namespace is None: namespace = getattr(command, 'namespace', None) - if namespace: + if namespace is None: + # root namespace + self._commands[name] = command + else: if namespace not in self._commands: self.add_command(namespace, Manager()) self._commands[namespace]._commands[name] = command - else: - self._commands[name] = command - def command(self, func): """ Decorator to add a command function to the registry. @@ -284,7 +283,6 @@ def command(self, func): options. """ - command = Command(func) self.add_command(func.__name__, command) @@ -310,7 +308,6 @@ def decorate(func): name = func.__name__ if name not in self._commands: - command = Command() command.run = func command.__doc__ = func.__doc__ @@ -320,6 +317,7 @@ def decorate(func): self._commands[name].option_list.append(option) return func + return decorate def shell(self, func): @@ -351,7 +349,7 @@ def set_defaults(self): def handle(self, prog, args=None): self.set_defaults() app_parser = self.create_parser(prog) - + args = list(args or []) app_namespace, remaining_args = app_parser.parse_known_args(args) @@ -370,7 +368,7 @@ def handle(self, prog, args=None): # get only safe config options config_keys = [action.dest for action in handle.parser._actions - if handle is last_func or action.__class__ in safe_actions] + if handle is last_func or action.__class__ in safe_actions] # pass only safe app config keys config = dict((k, v) for k, v in iteritems(kwargs) @@ -385,7 +383,7 @@ def handle(self, prog, args=None): try: res = handle(*args, **config) except TypeError as err: - err.args = ("{0}: {1}".format(handle,str(err)),) + err.args = ("{0}: {1}".format(handle, str(err)),) raise args = [res] diff --git a/flask_script/_compat.py b/flask_script/_compat.py index 63f2173..aebea84 100644 --- a/flask_script/_compat.py +++ b/flask_script/_compat.py @@ -18,6 +18,7 @@ if not PY2: + # objects for Python >= 3 unichr = chr range_type = range text_type = str @@ -37,6 +38,8 @@ def reraise(tp, value, tb=None): raise value.with_traceback(tb) raise value + from inspect import getfullargspec as getargspec + ifilter = filter imap = map izip = zip @@ -50,9 +53,10 @@ def reraise(tp, value, tb=None): input = input else: + # objects for Python 2.7 unichr = unichr - text_type = unicode range_type = xrange + text_type = unicode string_types = (str, unicode) integer_types = (int, long) @@ -66,6 +70,8 @@ def reraise(tp, value, tb=None): exec('def reraise(tp, value, tb=None):\n raise tp, value, tb') + from inspect import getargspec + from itertools import imap, izip, ifilter intern = intern @@ -113,3 +119,5 @@ def __new__(cls, name, this_bases, d): from urllib.parse import quote_from_bytes as url_quote except ImportError: from urllib import quote as url_quote + +__all__ = [] \ No newline at end of file diff --git a/flask_script/commands.py b/flask_script/commands.py index 4d401eb..7f909cd 100644 --- a/flask_script/commands.py +++ b/flask_script/commands.py @@ -2,6 +2,7 @@ from __future__ import absolute_import,print_function import os +import re import sys import code import warnings @@ -13,7 +14,7 @@ from flask import _request_ctx_stack from .cli import prompt, prompt_pass, prompt_bool, prompt_choices -from ._compat import izip, text_type +from ._compat import izip, text_type, getargspec, iteritems class InvalidCommand(Exception): @@ -98,6 +99,54 @@ def __init__(self, *args, **kwargs): self.args = args self.kwargs = kwargs +decl_re = re.compile(':([a-z]+) ([A-Za-z_]+): ') +option_re = re.compile(r'\.\. option:: +(-*[a-z_]+)((?:, -+[a-z_]+)*)') + + +def clean_doc(doc): + """ + Cleans up a docstring and separates the main function documentation + from the documentation for the parameters + + :param doc: a docstring + :return: a tuple of (cleaned up docstring, map of parameter docs) + """ + if doc is None: + return None, {} + doc = inspect.cleandoc(doc) + main_part = [] + opt_parts = {} + cur_part = main_part + for line in doc.split('\n'): + m = decl_re.search(line) + if m: + if m.group(1) == 'param': + cur_part = [line[m.end():]] + opt_parts[m.group(2)] = cur_part + else: + # do not store + cur_part = [] + else: + m = option_re.search(line) + if m: + cur_part = [line[m.end():]] + opt_parts[m.group(1)] = cur_part + else: + cur_part.append(line) + result_main = '\n'.join(main_part) + result_opts = dict((k, '\n'.join(v)) for (k,v) in iteritems(opt_parts)) + return result_main, result_opts + +def add_help_text(option_list, arg_docs): + """ + add help text from param or option docstring + + :param option_list: a list of Option objects + :param arg_docs: a dictionary mapping option name to help text + """ + for opt in option_list: + if opt.args[0] in arg_docs and 'help' not in opt.kwargs: + opt.kwargs['help'] = arg_docs[opt.args[0]] class Command(object): """ @@ -113,12 +162,19 @@ def __init__(self, func=None): if func is None: if not self.option_list: self.option_list = [] + if self.__doc__ and not hasattr(self, 'help'): + self.help, arg_docs = clean_doc(self.__doc__) + add_help_text(self.option_list, arg_docs) return - args, varargs, keywords, defaults = inspect.getargspec(func) + args, varargs, keywords, defaults = getargspec(func)[:4] if inspect.ismethod(func): args = args[1:] + help, arg_docs = clean_doc(func.__doc__) + if not hasattr(self, 'help'): + self.help = help + options = [] # first arg is always "app" : ignore @@ -127,36 +183,35 @@ def __init__(self, func=None): kwargs = dict(izip(*[reversed(l) for l in (args, defaults)])) for arg in args: - + help_str = arg_docs.get(arg) if arg in kwargs: - default = kwargs[arg] - if isinstance(default, bool): options.append(Option('-%s' % arg[0], '--%s' % arg, action="store_true", dest=arg, + help=help_str, required=False, default=default)) else: options.append(Option('-%s' % arg[0], '--%s' % arg, dest=arg, + help=help_str, type=text_type, required=False, default=default)) else: - options.append(Option(arg, type=text_type)) + options.append(Option(arg, type=text_type, help=help_str)) self.run = func - self.__doc__ = func.__doc__ self.option_list = options @property def description(self): - description = self.__doc__ or '' + description = self.help or self.__doc__ or '' return description.strip() def add_option(self, option):