Merge lp:~frankban/juju-quickstart/quickstart-bundle-file into lp:juju-quickstart

[Francesco Banconi]

Deploy a bundle from a file path.

Tests: run `make check`.
QA (assuming you have an ec2 environment set up named 'ec2'):
- run `.venv/bin/python juju-quickstart /no/such/file`:
  you should see the following error:
  "unable to open bundle file: [Errno 2]
  No such file or directory: '/no/such/file'";
- run `echo "env: no-services" > ~/invalid-bundle.yaml`;
- run `.venv/bin/python juju-quickstart ~/invalid-bundle.yaml`:
  you should see the following error:
  "invalid YAML contents: {'env': 'no-services'}";
- remove the file you created in your home:
  `rm ~/invalid-bundle.yaml`;
- download the bundle file from
  http://pastebin.ubuntu.com/6283832/ and save it
  for later as '../mybundle.yaml';
- run `.venv/bin/python juju-quickstart ../mybundle.yaml`:
  you should see the following error:
  "multiple bundles found (exp1, exp2) but no bundle name specified";
- run `.venv/bin/python juju-quickstart ../mybundle.yaml -n exp1`:
  this time the quickstart application should start normally.
- wait fr quickstart to complete: after some minutes the browser
  should open on the GUI page, the bundle deployment should be
  started, and the app exits without erros.

Remember to destroy your ec2 environment.

https://codereview.appspot.com/15880043/

[Francesco Banconi (frankban)]

Reviewers: mp+192194_code.launchpad.net,

Message:
Please take a look.

Description:
Deploy a bundle from a file path.

Tests: run `make check`.
QA (assuming you have an ec2 environment set up named 'ec2'):
- run `.venv/bin/python juju-quickstart /no/such/file`:
   you should see the following error:
   "unable to open bundle file: [Errno 2]
   No such file or directory: '/no/such/file'";
- run `echo "env: no-services" > ~/invalid-bundle.yaml`;
- run `.venv/bin/python juju-quickstart ~/invalid-bundle.yaml`:
   you should see the following error:
   "invalid YAML contents: {'env': 'no-services'}";
- remove the file you created in your home:
   `rm ~/invalid-bundle.yaml`;
- download the bundle file from
   http://pastebin.ubuntu.com/6283832/ and save it
   for later as '../mybundle.yaml';
- run `.venv/bin/python juju-quickstart ../mybundle.yaml`:
   you should see the following error:
   "multiple bundles found (exp1, exp2) but no bundle name specified";
- run `.venv/bin/python juju-quickstart ../mybundle.yaml -n exp1`:
   this time the quickstart application should start normally.
- wait fr quickstart to complete: after some minutes the browser
   should open on the GUI page, the bundle deployment should be
   started, and the app exits without erros.

Remember to destroy your ec2 environment.

https://code.launchpad.net/~frankban/juju-quickstart/quickstart-bundle-file/+merge/192194

(do not edit description out of merge proposal)

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

Affected files (+423, -1 lines):
   A [revision details]
   M quickstart/__init__.py
   M quickstart/app.py
   M quickstart/juju.py
   M quickstart/manage.py
   M quickstart/tests/helpers.py
   M quickstart/tests/test_app.py
   M quickstart/tests/test_juju.py
   M quickstart/tests/test_manage.py
   M quickstart/tests/test_utils.py
   M quickstart/utils.py

[Gary Poster (gary)]

LGTM! Thank you. :-)

I will qa later if no one else has been able to.

Gary

https://codereview.appspot.com/15880043/diff/1/quickstart/manage.py
File quickstart/manage.py (right):

https://codereview.appspot.com/15880043/diff/1/quickstart/manage.py#newcode156
quickstart/manage.py:156: 'option is ignored if the bundle file is not
specified')
I'd be tempted to change all the help to full sentences, with capital
letters and such, and then replace a lot of the semicolons with periods.

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

https://codereview.appspot.com/15880043/diff/1/quickstart/utils.py#newcode130
quickstart/utils.py:130: msg = 'bundle {} does not include any
service'.format(bundle_name)
any services

