Merge lp:~frankban/juju-gui/quickstart-real-bootstrap into lp:juju-gui/juju-quickstart

[Francesco Banconi]

Bootstrap the Juju environment.

Wait until the API server is ready.
Retrieve the API address.

Also added --debug support (logging).

Tests: `make check`.

QA: assuming you have a local provider env
named 'local' and an ec2 one named 'ec2'

- run `.venv/bin/python juju-quickstart -e local`
  -> error: the local provider is not currently supported;
- run `.venv/bin/python juju-quickstart -e no-such-env`
  -> error: environment no-such-env not found in ...;
- run `juju switch ec2`;
- run `.venv/bin/python juju-quickstart --debug`
  -> the debug messages are shown, the env is bootstrapped,
     the API URL is printed at the end of the process.
- run `.venv/bin/python juju-quickstart`
  -? like above but this time no debug messages are shown.

https://codereview.appspot.com/14441074/

[Francesco Banconi (frankban)]

Reviewers: mp+191410_code.launchpad.net,

Message:
Please take a look.

Description:
Bootstrap the Juju environment.

Wait until the API server is ready.
Retrieve the API address.

Also added --debug support (logging).

Tests: `make check`.

QA: assuming you have a local provider env
named 'local' and an ec2 one named 'ec2'

- run `.venv/bin/python juju-quickstart -e local`
   -> error: the local provider is not currently supported;
- run `.venv/bin/python juju-quickstart -e no-such-env`
   -> error: environment no-such-env not found in ...;
- run `juju switch ec2`;
- run `.venv/bin/python juju-quickstart --debug`
   -> the debug messages are shown, the env is bootstrapped,
      the API URL is printed at the end of the process.
- run `.venv/bin/python juju-quickstart`
   -? like above but this time no debug messages are shown.

https://code.launchpad.net/~frankban/juju-gui/quickstart-real-bootstrap/+merge/191410

(do not edit description out of merge proposal)

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

Affected files (+371, -33 lines):
   A [revision details]
   M quickstart/app.py
   M quickstart/manage.py
   M quickstart/tests/helpers.py
   M quickstart/tests/test_app.py
   M quickstart/tests/test_manage.py
   M quickstart/tests/test_utils.py
   M quickstart/utils.py

[Brad Crittenden (bac)]

LGTM Francesco. I have not yet done QA but can if needed.

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

https://codereview.appspot.com/14441074/diff/1/quickstart/manage.py#newcode78
quickstart/manage.py:78: if root.handlers:
A comment here explaining what you're doing would be welcome.

https://codereview.appspot.com/14441074/

[lp:~frankban/juju-gui/quickstart-real-bootstrap]

15. By Francesco Banconi on 2013-10-16

Changes as per review.

[Francesco Banconi (frankban)]

Please take a look.

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

https://codereview.appspot.com/14441074/diff/1/quickstart/manage.py#newcode78
quickstart/manage.py:78: if root.handlers:
On 2013/10/16 14:51:20, bac wrote:
> A comment here explaining what you're doing would be welcome.

Done.

https://codereview.appspot.com/14441074/

[Gary Poster (gary)]

LGTM with an extremely small suggestion that you are welcome to ignore.
It is interesting and convenient that so many of the commands have
(seemingly) reliably parsable output. The branch has nice and
interesting tests. Thank you!

https://codereview.appspot.com/14441074/diff/5001/quickstart/app.py
File quickstart/app.py (right):

https://codereview.appspot.com/14441074/diff/5001/quickstart/app.py#newcode49
quickstart/app.py:49: retcode, output, error = utils.call('juju',
'status', '-e', env_name)
I'm OK with this for expediency, but wouldn't the API (Kapil's library)
be better in a revision?

[later] Oh, it's YAML, yeah? I guess that's OK. I think it would be
nice to add a comment to that effect, but others might disagree. Just a
suggestion.

https://codereview.appspot.com/14441074/diff/5001/quickstart/app.py#newcode70
quickstart/app.py:70: 'juju', 'api-endpoints', '-e', env_name,
'--format', 'json')
yay, --format json

