Merge lp:~frankban/lpsetup/interactive-execution into lp:lpsetup

[Francesco Banconi]

Interactive and dry command execution.

This branch adds interactive and dry execution for lpsetup commands.
The diff is very long, I am sorry.

== Changes ==

Fixed *ArgumentParser.get_args_from_namespace*: now `store_false` actions are correctly handled, i.e. if a '--option' is a boolean flag with action `store_false`, then '--option' is added as an argument if the corresponding namespace value is False. Added missing tests.

Added *StepsBasedSubCommand.has_interactive_run* attribute, defaulting to True. If *has_interactive_run* is True, a --yes option is automatically added to the subcommand. This attribute is also used to decide if the current run is an interactive one (i.e. if we need to prompt the user at the beginning of the process). All the commands except *update* and *version* are currently interactive.

Introduced steps' descriptions: the *description* attributes of each step are collected and used as command description. If the attribute is not found, the description is an empty string. It is possible to format description using using the Python's builtin templating system *string.Template* supporting $-based substitutions. The current namespace is used as context for substitutions.

Implemented the *confirm* function, and the RawInputReturning context manager that is used to temporarily mock raw_input so that it is possible to easily test *confirm*.

Added descriptions for all the relevant steps.

Added a --dry option to force the command to just display steps' descriptions and then exit.

Updated *handle_testing* to automatically imply a non-interactive run.

Updated *install_lxc* to pass --yes to the interactive sub commands re-invoked from inside the LXC.

Added --yes to integration tests.

[Benji York (benji)]

I like the dry run and description functionality.

The use of $templates for the descriptions was a good choice. It keeps
them simpler than having to have a function for each, but provides the
dynamism we need to be able to include runtime values.

We might want an assertion that no un-replaced substitutions are left in
the description after substitution takes place. I wouldn't be surprised
if we typo a name now and then and it would keep those from persisting
very long.

The careful indention of description strings only for them to be
dedented in the future seems odd. This:

fetch.description = """Set up a Launchpad repository in $repository,
    retrieving the source code from $source."""

or this:

fetch.description = ('Set up a Launchpad repository in $repository,'
    'retrieving the source code from $source.')

better matches prevailing Python style than this:

fetch.description = """
    Set up a Launchpad repository in $repository,
    retrieving the source code from $source.
"""

I don't feel strongly about it, but normally see dry-run options spelled
"--dry-run" I don't recall seeing one spelled "--dry".

Having the namespace attribute as "dry" is a bit terse. Spelling it
"dry_run" would help when reading the code.

I'm surprised that the bit about inverting the boolean if store_false is
used (in lpsetup/argparser.py, line 19 of the diff) is necessary. I
didn't look deeply enough into it to understand why, but I just wanted
to point it out in case it made you realize anything.

Having to do self.is_interactive(namespace) instead of something like
namespace.is_interactive is unfortunate. I think I see why: because not
all commands have the option, so sometimes the attribute won't be there.
I wonder if it would be better to always have the attribute available,
even if it can not be true would be better.

The fact that steps can have empty descriptions feels like a trap.
Perhaps it should be an error for that to happen.

The confirm function is never called with a question other than "Do you
want to proceed?" and the "suffix" parameter is never used so it could
be simplified. Some tests would go away too.

It feels like there should be some whitespace between the step function
definitions and the description attribute assignment for the functions.
I don't know if the pep8 formatting checker will warn about them or not.

The way descriptions are presented is a little hard to read. Here is
some output from my system:

Update your system and install necessary deb packages (ssh bzr
apache2.2-common).
Create the user benji if it does not exist.
Create Apache document roots for launchpad and enable required Apache
modules (proxy proxy_http rewrite ssl deflate headers).
Set up hosts file for Launchpad (/etc/hosts).
Set up the user's ssh directory (/home/benji/.ssh).
Create, if it does not exist, the ssh key /home/benji/.ssh/id_rsa.
Authorize this key for the user benji.
Add bazaar.launchpad.net to known hosts.
Set up bazaar authentication: Benji York <email address hidden>.
Set up Launchpad user id: benji.
Add required APT repositories and install Launchpad dependencies:
launchpad-database-dependencies-9.1 launchpad-developer-depe...

[Francesco Banconi (frankban)]

Thanks for all your comments Benji. Replies follow.

> The use of $templates for the descriptions was a good choice. It keeps
> them simpler than having to have a function for each, but provides the
> dynamism we need to be able to include runtime values.

Exactly.

> We might want an assertion that no un-replaced substitutions are left in
> the description after substitution takes place. I wouldn't be surprised
> if we typo a name now and then and it would keep those from persisting
> very long.

Didn't thought about typos. I think what you are suggesting can be implemented just replacing Template.safe_substitute with Template.substitute, that raises a KeyError or a ValueError if placeholders are missing. I used safe_substitute to ensure we always have a string even if the context is missing, but your typo argument convinced me otherwise.

> The careful indention of description strings only for them to be
> dedented in the future seems odd. This:
>
> fetch.description = """Set up a Launchpad repository in $repository,
> retrieving the source code from $source."""
>
> or this:
>
> fetch.description = ('Set up a Launchpad repository in $repository,'
> 'retrieving the source code from $source.')
>
> better matches prevailing Python style than this:
>
> fetch.description = """
> Set up a Launchpad repository in $repository,
> retrieving the source code from $source.
> """

I will change the style of the descriptions.

> I don't feel strongly about it, but normally see dry-run options spelled
> "--dry-run" I don't recall seeing one spelled "--dry".
>
> Having the namespace attribute as "dry" is a bit terse. Spelling it
> "dry_run" would help when reading the code.

Agreed.

>
> I'm surprised that the bit about inverting the boolean if store_false is
> used (in lpsetup/argparser.py, line 19 of the diff) is necessary. I
> didn't look deeply enough into it to understand why, but I just wanted
> to point it out in case it made you realize anything.

Unfortunately that's necessary. Normally you have flags like:

parser.add_argument('--dry', action='store_true')

And the old code to regenerate the args from the namespace worked in this case, because the logic was:
if the value is boolean, and the value is True, then add the corresponding argument

But what about:

parser.add_argument('--yes', action='store_false', dest='interactive')

In this case, following the logic above, --yes is not re-added to the arguments, because interactive will be False.

That's why, when store_false is used, we need to invert the logic: if value if False, add the argument. To keep the existing code as is, I decided to just invert the value before the check.

> Having to do self.is_interactive(namespace) instead of something like
> namespace.is_interactive is unfortunate. I think I see why: because not
> all commands have the option, so sometimes the attribute won't be there.
> I wonder if it would be better to always have the attribute available,
> even if it can not be true would be better.

namespace.interactive is False when --yes is provided. command.is_interactive() also checks for subcommand.has_interactive_run. I agree that, if has_intera...