https://codereview.appspot.com/15880043/

[lp:~frankban/juju-quickstart/quickstart-bundle-file]

29. By Francesco Banconi on 2013-10-22

Changes as per review.

30. By Francesco Banconi on 2013-10-22

Fix tests.

[Francesco Banconi (frankban)]

*** Submitted:

Deploy a bundle from a file path.

Tests: run `make check`.
QA (assuming you have an ec2 environment set up named 'ec2'):
- run `.venv/bin/python juju-quickstart /no/such/file`:
   you should see the following error:
   "unable to open bundle file: [Errno 2]
   No such file or directory: '/no/such/file'";
- run `echo "env: no-services" > ~/invalid-bundle.yaml`;
- run `.venv/bin/python juju-quickstart ~/invalid-bundle.yaml`:
   you should see the following error:
   "invalid YAML contents: {'env': 'no-services'}";
- remove the file you created in your home:
   `rm ~/invalid-bundle.yaml`;
- download the bundle file from
   http://pastebin.ubuntu.com/6283832/ and save it
   for later as '../mybundle.yaml';
- run `.venv/bin/python juju-quickstart ../mybundle.yaml`:
   you should see the following error:
   "multiple bundles found (exp1, exp2) but no bundle name specified";
- run `.venv/bin/python juju-quickstart ../mybundle.yaml -n exp1`:
   this time the quickstart application should start normally.
- wait fr quickstart to complete: after some minutes the browser
   should open on the GUI page, the bundle deployment should be
   started, and the app exits without erros.

Remember to destroy your ec2 environment.

R=gary.poster
CC=
https://codereview.appspot.com/15880043

https://codereview.appspot.com/15880043/diff/1/quickstart/manage.py
File quickstart/manage.py (right):

https://codereview.appspot.com/15880043/diff/1/quickstart/manage.py#newcode156
quickstart/manage.py:156: 'option is ignored if the bundle file is not
specified')
On 2013/10/22 21:00:51, gary.poster wrote:
> I'd be tempted to change all the help to full sentences, with capital
letters
> and such, and then replace a lot of the semicolons with periods.

Done.

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

https://codereview.appspot.com/15880043/diff/1/quickstart/utils.py#newcode130
quickstart/utils.py:130: msg = 'bundle {} does not include any
service'.format(bundle_name)
On 2013/10/22 21:00:51, gary.poster wrote:
> any services

Done.

https://codereview.appspot.com/15880043/

[Francesco Banconi (frankban)]

Thanks Gary and Matthew!

https://codereview.appspot.com/15880043/

=== modified file 'quickstart/__init__.py'
--- quickstart/__init__.py	2013-10-18 08:05:43 +0000
+++ quickstart/__init__.py	2013-10-22 22:03:55 +0000
@@ -19,7 +19,7 @@
 that it can be managed using a Web interface (the Juju GUI).
 """
 
-VERSION = (0, 1, 0)
+VERSION = (0, 2, 0)
 
 
 def get_version():

=== modified file 'quickstart/app.py'
--- quickstart/app.py	2013-10-18 14:06:25 +0000
+++ quickstart/app.py	2013-10-22 22:03:55 +0000
@@ -174,3 +174,20 @@
                 print('{} is ready'.format(unit_name))
                 return address
             current_status = status
+
+
+def deploy_bundle(api_url, admin_secret, bundle_yaml, bundle_name):
+    """Deploy a bundle.
+
+    Receive an API URL to a WebSocket server supporting bundle deployments, the
+    admin_secret to use in the authentication process, the bundle YAML encoded
+    contents and the bundle name to be imported.
+
+    Raise a ProgramExit if the API server returns an error response.
+    """
+    env = connect(api_url, admin_secret)
+    try:
+        env.deploy_bundle(bundle_yaml, name=bundle_name)
+        env.close()
+    except jujuclient.EnvError as err:
+        raise ProgramExit('bad API server response: {}'.format(err.message))

=== modified file 'quickstart/juju.py'
--- quickstart/juju.py	2013-10-17 19:20:55 +0000
+++ quickstart/juju.py	2013-10-22 22:03:55 +0000
@@ -70,6 +70,18 @@
         }
         return self._rpc(request)
 
+    def deploy_bundle(self, yaml, name=None):
+        """Deploy a bundle."""
+        params = {'YAML': yaml}
+        if name is not None:
+            params['Name'] = name
+        request = {
+            'Type': 'Deployer',
+            'Request': 'Import',
+            'Params': params,
+        }
+        return self._rpc(request)
+
     def watch_changes(self, processor):
         """Start watching the changes occurring in the Juju environment.
 

