Merge lp:~frankban/juju-quickstart/env-manage-base-views into lp:juju-quickstart

[Francesco Banconi]

Quickstart base structure for views.

This branch implements a way to start
Urwid interactive sessions in quickstart.
This infrastructure will be used in
future branches to implement the
quickstart environment management system.

My apologies for the long diff, but you
can safely ignore all the file headers,
and the code includes long module
docstrings which can help reviewing the
branch.

Tests: `make check`.

QA:
run `make` and then `./cli-app-demo.py`:
this will start a demo application using
the views infrastructure.

Thank you!

https://codereview.appspot.com/42600044/

[Francesco Banconi (frankban)]

Reviewers: mp+199254_code.launchpad.net,

Message:
Please take a look.

Description:
Quickstart base structure for views.

This branch implements a way to start
Urwid interactive sessions in quickstart.
This infrastructure will be used in
future branches to implement the
quickstart environment management system.

My apologies for the long diff, but you
can safely ignore all the file headers,
and the code includes long module
docstrings which can help reviewing the
branch.

Tests: `make check`.

QA:
run `make` and then `./cli-app-demo.py`:
this will start a demo application using
the views infrastructure.

Thank you!

https://code.launchpad.net/~frankban/juju-quickstart/env-manage-base-views/+merge/199254

(do not edit description out of merge proposal)

Please review this at https://codereview.appspot.com/42600044/

Affected files (+913, -1 lines):
   A [revision details]
   A cli-app-demo.py
   A quickstart/cli/__init__.py
   A quickstart/cli/base.py
   A quickstart/cli/ui.py
   A quickstart/cli/views.py
   M quickstart/models/envs.py
   A quickstart/tests/cli/__init__.py
   A quickstart/tests/cli/test_base.py
   A quickstart/tests/cli/test_ui.py
   A quickstart/tests/cli/test_views.py
   M quickstart/tests/test_utils.py
   M quickstart/utils.py
   M requirements.pip

[Gary Poster (gary)]

Ran out of time, but I think this looks great. Count me as an LGTM
'cause I know bac will do a great review. :-)

https://codereview.appspot.com/42600044/diff/1/quickstart/cli/ui.py
File quickstart/cli/ui.py (right):

https://codereview.appspot.com/42600044/diff/1/quickstart/cli/ui.py#newcode28
quickstart/cli/ui.py:28: # Define the color palette used by the Urwid
application.
Might be nice to describe the columns. I assume they are class name (or
None for default), text style, background style.

https://codereview.appspot.com/42600044/diff/1/quickstart/cli/ui.py#newcode70
quickstart/cli/ui.py:70: def bind(function, *args):
Huh. So...this effectively produces a thunk that discards/ignores the
argument. You could call it that, I guess. This functionality is
really generic. If you didn't need to discard the argument, you could
just use functools.partial.

def make_aggressive_thunk(function, *args, **kwargs):
     def thunk(*ignored, **ignored_kwargs):
         return function(*args, **kwargs)
     return thunk

<shrug> :-)

https://codereview.appspot.com/42600044/

[Brad Crittenden (bac)]

LGTM and QA-OK. Some changes suggested below but nothing substantial.
Thanks for the interesting work.

https://codereview.appspot.com/42600044/diff/1/quickstart/cli/base.py
File quickstart/cli/base.py (right):

https://codereview.appspot.com/42600044/diff/1/quickstart/cli/base.py#newcode19
quickstart/cli/base.py:19: A collection of objects which help building a
Quickstart CLI application
change 'building' -> 'in building' or 'build'

https://codereview.appspot.com/42600044/diff/1/quickstart/cli/base.py#newcode55
quickstart/cli/base.py:55: Improve the level of event loop introspection
so that code and tests
Improves

https://codereview.appspot.com/42600044/diff/1/quickstart/cli/base.py#newcode111
quickstart/cli/base.py:111: def set_contents(listbox):
In the docstring you call the param a generic 'widget'. They should
match. If not generic then should you validate that the param is a
listbox? I think using a generic widget is better.

https://codereview.appspot.com/42600044/diff/1/quickstart/cli/base.py#newcode112
quickstart/cli/base.py:112: contents.original_widget = listbox
original_widget seems like an odd name since it is really just the
current widget.

https://codereview.appspot.com/42600044/diff/1/quickstart/cli/views.py
File quickstart/cli/views.py (right):

https://codereview.appspot.com/42600044/diff/1/quickstart/cli/views.py#newcode51
quickstart/cli/views.py:51: pressing a keyboard shortcut;
by pressing

https://codereview.appspot.com/42600044/diff/1/quickstart/utils.py
File quickstart/utils.py (right):

https://codereview.appspot.com/42600044/diff/1/quickstart/utils.py#newcode194
quickstart/utils.py:194:
http://www.tornadoweb.org/en/stable/_modules/tornado/util.html#ObjectDict
Does the use here complicate our copyright statement above? You've
given attribution but it looks like Canonical is claiming copyright to
it.

Perhaps we include at the top the copyright statement from tornado with
the reference to ObjectDict.

# The ObjectDict code:
#
# Copyright 2009 Facebook
#
# Licensed under the Apache License, Version 2.0 (the "License"); you
may
# not use this file except in compliance with the License. You may
obtain
# a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See
the
# License for the specific language governing permissions and
limitations
# under the License.

https://codereview.appspot.com/42600044/

[lp:~frankban/juju-quickstart/env-manage-base-views]

55. By Francesco Banconi on 2013-12-17

Changes as per review.

[Francesco Banconi (frankban)]

*** Submitted:

Quickstart base structure for views.

This branch implements a way to start
Urwid interactive sessions in quickstart.
This infrastructure will be used in
future branches to implement the
quickstart environment management system.

My apologies for the long diff, but you
can safely ignore all the file headers,
and the code includes long module
docstrings which can help reviewing the
branch.

Tests: `make check`.

QA:
run `make` and then `./cli-app-demo.py`:
this will start a demo application using
the views infrastructure.

Thank you!

R=gary.poster, bac
CC=
https://codereview.appspot.com/42600044

https://codereview.appspot.com/42600044/diff/1/quickstart/cli/base.py
File quickstart/cli/base.py (right):

https://codereview.appspot.com/42600044/diff/1/quickstart/cli/base.py#newcode19
quickstart/cli/base.py:19: A collection of objects which help building a
Quickstart CLI application
On 2013/12/17 14:30:47, bac wrote:
> change 'building' -> 'in building' or 'build'

Done.

https://codereview.appspot.com/42600044/diff/1/quickstart/cli/base.py#newcode55
quickstart/cli/base.py:55: Improve the level of event loop introspection
so that code and tests
On 2013/12/17 14:30:47, bac wrote:
> Improves

Done.

https://codereview.appspot.com/42600044/diff/1/quickstart/cli/base.py#newcode111
quickstart/cli/base.py:111: def set_contents(listbox):
On 2013/12/17 14:30:47, bac wrote:
> In the docstring you call the param a generic 'widget'. They should
match. If
> not generic then should you validate that the param is a listbox? I
think using
> a generic widget is better.

Done.

https://codereview.appspot.com/42600044/diff/1/quickstart/cli/base.py#newcode112
quickstart/cli/base.py:112: contents.original_widget = listbox
On 2013/12/17 14:30:47, bac wrote:
> original_widget seems like an odd name since it is really just the
current
> widget.

Unfortunately this is how the wrapped widget is named in Urwid.

https://codereview.appspot.com/42600044/diff/1/quickstart/cli/ui.py
File quickstart/cli/ui.py (right):

https://codereview.appspot.com/42600044/diff/1/quickstart/cli/ui.py#newcode28
quickstart/cli/ui.py:28: # Define the color palette used by the Urwid
application.
On 2013/12/17 14:00:43, gary.poster wrote:
> Might be nice to describe the columns. I assume they are class name
(or None
> for default), text style, background style.

Done.

https://codereview.appspot.com/42600044/diff/1/quickstart/cli/ui.py#newcode70
quickstart/cli/ui.py:70: def bind(function, *args):
On 2013/12/17 14:00:43, gary.poster wrote:
> Huh. So...this effectively produces a thunk that discards/ignores the
argument.
> You could call it that, I guess. This functionality is really
generic. If you
> didn't need to discard the argument, you could just use
functools.partial.

> def make_aggressive_thunk(function, *args, **kwargs):
> def thunk(*ignored, **ignored_kwargs):
> return function(*args, **kwargs)
> return thunk

> <shrug> :-)

Renamed to thunk.

https://codereview.appspot.com/42600044/diff/1/quickstart/cli/views.py
File quickstart/cli/views.py (right):

https://codereview.appspot.com/42600044/diff/1/quickstart/cli/views.py#newcode51
quickstart/...

[Francesco Banconi (frankban)]

Thank you both!

https://codereview.appspot.com/42600044/

=== added file 'cli-app-demo.py'
--- cli-app-demo.py	1970-01-01 00:00:00 +0000
+++ cli-app-demo.py	2013-12-17 15:23:53 +0000
@@ -0,0 +1,52 @@
+#!.venv/bin/python
+
+# This file is part of the Juju Quickstart Plugin, which lets users set up a
+# Juju environment in very few steps (https://launchpad.net/juju-quickstart).
+# Copyright (C) 2013 Canonical Ltd.
+#
+# This program is free software: you can redistribute it and/or modify it under
+# the terms of the GNU Affero General Public License version 3, as published by
+# the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranties of MERCHANTABILITY,
+# SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+"""Juju Quickstart CLI application demo."""
+
+# XXX frankban (2013-12-16): this file is only for demonstration/QA purposes.
+# Remove this file when the environment management integration is completed.
+# Run "make" before running this file.
+
+from __future__ import (
+    print_function,
+    unicode_literals,
+)
+
+import urwid
+
+from quickstart.cli import views
+
+
+def example_view(app, message):
+    """An example Quickstart view."""
+    app.set_title('This is the title')
+    widgets = [
+        urwid.Text('These are the app contents. Press ^X to exit.'),
+        urwid.Divider(),
+        urwid.Text('Message: {}'.format(message)),
+    ]
+    contents = urwid.ListBox(urwid.SimpleFocusListWalker(widgets))
+    app.set_contents(contents)
+    app.set_status(('status error', '\u2622 Look! A toxic status! \u2622'))
+    app.set_message('this notification will disappear in three seconds')
+    return 'Goodbye, world'
+
+
+if __name__ == '__main__':
+    return_value = views.show(example_view, 'Hello, world')
+    print(return_value)