[Benji York (benji)]

On Fri, Jul 27, 2012 at 1:13 PM, Francesco Banconi
<email address hidden> wrote:
> Thanks for all your comments Benji. Replies follow.

[snip lots of good stuff that doesn't need comment]

>> Having to do self.is_interactive(namespace) instead of something like
>> namespace.is_interactive is unfortunate. I think I see why: because not
>> all commands have the option, so sometimes the attribute won't be there.
>> I wonder if it would be better to always have the attribute available,
>> even if it can not be true would be better.
>
> namespace.interactive is False when --yes is provided. command.is_interactive() also checks for subcommand.has_interactive_run. I agree that, if has_interactive_run is False, then namespace.interactive is not defined, so we could simplify that like:
>
> is_interactive = getattr(namespace, 'interactive', False)
>
> This can be done in the run() method, or, maybe better, in init_namespace.
>
> I decided to create a method to allow sub commands to override that method and decide themselves if they are interactive. However, this machinery is not used, and, as I think you suggested, having the calculated value in the namespace could be nice. Having this context, what you'd suggest?

Could we have a handler that sets namespace.is_interactive to False if
there is otherwise no value? Hmm, I can't check right now, but
doesn't argparse's add_option take a "default" argument. That seems
like it would work.

>> The fact that steps can have empty descriptions feels like a trap.
>> Perhaps it should be an error for that to happen.
>
> I am confused here, could you please deepen this argument

I'm worried that someone will add a step that does something dramatic
-- say "delete the entire hard disk" for effect -- and forgets to add
a description. Maybe we could have a foo.description = None so if
there is really no description we have to be explicit about it.

>> It feels like there should be some whitespace between the step function
>> definitions and the description attribute assignment for the functions.
>> I don't know if the pep8 formatting checker will warn about them or not.
>
> I don't know either, but, AFAICT, tarmac doesn't complain about the steps
> already defining their name like that in tests.examples.

I would like at least one blank line separating them.

>> The way descriptions are presented is a little hard to read. Here is
>> some output from my system:
>
>> If we wanted to be extra fancy in get_step_description we could check
>> the current terminal width and wrap to that.
>
> These suggestions definitely improve the description readability, I will try
> to add these changes in this branch.

Cool.
--
Benji York

[Francesco Banconi (frankban)]

Benji, I updated this branch following you suggestions:

- fIxed steps' descriptions indentation and formatting, e.g.::

$ ./lp-setup init-host --dry-run
This command will perform the following actions:

* Update your system and install necessary deb packages (ssh bzr apache2.2-common).
* Create the user frankban if it does not exist.
* Create Apache document roots for launchpad and enable required Apache modules (proxy proxy_http rewrite ssl
  deflate headers).
* Set up hosts file for Launchpad (/etc/hosts).
* Set up the user's ssh directory (/home/frankban/.ssh).
* Create, if it does not exist, the ssh key /home/frankban/.ssh/id_rsa and authorize this key for the user
  frankban.
* Add bazaar.launchpad.net to known hosts.
* Set up bazaar authentication: Francesco Banconi <email address hidden>.
* Set up Launchpad user id: frankban.
* Add required APT repositories and install Launchpad dependencies: launchpad-database-dependencies-9.1 launchpad-
  developer-dependencies apache2 apache2-mpm-worker libapache2-mod-wsgi.

- descriptions are now wrapped at terminal size
- simplified the confirm function, updated the corresponding tests
- s/dry/dry_run

Also updated the descriptions handling, in particular:
- an error is raised if placeholders are missing in the steps' descriptions
- an error is raised for missing descriptions
These changes convinced me to implement a --dry-run smoke test, so that we can ensure our steps are correctly described.

- *interactive* now is always an attribute of namespace, even if the sub command does not support interactive execution. => Removed the is_interactive method.

[Benji York (benji)]

The branch looks good. The wrapping to the terminal width is especially nice.

review: Approve (code)

[Launchpad QA Bot (lpqabot)]

Attempt to merge into lp:lpsetup failed due to conflicts:

text conflict in lpsetup/tests/integration/test_install_lxc.py

[Launchpad QA Bot (lpqabot)]

There are additional revisions which have not been approved in review. Please seek review and approval of these new revisions.

[Francesco Banconi (frankban)]

review: Approve

[Launchpad QA Bot (lpqabot)]

The attempt to merge lp:~frankban/lpsetup/interactive-execution into lp:lpsetup failed. Below is the output from the failed tests.

nose.plugins.cover: ERROR: Coverage not available: unable to import coverage module
...........................................E..........................EEEE..........................................................EE..EE.EEE........
======================================================================
ERROR: test_subcommand_smoke_via_dry_run (lpsetup.tests.subcommands.test_smoke.SmokeTest)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/home/tarmac/repos/lpsetup/trunk/lpsetup/tests/subcommands/test_smoke.py", line 46, in test_subcommand_smoke_via_dry_run
    retcode = main([name, '--dry-run'] + args)
  File "/home/tarmac/repos/lpsetup/trunk/lpsetup/cli.py", line 51, in main
    return args.main(args)
  File "/home/tarmac/repos/lpsetup/trunk/lpsetup/argparser.py", line 315, in main
    return self.callback(namespace)
  File "/home/tarmac/repos/lpsetup/trunk/lpsetup/argparser.py", line 534, in run
    description = self.get_steps_description(namespace, steps)
  File "/home/tarmac/repos/lpsetup/trunk/lpsetup/argparser.py", line 527, in get_steps_description
    descriptions = [get_step_description(i[1], **context) for i in steps]
  File "/home/tarmac/repos/lpsetup/trunk/lpsetup/utils.py", line 194, in get_step_description
    width = get_terminal_width()
  File "/home/tarmac/repos/lpsetup/trunk/lpsetup/utils.py", line 202, in get_terminal_width
    return int(run('stty', 'size').split()[1])
  File "/usr/lib/python2.7/dist-packages/shelltoolbox/__init__.py", line 452, in run
    raise exception
CalledProcessError: Command '['stty', 'size']' returned non-zero exit status 1

======================================================================
ERROR: test_command_description (lpsetup.tests.test_argparser.InteractiveStepsBasedSubCommandTest)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/home/tarmac/repos/lpsetup/trunk/lpsetup/tests/test_argparser.py", line 230, in test_command_description
    self.parse_and_call_main()
  File "/home/tarmac/repos/lpsetup/trunk/lpsetup/tests/utils.py", line 198, in parse_and_call_main
    return namespace.main(namespace)
  File "/home/tarmac/repos/lpsetup/trunk/lpsetup/argparser.py", line 315, in main
    return self.callback(namespace)
  File "/home/tarmac/repos/lpsetup/trunk/lpsetup/argparser.py", line 534, in run
    description = self.get_steps_description(namespace, steps)
  File "/home/tarmac/repos/lpsetup/trunk/lpsetup/argparser.py", line 527, in get_steps_description
    descriptions = [get_step_description(i[1], **context) for i in steps]
  File "/home/tarmac/repos/lpsetup/trunk/lpsetup/utils.py", line 194, in get_step_description
    width = get_terminal_width()
  File "/home/tarmac/repos/lpsetup/trunk/lpsetup/utils.py", line 202, in get_terminal_width
    return int(run('stty', 'size').split()[1])
  File "/usr/lib/python2.7/dist-packages/shelltoolbox/__init__.py", line 452, in run
    raise exception
CalledProcessError: Command '['stty', '...

[Francesco Banconi (frankban)]

review: Approve

[Launchpad QA Bot (lpqabot)]

The attempt to merge lp:~frankban/lpsetup/interactive-execution into lp:lpsetup failed. Below is the output from the failed tests.

nose.plugins.cover: ERROR: Coverage not available: unable to import coverage module
...........................................E..........................EEEE..........................................................EE..EE.EEE........
======================================================================
ERROR: test_subcommand_smoke_via_dry_run (lpsetup.tests.subcommands.test_smoke.SmokeTest)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/home/tarmac/repos/lpsetup/trunk/lpsetup/tests/subcommands/test_smoke.py", line 46, in test_subcommand_smoke_via_dry_run
    retcode = main([name, '--dry-run'] + args)
  File "/home/tarmac/repos/lpsetup/trunk/lpsetup/cli.py", line 51, in main
    return args.main(args)
  File "/home/tarmac/repos/lpsetup/trunk/lpsetup/argparser.py", line 315, in main
    return self.callback(namespace)
  File "/home/tarmac/repos/lpsetup/trunk/lpsetup/argparser.py", line 534, in run
    description = self.get_steps_description(namespace, steps)
  File "/home/tarmac/repos/lpsetup/trunk/lpsetup/argparser.py", line 527, in get_steps_description
    descriptions = [get_step_description(i[1], **context) for i in steps]
  File "/home/tarmac/repos/lpsetup/trunk/lpsetup/utils.py", line 194, in get_step_description
    width = get_terminal_width()
  File "/home/tarmac/repos/lpsetup/trunk/lpsetup/utils.py", line 205, in get_terminal_width
    raise ValueError(str(err) + ' - ' + err.output)
ValueError: Command '['stty', 'size']' returned non-zero exit status 1 - stty: standard input: Invalid argument

======================================================================
ERROR: test_command_description (lpsetup.tests.test_argparser.InteractiveStepsBasedSubCommandTest)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/home/tarmac/repos/lpsetup/trunk/lpsetup/tests/test_argparser.py", line 230, in test_command_description
    self.parse_and_call_main()
  File "/home/tarmac/repos/lpsetup/trunk/lpsetup/tests/utils.py", line 198, in parse_and_call_main
    return namespace.main(namespace)
  File "/home/tarmac/repos/lpsetup/trunk/lpsetup/argparser.py", line 315, in main
    return self.callback(namespace)
  File "/home/tarmac/repos/lpsetup/trunk/lpsetup/argparser.py", line 534, in run
    description = self.get_steps_description(namespace, steps)
  File "/home/tarmac/repos/lpsetup/trunk/lpsetup/argparser.py", line 527, in get_steps_description
    descriptions = [get_step_description(i[1], **context) for i in steps]
  File "/home/tarmac/repos/lpsetup/trunk/lpsetup/utils.py", line 194, in get_step_description
    width = get_terminal_width()
  File "/home/tarmac/repos/lpsetup/trunk/lpsetup/utils.py", line 205, in get_terminal_width
    raise ValueError(str(err) + ' - ' + err.output)
ValueError: Command '['stty', 'size']' returned non-zero exit status 1 - stty: standard input: Invalid argument

======================================================================
ERROR: test_dry_run ...

[lp:~frankban/lpsetup/interactive-execution]

82. By Francesco Banconi on 2012-07-31

get_terminal_width does not raise an error when the terminal is not found.

83. By Francesco Banconi on 2012-07-31

Checkpoint

[Francesco Banconi (frankban)]

review: Approve

=== modified file 'lpsetup/argparser.py'
--- lpsetup/argparser.py	2012-06-27 12:00:03 +0000
+++ lpsetup/argparser.py	2012-07-31 08:52:19 +0000
@@ -17,6 +17,10 @@
 import sys
 
 from lpsetup.exceptions import ValidationError
+from lpsetup.utils import (
+    confirm,
+    get_step_description,
+    )
 
 
 class ArgumentParser(argparse.ArgumentParser):
@@ -106,12 +110,19 @@
             dest = action.dest
             option_strings = action.option_strings
             value = getattr(namespace, dest, None)
+            isbool = isinstance(value, bool)
+            # If the value is boolean and the action is 'store_false', we
+            # invert the value. This way the following `if value:` block
+            # is executed if the original value is False, and the argument
+            # is correctly added.
+            if isbool and isinstance(action, argparse._StoreFalseAction):
+                value = not value
             if value:
                 if option_strings:
                     args.append(option_strings[0])
                 if isinstance(value, list):
                     args.extend(value)
-                elif not isinstance(value, bool):
+                elif not isbool:
                     args.append(value)
         return args
 
@@ -332,6 +343,7 @@
         ...     trace.append('step2 received {0} and {1}'.format(foo, bar))
 
         >>> class SubCommand(StepsBasedSubCommand):
+        ...     has_interactive_run = False
         ...     steps = (
         ...         (step1, 'foo'),
         ...         (step2, 'foo', 'bar'),
@@ -419,9 +431,11 @@
     """
 
     steps = ()
+    has_interactive_run = True
 
     def add_arguments(self, parser):
         super(StepsBasedSubCommand, self).add_arguments(parser)
+        # Add steps related arguments.
         step_names = [self._get_step_name(i[0]) for i in self.steps]
         parser.add_argument(
             '-s', '--steps', nargs='+', choices=step_names,
@@ -429,6 +443,23 @@
         parser.add_argument(
             '--skip-steps', nargs='+', choices=step_names,
             help='Skip one or more internal functions.')
+        # Add developer interaction related arguments.
+        if self.has_interactive_run:
+            parser.add_argument(
+                '-y', '--yes', action='store_false', dest='interactive',
+                help='Assume yes to all queries.')
+        parser.add_argument(
+            '--dry-run', action='store_true', help='Dry run.')
+
+    def init_namespace(self, namespace):
+        """Override to add *namespace.interactive*.
+
+        This is done to ensure *interactive* is always present as an
+        attribute of *namespace*, even if self.has_interactive_run is False.
+        """
+        super(StepsBasedSubCommand, self).init_namespace(namespace)
+        if not self.has_interactive_run:
+            namespace.interactive = False
 
     def _get_step_name(self, step):
         """Return the string representation of a step callable.
@@ -487,9 +518,34 @@
         """Default callable used to run a `step`, using given `args`."""
         return step(*args)
 
+    def get_steps_description(self, namespace, steps):
+        """Retrieve steps' descriptions from the given *steps*.
+
+        Return a string containing all the descriptions.
+        """
+        context = namespace.__dict__
+        descriptions = [get_step_description(i[1], **context) for i in steps]
+        return '\n'.join(filter(None, descriptions))
+
     def run(self, namespace):
+        steps = self.get_steps(namespace)
+        if namespace.dry_run or namespace.interactive:
+            # Collect and display the description of each step.
+            description = self.get_steps_description(namespace, steps)
+            if description:
+                print 'This command will perform the following actions:\n'
+                print description + '\n'
+            # Quit without errors if this is a dry run.
+            if namespace.dry_run:
+                return
+            # If this is not a dry run, then it is an interactive one.
+            # Prompt the user for confirmation to proceed and quit if
+            # requested (in this case with exit code 1).
+            if not confirm():
+                return 1
+        # Execute all the steps.
         default_step_runner = self._call_step
-        for step_name, step, args in self.get_steps(namespace):
+        for step_name, step, args in steps:
             # Run the step using a dynamic dispatcher.
             step_runner = getattr(
                 self, 'call_' + step_name, default_step_runner)

=== modified file 'lpsetup/handlers.py'
--- lpsetup/handlers.py	2012-07-23 15:01:16 +0000
+++ lpsetup/handlers.py	2012-07-31 08:52:19 +0000
@@ -280,6 +280,7 @@
     if getattr(namespace, 'testing', False):
         namespace.create_scripts = True
         namespace.install_subunit = True
+        namespace.interactive = False
         namespace.no_checkout = True
         namespace.stop_lxc = True
         namespace.use_http = True

=== modified file 'lpsetup/subcommands/finish_inithost.py'
--- lpsetup/subcommands/finish_inithost.py	2012-07-20 10:40:43 +0000
+++ lpsetup/subcommands/finish_inithost.py	2012-07-31 08:52:19 +0000
@@ -53,6 +53,11 @@
     pwd_database = pwd.getpwnam(user)
     os.chown('/srv/launchpad.dev/', pwd_database.pw_uid, pwd_database.pw_gid)
 
+setup_launchpad.description = """Set up the Launchpad database: this will \
+    destroy any other Postgres db!
+    Make and install Launchpad (buildout dependencies, Apache configuration).
+"""
+
 
 class SubCommand(argparser.StepsBasedSubCommand):
     """Finish the initialization of a Launchpad development host.

=== modified file 'lpsetup/subcommands/inithost.py'
--- lpsetup/subcommands/inithost.py	2012-07-24 15:27:08 +0000
+++ lpsetup/subcommands/inithost.py	2012-07-31 08:52:19 +0000
@@ -140,6 +140,11 @@
     if not user_exists(user):
         call('useradd', '-m', '-s', '/bin/bash', '-U', user)
 
+initialize_base.description = """Update your system and install necessary \
+    deb packages ({packages}).
+    Create the user $user if it does not exist.
+""".format(packages=' '.join(BASE_PACKAGES))
+
 
 def initialize(user):
     """Initialize host machine."""
@@ -170,6 +175,12 @@
     for line in lines:
         file_append(HOSTS_FILE, line)
 
+initialize.description = initialize_base.description + """ Create Apache \
+    document roots for launchpad and enable required Apache \
+    modules ({modules}).
+    Set up hosts file for Launchpad ({hosts}).
+""".format(modules=LP_APACHE_MODULES, hosts=HOSTS_FILE)
+
 
 def setup_home(
     user, full_name, email, lpuser, private_key, public_key, valid_ssh_keys,
@@ -196,6 +207,14 @@
         if valid_ssh_keys:
             subprocess.call(['bzr', 'launchpad-login', lpuser])
 
+setup_home.description = """Set up the user's ssh directory ($home_dir/.ssh).
+    Create, if it does not exist, the ssh key $ssh_key_path and authorize \
+    this key for the user $user.
+    Add bazaar.launchpad.net to known hosts.
+    Set up bazaar authentication: $full_name <$email>.
+    Set up Launchpad user id: $lpuser.
+"""
+
 
 def initialize_lxc():
     """Initialize LXC container.
@@ -223,6 +242,8 @@
         make_backup(networking)
         render_to_file('networking.conf', {}, networking)
 
+initialize_lxc.description = None
+
 
 def get_distro():
     return run('lsb_release', '-cs').strip()
@@ -240,6 +261,10 @@
     # Install base and Launchpad deb packages.
     apt_get_install(*LP_PACKAGES, LC_ALL='C', caller=call)
 
+setup_apt.description = """Add required APT repositories and install \
+    Launchpad dependencies: {dependencies}.
+""".format(dependencies=' '.join(LP_PACKAGES))
+
 
 class SubCommand(argparser.StepsBasedSubCommand):
     """Prepare a machine to run Launchpad.  May be an LXC container or not."""

=== modified file 'lpsetup/subcommands/initlxc.py'
--- lpsetup/subcommands/initlxc.py	2012-07-24 15:34:58 +0000
+++ lpsetup/subcommands/initlxc.py	2012-07-31 08:52:19 +0000
@@ -64,6 +64,11 @@
     # entropy exhaustion during automated parallel tests.
     apt_get_install('haveged', caller=call)
 
+initialize.description = inithost.initialize_base.description + """Install \
+    haveged in order to fill /dev/random, avoiding entropy exhaustion \
+    during automated parallel tests.
+"""
+
 
 def create_lxc(lxc_name, lxc_arch, lxc_os, user, install_subunit):
     """Create the LXC named `lxc_name` sharing `user` home directory.
@@ -121,17 +126,27 @@
             '/var/lib/lxc/{0}/fstab'.format(lxc_name),
             'none dev/shm tmpfs defaults 0 0\n')
 
+create_lxc.description = """Create an LXC container named $lxc_name \
+    ($lxc_os $lxc_arch), bind mounting $home_dir, and disabling apparmor \
+    profiles for lxc so that we don't have problems installing Postgres.
+    Allow root access to the container.
+"""
+
 
 def start_lxc(lxc_name):
     """Start the lxc instance named `lxc_name`."""
     call('lxc-start', '-n', lxc_name, '-d')
 
+start_lxc.description = 'Start the LXC container named $lxc_name.\n'
+
 
 def wait_for_lxc(lxc_name, ssh_key_path):
     """Try to ssh into the LXC container named `lxc_name`."""
     retry_ssh = retry(subprocess.CalledProcessError)(ssh)
     retry_ssh(lxc_name, 'true', key=ssh_key_path)
 
+wait_for_lxc.description = None
+
 
 def install_lpsetup_in_lxc(lxc_name, ssh_key_path, lxc_os,
                            user, home_dir, lpsetup_branch=None):
@@ -188,16 +203,20 @@
         # must be done as root.
         shutil.rmtree(dest)
 
+install_lpsetup_in_lxc.description = None
+
 
 def inithost_in_lxc(lxc_name, ssh_key_path, user, email, full_name, lpuser,
                     private_key, public_key, ssh_key_name, home_dir):
     """Prepare the Launchpad environment inside an LXC."""
     # Use ssh to call this script from inside the container.
-    args = ['init-host', '-u', user, '-E', email, '-f', full_name,
+    args = ['init-host', '--yes', '-u', user, '-E', email, '-f', full_name,
             '-l', lpuser, '-S', ssh_key_name, '--skip-steps', 'setup_home']
     cmd = this_command(home_dir, args)
     ssh(lxc_name, cmd, key=ssh_key_path)
 
+inithost_in_lxc.description = 'Initialize the LXC instance $lxc_name.\n'
+
 
 def stop_lxc(lxc_name, ssh_key_path):
     """Stop the lxc instance named `lxc_name`."""
@@ -205,6 +224,8 @@
     if not lxc_stopped(lxc_name):
         subprocess.call(['lxc-stop', '-n', lxc_name])
 
+stop_lxc.description = None
+
 
 class SubCommand(inithost.SubCommand):
     """Create an LXC container suitable for later installing a Launchpad

=== modified file 'lpsetup/subcommands/initrepo.py'
--- lpsetup/subcommands/initrepo.py	2012-07-20 10:40:43 +0000
+++ lpsetup/subcommands/initrepo.py	2012-07-31 08:52:19 +0000
@@ -83,6 +83,10 @@
                 msg = 'Error: unable to create the lightweight checkout: '
                 raise exceptions.ExecutionError(msg + err.output)
 
+fetch.description = """Set up a Launchpad repository in $repository, \
+    retrieving the source code from $source.
+"""
+
 
 def setup_bzr_locations(
     lpuser, repository, branch_name, template=LP_BZR_LOCATIONS):
@@ -112,6 +116,11 @@
             f.write(get_file_header() + '\n')
             parser.write(f)
 
+setup_bzr_locations.description = """If bzr+ssh is used, update bazaar \
+    locations ($home_dir/.bazaar/locations.conf) to include repository \
+    $repository and branch $branch_name.
+"""
+
 
 class SubCommand(argparser.StepsBasedSubCommand):
     """Get the Launchpad code and dependent source code."""

=== modified file 'lpsetup/subcommands/install_lxc.py'
--- lpsetup/subcommands/install_lxc.py	2012-07-24 14:07:50 +0000
+++ lpsetup/subcommands/install_lxc.py	2012-07-31 08:52:19 +0000
@@ -69,6 +69,11 @@
     with open(procfile, 'w') as f:
         f.write('0\n')
 
+create_scripts.description = """If requested, create helper script \
+    /usr/locl/bin/lp-setup-*: they can be used to build Launchpad and \
+    start a parallel test run.
+"""
+
 
 def cmd_in_lxc(lxc_name, ssh_key_path, home_dir, args, as_user=None):
     cmd = this_command(home_dir, args)
@@ -81,7 +86,7 @@
     args = [
         'init-repo', '--source', source,
         '--branch-name', branch_name, '--checkout-name', checkout_name,
-        '--repository', repository,
+        '--repository', repository, '--yes',
         ]
     if use_http:
         args.append('--use-http')
@@ -89,6 +94,10 @@
         args.append('--no-checkout')
     cmd_in_lxc(lxc_name, ssh_key_path, home_dir, args, as_user=user)
 
+init_repo_in_lxc.description = """Initialize the Launchpad repository \
+    inside the LXC container $lxc_name.
+""" + initrepo.fetch.description + initrepo.setup_bzr_locations.description
+
 
 def update_in_lxc(
     lxc_name, ssh_key_path, home_dir, user, external_path,
@@ -98,12 +107,21 @@
         args.append('--use-http')
     cmd_in_lxc(lxc_name, ssh_key_path, home_dir, args, as_user=user)
 
+update_in_lxc.description = (
+    update.initialize_directories.description +
+    update.update_dependencies.description +
+    update.update_tree.description)
+
 
 def finish_inithost_in_lxc(
     lxc_name, ssh_key_path, home_dir, user, target_dir):
-    args = ['finish-init-host', target_dir, '--user', user]
+    args = ['finish-init-host', target_dir, '--user', user, '--yes']
     cmd_in_lxc(lxc_name, ssh_key_path, home_dir, args)
 
+finish_inithost_in_lxc.description = """Set up the database, make and \
+    install Launchpad inside the LXC instance $lxc_name.
+"""
+
 
 class SubCommand(initlxc.SubCommand):
     """Completely sets up an LXC environment with Launchpad using the sandbox
@@ -154,4 +172,4 @@
         parser.add_argument(
             '--testing', action='store_true',
             help='Alias for --create-scripts --install-subunit --no-checkout '
-                 '--stop_lxc --use-http.')
+                 '--stop_lxc --use-http --yes.')

=== modified file 'lpsetup/subcommands/update.py'
--- lpsetup/subcommands/update.py	2012-07-20 10:40:43 +0000
+++ lpsetup/subcommands/update.py	2012-07-31 08:52:19 +0000
@@ -29,6 +29,10 @@
     for dir_ in ['eggs', 'yui', 'sourcecode']:
         mkdirs(os.path.join(target_dir, external_path, dir_))
 
+initialize_directories.description = """Initialize the eggs, yui, and \
+    sourcecode directories in $target_dir.
+"""
+
 
 def update_dependencies(target_dir, external_path, use_http):
     """Update the external dependencies."""
@@ -54,12 +58,20 @@
             '--target', target_dir,
             '--parent', external_path)
 
+update_dependencies.description = """Update Launchpad external \
+    dependencies in $target_dir.
+"""
+
 
 def update_tree(target_dir):
     """Update the tree at target_dir with the latest LP code."""
     with cd(target_dir):
         run('bzr', 'pull')
 
+update_tree.description = """Update the tree at $target_dir with the \
+    latest LP code.
+"""
+
 
 class SubCommand(argparser.StepsBasedSubCommand):
     """Updates an existing Launchpad development environment.
@@ -67,6 +79,7 @@
     Gets new versions of Launchpad source and external sources.
     """
 
+    has_interactive_run = False
     steps = (
         (initialize_directories, 'target_dir', 'external_path'),
         (update_dependencies, 'target_dir', 'external_path', 'use_http'),

=== modified file 'lpsetup/tests/examples.py'
--- lpsetup/tests/examples.py	2012-06-27 09:20:50 +0000
+++ lpsetup/tests/examples.py	2012-07-31 08:52:19 +0000
@@ -25,9 +25,16 @@
 
 def step2(foo, bar):
     print 'step2 received {0} and {1}'.format(foo, bar)
+
 step2.step_name = 'mystep'
 
 
+def step_with_description(foo):
+    pass
+
+step_with_description.description = 'step description'
+
+
 def bad_step(foo):
     raise subprocess.CalledProcessError(1, 'command')
 
@@ -48,6 +55,7 @@
 class StepsBasedSubCommand(argparser.StepsBasedSubCommand):
     """An example steps based sub command."""
 
+    has_interactive_run = False
     steps = (
         (step1, 'foo'),
         (step2, 'foo', 'bar'),
@@ -76,3 +84,10 @@
         print 'running step1 with {args} while bar is {bar}'.format(
             args=','.join(args), bar=namespace.bar)
         step(*args)
+
+
+class InteractiveStepsBasedSubCommand(StepsBasedSubCommand):
+    """An example interactive steps based sub command."""
+
+    has_interactive_run = True
+    steps = [(step_with_description, 'foo')]

=== modified file 'lpsetup/tests/integration/test_init_host.py'
--- lpsetup/tests/integration/test_init_host.py	2012-07-25 13:11:25 +0000
+++ lpsetup/tests/integration/test_init_host.py	2012-07-31 08:52:19 +0000
@@ -27,7 +27,7 @@
         # Since the most common scenario is to have bzr whoami setup, we do
         # that instead of providing the arguments directly to lpsetup.
         super(InitHostTest, self).do_test()
-        self.on_remote('cd lpsetup; ./lp-setup init-host')
+        self.on_remote('cd lpsetup; ./lp-setup init-host --yes')
 
 
 if __name__ == '__main__':

=== modified file 'lpsetup/tests/integration/test_install_lxc.py'
--- lpsetup/tests/integration/test_install_lxc.py	2012-07-27 12:12:46 +0000
+++ lpsetup/tests/integration/test_install_lxc.py	2012-07-31 08:52:19 +0000
@@ -95,7 +95,7 @@
         lp_source = 'http://bazaar.launchpad.net/~yellow/launchpad/stub'
         cmd = (
             'lpsetup/lp-setup install-lxc --use-http '
-            '--source {} -B {} -r {}'.format(
+            '--source {} -B {} -r {} --yes'.format(
             lp_source, branch_location, self.repo))
         self.on_remote(cmd)
 

=== modified file 'lpsetup/tests/subcommands/test_initrepo.py'
--- lpsetup/tests/subcommands/test_initrepo.py	2012-07-19 14:17:15 +0000
+++ lpsetup/tests/subcommands/test_initrepo.py	2012-07-31 08:52:19 +0000
@@ -96,6 +96,7 @@
             '--repository', self.repository,
             '--branch-name', branch_name,
             '--checkout-name', checkout_name,
+            '--yes',
             )
         self.branch = os.path.join(self.repository, branch_name)
         self.checkout = os.path.join(self.repository, checkout_name)

=== modified file 'lpsetup/tests/subcommands/test_smoke.py'
--- lpsetup/tests/subcommands/test_smoke.py	2012-06-26 15:02:09 +0000
+++ lpsetup/tests/subcommands/test_smoke.py	2012-07-31 08:52:19 +0000
@@ -10,6 +10,11 @@
     subcommands,
     )
 
+from lpsetup.tests.utils import (
+    capture_output,
+    root_not_needed,
+    )
+
 
 class SmokeTest(unittest.TestCase):
     """Tests which are intended to do a quick check for broken subcommands."""
@@ -19,3 +24,26 @@
         # function and verify that a non-error exit code is returned.
         for subcommand, callable in subcommands:
             self.assertEqual(main([subcommand, '--help']), 0)
+
+    def test_subcommand_smoke_via_dry_run(self):
+        # Perform a basic smoke test by running each subcommand's dry run
+        # and verify that a non-error exit code is returned.
+        required_args = ['-f', 'Example User', '-E', '[e-mail]']
+        name_args_map = {
+            'finish-init-host': [],
+            'init-host': required_args,
+            'init-lxc': required_args,
+            'init-repo': [],
+            'install-lxc': required_args,
+            'update': [],
+            }
+        name_class_map = dict(subcommands)
+        warning = 'This command will perform the following actions:'
+        for name, args in name_args_map.items():
+            subcommand = name_class_map[name]
+            with capture_output() as output:
+                with root_not_needed(subcommand):
+                    retcode = main([name, '--dry-run'] + args)
+            self.assertFalse(retcode)
+            # Ensure sub command description is printed to stdout.
+            self.assertIn(warning, output.getvalue())

=== modified file 'lpsetup/tests/test_argparser.py'
--- lpsetup/tests/test_argparser.py	2012-06-27 09:20:50 +0000
+++ lpsetup/tests/test_argparser.py	2012-07-31 08:52:19 +0000
@@ -4,6 +4,7 @@
 
 """Tests for the argparser module."""
 
+from contextlib import nested
 import subprocess
 import unittest
 
@@ -13,6 +14,7 @@
 from lpsetup.tests.utils import (
     capture_error,
     capture_output,
+    RawInputReturning,
     SubCommandTestMixin,
     )
 
@@ -61,6 +63,27 @@
         args = self.parser.get_args_from_namespace(namespace)
         self.assertSequenceEqual(['--foo', 'changed', 'spam'], args)
 
+    def test_args_from_namespace_with_multiple_values(self):
+        # Ensure *get_args_from_namespace* correcty handles options
+        # accepting multiple values.
+        self.parser.add_argument('foo')
+        self.parser.add_argument('--bar', nargs='+')
+        namespace = self.parser.parse_args('foo --bar eggs spam'.split())
+        namespace.bar.append('another argument')
+        args = self.parser.get_args_from_namespace(namespace)
+        expected = ['foo', '--bar', 'eggs', 'spam', 'another argument']
+        self.assertSequenceEqual(expected, args)
+
+    def test_args_from_namespace_with_boolean_values(self):
+        # Ensure *get_args_from_namespace* correcty handles options
+        # accepting boolean values.
+        self.parser.add_argument('--foo', action='store_true')
+        self.parser.add_argument('--bar', action='store_false')
+        expected = ['--foo', '--bar']
+        namespace = self.parser.parse_args(expected)
+        args = self.parser.get_args_from_namespace(namespace)
+        self.assertSequenceEqual(expected, args)
+
     def test_help_subcommand(self):
         # Ensure the help sub command is added if other commands exist.
         self.parser.register_subcommand('foo', self.get_sub_command())
@@ -170,7 +193,9 @@
     def test_failing_step(self):
         # Ensure the steps execution is stopped if a step raises
         # `subprocess.CalledProcessError`.
-        with self.assertRaises(subprocess.CalledProcessError):
+        with nested(
+            capture_output(),
+            self.assertRaises(subprocess.CalledProcessError)):
             self.parse_and_call_main('--foo', 'eggs')
 
 
@@ -189,3 +214,50 @@
             'step2 received eggs and spam'
             ]
         self.check_output(expected, output)
+
+
+class InteractiveStepsBasedSubCommandTest(
+    SubCommandTestMixin, unittest.TestCase):
+
+    sub_command_class = examples.InteractiveStepsBasedSubCommand
+    step_description = examples.step_with_description.description
+
+    def test_command_description(self):
+        # Ensure the command description is generated collecting steps'
+        # descriptions.
+        with capture_output() as output:
+            with RawInputReturning('yes'):
+                self.parse_and_call_main()
+        self.assertIn(self.step_description, output.getvalue())
+
+    def test_interactive_execution_granted(self):
+        # Ensure the command executes if the user confirms to proceed.
+        with nested(capture_output(), RawInputReturning('yes')):
+            retcode = self.parse_and_call_main()
+        self.assertFalse(retcode)
+
+    def test_interactive_execution_denied(self):
+        # Ensure the command exits with an error if the user denies execution.
+        with nested(capture_output(), RawInputReturning('no')):
+            retcode = self.parse_and_call_main()
+        self.assertEqual(1, retcode)
+
+    def test_assume_yes(self):
+        # Ensure confirmation is not asked if `--yes` is provided.
+        with capture_output():
+            with RawInputReturning('') as cm:
+                self.parse_and_call_main('--yes')
+        self.assertEqual(0, cm.call_count)
+
+    def test_dry_run(self):
+        # Ensure a dry run is never interactive, exits without errors and
+        # prints out the command description.
+        with capture_output() as output:
+            with RawInputReturning('') as cm:
+                retcode = self.parse_and_call_main('--dry-run')
+        # Confirm has not been called.
+        self.assertEqual(0, cm.call_count)
+        # The command exits without errors.
+        self.assertFalse(retcode)
+        # The command description is displayed.
+        self.assertIn(self.step_description, output.getvalue())

=== modified file 'lpsetup/tests/test_handlers.py'
--- lpsetup/tests/test_handlers.py	2012-07-23 15:01:16 +0000
+++ lpsetup/tests/test_handlers.py	2012-07-31 08:52:19 +0000
@@ -319,17 +319,21 @@
 
     def test_true(self):
         # Ensure aliased options are set to True if testing is True.
-        namespace = argparse.Namespace(testing=True, **self.ctx)
+        namespace = argparse.Namespace(
+            testing=True, interactive=True, **self.ctx)
         handle_testing(namespace)
         for key in self.ctx:
             self.assertTrue(getattr(namespace, key))
+        self.assertFalse(namespace.interactive)
 
     def test_false(self):
         # Ensure no changes are made to aliased options if testing is False.
-        namespace = argparse.Namespace(testing=False, **self.ctx)
+        namespace = argparse.Namespace(
+            testing=False, interactive=True, **self.ctx)
         handle_testing(namespace)
         for key, value in self.ctx.items():
             self.assertEqual(value, getattr(namespace, key))
+        self.assertTrue(namespace.interactive)
 
 
 class HandleUserTest(HandlersTestMixin, unittest.TestCase):

=== modified file 'lpsetup/tests/test_utils.py'
--- lpsetup/tests/test_utils.py	2012-07-18 14:27:32 +0000
+++ lpsetup/tests/test_utils.py	2012-07-31 08:52:19 +0000
@@ -6,6 +6,7 @@
 
 from datetime import datetime
 import getpass
+import itertools
 import os
 import shutil
 import sys
@@ -19,13 +20,20 @@
     LXC_LP_TEST_DIR_PATTERN,
     LXC_NAME,
     )
+from lpsetup.tests.utils import (
+    capture_output,
+    RawInputReturning,
+    )
 from lpsetup.utils import (
     ConfigParser,
+    confirm,
     get_container_path,
     get_file_header,
     get_lxc_gateway,
     get_network_interfaces,
     get_running_containers,
+    get_step_description,
+    get_terminal_width,
     render_to_file,
     retry,
     Scrubber,
@@ -48,6 +56,36 @@
         self.assertEqual('value2', items['option2:colon'])
 
 
+class ConfirmTest(unittest.TestCase):
+
+    def test_yes(self):
+        # Ensure *confirm* returns True if the response is 'yes'.
+        for response in ('y', 'Y', 'yes', 'Yes'):
+            with RawInputReturning(response) as cm:
+                self.assertTrue(confirm())
+                self.assertEqual(1, cm.call_count)
+
+    def test_no(self):
+        # Ensure *confirm* returns False if the response is 'no'.
+        for response in ('n', 'N', 'no', 'No'):
+            with RawInputReturning(response) as cm:
+                self.assertFalse(confirm())
+                self.assertEqual(1, cm.call_count)
+
+    def test_default(self):
+        # Ensure *confirm* returns False if no input is given.
+        with RawInputReturning('') as cm:
+            self.assertFalse(confirm())
+            self.assertEqual(1, cm.call_count)
+
+    def test_wrong_input(self):
+        # Ensure the question is asked again if the answer is wrong.
+        with capture_output():
+            with RawInputReturning('Nope', 'Yep', 'y') as cm:
+                self.assertTrue(confirm())
+                self.assertEqual(3, cm.call_count)
+
+
 class GetContainerPathTest(unittest.TestCase):
 
     def test_root_path(self):
@@ -169,6 +207,85 @@
         self.assertRunning([], ['c1', 'c2', 'c3'])
 
 
+class GetStepDescriptionTest(unittest.TestCase):
+
+    def assertStartsWith(self, prefix, content):
+        """Assert that content starts with prefix."""
+        self.assertTrue(
+            content.startswith(prefix),
+            '%r does not start with %r' % (content, prefix))
+
+    def get_step(self, description=None):
+        step = lambda: None
+        step.description = description
+        return step
+
+    def test_with_context(self):
+        # Ensure the description is correctly retrieved and formatted.
+        step = self.get_step('This step will do $stuff.')
+        description = get_step_description(step, stuff='nothing')
+        self.assertEqual('* This step will do nothing.', description)
+
+    def test_without_context(self):
+        # The description can be still retrieved if no context is provided.
+        original = 'This step will do $stuff.'
+        description = get_step_description(self.get_step(original))
+        self.assertEqual('* ' + original, description)
+
+    def test_without_placeholder(self):
+        # Ensure an error is raised if a placeholder is missing.
+        expected = 'This step will do $stuff.'
+        with self.assertRaises(KeyError):
+            get_step_description(self.get_step(expected), foo='bar')
+
+    def test_missing_description(self):
+        # Ensure an empty string is returned if the description is None.
+        description = get_step_description(self.get_step())
+        self.assertEqual('', description)
+
+    def test_no_description(self):
+        # Ensure an AttrubuteError is raised if the description is not found.
+        with self.assertRaises(AttributeError):
+            get_step_description(lambda: None)
+
+    def test_dedent(self):
+        # Ensure the description is correctly dedented.
+        original = """
+            Hi there!
+        """
+        description = get_step_description(self.get_step(original))
+        self.assertEqual('* Hi there!', description)
+
+    def test_empty_lines(self):
+        # Ensure empty lines in description are removed.
+        original = 'Hello.\n  \nGoodbye.'
+        description = get_step_description(self.get_step(original))
+        self.assertEqual('* Hello.\n* Goodbye.', description)
+
+    def test_wrapping(self):
+        # Ensure the description is correctly wrapped.
+        width = get_terminal_width()
+        elements = itertools.cycle('Lorem ipsum dolor sit amet.')
+        original = ''.join(itertools.islice(elements, width + 1))
+        description = get_step_description(self.get_step(original))
+        lines = description.splitlines()
+        self.assertEqual(2, len(lines))
+        first_line, second_line = lines
+        self.assertStartsWith('* ', first_line)
+        self.assertStartsWith('  ', second_line)
+
+
+class GetTerminalSizeTest(unittest.TestCase):
+
+    def test_is_integer(self):
+        # Ensure the returned value is an integer number.
+        self.assertIsInstance(get_terminal_width(), int)
+
+    def test_positive_values(self):
+        # Ensure the returned value is greater than 0.
+        self.assertGreater(get_terminal_width(), 0)
+
+
 class RenderToFileTest(unittest.TestCase):
 
     def setUp(self):

=== modified file 'lpsetup/tests/utils.py'
--- lpsetup/tests/utils.py	2012-07-19 14:17:15 +0000
+++ lpsetup/tests/utils.py	2012-07-31 08:52:19 +0000
@@ -124,6 +124,51 @@
     lpuser is None, 'You need to set up a Launchpad login to run this test.')
 
 
+class RawInputReturning(object):
+    """Mocks the *raw_input* builtin function.
+
+    This context manager takes one or more pre-defined answers and
+    keeps track of mocked *raw_input* call count.
+    """
+    def __init__(self, *args):
+        self.answers = iter(args)
+        self._builtin = __import__('__builtin__')
+        self.call_count = 0
+        self.original = self._builtin.raw_input
+
+    def __enter__(self):
+        self._builtin.raw_input = self.input
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self._builtin.raw_input = self.original
+
+    def input(self, question):
+        self.call_count += 1
+        return self.answers.next()
+
+
+@contextmanager
+def root_not_needed(subcommand):
+    """Temporarily set to False the *needs_root* flag of *subcommand*."""
+    original, subcommand.needs_root = subcommand.needs_root, False
+    try:
+        yield
+    finally:
+        subcommand.needs_root = original
+
+
+class RootNotNeededTest(unittest.TestCase):
+
+    def test_context_manager(self):
+        # Ensure the context manager temporarily sets to False *needs_root*.
+        subcommand = type(
+            'SubCommand', (argparser.BaseSubCommand,), {'needs_root': True})
+        with root_not_needed(subcommand):
+            self.assertFalse(subcommand.needs_root)
+        self.assertTrue(subcommand.needs_root)
+
+
 class SubCommandTestMixin(object):
 
     sub_command_class = examples.SubCommand

=== modified file 'lpsetup/utils.py'
--- lpsetup/utils.py	2012-07-24 14:07:50 +0000
+++ lpsetup/utils.py	2012-07-31 08:52:19 +0000
@@ -7,11 +7,14 @@
 __metaclass__ = type
 __all__ = [
     'call',
+    'confirm',
     'get_container_path',
     'get_file_header',
     'get_lxc_gateway',
     'get_network_interfaces',
     'get_running_containers',
+    'get_step_description',
+    'get_terminal_width',
     'lxc_in_state',
     'lxc_ip',
     'lxc_stopped',
@@ -35,6 +38,7 @@
 import re
 import subprocess
 import shutil
+import string
 import sys
 import textwrap
 import time
@@ -79,6 +83,23 @@
         )
 
 
+def confirm():
+    """Ask a yes/no confirmation to proceed.
+
+    Return True if the answer is 'yes', False otherwise.
+    When the user presses Enter without typing anything, False is assumed.
+    """
+    while True:
+        response = raw_input('Do you want to proceed? [y/N] ').lower()
+        if not response:
+            return False
+        if response in ('y', 'yes'):
+            return True
+        if response in ('n', 'no'):
+            return False
+        print("I didn't understand you. Please specify '(y)es' or'(n)o'.")
+
+
 def get_container_path(lxc_name, path='', base_path=LXC_PATH):
     """Return the path of LXC container called `lxc_name`.
 
@@ -148,6 +169,45 @@
             visited[container] = 1
 
 
+def get_step_description(step, **kwargs):
+    """Retrieve and format step description from the given *step* callable.
+
+    *kwargs*, if provided, will be used as context to format the description.
+    Formatting is done using the Python's builtin templating system
+    *string.Template* supporting $-based substitutions.
+
+    If placeholders are missing from *kwargs* an error will be raised.
+    """
+    description = step.description
+    if not description:
+        # This step has no description, nothing else to do.
+        return ''
+    if kwargs:
+        s = string.Template(description)
+        description = s.substitute(**kwargs)
+    # Remove multiple spaces from lines.
+    lines = [' '.join(line.split()) for line in description.splitlines()]
+    # Retrieve all the non empty lines.
+    lines = filter(None, lines)
+    # For each line, wrap the contents. Note that we can't wrap the text of
+    # the entire paragraph because we want to preserve existing new lines.
+    width = get_terminal_width()
+    return '\n'.join(textwrap.fill(
+        line, width=width, initial_indent='* ', subsequent_indent='  ')
+        for line in lines)
+
+
+def get_terminal_width():
+    """Return the terminal width (number of columns)."""
+    try:
+        width = run('stty', 'size').split()[1]
+    except subprocess.CalledProcessError:
+        # No input available for stty, falling back to $COLUMNS.
+        # If $COLUMNS is not exported, return a default value.
+        width = os.getenv('COLUMNS', 79)
+    return int(width)
+
+
 def lxc_in_state(state, lxc_name, timeout=30):
     """Return True if the LXC named `lxc_name` is in state `state`.