=== modified file 'quickstart/manage.py'
--- quickstart/manage.py	2013-10-18 14:15:49 +0000
+++ quickstart/manage.py	2013-10-22 22:03:55 +0000
@@ -42,6 +42,38 @@
         parser.exit()
 
 
+def _validate_bundle(options, parser):
+    """Validate and process the bundle options.
+
+    Populate the options namespace with the following names:
+        - bundle_file: the full path to the bundle file;
+        - bundle_name: the name of the bundle;
+        - bundle_services: a list of service names included in the bundle;
+        - bundle_yaml: the YAML encoded contents of the bundle.
+
+    Exit with an error if the bundle options are not valid.
+    """
+    # XXX 2013-10-18 frankban:
+        # This function is supposed to also support bundle URLs.
+    bundle_file = os.path.abspath(os.path.expanduser(options.bundle))
+    # Load the bundle file.
+    try:
+        bundle_yaml = open(bundle_file).read()
+    except IOError as err:
+        return parser.error('unable to open bundle file: {}'.format(err))
+    # Validate the bundle.
+    try:
+        bundle_name, bundle_services = utils.parse_bundle(
+            bundle_yaml, options.bundle_name)
+    except ValueError as err:
+        return parser.error(str(err))
+    # Update the options namespace with the new values.
+    options.bundle_file = bundle_file
+    options.bundle_name = bundle_name
+    options.bundle_services = bundle_services
+    options.bundle_yaml = bundle_yaml
+
+
 def _validate_env(options, parser):
     """Validate and process the provided environment related options.
 
@@ -103,30 +135,43 @@
     """
     default_env_name = utils.get_default_env_name()
     # Define the help message for the --environment option.
-    env_help = 'the name of the Juju environment to use'
+    env_help = 'The name of the Juju environment to use'
     if default_env_name is not None:
         env_help = '{} (%(default)s)'.format(env_help)
     # Create and set up the arguments parser.
     parser = argparse.ArgumentParser(description=quickstart.__doc__)
+    # XXX 2013-10-18 frankban:
+        # Make it possible to pass a URL as bundle argument.
+    parser.add_argument(
+        'bundle', default=None, nargs='?',
+        help='The path to the bundle file to deploy')
     parser.add_argument(
         '-e', '--environment', default=default_env_name, dest='env_name',
         help=env_help)
     parser.add_argument(
+        '-n', '--bundle-name', default=None, dest='bundle_name',
+        help='The name of the bundle to use. This must be included in the '
+             'provided bundle file. Specifying the bundle name is not '
+             'required if the bundle file only contains one bundle. This '
+             'option is ignored if the bundle file is not specified')
+    parser.add_argument(
         '--environments-file',
         default=os.path.join(juju_home, 'environments.yaml'), dest='env_file',
-        help='the path to the Juju environments YAML file (%(default)s)')
+        help='The path to the Juju environments YAML file (%(default)s)')
     parser.add_argument(
         '--version', action='version', version='%(prog)s {}'.format(version))
     parser.add_argument(
-        '--debug', action='store_true', help='turn debug mode on')
+        '--debug', action='store_true', help='Turn debug mode on')
     # This is required by juju-core: see "juju help plugins".
     parser.add_argument(
         '--description', action=_DescriptionAction, default=argparse.SUPPRESS,
-        nargs=0, help="show program's description and exit")
+        nargs=0, help="Show program's description and exit")
     # Parse the provided arguments.
     options = parser.parse_args()
     # Validate and process the provided arguments.
     _validate_env(options, parser)