https://codereview.appspot.com/14441074/diff/5001/quickstart/utils.py
File quickstart/utils.py (right):

https://codereview.appspot.com/14441074/diff/5001/quickstart/utils.py#newcode69
quickstart/utils.py:69: # Switch to using "juju switch --raw" in order
to avoid the fragility
oh, cool.

https://codereview.appspot.com/14441074/

[Brad Crittenden (bac)]

QA-OK

https://codereview.appspot.com/14441074/

[Francesco Banconi (frankban)]

*** Submitted:

Bootstrap the Juju environment.

Wait until the API server is ready.
Retrieve the API address.

Also added --debug support (logging).

Tests: `make check`.

QA: assuming you have a local provider env
named 'local' and an ec2 one named 'ec2'

- run `.venv/bin/python juju-quickstart -e local`
   -> error: the local provider is not currently supported;
- run `.venv/bin/python juju-quickstart -e no-such-env`
   -> error: environment no-such-env not found in ...;
- run `juju switch ec2`;
- run `.venv/bin/python juju-quickstart --debug`
   -> the debug messages are shown, the env is bootstrapped,
      the API URL is printed at the end of the process.
- run `.venv/bin/python juju-quickstart`
   -? like above but this time no debug messages are shown.

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

https://codereview.appspot.com/14441074/diff/5001/quickstart/app.py
File quickstart/app.py (right):

https://codereview.appspot.com/14441074/diff/5001/quickstart/app.py#newcode49
quickstart/app.py:49: retcode, output, error = utils.call('juju',
'status', '-e', env_name)
On 2013/10/16 15:43:40, gary.poster wrote:
> I'm OK with this for expediency, but wouldn't the API (Kapil's
library) be
> better in a revision?

> [later] Oh, it's YAML, yeah? I guess that's OK. I think it would be
nice to
> add a comment to that effect, but others might disagree. Just a
suggestion.

Good suggestion. As discussed, I will explicitly add "--format yaml"
here.

https://codereview.appspot.com/14441074/

[Francesco Banconi (frankban)]

Thank you both!

https://codereview.appspot.com/14441074/

=== modified file 'quickstart/app.py'
--- quickstart/app.py	2013-10-15 15:31:12 +0000
+++ quickstart/app.py	2013-10-16 15:23:20 +0000
@@ -16,6 +16,10 @@
 
 """Juju Quickstart base application functions."""
 
+import json
+
+from quickstart import utils
+
 
 class ProgramExit(Exception):
     """An error occurred while setting up the Juju environment.
@@ -34,9 +38,39 @@
 def bootstrap(env_name):
     """Bootstrap the Juju environment with the given name.
 
-    Return the environment API address (e.g. "api.example.com:17070").
+    Return when the bootstrap node is ready.
     Raise a ProgramExit if any error occurs in the bootstrap process.
-    Otherwise return when the environment is bootstrapped and the API server
-    is ready to accept connections.
-    """
-    # TODO: everything!
+    """
+    retcode, _, error = utils.call('juju', 'bootstrap', '-e', env_name)
+    if retcode:
+        raise ProgramExit(error)
+    # Call "juju status" multiple times until the bootstrap node is ready.
+    for _ in range(5):
+        retcode, output, error = utils.call('juju', 'status', '-e', env_name)
+        if retcode:
+            continue
+        # Ensure the state server is up and the agent is started.
+        try:
+            agent_state = utils.parse_status_output(output)
+        except ValueError:
+            continue
+        if agent_state == 'started':
+            return
+    details = ''.join(filter(None, [output, error])).strip()
+    raise ProgramExit('the state server is not ready:\n{}'.format(details))
+
+
+def get_api_url(env_name):
+    """Return a Juju API URL for the given environment name.
+
+    Use the Juju CLI in a subprocess in order to retrieve the API addresses.
+    Return the complete URL, e.g. "wss://api.example.com:17070".
+    """
+    retcode, output, error = utils.call(
+        'juju', 'api-endpoints', '-e', env_name, '--format', 'json')
+    if retcode:
+        raise ProgramExit(error)
+    # Assuming there is always at least one API address, grab the first one
+    # from the JSON output.
+    api_address = json.loads(output)[0]
+    return 'wss://{}'.format(api_address)

