BREAKING CHANGE: adjust cli API on KegApp

- `KegApp.cli` is now a `keg.cli.KegAppGroup` instance, which is a subclass of `Click.Group` and knows how to instantiate the Keg app when needed.
- `KegApp.command()` is no longer available.  Use `.cli.command()` instead.
- `KegApp.cli_run()` is no longer available.  Use `.cli.main()` or it's alias `.cl()` instead.

See keg_apps.cli2 for example usage on a minimal app.

Author: rsyring

keg/_flask_cli.py

@@ -24,13 +24,16 @@ class KegAppError(Exception):
 
 class Keg(flask.Flask):
     import_name = None
-    use_blueprints = []
-    oauth_providers = []
+    use_blueprints = ()
+    oauth_providers = ()
     keyring_enabled = ConfigAttribute('KEG_KEYRING_ENABLE')
     config_class = keg.config.Config
     logging_class = keg.logging.Logging
     keyring_manager_class = None
 
+    _cli = None
+    cli_loader_class = keg.cli.CLILoader
+
     db_enabled = False
     db_visit_modules = ['.model.entities']
     db_manager = None
@@ -39,8 +42,8 @@ class Keg(flask.Flask):
         extensions=['jinja2.ext.autoescape', 'jinja2.ext.with_', AssetsExtension]
     )
 
-    template_filters = {}
-    template_globals = {}
+    template_filters = ImmutableDict()
+    template_globals = ImmutableDict()
 
     visit_modules = False
 
@@ -194,23 +197,12 @@ def handle_server_error(self, error):
     def request_context(self, environ):
         return KegRequestContext(self, environ)
 
-    @classproperty
-    def cli_group(cls):  # noqa
-        if not hasattr(cls, '_cli_group'):
-            cls._cli_group = keg.cli.init_app_cli(cls)
-        return cls._cli_group
-
-    @classmethod
-    def command(cls, *args, **kwargs):
-        return cls.cli_group.command(*args, **kwargs)
-
-    @classmethod
-    def cli_run(cls):
-        """
-            Convience function intended to be an entry point for an app's command.  Sets up the
-            app and kicks off the cli command processing.
-        """
-        cls.cli_group()
+    def _cli_getter(cls):  # noqa: first argument is not self in this context due to @classproperty
+        if cls._cli is None:
+            cal = cls.cli_loader_class(cls)
+            cls._cli = cal.create_group()
+        return cls._cli
+    cli = classproperty(_cli_getter, ignore_set=True)
 
     @classmethod
     def environ_key(cls, key):

keg/app.py

@@ -5,20 +5,60 @@
 
 import click
 import flask
+from flask.cli import AppGroup, with_appcontext, run_command, shell_command, ScriptInfo
 from six.moves import urllib
 
 from keg import current_app
-from keg._flask_cli import FlaskGroup, script_info_option, with_appcontext, run_command, \
-    shell_command
 from keg.keyring import keyring as keg_keyring
 
 
-class KegGroup(FlaskGroup):
-    def __init__(self, add_default_commands=True, *args, **kwargs):
-        FlaskGroup.__init__(self, add_default_commands=False, *args, **kwargs)
+class KegAppGroup(AppGroup):
+    def __init__(self, create_app, add_default_commands=True, *args, **kwargs):
+        self.create_app = create_app
+
+        AppGroup.__init__(self, *args, **kwargs)
         if add_default_commands:
             self.add_command(dev_command)
 
+        self._loaded_plugin_commands = False
+
+    def _load_plugin_commands(self):
+        if self._loaded_plugin_commands:
+            return
+        try:
+            import pkg_resources
+        except ImportError:
+            self._loaded_plugin_commands = True
+            return
+
+        for ep in pkg_resources.iter_entry_points('flask.commands'):
+            self.add_command(ep.load(), ep.name)
+        for ep in pkg_resources.iter_entry_points('keg.commands'):
+            self.add_command(ep.load(), ep.name)
+        self._loaded_plugin_commands = True
+
+    def list_commands(self, ctx):
+        self._load_plugin_commands()
+
+        info = ctx.ensure_object(ScriptInfo)
+        info.load_app()
+        rv = set(click.Group.list_commands(self, ctx))
+        return sorted(rv)
+
+    def get_command(self, ctx, name):
+        info = ctx.ensure_object(ScriptInfo)
+        info.load_app()
+        return click.Group.get_command(self, ctx, name)
+
+    def main(self, *args, **kwargs):
+        obj = kwargs.get('obj')
+        if obj is None:
+            obj = ScriptInfo(create_app=self.create_app)
+        kwargs['obj'] = obj
+        # TODO: figure out if we want to use this next line.
+        #kwargs.setdefault('auto_envvar_prefix', 'FLASK')
+        return AppGroup.main(self, *args, **kwargs)
+
 
 @click.group('develop', help='Developer info and utils.')
 def dev_command():