+    if options.bundle is not None:
+        _validate_bundle(options, parser)
     # Set up logging.
     _configure_logging(logging.DEBUG if options.debug else logging.INFO)
     return options
@@ -148,6 +193,19 @@
     address = app.watch(env, 'juju-gui')
     url = 'https://{}'.format(address)
     print('url: {}\npassword: {}'.format(url, options.admin_secret))
+
+    # Handle bundle deployment.
+    if options.bundle is not None:
+        print('deploying the bundle {} with the following services: {}'.format(
+            options.bundle_name, ', '.join(options.bundle_services)))
+        # We need to connect to an API WebSocket server supporting bundle
+        # deployments. The GUI builtin server, listening on the Juju GUI
+        # address, exposes an API suitable for deploying bundles.
+        gui_api_url = 'wss://{}:443/ws'.format(address)
+        app.deploy_bundle(
+            gui_api_url, options.admin_secret,
+            options.bundle_yaml, options.bundle_name)
+
     # XXX 2013-10-18 frankban:
         # Add a command line option to decline opening the browser.
     webbrowser.open(url)

=== modified file 'quickstart/tests/helpers.py'
--- quickstart/tests/helpers.py	2013-10-17 16:51:55 +0000
+++ quickstart/tests/helpers.py	2013-10-22 22:03:55 +0000
@@ -51,6 +51,32 @@
         return mock.patch('quickstart.utils.call', mock_call)
 
 
+class BundleFileTestsMixin(object):
+    """Shared methods for testing Juju bundle files."""
+
+    valid_bundle = yaml.safe_dump({
+        'bundle1': {'services': {'wordpress': {}, 'mysql': {}}},
+        'bundle2': {'services': {'django': {}, 'nodejs': {}}},
+    })
+
+    def make_bundle_file(self, contents=None):
+        """Create a Juju bundle file containing the given contents.
+
+        If contents is None, use the valid bundle contents defined in
+        self.valid_bundle.
+        Return the bundle file path.
+        """
+        if contents is None:
+            contents = self.valid_bundle
+        elif isinstance(contents, dict):
+            contents = yaml.safe_dump(contents)
+        bundle_file = tempfile.NamedTemporaryFile(delete=False)
+        self.addCleanup(os.remove, bundle_file.name)
+        bundle_file.write(contents)
+        bundle_file.close()
+        return bundle_file.name
+
+
 class EnvFileTestsMixin(object):
     """Shared methods for testing a Juju environments file."""
 

=== modified file 'quickstart/tests/test_app.py'
--- quickstart/tests/test_app.py	2013-10-18 14:07:28 +0000
+++ quickstart/tests/test_app.py	2013-10-22 22:03:55 +0000
@@ -431,3 +431,40 @@
         with self.assert_program_exit(expected):
             app.watch(env, 'django')
         mock_print.assert_has_calls([self.pending_call])
+
+
[e-mail]('quickstart.app.connect')
+class TestDeployBundle(ProgramExitTestsMixin, unittest.TestCase):
+
+    admin_secret = 'Secret!'
+    api_url = 'wss://juju-gui.example.com:443/ws'
+    name = 'mybundle'
+    yaml = 'mybundle: contents'
+
+    def test_bundle_deployment(self, mock_connect):
+        # A bundle is successfully deployed.
+        app.deploy_bundle(
+            self.api_url, self.admin_secret, self.yaml, self.name)
+        mock_connect.assert_called_once_with(self.api_url, self.admin_secret)
+        mock_connect().assert_has_calls([
+            mock.call.deploy_bundle(self.yaml, name=self.name),
+            mock.call.close(),
+        ])
+
+    def test_api_error(self, mock_connect):
+        # A ProgramExit is raised if an error occurs in one of the API calls.
+        mock_connect().deploy_bundle.side_effect = self.make_env_error(
+            'bundle deployment failure')
+        expected = 'bad API server response: bundle deployment failure'
+        with self.assert_program_exit(expected):
+            app.deploy_bundle(
+                self.api_url, self.admin_secret, self.yaml, self.name)
+
+    def test_other_errors(self, mock_connect):
+        # Any other errors occurred during the process are not trapped.
+        error = ValueError('explode!')
+        mock_connect().deploy_bundle.side_effect = error
+        with self.assertRaises(ValueError) as context_manager:
+            app.deploy_bundle(
+                self.api_url, self.admin_secret, self.yaml, self.name)
+        self.assertIs(error, context_manager.exception)