=== modified file 'quickstart/manage.py'
--- quickstart/manage.py	2013-10-15 15:40:31 +0000
+++ quickstart/manage.py	2013-10-16 15:23:20 +0000
@@ -18,6 +18,7 @@
 
 from __future__ import print_function
 import argparse
+import logging
 import os
 
 import quickstart
@@ -54,7 +55,8 @@
             'It is possible to specify the environment name by either:\n'
             '  - passing the -e or --environment argument;\n'
             '  - setting the JUJU_ENV environment variable;\n'
-            '  - using "juju switch" to select the default environment to use.'
+            '  - using "juju switch" to select the default environment;\n'
+            '  - setting the default environment in {}.'.format(env_file)
         )
     # Validate the environment file.
     try:
@@ -70,8 +72,25 @@
     options.env_type = env_type
 
 
+def _configure_logging(level):
+    """Set up the application logging."""
+    root = logging.getLogger()
+    # Remove any previous handler on the root logger.
+    for handler in root.handlers[:]:
+        root.removeHandler(handler)
+    logging.basicConfig(
+        level=level,
+        format=(
+            '%(asctime)s %(levelname)s '
+            '%(module)s@%(funcName)s:%(lineno)d '
+            '%(message)s'
+        ),
+        datefmt='%H:%M:%S',
+    )
+
+
 def setup():
-    """Set up the application options.
+    """Set up the application options and logger.
 
     Return the options as a namespace containing the followin attributes:
         - admin_secret: the password to use to access the Juju API;