@@ -244,19 +284,85 @@ def keyring_delete(key):
     flask.current_app.keyring_manager.delete(key)
 
 
-def init_app_cli(appcls):
-
-    # this function will be used to initialize the app along, including the value of config_profile
-    # which can be passed on the command line.
-    def _create_app(script_info):
-        app = appcls()
-        app.init(config_profile=script_info.data['config_profile'])
-        return app
-
-    @click.group(cls=KegGroup, create_app=_create_app)
-    @script_info_option('--profile', script_info_key='config_profile', default=None,
-                        help='Name of the configuration profile to use.')
-    def cli(**kwargs):
-        pass
-
-    return cli
+class CLILoader(object):
+    """
+        This loader takes care of the complexity of click object setup and instantiation in the
+        correct order so that application level CLI options are available before the Keg app is
+        instantiated (so the options can be used to configure the app).
+
+        The order of events is:
+
+        - instantiate KegAppGroup
+        - KegAppGroup.main() is called
+            1. the ScriptInfo object is instantiated
+            2. normal click behavior starts, including argument parsing
+                - arguments are always parsed due to invoke_without_command=True
+            3. during argument parsing, option callbacks are excuted which will result in at least
+               the profile name being saved in ScriptInfo().data
+            4. Normal click .main() behavior will continue which could include processing commands
+               decorated with flask.cli.with_appcontext() or calls to KegAppGroup.list_commands()
+               or KegAppGroup.get_command().
+                - ScriptInfo.init_app() will be called during any of these operations
+                - ScriptInfo.init_app() will call self.create_app() below with the ScriptInfo
+                  instance
+    """
+    def __init__(self, appcls):
+        self.appcls = appcls
+        # Don't store instance-level vars here.  This object is only instantiated once per Keg
+        # sub-class but can be used across multiple app instance creations.  So, anything app
+        # instance specific should go on the ScriptInfo instance (see self.options_callback()).
+
+    def create_group(self):
+        """ Create the top most click Group instance which is the entry point for any Keg app
+            being called in a CLI context.
+
+            The return value of this context gets set on Keg.cli
+        """
+
+        return KegAppGroup(
+            self.create_app,
+            params=self.create_script_options(),
+            callback=self.main_callback,
+            invoke_without_command=True,
+        )
+
+    def create_app(self, script_info):
+        """ Instantiate our app, sending CLI option values through as needed. """
+        return self.appcls().init(config_profile=script_info.data['profile'])
+
+    def create_script_options(self):
+        """ Create app level options, ideally that are used to configure the app itself.  """
+        return [
+            click.Option(['--profile'], is_eager=True, default=None, callback=self.options_callback,
+                         help='Name of the configuration profile to use.')
+        ]
+
+    def options_callback(self, ctx, param, value):
+        """ This method is called after argument parsing, after ScriptInfo instantiation but before
+            create_app() is called.  It's the only way to get the options into ScriptInfo.data
+            before the Keg app instance is instantiated.
+        """
+        si = ctx.ensure_object(ScriptInfo)
+        si.data[param.name] = value
+
+    def main_callback(self, **kwargs):
+        """
+            Default Click behavior is to call the help method if no arguments are given to the
+            top-most command.  That's good UX, but the way Click impliments it, the help is
+            shown before argument parsing takes place.  That's bad, because it means our
+            options_callback() is never called and the config profile isn't available when the
+            help command calls KegAppGroup.list_commands().
+
+            So, we force Click to always parse the args using `invoke_without_command=True` above,
+            but when we do that, Click turns off the automatic display of help.  So, we just
+            impliment help-like behavior in this method, which gives us the same net result
+            as default Click behavior.
+        """
+        ctx = click.get_current_context()
+
+        if ctx.invoked_subcommand is not None:
+            # A subcommand is present, so arguments were passed.
+            return
+
+        click.echo(ctx.get_help(), color=ctx.color)
+        ctx.exit()

keg/cli.py