=== modified file 'quickstart/tests/test_juju.py'
--- quickstart/tests/test_juju.py	2013-10-17 15:05:11 +0000
+++ quickstart/tests/test_juju.py	2013-10-22 22:03:55 +0000
@@ -115,6 +115,28 @@
         expected = self.make_deploy_request(ToMachineSpec='0')
         mock_rpc.assert_called_once_with(expected)
 
+    @mock.patch('quickstart.juju.Environment._rpc')
+    def test_deploy_bundle(self, mock_rpc):
+        # The deploy bundle call is properly generated.
+        self.env.deploy_bundle('name: contents')
+        expected = {
+            'Type': 'Deployer',
+            'Request': 'Import',
+            'Params': {'YAML': 'name: contents'},
+        }
+        mock_rpc.assert_called_once_with(expected)
+
+    @mock.patch('quickstart.juju.Environment._rpc')
+    def test_deploy_bundle_with_name(self, mock_rpc):
+        # The deploy bundle call is properly generated when passing a name.
+        self.env.deploy_bundle('name: contents', name='name')
+        expected = {
+            'Type': 'Deployer',
+            'Request': 'Import',
+            'Params': {'Name': 'name', 'YAML': 'name: contents'},
+        }
+        mock_rpc.assert_called_once_with(expected)
+
     @mock.patch('quickstart.juju.jujuclient.Watcher._rpc')
     def test_watch_changes(self, mock_rpc):
         # It is possible to watch for changes using a processor callable.

=== modified file 'quickstart/tests/test_manage.py'
--- quickstart/tests/test_manage.py	2013-10-16 15:23:08 +0000
+++ quickstart/tests/test_manage.py	2013-10-22 22:03:55 +0000
@@ -46,6 +46,60 @@
         mock_exit.assert_called_once_with(0)
 
 
+class TestValidateBundle(helpers.BundleFileTestsMixin, unittest.TestCase):
+
+    def setUp(self):
+        self.parser = mock.Mock()
+
+    def make_options(self, bundle, bundle_name=None):
+        """Return a mock options object which includes the passed arguments."""
+        return mock.Mock(bundle=bundle, bundle_name=bundle_name)
+
+    def test_resulting_options(self):
+        # The options object is correctly set up.
+        bundle_file = self.make_bundle_file()
+        options = self.make_options(bundle_file, bundle_name='bundle1')
+        manage._validate_bundle(options, self.parser)
+        self.assertEqual(bundle_file, options.bundle_file)
+        self.assertEqual('bundle1', options.bundle_name)
+        self.assertEqual(
+            ['mysql', 'wordpress'], sorted(options.bundle_services))
+        self.assertEqual(open(bundle_file).read(), options.bundle_yaml)
+
+    def test_expand_user(self):
+        # The ~ construct is correctly expanded in the validation process.
+        bundle_file = self.make_bundle_file()
+        # Split the full path of the bundle file, e.g. from a full
+        # "/tmp/bundle.file" path retrieve the base path "/tmp" and the file
+        # name "bundle.file". By doing that we can simulate that the user's
+        # home is "/tmp" and that the bundle file is "~/bundle.file".
+        base_path, filename = os.path.split(bundle_file)
+        path = '~/{}'.format(filename)
+        options = self.make_options(bundle=path, bundle_name='bundle2')
+        with mock.patch('os.environ', {'HOME': base_path}):
+            manage._validate_bundle(options, self.parser)
+        self.assertEqual(bundle_file, options.bundle_file)
+
+    def test_bundle_file_not_found(self):
+        # A parser error is invoked if the bundle file is not found.
+        options = self.make_options('/no/such/file.yaml')
+        manage._validate_bundle(options, self.parser)
+        expected = (
+            'unable to open bundle file: '
+            "[Errno 2] No such file or directory: '/no/such/file.yaml'"
+        )
+        self.parser.error.assert_called_once_with(expected)
+
+    def test_error_parsing_bundle_file(self):
+        # A parser error is invoked if an error occurs parsing the bundle file.
+        bundle_file = self.make_bundle_file()
+        options = self.make_options(bundle_file, bundle_name='no-such')
+        manage._validate_bundle(options, self.parser)
+        expected = ('bundle no-such not found in the provided list of bundles '
+                    '(bundle1, bundle2)')
+        self.parser.error.assert_called_once_with(expected)
+
+
 class TestValidateEnv(helpers.EnvFileTestsMixin, unittest.TestCase):
 
     def setUp(self):