@@ -97,6 +116,8 @@
         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')
     # This is required by juju-core: see "juju help plugins".
     parser.add_argument(
         '--description', action=_DescriptionAction, default=argparse.SUPPRESS,
@@ -105,6 +126,8 @@
     options = parser.parse_args()
     # Validate and process the provided arguments.
     _validate_env(options, parser)
+    # Set up logging.
+    _configure_logging(logging.DEBUG if options.debug else logging.INFO)
     return options
 
 
@@ -114,3 +137,6 @@
     print('bootstrapping the {} environment (type: {})'.format(
         options.env_name, options.env_type))
     app.bootstrap(options.env_name)
+    print('retrieving the Juju API address')
+    api_url = app.get_api_url(options.env_name)
+    print('connecting to {}'.format(api_url))

=== modified file 'quickstart/tests/helpers.py'
--- quickstart/tests/helpers.py	2013-10-15 18:25:57 +0000
+++ quickstart/tests/helpers.py	2013-10-16 15:23:20 +0000
@@ -20,21 +20,35 @@
 import os
 import tempfile
 
+import mock
 import yaml
 
 
-class ValueErrorTestsMixin(object):
-    """Set up some base methods for testing functions raising ValueErrors."""
-
-    @contextmanager
-    def assert_value_error(self, error):
-        """Ensure a ValueError is raised in the context block.
-
-        Also check that the exception includes the expected error message.
-        """
-        with self.assertRaises(ValueError) as context_manager:
-            yield
-        self.assertEqual(error, str(context_manager.exception))
+class CallTestsMixin(object):
+    """Easily use the quickstart.utils.call function."""
+
+    def patch_call(self, retcode, output='', error=''):
+        """Patch the quickstart.utils.call function."""
+        mock_call = mock.Mock(return_value=(retcode, output, error))
+        return mock.patch('quickstart.utils.call', mock_call)
+
+    def patch_multiple_calls(self, side_effect):
+        """Patch multiple subsequent quickstart.utils.call calls."""
+        mock_call = mock.Mock(side_effect=side_effect)
+        return mock.patch('quickstart.utils.call', mock_call)
+
+
+@contextmanager
+def assert_logs(messages, level='debug'):
+    """Ensure the given messages are logged using the given log level.
+
+    Use this function as a context manager: the code executed in the context
+    block must add the expected log entries.
+    """
+    with mock.patch('logging.{}'.format(level.lower())) as mock_log:
+        yield
+    expected_calls = [mock.call(message) for message in messages]
+    mock_log.assert_has_calls(expected_calls)
 
 
 class EnvFileTestsMixin(object):
@@ -58,3 +72,17 @@
         env_file.write(contents)
         env_file.close()
         return env_file.name
+
+
+class ValueErrorTestsMixin(object):
+    """Set up some base methods for testing functions raising ValueErrors."""
+
+    @contextmanager
+    def assert_value_error(self, error):
+        """Ensure a ValueError is raised in the context block.
+
+        Also check that the exception includes the expected error message.
+        """
+        with self.assertRaises(ValueError) as context_manager:
+            yield
+        self.assertEqual(error, str(context_manager.exception))

=== modified file 'quickstart/tests/test_app.py'
--- quickstart/tests/test_app.py	2013-10-15 15:31:32 +0000
+++ quickstart/tests/test_app.py	2013-10-16 15:23:20 +0000
@@ -16,9 +16,15 @@
 
 """Tests for the Juju Quickstart base application functions."""
 
+from contextlib import contextmanager
+import json
 import unittest
 
+import mock
+import yaml
+
 from quickstart import app
+from quickstart.tests import helpers
 
 
 class TestProgramExit(unittest.TestCase):
@@ -27,3 +33,152 @@
         # The error is properly represented as a string.
         exception = app.ProgramExit('bad wolf')
         self.assertEqual('juju-quickstart: error: bad wolf', str(exception))
+
+
+class ProgramExitTestsMixin(object):
+    """Set up some base methods for testing functions raising ProgramExit."""
+
+    @contextmanager
+    def assert_program_exit(self, error):
+        """Ensure a ProgramExit is raised in the context block.
+
+        Also check that the exception includes the expected error message.
+        """
+        with self.assertRaises(app.ProgramExit) as context_manager:
+            yield
+        expected = 'juju-quickstart: error: {}'.format(error)
+        self.assertEqual(expected, str(context_manager.exception))
+
+
+class TestBootstrap(
+        helpers.CallTestsMixin, ProgramExitTestsMixin, unittest.TestCase):
+
+    env_name = 'ec2'
+
+    def make_status_output(self, agent_state):
+        """Create and return a YAML status output."""
+        return yaml.safe_dump({
+            'machines': {'0': {'agent-state': agent_state}},
+        })
+
+    def make_status_calls(self, number):
+        """Return a list containing the given number of status calls."""
+        return [
+            mock.call('juju', 'status', '-e', self.env_name)
+            for _ in range(number)
+        ]
+
+    def assert_status_retried(self, side_effects):
+        """Ensure the "juju status" command is retried several times.
+
+        Receive the list of side effects the mock status call will return.
+        """
+        with self.patch_multiple_calls(side_effects) as mock_call:
+            app.bootstrap(self.env_name)
+        mock_call.assert_has_calls([
+            mock.call('juju', 'bootstrap', '-e', self.env_name),
+        ] + self.make_status_calls(5))
+
+    def test_success(self):
+        # The environment is successfully bootstrapped.
+        side_effects = [
+            (0, '', ''),  # Add a bootstrap call.
+            (0, self.make_status_output('started'), ''),  # Add a status call.
+        ]
+        with self.patch_multiple_calls(side_effects) as mock_call:
+            app.bootstrap(self.env_name)
+        mock_call.assert_has_calls([
+            mock.call('juju', 'bootstrap', '-e', self.env_name),
+        ] + self.make_status_calls(1))
+
+    def test_bootstrap_failure(self):
+        # A ProgramExit is raised if an error occurs while bootstrapping.
+        with self.patch_call(1, error='bad wolf') as mock_call:
+            with self.assert_program_exit('bad wolf'):
+                app.bootstrap(self.env_name)
+        mock_call.assert_called_once_with(
+            'juju', 'bootstrap', '-e', self.env_name)
+
+    def test_status_retry_error(self):
+        # Before raising a ProgramExit, the functions tries to call
+        # "juju status" multiple times if it exits with an error.
+        side_effects = [
+            (0, '', ''),  # Add the bootstrap call.
+            # Add four status calls with a non-zero exit code.
+            (1, '', 'these'),
+            (2, '', 'are'),
+            (3, '', 'the'),
+            (4, '', 'voyages'),
+            # Add a final valid status call.
+            (0, self.make_status_output('started'), ''),
+        ]
+        self.assert_status_retried(side_effects)
+
+    def test_status_retry_invalid_output(self):
+        # Before raising a ProgramExit, the functions tries to call
+        # "juju status" multiple times if its output is not well formed or if
+        # the agent is not started.
+        side_effects = [
+            (0, '', ''),  # Add the bootstrap call.
+            (0, '', ''),  # Add the first status call: no output.
+            (0, ':', ''),  # Add the second status call: not YAML.
+            (0, 'just-a-string', ''),  # Add the third status call: bad YAML.
+            # Add the fourth status call: the agent is still pending.
+            (0, self.make_status_output('pending'), ''),
+            # Add a final valid status call.
+            (0, self.make_status_output('started'), ''),
+        ]
+        self.assert_status_retried(side_effects)
+
+    def test_status_retry_both(self):
+        # Before raising a ProgramExit, the functions tries to call
+        # "juju status" multiple times in any case.
+        side_effects = [
+            (0, '', ''),  # Add the bootstrap call.
+            (1, '', 'error'),  # Add the first status call: error.
+            (2, '', 'another error'),  # Add the second status call: error.
+            # Add the third status call: the agent is still pending.
+            (0, self.make_status_output('pending'), ''),
+            (0, 'just-a-string', ''),  # Add the fourth status call: bad YAML.
+            # Add a final valid status call.
+            (0, self.make_status_output('started'), ''),
+        ]
+        self.assert_status_retried(side_effects)
+
+    def test_status_failure(self):
+        # A ProgramExit is raised if "juju status" keeps failing.
+        status_side_effects = [
+            (i, 'output #{}\n'.format(i), 'error #{}\n'.format(i))
+            for i in range(5)
+        ]
+        side_effects = [(0, '', '')] + status_side_effects
+        expected = 'the state server is not ready:\noutput #4\nerror #4'
+        with self.patch_multiple_calls(side_effects) as mock_call:
+            with self.assert_program_exit(expected):
+                app.bootstrap(self.env_name)
+        mock_call.assert_has_calls([
+            mock.call('juju', 'bootstrap', '-e', self.env_name),
+        ] + self.make_status_calls(5))
+
+
+class TestGetApiUrl(
+        helpers.CallTestsMixin, ProgramExitTestsMixin, unittest.TestCase):
+
+    env_name = 'ec2'
+
+    def test_success(self):
+        # The API URL is correctly returned.
+        api_addresses = json.dumps(['api.example.com:17070', 'not-today'])
+        with self.patch_call(0, output=api_addresses) as mock_call:
+            api_url = app.get_api_url(self.env_name)
+        self.assertEqual('wss://api.example.com:17070', api_url)
+        mock_call.assert_called_once_with(
+            'juju', 'api-endpoints', '-e', self.env_name, '--format', 'json')
+
+    def test_failure(self):
+        # A ProgramExit is raised if an error occurs retrieving the API URL.
+        with self.patch_call(1, error='bad wolf') as mock_call:
+            with self.assert_program_exit('bad wolf'):
+                app.get_api_url(self.env_name)
+        mock_call.assert_called_once_with(
+            'juju', 'api-endpoints', '-e', self.env_name, '--format', 'json')

=== modified file 'quickstart/tests/test_manage.py'
--- quickstart/tests/test_manage.py	2013-10-15 18:25:57 +0000
+++ quickstart/tests/test_manage.py	2013-10-16 15:23:20 +0000
@@ -17,6 +17,7 @@
 """Tests for the Juju Quickstart management infrastructure."""
 
 import argparse
+import logging
 import os
 import unittest
 
@@ -122,16 +123,17 @@
         path = 'quickstart.manage.utils.get_default_env_name'
         return mock.patch(path, mock_get_default_env_name)
 
-    def call_setup(self, args, env_name=None):
+    def call_setup(self, args, env_name=None, exit_called=True):
         """Call the setup function simulating the given args and env name.
 
-        Also ensure the program exits without errors.
+        Also ensure the program exits without errors if exit_called is True.
         """
         with mock.patch('sys.argv', ['juju-quickstart'] + args):
             with mock.patch('sys.exit') as mock_exit:
                 with self.patch_get_default_env_name(env_name):
                     manage.setup()
-        mock_exit.assert_called_once_with(0)
+        if exit_called:
+            mock_exit.assert_called_once_with(0)
 
     def test_help(self):
         # The program help message is properly formatted.
@@ -170,3 +172,15 @@
             self.call_setup(['--version'])
         expected = 'juju-quickstart {}\n'.format(quickstart.get_version())
         mock_stderr.write.assert_called_once_with(expected)
+
+    def test_configure_logging(self):
+        # Logging is properly set up at the info level.
+        logger = logging.getLogger()
+        self.call_setup([], 'ec2', exit_called=False)
+        self.assertEqual(logging.INFO, logger.level)
+
+    def test_configure_logging_debug(self):
+        # Logging is properly set up at the debug level.
+        logger = logging.getLogger()
+        self.call_setup(['--debug'], 'ec2', exit_called=False)
+        self.assertEqual(logging.DEBUG, logger.level)

=== modified file 'quickstart/tests/test_utils.py'
--- quickstart/tests/test_utils.py	2013-10-15 18:25:57 +0000
+++ quickstart/tests/test_utils.py	2013-10-16 15:23:20 +0000
@@ -61,13 +61,17 @@
             'no-such-command: [Errno 2] No such file or directory',
             error)
 