=== added directory 'quickstart/cli'
=== added file 'quickstart/cli/__init__.py'
--- quickstart/cli/__init__.py	1970-01-01 00:00:00 +0000
+++ quickstart/cli/__init__.py	2013-12-17 15:23:53 +0000
@@ -0,0 +1,33 @@
+# This file is part of the Juju Quickstart Plugin, which lets users set up a
+# Juju environment in very few steps (https://launchpad.net/juju-quickstart).
+# Copyright (C) 2013 Canonical Ltd.
+#
+# This program is free software: you can redistribute it and/or modify it under
+# the terms of the GNU Affero General Public License version 3, as published by
+# the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranties of MERCHANTABILITY,
+# SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+"""Juju Quickstart command line interface management.
+
+The functions and objects included in this package can be used to build
+rich command line interfaces using the Urwid console interface library
+(see <http://excess.org/urwid/>).
+
+This package is organized in several modules:
+    - base: the base pieces used to set up Urwid applications;
+    - views: view functions responsible for showing specific contents in the
+      context of a Urwid app;
+    - ui: Urwid related utility objects, including callback wrappers,
+      customized widgets and style specific helpers.
+
+Client code usually starts a Quickstart terminal application calling
+views.show() with the view to display along with the view required arguments.
+See the quickstart.cli.views module docstring for further details.
+"""

=== added file 'quickstart/cli/base.py'
--- quickstart/cli/base.py	1970-01-01 00:00:00 +0000
+++ quickstart/cli/base.py	2013-12-17 15:23:53 +0000
@@ -0,0 +1,155 @@
+# This file is part of the Juju Quickstart Plugin, which lets users set up a
+# Juju environment in very few steps (https://launchpad.net/juju-quickstart).
+# Copyright (C) 2013 Canonical Ltd.
+#
+# This program is free software: you can redistribute it and/or modify it under
+# the terms of the GNU Affero General Public License version 3, as published by
+# the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranties of MERCHANTABILITY,
+# SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+"""Juju Quickstart Urwid application base handling.
+
+A collection of objects which help in building a Quickstart CLI application
+skeleton. Views use these functions to set up the Urwid top widget and to start
+the application main loop.
+
+See the quickstart.cli.views module docstring for further details.
+"""
+
+from __future__ import unicode_literals
+
+import urwid
+
+from quickstart import (
+    get_version,
+    utils,
+)
+from quickstart.cli import ui
+
+
+class _MainLoop(urwid.MainLoop):
+    """A customized Urwid loop.
+
+    Allow for setting the unhandled_input callable after the loop
+    initialization.
+    """
+
+    def set_unhandled_input(self, unhandled_input):
+        """Set the unhandled_input callable.
+
+        The passed unhandled_input is a callable called when input is not
+        handled by the application top widget.
+        """
+        self._unhandled_input = unhandled_input
+
+    def get_alarms(self):
+        """Return all the alarms set for this loop.
+
+        Improves the level of event loop introspection so that code and tests
+        can easily access the alarms list.
+
+        The alarms list is a sequence of (time, callback) tuples.
+        """
+        return self.event_loop._alarms
+
+
+def setup_urwid_app():
+    """Configure a Urwid application suitable for being used by views.
+
+    Build the Urwid top widget and instantiate a main loop. The top widget
+    is basically a frame, composed by a header, some contents, and a footer.
+    This application skeleton is Quickstart branded, and exposes functions
+    that can be used by views to change the contents of the frame.
+
+    Return a tuple (loop, app) where loop is the interactive session main loop
+    (ready to be started invoking loop.run()) and app is an ObjectDict exposing
+    an API to be used by views to customize the application.
+
+    The API exposed by app is limited by design, and includes:
+
+        - set_title(text): set/change the title displayed in the application
+          header (e.g.: app.set_title('my title'));
+        - get_title(): return the current application title;
+
+        - set_contents(widget): set/change the application body contents. A
+          Urwid ListBox widget instance is usually provided, which replaces the
+          current application contents;
+        - get_contents(): return the current application contents widget;
+
+        - set_status(text): set/change the status text displayed in the
+          application footer (e.g.: set_status('press play on tape')). The
+          status message can also be passed as a (style, text) tuple, as usual
+          in Urwid code, e.g.: app.set_status(('error', 'error message'));
+        - get_status(): return the current status message;
+
+        - set_message(text): set/change a notification message, which is
+          displayed in the footer for a couple of seconds before disappearing;
+        - get_message(): return the message currently displayed in the
+          notifications area.
+    """
+    # Set up the application header.
+    title = urwid.Text('\npreparing...')
+    header_line = urwid.Divider('\N{LOWER ONE QUARTER BLOCK}')
+    header = urwid.Pile([
+        urwid.AttrMap(ui.padding(title), 'header'),
+        urwid.AttrMap(header_line, 'line header'),
+        urwid.Divider(),
+    ])
+    # Set up the application default contents.
+    # View code is assumed to replace the placeholder widget using
+    # app.set_contents(widget).
+    placeholder = urwid.ListBox(urwid.SimpleFocusListWalker([]))
+    contents = ui.padding(urwid.AttrMap(placeholder, None))
+
+    def set_contents(widget):
+        contents.original_widget = widget
+
+    # Set up the application footer.
+    # The CTRL-x shortcut is automatically set up by views.show().
+    brand_message = 'juju-quickstart v{} - ^X exit '.format(get_version())
+    brand = urwid.Text(brand_message)
+    status = urwid.Text('')
+    message = urwid.Text('', align='right')
+    footer_line = urwid.Divider('\N{UPPER ONE EIGHTH BLOCK}')
+    status_columns = urwid.Columns([('pack', brand), status, message])
+    footer = urwid.Pile([
+        urwid.Divider(),
+        urwid.AttrMap(ui.padding(status_columns), 'footer'),
+        urwid.AttrMap(footer_line, 'line footer'),
+    ])
+    # Compose the components in a frame, and set up the top widget. The top
+    # widget is the topmost widget used for painting the screen.
+    page = urwid.Frame(contents, header=header, footer=footer)
+    top_widget = urwid.Overlay(
+        page, urwid.SolidFill('\N{MEDIUM SHADE}'),
+        align='center', width=('relative', 90),
+        valign='middle', height=('relative', 90),
+        min_width=78, min_height=20)
+    # Instantiate the Urwid main loop.
+    loop = _MainLoop(top_widget, palette=ui.PALETTE)
+
+    def set_message(msg):
+        message.set_text(('message', msg))
+        loop.set_alarm_in(3, lambda *args: message.set_text(''))
+
+    # Create the app ObjectDict. If in the future we will find a view to
+    # require more capabilities/API access than the current one, this is the
+    # place where to add new API functions.
+    app = utils.ObjectDict(
+        set_title=lambda msg: title.set_text('\n{}'.format(msg)),
+        get_title=lambda: title.text.lstrip(),
+        set_contents=set_contents,
+        get_contents=lambda: contents.original_widget,
+        set_status=lambda msg: status.set_text(msg),
+        get_status=lambda: status.text,
+        set_message=set_message,
+        get_message=lambda: message.text,
+    )
+    return loop, app

=== added file 'quickstart/cli/ui.py'
--- quickstart/cli/ui.py	1970-01-01 00:00:00 +0000
+++ quickstart/cli/ui.py	2013-12-17 15:23:53 +0000
@@ -0,0 +1,118 @@
+# This file is part of the Juju Quickstart Plugin, which lets users set up a
+# Juju environment in very few steps (https://launchpad.net/juju-quickstart).
+# Copyright (C) 2013 Canonical Ltd.
+#
+# This program is free software: you can redistribute it and/or modify it under
+# the terms of the GNU Affero General Public License version 3, as published by
+# the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranties of MERCHANTABILITY,
+# SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+"""Juju Quickstart Urwid related utility objects."""
+
+from __future__ import unicode_literals
+
+import functools
+
+import urwid
+
+
+# Define the shortcut used to quit the interactive session.
+EXIT_KEY = 'ctrl x'
+# Define the color palette used by the Urwid application.
+PALETTE = [
+    # Class name, foreground color, background color.
+    # See <http://excess.org/urwid/docs/reference/constants.html
+    # foreground-and-background-colors>.
+    (None, 'light gray', 'black'),
+    ('controls', 'dark gray', 'light gray'),
+    ('edit', 'white,underline', 'black'),
+    ('error', 'light red', 'black'),
+    ('status error', 'light red', 'light gray'),
+    ('footer', 'black', 'light gray'),
+    ('message', 'white', 'dark green'),
+    ('header', 'white', 'dark magenta'),
+    ('highlight', 'white', 'black'),
+    ('line header', 'dark gray', 'dark magenta'),
+    ('line footer', 'light gray', 'light gray'),
+    ('selected', 'white', 'dark blue'),
+]
+# Define a default padding for the Urwid application.
+padding = functools.partial(urwid.Padding, left=2, right=2)
+
+
+class AppExit(Exception):
+    """Used by views to stop the interactive execution returning a value."""
+
+    def __init__(self, return_value=None):
+        """Set the value to return to the view caller (default is None)."""
+        self.return_value = return_value
+
+    def __str__(self):
+        return b'{}: {!r}'.format(self.__class__.__name__, self.return_value)
+
+
+def exit_and_return(return_value):
+    """Return a function that can be used as unhandled_input for an Urwid app.
+
+    The resulting function terminates the interactive session with the given
+    return_value when the user hits CTRL-x.
+    """
+    def unhandled_input(key):
+        if key == EXIT_KEY:
+            raise AppExit(return_value)
+    return unhandled_input
+
+
+def create_controls(*args):
+    """Create a row of control widgets surrounded by line boxes."""
+    controls = urwid.Columns([padding(urwid.LineBox(arg)) for arg in args])
+    return urwid.Pile([
+        urwid.Divider(top=1, bottom=1),
+        urwid.AttrMap(controls, 'controls')
+    ])
+
+
+class MenuButton(urwid.Button):
+    """A customized Urwid button widget.
+
+    This behaves like a regular button, but also takes a callback that is
+    called when the button is clicked.
+    """
+
+    def __init__(self, caption, callback):
+        super(MenuButton, self).__init__('')
+        urwid.connect_signal(self, 'click', callback)
+        icon = urwid.SelectableIcon(caption, 0)
+        # Replace the original widget: it seems ugly but it is Urwid idiomatic.
+        self._w = urwid.AttrMap(icon, None, 'selected')
+
+
+def thunk(function, *args, **kwargs):
+    """Create and return a callable binding the given method and args/kwargs.
+
+    This is useful when the given function is used as a signal subscriber, e.g.
+    as a callback to be called when an Urwid signal is sent. In most cases, the
+    widget which generated the event is sent as first argument to the callback.
+    Moreover, urwid.connect_signal handles only one user argument.
+    See <http://excess.org/urwid/docs/reference/signals.html>.
+
+    This function helps when the callback does not require the original widget
+    and/or when it instead requires more than one argument, e.g.:
+
+        def save(contents, commit=False):
+            ...
+
+        button = MenuButton('save and commit', ui.thunk(save, contents, True))
+
+    This example uses the MenuButton widget defined above in this module.
+    """
+    def callback(*ignored_args, **ignored_kwargs):
+        return function(*args, **kwargs)
+    return callback

=== added file 'quickstart/cli/views.py'
--- quickstart/cli/views.py	1970-01-01 00:00:00 +0000
+++ quickstart/cli/views.py	2013-12-17 15:23:53 +0000
@@ -0,0 +1,119 @@
+# This file is part of the Juju Quickstart Plugin, which lets users set up a
+# Juju environment in very few steps (https://launchpad.net/juju-quickstart).
+# Copyright (C) 2013 Canonical Ltd.
+#
+# This program is free software: you can redistribute it and/or modify it under
+# the terms of the GNU Affero General Public License version 3, as published by
+# the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranties of MERCHANTABILITY,
+# SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+"""Juju Quickstart CLI application views.
+
+This module contains the Quickstart view implementations along with a function
+(show) to easily start a view automatically creating an Urwid application.
+
+To start a Quickstart interactive session, just run the following:
+
+    show(view, *args)
+
+The code above sets up a Quickstart branded CLI application, then calls the
+given view callable passing the application object ready to be configured
+and all the given optional arguments. Finally the interactive session is
+started, and the show function blocks until the user or the view itself
+request to exit the application.
+
+A view is a callable receiving an app ObjectDict and other optional arguments
+(based on specific view needs). A view function can configure the Urwid
+application using the API exposed by the application object
+(see quickstart.cli.base.setup_urwid_app).
+
+Assume a view is defined like the following:
+
+    def myview(app, title):
+        app.set_title(title)
+        return 42
+
+The view above, requiring a title argument, can be started this way:
+
+    show(myview, 'this title will be shown in the header')
+
+At this point the application main loop is started, and the user can interact
+with the CLI interface. There are two ways to stop the interactive session:
+    1) the user explicitly requests to exit. The Urwid application is
+       automatically configured to allow the user to quit whenever she wants by
+       pressing a keyboard shortcut;
+    2) a view decides it is time to quit (e.g. reacting to an event/input).
+
+In both cases, the show function returns something to the caller:
+    1) when the user explicitly requests to quit, the value returned by the
+       view itself (the callable passed to show()) is returned. For instance,
+       the show(myview...) call above would return 42;
+    2) to force the end of the interactive session, a view can raise a
+       quickstart.cli.ui.AppExit exception, passing a return value: if the
+       application is exited this way, then show() returns the value
+       encapsulated in the exception. Note that this exception can be raised
+       as a reaction to an event, and not in the first execution of the view
+       body, i.e. during the app configuration.
+
+The above is better described by code:
+
+    from quickstart.cli import views, ui
+
+    def button_view(app):
+
+        def exit():
+            raise ui.AppExit(True)
+
+        app.set_title('behold the button below')
+        button = ui.MenuButton('press to exit', ui.thunk(exit))
+        widgets = urwid.ListBox(urwid.SimpleFocusListWalker([button]))
+        app.set_contents(widgets)
+        return False
+
+    pressed = views.show(button_view)
+
+In this example the button_view function configures the app to show a button.
+Clicking that button an AppExit(True) is raised. The view itself instead just
+returns False. This means that "pressed" will be True if the user exited using
+the button, or False if the user exited using the global shortcut.
+
+As a final note, it is absolutely safe for a view to call, directly or
+indirectly, other views, as long as all the arguments required by the other
+views, including app, are properly provided. This is effectively the proposed
+solution to build multi-views CLI applications in Quickstart.
+"""
+
+from __future__ import unicode_literals
+
+from quickstart.cli import (
+    base,
+    ui,
+)
+
+
+def show(view, *args):
+    """Start an Urwid interactive session showing the given view.
+
+    The view is called passing an app ObjectDict and the provided *args.
+
+    Block until the main loop is stopped, either by the user with the exit
+    shortcut or by the view itself with the AppExit exception. In the former
+    case, return what is returned by the view. In the AppExit case, return
+    the value encapsulated in the exception.
+    """
+    loop, app = base.setup_urwid_app()
+    default_return_value = view(app, *args)
+    unhandled_input = ui.exit_and_return(default_return_value)
+    loop.set_unhandled_input(unhandled_input)
+    # Start the Urwid interactive session (main loop).
+    try:
+        loop.run()
+    except ui.AppExit as err:
+        return err.return_value

=== modified file 'quickstart/models/envs.py'
--- quickstart/models/envs.py	2013-12-16 08:21:57 +0000
+++ quickstart/models/envs.py	2013-12-17 15:23:53 +0000
@@ -321,7 +321,8 @@
         label='default series', required=False,
         help='the default Ubuntu series to use for the bootstrap node')
     is_default_field = fields.BoolField(
-        'is-default', help='make this the default environment', required=True)
+        'is-default', label='default', allow_mixed=False, required=True,
+        help='make this the default environment')
     # Define data structures used as part of the metadata below.
     ec2_regions = (
         'ap-northeast-1', 'ap-southeast-1', 'ap-southeast-2',

=== added directory 'quickstart/tests/cli'
=== added file 'quickstart/tests/cli/__init__.py'
--- quickstart/tests/cli/__init__.py	1970-01-01 00:00:00 +0000
+++ quickstart/tests/cli/__init__.py	2013-12-17 15:23:53 +0000
@@ -0,0 +1,15 @@
+# This file is part of the Juju Quickstart Plugin, which lets users set up a
+# Juju environment in very few steps (https://launchpad.net/juju-quickstart).
+# Copyright (C) 2013 Canonical Ltd.
+#
+# This program is free software: you can redistribute it and/or modify it under
+# the terms of the GNU Affero General Public License version 3, as published by
+# the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranties of MERCHANTABILITY,
+# SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.

=== added file 'quickstart/tests/cli/test_base.py'
--- quickstart/tests/cli/test_base.py	1970-01-01 00:00:00 +0000
+++ quickstart/tests/cli/test_base.py	2013-12-17 15:23:53 +0000
@@ -0,0 +1,174 @@
+# This file is part of the Juju Quickstart Plugin, which lets users set up a
+# Juju environment in very few steps (https://launchpad.net/juju-quickstart).
+# Copyright (C) 2013 Canonical Ltd.
+#
+# This program is free software: you can redistribute it and/or modify it under
+# the terms of the GNU Affero General Public License version 3, as published by
+# the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranties of MERCHANTABILITY,
+# SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+"""Tests for the Juju Quickstart Urwid application base handling."""
+
+from __future__ import unicode_literals
+
+import unittest
+
+import urwid
+
+from quickstart import utils
+from quickstart.cli import base
+
+
+class TestMainLoop(unittest.TestCase):
+
+    def setUp(self):
+        # Create a loop instance.
+        self.widget = urwid.ListBox(urwid.SimpleFocusListWalker([]))
+        self.loop = base._MainLoop(self.widget)
+
+    def test_initialization(self):
+        # The customized loop is properly initialized, and it is an instance
+        # of the Urwid loop.
+        self.assertEqual(self.widget, self.loop.widget)
+        self.assertIsInstance(self.loop, urwid.MainLoop)
+
+    def test_unhandled_input(self):
+        # The unhandled_input function can be set after the initialization.
+        inputs = []
+        self.loop.set_unhandled_input(inputs.append)
+        self.loop.unhandled_input('ctrl z')
+        self.assertEqual(['ctrl z'], inputs)
+
+    def test_alarms(self):
+        # It is possible to retrieve the list of event loop alarms.
+        times_called = []
+        self.assertEqual(0, len(self.loop.get_alarms()))
+        callback = lambda *args: times_called.append(1)
+        self.loop.set_alarm_in(3, callback)
+        alarms = self.loop.get_alarms()
+        self.assertEqual(1, len(alarms))
+        alarms[0][1]()
+        self.assertEqual(1, sum(times_called))
+
+
+class TestSetupUrwidApp(unittest.TestCase):
+
+    def setUp(self):
+        # Set up the base Urwid application.
+        self.loop, self.app = base.setup_urwid_app()
+
+    def get_title_widget(self, loop):
+        """Return the title widget given the application main loop."""
+        # The frame is the main overlay's top widget.
+        frame = loop.widget.top_w
+        # Retrieve the header.
+        header = frame.contents['header'][0]
+        # The title widget is the first in the header pile.
+        return header.contents[0][0].base_widget
+
+    def get_contents_widget(self, loop):
+        """Return the contents widget given the application main loop."""
+        # The frame is the main overlay's top widget.
+        frame = loop.widget.top_w
+        # Retrieve the body.
+        body = frame.contents['body'][0]
+        # The contents widget is the body's original widget.
+        return body.original_widget
+
+    def _get_footer_columns(self, loop):
+        # The frame is the main overlay's top widget.
+        frame = loop.widget.top_w
+        # Retrieve the footer.
+        footer = frame.contents['footer'][0]
+        # Return the columns widget.
+        return footer.contents[1][0].base_widget
+
+    def get_status_widget(self, loop):
+        """Return the status widget given the application main loop."""
+        columns = self._get_footer_columns(loop)
+        # The status widget is the second one (brand, status, message).
+        return columns.contents[1][0]
+
+    def get_message_widget(self, loop):
+        """Return the message widget given the application main loop."""
+        columns = self._get_footer_columns(loop)
+        # The message widget is the third one (brand, status, message).
+        return columns.contents[2][0]
+
+    def test_loop(self):
+        # The returned loop is an instance of the base customized loop.
+        self.assertIsInstance(self.loop, base._MainLoop)
+
+    def test_app(self):
+        # The returned app is an ObjectDict including the expected keys.
+        expected_keys = set([
+            'set_title', 'get_title',
+            'set_contents', 'get_contents',
+            'set_status', 'get_status',
+            'set_message', 'get_message',
+        ])
+        self.assertIsInstance(self.app, utils.ObjectDict)
+        self.assertEqual(expected_keys, set(self.app.keys()))
+
+    def test_set_title(self):
+        # The set_title API sets the application title.
+        self.app.set_title('The Inner Light')
+        title_widget = self.get_title_widget(self.loop)
+        self.assertEqual('\nThe Inner Light', title_widget.text)
+
+    def test_get_title(self):
+        # The get_title API retrieves the application title.
+        title_widget = self.get_title_widget(self.loop)
+        title_widget.set_text('The Outer Space')
+        self.assertEqual('The Outer Space', self.app.get_title())
+
+    def test_set_contents(self):
+        # The set_contents API changes the application main contents widget.
+        text_widget = urwid.Text('my contents')
+        self.app.set_contents(text_widget)
+        contents_widget = self.get_contents_widget(self.loop)
+        self.assertEqual('my contents', contents_widget.text)
+
+    def test_get_contents(self):
+        # The get_contents API returns the contents widget.
+        contents_widget = self.get_contents_widget(self.loop)
+        self.assertEqual(contents_widget, self.app.get_contents())
+
+    def test_set_status(self):
+        # The set_status API sets the status message displayed in the footer.
+        self.app.set_status('press play on tape')
+        status_widget = self.get_status_widget(self.loop)
+        self.assertEqual('press play on tape', status_widget.text)
+
+    def test_get_status(self):
+        # The get_status API returns the current status message.
+        status_widget = self.get_status_widget(self.loop)
+        status_widget.set_text('hit space to continue')
+        self.assertEqual('hit space to continue', self.app.get_status())
+
+    def test_set_message(self):
+        # The set_message API sets the message to be displayed in the
+        # notification area.
+        self.app.set_message('this will disappear')
+        message_widget = self.get_message_widget(self.loop)
+        self.assertEqual('this will disappear', message_widget.text)
+        # An alarm is set to make this message disappear.
+        alarms = self.loop.get_alarms()
+        self.assertEqual(1, len(alarms))
+        # Calling the callback makes the message go away.
+        _, callback = alarms[0]
+        callback()
+        self.assertEqual('', message_widget.text)
+
+    def test_get_message(self):
+        # The get_message API returns the current notification message.
+        message_widget = self.get_message_widget(self.loop)
+        message_widget.set_text('42')
+        self.assertEqual('42', self.app.get_message())

=== added file 'quickstart/tests/cli/test_ui.py'
--- quickstart/tests/cli/test_ui.py	1970-01-01 00:00:00 +0000
+++ quickstart/tests/cli/test_ui.py	2013-12-17 15:23:53 +0000
@@ -0,0 +1,117 @@
+# This file is part of the Juju Quickstart Plugin, which lets users set up a
+# Juju environment in very few steps (https://launchpad.net/juju-quickstart).
+# Copyright (C) 2013 Canonical Ltd.
+#
+# This program is free software: you can redistribute it and/or modify it under
+# the terms of the GNU Affero General Public License version 3, as published by
+# the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranties of MERCHANTABILITY,
+# SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+"""Tests for the Juju Quickstart Urwid related utility objects."""
+
+from __future__ import unicode_literals
+
+import unittest
+
+import mock
+import urwid
+
+from quickstart.cli import ui
+
+
+class TestAppExit(unittest.TestCase):
+
+    def test_no_return_value(self):
+        # The exception accepts a return value argument.
+        exception = ui.AppExit(42)
+        self.assertEqual(42, exception.return_value)
+
+    def test_return_value(self):
+        # The exception's return value defaults to None.
+        exception = ui.AppExit()
+        self.assertIsNone(exception.return_value)
+
+    def test_string_representation(self):
+        # The exception is correctly represented as a byte string.
+        exception = ui.AppExit(42)
+        str_exception = str(exception)
+        self.assertIsInstance(str_exception, bytes)
+        self.assertEqual(b'AppExit: 42', str_exception)
+
+
+class TestExitAndReturn(unittest.TestCase):
+
+    def test_app_exit(self):
+        # The function returned raises an AppExit error if CTRL-x is passed.
+        function = ui.exit_and_return(42)
+        with self.assertRaises(ui.AppExit) as context_manager:
+            function(ui.EXIT_KEY)
+        self.assertEqual(42, context_manager.exception.return_value)
+
+    def test_unhandled(self):
+        # Passing other keys, the resulting function is a no-op.
+        function = ui.exit_and_return(42)
+        self.assertIsNone(function('alt z'))
+
+
+class TestCreateControls(unittest.TestCase):
+
+    def test_resulting_pile(self):
+        # The resulting pile is properly structured: it includes a columns
+        # widget containing the provided widgets.
+        widget0 = urwid.Text('w0')
+        widget1 = urwid.Text('w1')
+        pile = ui.create_controls(widget0, widget1)
+        divider_contents, columns_contents = pile.contents
+        self.assertIsInstance(divider_contents[0], urwid.Divider)
+        columns = columns_contents[0].original_widget
+        widgets = [content[0].base_widget for content in columns.contents]
+        self.assertIs(widget0, widgets[0])
+        self.assertIs(widget1, widgets[1])
+
+
+class TestMenuButton(unittest.TestCase):
+
+    def test_caption(self):
+        # The button's caption is properly set up.
+        button = ui.MenuButton('my caption', mock.Mock())
+        self.assertEqual('my caption', button._w.base_widget.text)
+
+    def test_signals(self):
+        # The given callback is called when the click signal is emitted.
+        callback = mock.Mock()
+        button = ui.MenuButton('my caption', callback)
+        urwid.emit_signal(button, 'click', button)
+        callback.assert_called_once_with(button)
+
+
+class TestThunk(unittest.TestCase):
+
+    widget = 'test-widget'
+
+    def test_no_args(self):
+        # A callback can be set up without arguments.
+        function = mock.Mock()
+        thunk_function = ui.thunk(function)
+        thunk_function(self.widget)
+        function.assert_called_once_with()
+
+    def test_args(self):
+        # It is possible to bind arguments to the callback function.
+        function = mock.Mock()
+        thunk_function = ui.thunk(function, 'arg1', 'arg2')
+        thunk_function(self.widget)
+        function.assert_called_once_with('arg1', 'arg2')
+
+    def test_return_value(self):
+        # The closure returns the value returned by the original callback.
+        sqr = lambda value: value * value
+        thunk_function = ui.thunk(sqr, 3)
+        self.assertEqual(9, thunk_function(self.widget))

=== added file 'quickstart/tests/cli/test_views.py'
--- quickstart/tests/cli/test_views.py	1970-01-01 00:00:00 +0000
+++ quickstart/tests/cli/test_views.py	2013-12-17 15:23:53 +0000
@@ -0,0 +1,86 @@
+# This file is part of the Juju Quickstart Plugin, which lets users set up a
+# Juju environment in very few steps (https://launchpad.net/juju-quickstart).
+# Copyright (C) 2013 Canonical Ltd.
+#
+# This program is free software: you can redistribute it and/or modify it under
+# the terms of the GNU Affero General Public License version 3, as published by
+# the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranties of MERCHANTABILITY,
+# SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+"""Tests for the Juju Quickstart CLI application views."""
+
+from __future__ import unicode_literals
+
+from contextlib import contextmanager
+import unittest
+
+import mock
+
+from quickstart.cli import (
+    ui,
+    views,
+)
+
+
+class TestShow(unittest.TestCase):
+
+    @contextmanager
+    def patch_setup_urwid_app(self, run_side_effect=None):
+        """Patch the base.setup_urwid_app function.
+
+        The context manager returns a tuple (mock_loop, mock_app) containing
+        the two mock objects returned by the mock call.
+
+        The run_side_effect argument can be provided to specify the side
+        effects of the mock_loop.run call.
+        """
+        mock_loop = mock.Mock()
+        mock_loop.run = mock.Mock(side_effect=run_side_effect)
+        mock_setup_urwid_app = mock.Mock(return_value=(mock_loop, mock.Mock()))
+        setup_urwid_app_path = 'quickstart.cli.views.base.setup_urwid_app'
+        with mock.patch(setup_urwid_app_path, mock_setup_urwid_app):
+            yield mock_setup_urwid_app()
+
+    def test_show_view(self):
+        # The loop and app objects are properly used by the show function:
+        # the loop is run and the app is passed to the view.
+        view = mock.Mock()
+        with self.patch_setup_urwid_app() as (mock_loop, mock_app):
+            views.show(view)
+        view.assert_called_once_with(mock_app)
+        mock_loop.run.assert_called_once_with()
+
+    def test_view_exit(self):
+        # An ui.AppExit correctly quits the application. The return value
+        # encapsulated on the exception is also returned by the show function.
+        view = mock.Mock()
+        run_side_effect = ui.AppExit('bad wolf')
+        with self.patch_setup_urwid_app(run_side_effect=run_side_effect):
+            return_value = views.show(view)
+        self.assertEqual('bad wolf', return_value)
+
+    def test_unhandled_input(self):
+        # The unhandled_input callable is properly set up and registered to
+        # the main loop.
+        view = mock.Mock(return_value=42)
+        with self.patch_setup_urwid_app() as (mock_loop, mock_app):
+            views.show(view)
+        unhandled_input = mock_loop.set_unhandled_input.call_args[0][0]
+        with self.assertRaises(ui.AppExit) as context_manager:
+            unhandled_input(ui.EXIT_KEY)
+        self.assertEqual(42, context_manager.exception.return_value)
+
+    def test_view_arguments(self):
+        # The view is invoked passing the app and all the optional show
+        # function arguments.
+        view = mock.Mock()
+        with self.patch_setup_urwid_app() as (mock_loop, mock_app):
+            views.show(view, 'arg1', 'arg2')
+        view.assert_called_once_with(mock_app, 'arg1', 'arg2')

=== modified file 'quickstart/tests/test_utils.py'
--- quickstart/tests/test_utils.py	2013-12-10 14:37:58 +0000
+++ quickstart/tests/test_utils.py	2013-12-17 15:23:53 +0000
@@ -349,6 +349,31 @@
         mock_call.assert_called_once_with('lsb_release', '-cs')
 
 
+class TestObjectDict(unittest.TestCase):
+
+    def setUp(self):
+        self.object_dict = utils.ObjectDict(mykey='myvalue')
+
+    def test_get_attribute(self):
+        # A value can be retrieved accessing the key as an attribute.
+        self.assertEqual('myvalue', self.object_dict.mykey)
+
+    def test_get_attribute_error(self):
+        # An AttributeError is raised if the key is not in the dictionary.
+        with self.assertRaises(AttributeError):
+            self.object_dict.no_such_key
+
+    def test_set_attribute(self):
+        # A key can be added by setting the corresponding attribute.
+        self.object_dict.another_key = 42
+        self.assertEqual(42, self.object_dict['another_key'])
+
+    def test_update_attribute(self):
+        # It is possible to update an attribute.
+        self.object_dict.mykey = 47
+        self.assertEqual(47, self.object_dict.mykey)
+
+
 class TestParseBundle(
         helpers.BundleFileTestsMixin, helpers.ValueErrorTestsMixin,
         unittest.TestCase):

=== modified file 'quickstart/utils.py'
--- quickstart/utils.py	2013-12-10 14:37:58 +0000
+++ quickstart/utils.py	2013-12-17 15:23:53 +0000
@@ -14,6 +14,22 @@
 # You should have received a copy of the GNU Affero General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+# The ObjectDict code:
+#
+# Copyright 2009 Facebook
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
 """Juju Quickstart utility functions and classes."""
 
 from __future__ import (
@@ -187,6 +203,23 @@
     return output.strip()
 
 
+class ObjectDict(dict):
+    """Makes a dictionary behave like an object, with attribute-style access.
+
+    Original:
+    http://www.tornadoweb.org/en/stable/_modules/tornado/util.html#ObjectDict
+    """
+
+    def __getattr__(self, name):
+        try:
+            return self[name]
+        except KeyError:
+            raise AttributeError(name)
+
+    def __setattr__(self, name, value):
+        self[name] = value
+
+
 def parse_bundle(bundle_yaml, bundle_name=None):
     """Parse the provided bundle YAML encoded contents.
 

=== modified file 'requirements.pip'
--- requirements.pip	2013-11-14 10:37:29 +0000
+++ requirements.pip	2013-12-17 15:23:53 +0000
@@ -23,3 +23,4 @@
 
 jujuclient==0.11
 PyYAML==3.10
+urwid==1.1.1