@@ -147,7 +201,7 @@
         self.assertIn(quickstart.__doc__, output)
         self.assertIn('--environment', output)
         # Without a default environment, the -e option has no default.
-        self.assertIn('the name of the Juju environment to use\n', output)
+        self.assertIn('The name of the Juju environment to use\n', output)
 
     def test_help_with_default_environment(self):
         # The program help message is properly formatted when a default Juju
@@ -158,7 +212,7 @@
         self.assertTrue(stdout_write.called)
         # Retrieve the output from the mock call.
         output = stdout_write.call_args[0][0]
-        self.assertIn('the name of the Juju environment to use (hp)\n', output)
+        self.assertIn('The name of the Juju environment to use (hp)\n', output)
 
     def test_description(self):
         # The program description is properly printed out as required by juju.
@@ -173,6 +227,15 @@
         expected = 'juju-quickstart {}\n'.format(quickstart.get_version())
         mock_stderr.write.assert_called_once_with(expected)
 
+    @mock.patch('quickstart.manage._validate_bundle')
+    def test_bundle(self, mock_validate_bundle):
+        # The bundle validation process is started if a bundle is provided.
+        self.call_setup(['/path/to/bundle.file'], exit_called=False)
+        self.assertTrue(mock_validate_bundle.called)
+        options, parser = mock_validate_bundle.call_args_list[0][0]
+        self.assertIsInstance(options, argparse.Namespace)
+        self.assertIsInstance(parser, argparse.ArgumentParser)
+
     def test_configure_logging(self):
         # Logging is properly set up at the info level.
         logger = logging.getLogger()
@@ -184,3 +247,46 @@
         logger = logging.getLogger()
         self.call_setup(['--debug'], 'ec2', exit_called=False)
         self.assertEqual(logging.DEBUG, logger.level)
+
+
[e-mail]('webbrowser.open')
[e-mail]('quickstart.manage.app')
[e-mail]('__builtin__.print', mock.Mock())
+class TestRun(unittest.TestCase):
+
+    def make_options(self, **kwargs):
+        """Set up the options to be passed to the run function."""
+        options = {
+            'admin_secret': 'Secret!',
+            'bundle': None,
+            'env_name': 'aws',
+            'env_type': 'ec2',
+        }
+        options.update(kwargs)
+        return mock.Mock(**options)
+
+    def test_no_bundle(self, mock_app, mock_open):
+        # The application runs correctly if no bundle is provided.
+        options = self.make_options()
+        manage.run(options)
+        mock_app.bootstrap.assert_called_once_with(options.env_name)
+        mock_app.get_api_url.assert_called_once_with(options.env_name)
+        mock_app.connect.assert_called_once_with(
+            mock_app.get_api_url(), options.admin_secret)
+        mock_app.deploy_gui.assert_called_once_with(
+            mock_app.connect(), 'juju-gui')
+        mock_app.watch.assert_called_once_with(mock_app.connect(), 'juju-gui')
+        mock_open.assert_called_once_with(
+            'https://{}'.format(mock_app.watch()))
+        self.assertFalse(mock_app.deploy_bundle.called)
+
+    def test_bundle(self, mock_app, mock_open):
+        # A bundle is correctly deployed by the application.
+        options = self.make_options(
+            bundle='/my/bunlde/file.yaml', bundle_yaml='mybundle: contents',
+            bundle_name='mybundle', bundle_services=['service1', 'service2'])
+        mock_app.watch.return_value = 'gui.example.com'
+        manage.run(options)
+        mock_app.deploy_bundle.assert_called_once_with(
+            'wss://gui.example.com:443/ws', options.admin_secret,
+            'mybundle: contents', 'mybundle')