-
-class TestGetDefaultEnvName(unittest.TestCase):
-
-    def patch_call(self, retcode, output='', error=''):
-        """Patch the quickstart.utils.call function."""
-        mock_call = mock.Mock(return_value=(retcode, output, error))
-        return mock.patch('quickstart.utils.call', mock_call)
+    def test_logging(self):
+        # The command line call and the results are properly logged.
+        expected_messages = (
+            "running the following: echo 'we are the borg!'",
+            r"retcode: 0 | output: 'we are the borg!\n' | error: ''",
+        )
+        with helpers.assert_logs(expected_messages):
+            utils.call('echo', 'we are the borg!')
+
+
+class TestGetDefaultEnvName(helpers.CallTestsMixin, unittest.TestCase):
 
     def test_environment_variable(self):
         # The environment name is successfully returned if JUJU_ENV is set.
@@ -176,3 +180,39 @@
         env_type, admin_secret = utils.parse_env_file(env_file, 'aws')
         self.assertEqual('ec2', env_type)
         self.assertEqual('Secret!', admin_secret)
+
+
+class TestParseStatusOutput(helpers.ValueErrorTestsMixin, unittest.TestCase):
+
+    def test_invalid_yaml(self):
+        # A ValueError is raised if the output is not a valid YAML.
+        with self.assertRaises(ValueError) as context_manager:
+            utils.parse_status_output(':')
+        expected = 'unable to parse the output'
+        self.assertIn(expected, str(context_manager.exception))
+
+    def test_invalid_yaml_contents(self):
+        # A ValueError is raised if the output is not well formed.
+        with self.assert_value_error('invalid YAML contents: a-string'):
+            utils.parse_status_output('a-string')
+
+    def test_no_env(self):
+        # A ValueError is raised if the agent-state is not found in the YAML.
+        data = {
+            'machines': {
+                '0': {'agent-version': '1.17.0.1'},
+            },
+        }
+        expected = 'agent state not found in {}'.format(str(data))
+        with self.assert_value_error(expected):
+            utils.parse_status_output(yaml.safe_dump(data))
+
+    def test_success(self):
+        # The agent state is correctly returned.
+        output = yaml.safe_dump({
+            'machines': {
+                '0': {'agent-version': '1.17.0.1', 'agent-state': 'started'},
+            },
+        })
+        agent_state = utils.parse_status_output(output)
+        self.assertEqual('started', agent_state)