@@ -66,7 +66,7 @@ def invoke_command(app_cls, *args, **kwargs):
     if use_test_profile:
         app_key = app_cls.environ_key('USE_TEST_PROFILE')
         env[app_key] = 'true'
-    result = runner.invoke(app_cls.cli_group, args, env=env, catch_exceptions=False)
+    result = runner.invoke(app_cls.cli, args, env=env, catch_exceptions=False)
 
     # if an exception was raised, make sure you output the output to make debugging easier
     # -1 as an exit code indicates a non SystemExit exception.
@@ -92,7 +92,11 @@ def setup_class(cls):
 
     def invoke(self, *args, **kwargs):
         cmd_name = kwargs.pop('cmd_name', self.cmd_name)
-        invoke_args = cmd_name.split(' ') + list(args)
+        if cmd_name is None:
+            cmd_name_args = []
+        else:
+            cmd_name_args = cmd_name.split(' ')
+        invoke_args = cmd_name_args + list(args)
         kwargs['runner'] = self.runner
         return invoke_command(self.app_cls, *invoke_args, **kwargs)
 

keg/testing.py

@@ -4,6 +4,7 @@
 import pytest
 
 from keg_apps.cli import CLIApp
+from keg_apps.cli2.app import CLI2App
 from keg_apps.db.app import DBApp
 from keg.testing import CLIBase
 
@@ -36,6 +37,21 @@ def test_default_exception_handling(self):
         """
 
 
+class TestCLI2(CLIBase):
+    app_cls = CLI2App
+
+    def test_invoke(self):
+        result = self.invoke('hello1')
+        assert 'hello1' in result.output
+
+    def test_no_commands_help_message(self):
+        result = self.invoke()
+        assert 'Usage: ' in result.output
+        assert '--profile TEXT  Name of the configuration profile to use.' in result.output
+        assert 'develop  Developer info and utils.'
+        assert 'hello1' in result.output
+
+
 class TestConfigCommand(CLIBase):
     app_cls = CLIApp
     cmd_name = 'develop config'

keg/tests/test_cli.py

@@ -43,11 +43,18 @@ class ClassProperty(property):
     on classes rather than instances.
     """
     def __init__(self, fget, *arg, **kw):
-        super(ClassProperty, self).__init__(fget, *arg, **kw)
+        self.ignore_set = kw.pop('ignore_set', False)
         self.__doc__ = fget.__doc__
+        super(ClassProperty, self).__init__(fget, *arg, **kw)
+
+    def __get__(self, obj, cls):  # noqa
+        return self.fget(cls)
 
-    def __get__(desc, self, cls):  # noqa
-        return desc.fget(cls)
+    def __set__(self, cls, value):  # noqa
+        if self.fset is None and not self.ignore_set:
+            raise AttributeError("can't set attribute")
+        if not self.ignore_set:
+            self.fset(cls, value)
 
 
 classproperty = ClassProperty

keg/utils.py

@@ -15,21 +15,21 @@ class CLIApp(Keg):
     keyring_enabled = False
 
 
-@CLIApp.command()
+@CLIApp.cli.command()
 def hello():
     print('hello keg test')  # noqa
 
 
-@CLIApp.command()
+@CLIApp.cli.command()
 @click.argument('name', default='foo')
 def foo2(name):
     print(('hello {}'.format(name)))  # noqa
 
 
-@CLIApp.command('catch-error')
+@CLIApp.cli.command('catch-error')
 def catch_error():
     raise Exception('deliberate exception for testing')
 
 
 if __name__ == '__main__':
-    CLIApp.cli_run()
+    CLIApp.cli.main()

keg_apps/cli.py

@@ -0,0 +1,18 @@
+from __future__ import absolute_import
+
+from keg.app import Keg
+
+
+class CLI2App(Keg):
+    import_name = 'keg_apps.cli2'
+
+    def on_init_complete(self):
+        # Want to test when the CLI command is registered after the app is initialized
+        import keg_apps.cli2.cli  # noqa
+
+
+if __name__ == '__main__':
+    # This import prevents a nasty bug where there are actually two classes __main__.CLI2App
+    # and the one with a full module path.
+    import keg_apps.cli2.app as app
+    app.CLI2App.cli.main()

keg_apps/cli2/__init__.py

@@ -0,0 +1,8 @@
+import click
+
+from .app import CLI2App
+
+
+@CLI2App.cli.command('hello1')
+def hello1():
+    click.echo('hello1')