=== modified file 'quickstart/tests/test_utils.py'
--- quickstart/tests/test_utils.py	2013-10-17 19:56:17 +0000
+++ quickstart/tests/test_utils.py	2013-10-22 22:03:55 +0000
@@ -120,6 +120,94 @@
         mock_call.assert_called_once_with('juju', 'switch')
 
 
+class TestParseBundle(
+        helpers.BundleFileTestsMixin, helpers.ValueErrorTestsMixin,
+        unittest.TestCase):
+
+    def test_invalid_yaml(self):
+        # A ValueError is raised if the bundle contents are not a valid YAML.
+        with self.assertRaises(ValueError) as context_manager:
+            utils.parse_bundle(':')
+        expected = 'unable to parse the bundle'
+        self.assertIn(expected, str(context_manager.exception))
+
+    def test_yaml_invalid_type(self):
+        # A ValueError is raised if the bundle contents are not well formed.
+        with self.assert_value_error("invalid YAML contents: 'a-string'"):
+            utils.parse_bundle('a-string')
+
+    def test_yaml_invalid_bundle_data(self):
+        # A ValueError is raised if bundles are not well formed.
+        contents = yaml.safe_dump({'mybundle': 'not valid'})
+        expected = "invalid YAML contents: {'mybundle': 'not valid'}"
+        with self.assert_value_error(expected):
+            utils.parse_bundle(contents)
+
+    def test_yaml_no_service(self):
+        # A ValueError is raised if bundles do not include services.
+        contents = yaml.safe_dump({'mybundle': {}})
+        expected = "invalid YAML contents: {'mybundle': {}}"
+        with self.assert_value_error(expected):
+            utils.parse_bundle(contents)
+
+    def test_yaml_none_bundle_services(self):
+        # A ValueError is raised if services are None.
+        contents = yaml.safe_dump({'mybundle': {'services': None}})
+        expected = "invalid YAML contents: {'mybundle': {'services': None}}"
+        with self.assert_value_error(expected):
+            utils.parse_bundle(contents)
+
+    def test_yaml_invalid_bundle_services_type(self):
+        # A ValueError is raised if services have an invalid type.
+        contents = yaml.safe_dump({'mybundle': {'services': 42}})
+        expected = "invalid YAML contents: {'mybundle': {'services': 42}}"
+        with self.assert_value_error(expected):
+            utils.parse_bundle(contents)
+
+    def test_yaml_no_bundles(self):
+        # A ValueError is raised if the bundle contents are empty.
+        with self.assert_value_error('no bundles found'):
+            utils.parse_bundle(yaml.safe_dump({}))
+
+    def test_bundle_name_not_specified(self):
+        # A ValueError is raised if the bundle name is not specified and the
+        # contents contain more than one bundle.
+        expected = ('multiple bundles found (bundle1, bundle2) '
+                    'but no bundle name specified')
+        with self.assert_value_error(expected):
+            utils.parse_bundle(self.valid_bundle)
+
+    def test_bundle_name_not_found(self):
+        # A ValueError is raised if the given bundle is not found in the file.
+        expected = ('bundle no-such not found in the provided list of bundles '
+                    '(bundle1, bundle2)')
+        with self.assert_value_error(expected):
+            utils.parse_bundle(self.valid_bundle, 'no-such')
+
+    def test_no_services(self):
+        # A ValueError is raised if the specified bundle does not contain
+        # services.
+        contents = yaml.safe_dump({'mybundle': {'services': {}}})
+        expected = 'bundle mybundle does not include any services'
+        with self.assert_value_error(expected):
+            utils.parse_bundle(contents)
+
+    def test_success_no_name(self):
+        # The function succeeds when an implicit bundle name is used.
+        contents = yaml.safe_dump({
+            'mybundle': {'services': {'wordpress': {}, 'mysql': {}}},
+        })
+        name, services = utils.parse_bundle(contents)
+        self.assertEqual('mybundle', name)
+        self.assertEqual(['mysql', 'wordpress'], sorted(services))
+
+    def test_success_multiple_bundles(self):
+        # The function succeeds with multiple bundles.
+        name, services = utils.parse_bundle(self.valid_bundle, 'bundle2')
+        self.assertEqual('bundle2', name)
+        self.assertEqual(['django', 'nodejs'], sorted(services))
+
+
 class TestParseEnvFile(
         helpers.EnvFileTestsMixin, helpers.ValueErrorTestsMixin,
         unittest.TestCase):