=== modified file 'quickstart/utils.py'
--- quickstart/utils.py	2013-10-15 15:47:31 +0000
+++ quickstart/utils.py	2013-10-16 15:23:20 +0000
@@ -18,6 +18,8 @@
 
 import re
 import os
+import logging
+import pipes
 import subprocess
 
 import yaml
@@ -34,6 +36,8 @@
     Return a tuple containing the subprocess return code, output and error.
     """
     pipe = subprocess.PIPE
+    cmdline = ' '.join(map(pipes.quote, args))
+    logging.debug('running the following: {}'.format(cmdline))
     try:
         process = subprocess.Popen(args, stdout=pipe, stderr=pipe)
     except OSError as err:
@@ -41,20 +45,32 @@
         # found in the PATH.
         return 127, '', '{}: {}'.format(args[0], err)
     output, error = process.communicate()
-    return process.poll(), output, error
+    retcode = process.poll()
+    logging.debug('retcode: {} | output: {!r} | error: {!r}'.format(
+        retcode, output, error))
+    return retcode, output, error
 
 
 def get_default_env_name():
     """Return the current Juju environment name.
 
-    The environment name can be set either by setting the JUJU_ENV environment
-    variable or by using "juju switch". The former overrides the latter.
+    The environment name can be set either by
+        - setting the JUJU_ENV environment variable;
+        - using "juju switch my-env-name";
+        - setting the default environment in the environments.yaml file.
+    The former overrides the latter.
 
     Return None if a default environment is not found.
     """
     env_name = os.getenv('JUJU_ENV', '').strip()
     if env_name:
         return env_name
+    # XXX 2013-10-16 frankban bug=1193244:
+        # Switch to using "juju switch --raw" in order to avoid the fragility
+        # of parsing the command output.
+    # The "juju switch" command parses ~/.juju/current-environment file. If the
+    # environment name is not found there, then it tries to retrieve the name
+    # from the "default" section of the ~/.juju/environments.yaml file.
     retcode, output, _ = call('juju', 'switch')
     if retcode:
         return None
@@ -64,7 +80,7 @@
 
 
 def parse_env_file(env_file, env_name):
-    """Parse the provided Juju environment.yaml file.
+    """Parse the provided Juju environments.yaml file.
 
     Return a tuple containing the provider type and the admin secret associated
     with the given environment name.
@@ -108,3 +124,22 @@
         msg = '{} admin secret not found in {}'.format(env_name, env_file)
         raise ValueError(msg)
     return env_type, admin_secret
+
+
+def parse_status_output(output):
+    """Parse the output of juju status.
+
+    Return the agent state.
+    Raise a ValueError if the agent state cannot be retrieved.
+    """
+    try:
+        status = yaml.safe_load(output)
+    except Exception as err:
+        raise ValueError('unable to parse the output: {}'.format(err))
+    try:
+        state = status.get('machines', {}).get('0', {}).get('agent-state')
+    except AttributeError as err:
+        raise ValueError('invalid YAML contents: {}'.format(status))
+    if state is None:
+        raise ValueError('agent state not found in {}'.format(status))
+    return state