=== modified file 'quickstart/utils.py'
--- quickstart/utils.py	2013-10-18 10:10:30 +0000
+++ quickstart/utils.py	2013-10-22 22:03:55 +0000
@@ -16,6 +16,7 @@
 
 """Juju Quickstart utility functions and classes."""
 
+import collections
 import re
 import os
 import logging
@@ -80,6 +81,59 @@
         return match.groups()[0]
 
 
+def parse_bundle(bundle_yaml, bundle_name=None):
+    """Parse the provided bundle YAML decoded contents.
+
+    Return a tuple containing the bundle name and the list of services included
+    in the bundle.
+
+    Raise a ValueError if:
+      - the bundle YAML contents are not parsable by YAML;
+      - the YAML contents are not properly structured;
+      - the bundle name is specified but not included in the bundle file;
+      - the bundle name is not specified and the bundle file includes more than
+        one bundle;
+      - the bundle does not include services.
+    """
+    # Parse the bundle file.
+    try:
+        bundles = yaml.safe_load(bundle_yaml)
+    except Exception as err:
+        msg = 'unable to parse the bundle: {}'.format(err)
+        raise ValueError(msg)
+    # Ensure the bundle file is well formed and contains at least one bundle.
+    if not isinstance(bundles, collections.Mapping):
+        raise ValueError('invalid YAML contents: {!r}'.format(bundles))
+    try:
+        name_services_map = dict(
+            (key, value['services'].keys())
+            for key, value in bundles.items()
+        )
+    except (AttributeError, KeyError, TypeError):
+        raise ValueError('invalid YAML contents: {!r}'.format(bundles))
+    if not name_services_map:
+        raise ValueError('no bundles found')
+    # Retrieve the bundle name and services.
+    if bundle_name is None:
+        if len(name_services_map) > 1:
+            msg = 'multiple bundles found ({}) but no bundle name specified'
+            bundle_names = ', '.join(sorted(name_services_map.keys()))
+            raise ValueError(msg.format(bundle_names))
+        bundle_name, bundle_services = name_services_map.items()[0]
+    else:
+        bundle_services = name_services_map.get(bundle_name)
+        if bundle_services is None:
+            msg = 'bundle {} not found in the provided list of bundles ({})'
+            bundle_names = ', '.join(sorted(name_services_map.keys()))
+            raise ValueError(msg.format(bundle_name, bundle_names))
+    if not bundle_services:
+        msg = 'bundle {} does not include any services'.format(bundle_name)
+        raise ValueError(msg)
+    # XXX 2013-10-21 frankban:
+        # Handle the case when the GUI is included in the bundle.
+    return bundle_name, bundle_services
+
+
 def parse_env_file(env_file, env_name):
     """Parse the provided Juju environments.yaml file.