Merge lp:~frankban/juju-quickstart/jujucharms-bundles into lp:juju-quickstart

[Francesco Banconi]

Support retrieving bundles from charm store v4.

This branch implements the ability to deploy
bundles from the new charm store, retrieving
them with the v4 API.

Also introduce the new preferred bundle id
spelling, i.e. reflecting jujucharms.com paths,
like "mediawiki-single" or "u/who/bundle-name".

The old "bundle:basket/name" identifiers are
still supported but deprecated.
Deploying a bundle by specifying a directory
containing the YAML file is instead not
supported anymore.

Ok, after this brief summary let me take two
lines to really apologize for the huge diff.
While I was there, I refactored some historical
inconsistencies (e.g. models.Charm really being
just a charm or bundle reference), and I also
improved the bundle model API so that the work
is done in the model and not in manage as before.
There are a lot of tests too, and some documentation.
Nonetheless, let me say sorry again, this is
really too much stuff.

With this branch Juju Quickstart is quite ready for
the v4 world. The "deploy bundle" API call to the GUI
server still uses the legacy format, but the ugliness
of being backward compatible with namespaced bundles
is very restrained and implemented in private logic
in the bundles model module.

Tests: `make check`.

QA: run `devenv/bin/juju-quickstart` to deploy
new style and old style bundles, with both version
3 and 4 formats. Note that version 3 can only be
provided with arbitrary URLs or local files.

Thanks a lot!

https://codereview.appspot.com/207040043/

[Francesco Banconi (frankban)]

Reviewers: mp+251156_code.launchpad.net,

Message:
Please take a look.

Description:
Support retrieving bundles from charm store v4.

This branch implements the ability to deploy
bundles from the new charm store, retrieving
them with the v4 API.

Also introduce the new preferred bundle id
spelling, i.e. reflecting jujucharms.com paths,
like "mediawiki-single" or "u/who/bundle-name".

The old "bundle:basket/name" identifiers are
still supported but deprecated.
Deploying a bundle by specifying a directory
containing the YAML file is instead not
supported anymore.

Ok, after this brief summary let me take two
lines to really apologize for the huge diff.
While I was there, I refactored some historical
inconsistencies (e.g. models.Charm really being
just a charm or bundle reference), and I also
improved the bundle model API so that the work
is done in the model and not in manage as before.
There are a lot of tests too, and some documentation.
Nonetheless, let me say sorry again, this is
really too much stuff.

With this branch Juju Quickstart is quite ready for
the v4 world. The "deploy bundle" API call to the GUI
server still uses the legacy format, but the ugliness
of being backward compatible with namespaced bundles
is very restrained and implemented in private logic
in the bundles model module.

Tests: `make check`.

QA: run `devenv/bin/juju-quickstart` to deploy
new style and old style bundles, with both version
3 and 4 formats. Note that version 3 can only be
provided with arbitrary URLs or local files.

Thanks a lot!

https://code.launchpad.net/~frankban/juju-quickstart/jujucharms-bundles/+merge/251156

(do not edit description out of merge proposal)

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

Affected files (+1520, -939 lines):
   M HACKING.rst
   A [revision details]
   M quickstart/__init__.py
   M quickstart/app.py
   M quickstart/juju.py
   M quickstart/jujutools.py
   M quickstart/manage.py
   M quickstart/models/bundles.py
   M quickstart/models/references.py
   M quickstart/netutils.py
   M quickstart/settings.py
   M quickstart/tests/functional/test_functional.py
   M quickstart/tests/helpers.py
   M quickstart/tests/models/test_bundles.py
   M quickstart/tests/models/test_references.py
   M quickstart/tests/test_app.py
   M quickstart/tests/test_juju.py
   M quickstart/tests/test_jujutools.py
   M quickstart/tests/test_manage.py

[Richard Harding (rharding)]

Thanks for this branch. It looks really solid and loving the new
features.

I'm not a huge fan of the 'reference' but can't think of a great
replacement word so oh well.

I've got one question on the rpc call changes to the gui server.

Heads up that Kapil updated the python-jujuclient tonight and says
"pushed new py j client w/ iterator fix .. version incr math fixed as
well (0.50.1)"

So if you get time in the morning please see if you can do a round of QA
with that and we need to look at what it'll take to get that into the
stable PPA. I mentioned to him how we'd be able to help packaging and I
think the tox work done here in quickstart might be useful for
python-jujuclient and the deployer in the future.

https://codereview.appspot.com/207040043/diff/1/HACKING.rst
File HACKING.rst (right):

https://codereview.appspot.com/207040043/diff/1/HACKING.rst#newcode228
HACKING.rst:228: juju quickstart -e local mediawiki-single
<3 nice pretty command

https://codereview.appspot.com/207040043/diff/1/quickstart/__init__.py
File quickstart/__init__.py (right):

https://codereview.appspot.com/207040043/diff/1/quickstart/__init__.py#newcode48
quickstart/__init__.py:48: VERSION = (1, 7, 0)
what do you think of a 2.0? I guess it's not backward incompatible but
wondering if new charmstore/etc will be worthy of a big version update?

https://codereview.appspot.com/207040043/diff/1/quickstart/juju.py
File quickstart/juju.py (right):

https://codereview.appspot.com/207040043/diff/1/quickstart/juju.py#newcode68
quickstart/juju.py:68: params['Version'] = version
so this seems like a change to the call to the charm? Is Version going
to be supported in the charm then and name no longer required as a
param? This is the guiserver bits correct?

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

https://codereview.appspot.com/207040043/diff/1/quickstart/manage.py#newcode399
quickstart/manage.py:399: ''.format(jujucharms=settings.JUJUCHARMS_URL))
<3 this looks great.

https://codereview.appspot.com/207040043/diff/1/quickstart/tests/test_juju.py
File quickstart/tests/test_juju.py (right):

https://codereview.appspot.com/207040043/diff/1/quickstart/tests/test_juju.py#newcode207
quickstart/tests/test_juju.py:207: 'Version': 4,
Yea, so this is where I'm curious on the changes on the gui charm end.

https://codereview.appspot.com/207040043/

[lp:~frankban/juju-quickstart/jujucharms-bundles]

135. By Francesco Banconi on 2015-02-27

Bump version up to 2.0.0

[Francesco Banconi (frankban)]

Please take a look.

https://codereview.appspot.com/207040043/diff/1/HACKING.rst
File HACKING.rst (right):

https://codereview.appspot.com/207040043/diff/1/HACKING.rst#newcode228
HACKING.rst:228: juju quickstart -e local mediawiki-single
On 2015/02/27 03:00:09, rharding wrote:
> <3 nice pretty command

Indeed!

https://codereview.appspot.com/207040043/diff/1/quickstart/__init__.py
File quickstart/__init__.py (right):

https://codereview.appspot.com/207040043/diff/1/quickstart/__init__.py#newcode48
quickstart/__init__.py:48: VERSION = (1, 7, 0)
On 2015/02/27 03:00:10, rharding wrote:
> what do you think of a 2.0? I guess it's not backward incompatible but
wondering
> if new charmstore/etc will be worthy of a big version update?

Sounds good, bumped version up to 2.0.

https://codereview.appspot.com/207040043/diff/1/quickstart/juju.py
File quickstart/juju.py (right):

https://codereview.appspot.com/207040043/diff/1/quickstart/juju.py#newcode68
quickstart/juju.py:68: params['Version'] = version
On 2015/02/27 03:00:10, rharding wrote:
> so this seems like a change to the call to the charm? Is Version going
to be
> supported in the charm then and name no longer required as a param?
This is the
> guiserver bits correct?

Yes this is a call to the GUI server.
Version is already supported in the charm, as implemented by Madison.
Name has always been optional, only required when sending a YAML with
more than one bundle, which is never the case in quickstart.

https://codereview.appspot.com/207040043/

[Richard Harding (rharding)]

LGTM with the feedback thanks Francesco!

https://codereview.appspot.com/207040043/

[Madison Scott-Clary (makyo)]

LGTM - thanks for this, I think it's a great cleanup and implementation
of the newer urls.

https://codereview.appspot.com/207040043/

[lp:~frankban/juju-quickstart/jujucharms-bundles]

136. By Francesco Banconi on 2015-02-27

Update jujuclient to version 0.50.1.

[Francesco Banconi (frankban)]

Please take a look.

https://codereview.appspot.com/207040043/

[Francesco Banconi (frankban)]

*** Submitted:

Support retrieving bundles from charm store v4.

This branch implements the ability to deploy
bundles from the new charm store, retrieving
them with the v4 API.

Also introduce the new preferred bundle id
spelling, i.e. reflecting jujucharms.com paths,
like "mediawiki-single" or "u/who/bundle-name".

The old "bundle:basket/name" identifiers are
still supported but deprecated.
Deploying a bundle by specifying a directory
containing the YAML file is instead not
supported anymore.

Ok, after this brief summary let me take two
lines to really apologize for the huge diff.
While I was there, I refactored some historical
inconsistencies (e.g. models.Charm really being
just a charm or bundle reference), and I also
improved the bundle model API so that the work
is done in the model and not in manage as before.
There are a lot of tests too, and some documentation.
Nonetheless, let me say sorry again, this is
really too much stuff.

With this branch Juju Quickstart is quite ready for
the v4 world. The "deploy bundle" API call to the GUI
server still uses the legacy format, but the ugliness
of being backward compatible with namespaced bundles
is very restrained and implemented in private logic
in the bundles model module.

Tests: `make check`.

QA: run `devenv/bin/juju-quickstart` to deploy
new style and old style bundles, with both version
3 and 4 formats. Note that version 3 can only be
provided with arbitrary URLs or local files.

Thanks a lot!

R=rharding, matthew.scott
CC=
https://codereview.appspot.com/207040043

https://codereview.appspot.com/207040043/

[Francesco Banconi (frankban)]

Thanks a lot for the reviews!

https://codereview.appspot.com/207040043/

=== modified file 'HACKING.rst'
--- HACKING.rst	2015-02-05 13:35:53 +0000
+++ HACKING.rst	2015-02-27 18:40:58 +0000
@@ -219,13 +219,13 @@
     juju-quickstart -e local -n single $HOME/bundles/mediawiki
     juju destroy-environment local -y
 
-* Verify an environment that has already been bootstrapped is recogized and
+* Verify an environment that has already been bootstrapped is recognized and
   the GUI is deployed.  This test also shows that a remote bundle is properly
   deployed
 ::
 
     juju bootstrap -e local
-    juju quickstart -e local bundle:mediawiki/single
+    juju quickstart -e local mediawiki-single
     juju destroy-environment local -y
 
 * Prove that an environments.yaml file can be created and used::
 
=== modified file 'quickstart/__init__.py'
--- quickstart/__init__.py	2015-01-12 14:30:44 +0000
+++ quickstart/__init__.py	2015-02-27 18:40:58 +0000
@@ -45,7 +45,7 @@
 Once Juju has been installed, the command can also be run as a juju plugin,
 without the hyphen ("juju quickstart").
 """
-VERSION = (1, 6, 0)
+VERSION = (2, 0, 0)
 
 
 def get_version():
 
=== modified file 'quickstart/app.py'
--- quickstart/app.py	2015-02-09 18:00:33 +0000
+++ quickstart/app.py	2015-02-27 18:40:58 +0000
@@ -408,8 +408,9 @@
     default charm URL is used if the charm store service is not available.
 
     Return a tuple including the following values:
-        - charm: the charm that will be used to deploy the service, as an
-          instance of "quickstart.models.charms.Charm";
+        - charm_ref: the entity reference of the charm that will be used to
+          deploy the service, as an instance of
+          "quickstart.models.references.Reference";
         - machine: the machine where to deploy to (e.g. "0") or None if a new
           machine must be created;
         - service_data: the service info as returned by the mega-watcher for
@@ -449,7 +450,7 @@
         # A deployed service already exists in the environment: ignore the
         # provided charm URL and just use the already deployed charm.
         charm_url = service_data['CharmURL']
-    charm = jujutools.parse_gui_charm_url(charm_url)
+    charm_ref = jujutools.parse_gui_charm_url(charm_url)
     # Deploy on the bootstrap node if the following conditions are satisfied:
     # - we are not using the local provider (which uses localhost);
     # - we are not using the azure provider (in which availability sets prevent
@@ -457,10 +458,10 @@
     # - the requested charm and the bootstrap node have the same series.
     if (
         (env_type not in ('local', 'azure')) and
-        (charm.series == bootstrap_node_series)
+        (charm_ref.series == bootstrap_node_series)
     ):
         machine = '0'
-    return charm, machine, service_data, unit_data
+    return charm_ref, machine, service_data, unit_data
 
 
 def deploy_gui(env, service_name, charm_url, machine, service_data, unit_data):
@@ -587,15 +588,23 @@
             return address
 
 
-def deploy_bundle(env, bundle_yaml, bundle_name, bundle_id):
-    """Deploy a bundle.
+def deploy_bundle(env, bundle):
+    """Deploy the given bundle connecting to the given environment.
 
-    Receive the environment connection to use for deploying the bundle, the
-    bundle YAML encoded contents, the bundle name to be imported and its id.
+    Receive the environment connection to use for deploying the bundle and the
+    bundle object as an instance of "quickstart.models.bundles.Bundle".
 
     Raise a ProgramExit if the API server returns an error response.
     """
+    # XXX frankban 2015-02-26: use new bundle format if the GUI server is
+    # capable of handling bundle deployments with the API version 4.
+    yaml = bundle.serialize_legacy()
+    version = 3
+    # XXX frankban 2015-02-26: find and implement a better way to increase the
+    # bundle deployments count.
+    ref = bundle.reference
+    bundle_id = None if ref is None else ref.charmworld_id
     try:
-        env.deploy_bundle(bundle_yaml, name=bundle_name, bundle_id=bundle_id)
+        env.deploy_bundle(yaml, version, bundle_id=bundle_id)
     except jujuclient.EnvError as err:
         raise ProgramExit('bad API server response: {}'.format(err.message))
 
=== modified file 'quickstart/juju.py'
--- quickstart/juju.py	2015-01-30 17:38:36 +0000
+++ quickstart/juju.py	2015-02-27 18:40:58 +0000
@@ -61,11 +61,11 @@
         return self.login(
             password, user='{}-{}'.format(JUJU_USER_TAG, username))
 
-    def deploy_bundle(self, yaml, name=None, bundle_id=None):
+    def deploy_bundle(self, yaml, version, bundle_id=None):
         """Deploy a bundle."""
         params = {'YAML': yaml}
-        if name is not None:
-            params['Name'] = name
+        if version > 3:
+            params['Version'] = version
         if bundle_id is not None:
             params['BundleID'] = bundle_id
         request = {
 
=== modified file 'quickstart/jujutools.py'
--- quickstart/jujutools.py	2015-02-09 18:00:33 +0000
+++ quickstart/jujutools.py	2015-02-27 18:40:58 +0000
@@ -27,10 +27,11 @@
     serializers,
     settings,
 )
-from quickstart.models import charms
-
-
-def get_api_url(api_address, juju_version, env_uuid, prefix='', charm=None):
+from quickstart.models import references
+
+
+def get_api_url(
+        api_address, juju_version, env_uuid, prefix='', charm_ref=None):
     """Return the Juju WebSocket API endpoint.
 
     Receives the Juju API server address, the Juju version and the unique
@@ -38,9 +39,9 @@
 
     Optionally receive a prefix to be used in the path.
 
-    Optionally also receive the Juju GUI charm object as an instance of
-    "quickstart.models.charms.Charm". If provided, the function checks that
-    the specified Juju GUI charm supports the new Juju API endpoint.
+    Optionally also receive the Juju GUI charm reference as an instance of
+    "quickstart.models.references.Reference". If provided, the function checks
+    that the corresponding Juju GUI charm supports the new Juju API endpoint.
     If not supported, the old endpoint is returned.
 
     The environment UUID can be None, in which case the old-style API URL
@@ -53,19 +54,19 @@
     if (env_uuid is None) or (juju_version < (1, 22, 0)):
         return base_url
     complete_url = '{}/environment/{}/api'.format(base_url, env_uuid)
-    if charm is None:
+    if charm_ref is None:
         return complete_url
     # If a customized Juju GUI charm is in use, there is no way to check if the
     # GUI server is recent enough to support the new Juju API endpoints.
     # In these cases, assume the customized charm is recent enough.
     if (
-        charm.name != settings.JUJU_GUI_CHARM_NAME or
-        charm.user or
-        charm.is_local()
+        charm_ref.name != settings.JUJU_GUI_CHARM_NAME or
+        charm_ref.user or
+        charm_ref.is_local()
     ):
         return complete_url
     # This is the promulgated Juju GUI charm. Check if it supports new APIs.
-    revision, series = charm.revision, charm.series
+    revision, series = charm_ref.revision, charm_ref.series
     if revision < settings.MINIMUM_REVISIONS_FOR_NEW_API_ENDPOINT[series]:
         return base_url
     return complete_url
@@ -99,29 +100,29 @@
 def parse_gui_charm_url(charm_url):
     """Parse the given charm URL.
 
-    Check if the charm looks like a Juju GUI charm.
+    Check if the charm URL seems to refer to a Juju GUI charm.
     Print (to stdout or to logs) info and warnings about the charm URL.
 
-    Return the parsed charm object as an instance of
-    "quickstart.models.charms.Charm".
+    Return the parsed charm reference object as an instance of
+    "quickstart.models.references.Reference".
     """
     print('charm URL: {}'.format(charm_url))
-    charm = charms.Charm.from_url(charm_url)
+    ref = references.Reference.from_fully_qualified_url(charm_url)
     charm_name = settings.JUJU_GUI_CHARM_NAME
-    if charm.name != charm_name:
+    if ref.name != charm_name:
         # This does not seem to be a Juju GUI charm.
         logging.warn(
             'unexpected URL for the {} charm: '
             'the service may not work as expected'.format(charm_name))
-        return charm
-    if charm.user or charm.is_local():
+        return ref
+    if ref.user or ref.is_local():
         # This is not the official Juju GUI charm.
         logging.warn('using a customized {} charm'.format(charm_name))
-    elif charm.revision < settings.MINIMUM_REVISIONS_FOR_BUNDLES[charm.series]:
+    elif ref.revision < settings.MINIMUM_REVISIONS_FOR_BUNDLES[ref.series]:
         # This is the official Juju GUI charm, but it is outdated.
         logging.warn(
             'charm is outdated and may not support bundle deployments')
-    return charm
+    return ref
 
 
 def parse_status_output(output, keys=None):
 
=== modified file 'quickstart/manage.py'
--- quickstart/manage.py	2015-02-09 18:00:33 +0000
+++ quickstart/manage.py	2015-02-27 18:40:58 +0000
@@ -22,7 +22,6 @@
 )
 
 import argparse
-import codecs
 import logging
 import os
 import shutil
@@ -33,7 +32,6 @@
 from quickstart import (
     app,
     jujutools,
-    netutils,
     packaging,
     platform_support,
     settings,
@@ -45,9 +43,9 @@
 )
 from quickstart.models import (
     bundles,
-    charms,
     envs,
     jenv,
+    references,
 )
 
 
@@ -97,50 +95,17 @@
     """Validate and process the bundle options.
 
     Populate the options namespace with the following names:
-        - 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.
-        - bundle_id: the bundle_id in Charmworld.  None if not a 'bundle:' URL.
-    Exit with an error if the bundle options are not valid.
+        - bundle: the bundle object as an instance of
+          "quickstart.models.bundles.Bundle";
+
+    Exit with an error if the bundle options are not valid, or if the bundle
+    content cannot be retrieved.
     """
-    bundle = options.bundle
-    bundle_id = None
-    jujucharms_prefix = settings.JUJUCHARMS_BUNDLE_URL
-    if bundle.startswith('bundle:') or bundle.startswith(jujucharms_prefix):
-        # Convert "bundle:" or jujucharms.com URLs into Charmworld HTTPS ones.
-        try:
-            bundle, bundle_id = bundles.convert_bundle_url(bundle)
-        except ValueError as err:
-            return parser.error('unable to open the bundle: {}'.format(err))
-        # The next if block below will then load the bundle contents from the
-        # remote location.
-    if bundle.startswith('http://') or bundle.startswith('https://'):
-        # Load the bundle from a remote URL.
-        try:
-            bundle_yaml = netutils.urlread(bundle)
-        except IOError as err:
-            return parser.error('unable to open bundle URL: {}'.format(err))
-    else:
-        # Load the bundle from a file.
-        bundle_file = os.path.abspath(os.path.expanduser(bundle))
-        if os.path.isdir(bundle_file):
-            bundle_file = os.path.join(bundle_file, 'bundles.yaml')
-        try:
-            bundle_yaml = codecs.open(
-                bundle_file.encode('utf-8'), encoding='utf-8').read()
-        except IOError as err:
-            return parser.error('unable to open bundle file: {}'.format(err))
-    # Validate the bundle.
     try:
-        bundle_name, bundle_services = bundles.parse_bundle(
-            bundle_yaml, options.bundle_name)
-    except ValueError as err:
-        return parser.error(bytes(err))
-    # Update the options namespace with the new values.
-    options.bundle_name = bundle_name
-    options.bundle_services = bundle_services
-    options.bundle_yaml = bundle_yaml
-    options.bundle_id = bundle_id
+        options.bundle = bundles.from_source(
+            options.bundle_source, options.bundle_name)
+    except (IOError, ValueError) as err:
+        return parser.error(b'unable to open the bundle: {}'.format(err))
 
 
 def _validate_charm_url(options, parser):
@@ -156,25 +121,24 @@
     Leave the options namespace untouched.
     """
     try:
-        charm = charms.Charm.from_url(options.charm_url)
+        ref = references.Reference.from_fully_qualified_url(options.charm_url)
     except ValueError as err:
         return parser.error(bytes(err))
-    if charm.is_local():
-        return parser.error(b'local charms are not allowed: {}'.format(charm))
-    if charm.series not in settings.JUJU_GUI_SUPPORTED_SERIES:
-        return parser.error(
-            'unsupported charm series: {}'.format(charm.series))
+    if ref.is_local():
+        return parser.error(b'local charms are not allowed: {}'.format(ref))
+    if ref.series not in settings.JUJU_GUI_SUPPORTED_SERIES:
+        return parser.error('unsupported charm series: {}'.format(ref.series))
     if (
         # The user requested a bundle deployment.
-        options.bundle and
+        options.bundle_source is not None and
         # This is the official Juju GUI charm.
-        charm.name == settings.JUJU_GUI_CHARM_NAME and not charm.user and
+        ref.name == settings.JUJU_GUI_CHARM_NAME and not ref.user and
         # The charm at this revision does not support bundle deployments.
-        charm.revision < settings.MINIMUM_REVISIONS_FOR_BUNDLES[charm.series]
+        ref.revision < settings.MINIMUM_REVISIONS_FOR_BUNDLES[ref.series]
     ):
         return parser.error(
             'bundle deployments not supported by the requested charm '
-            'revision: {}'.format(charm))
+            'revision: {}'.format(ref))
 
 
 def _retrieve_env_db(parser, env_file=None):
@@ -363,7 +327,10 @@
     """Set up the application options and logger.
 
     Return the options as a namespace containing the following attributes:
-        - bundle: the optional bundle (path or URL) to be deployed;
+        - bundle_name: the optional name of the bundle in the case the legacy
+          bundle format is being used, or None if the name is not specified;
+        - bundle_source: the optional bundle identifier to be deployed, or None
+          if a bundle deployment is not requested;
         - charm_url: the Juju GUI charm URL or None if not specified;
         - constraints: the environment constrains or None if not set;
         - debug: whether debug mode is activated;
@@ -380,11 +347,8 @@
 
     The following attributes will also be included in the namespace if a bundle
     deployment is requested:
-        - bundle_name: the name of the bundle to be deployed;
-        - bundle_services: a list of service names included in the bundle;
-        - bundle_yaml: the YAML encoded contents of the bundle.
-        - bundle_id: the Charmworld identifier for the bundle if a
-            'bundle:' URL is provided.
+        - bundle: the bundle instance to be deployed, as an instance of
+          "quickstart.models.bundles.Bundle".
 
     Exit with an error if the provided arguments are not valid.
     """
@@ -406,26 +370,33 @@
     # Note: since we use the RawTextHelpFormatter, when adding/changing options
     # make sure the help text is nicely displayed on small 80 columns terms.
     parser.add_argument(
-        'bundle', default=None, nargs='?',
+        'bundle_source', default=None, nargs='?', metavar='BUNDLE',
         help='The optional bundle to be deployed. The bundle can be:\n'
-             '1) a fully qualified bundle URL, starting with "bundle:"\n'
-             '   e.g. "bundle:mediawiki/single".\n'
+             '1) a bundle path as shown in jujucharms.com, e.g.\n'
+             '   "mediawiki-single" or "django".\n'
+             '   Non promulgated bundles can be requested providing\n'
+             '   the user, e.g. "u/bigdata-dev/apache-analytics-sql".\n'
+             '   A specific bundle revision can also be requested,\n'
+             '   e.g. "mediawiki-scalable/7".\n'
+             '   If not specified, the most recent revision is used;\n'
+             '2) a jujucharms.com full URL of the bundle detail page,\n'
+             '   with or without the revision. e.g.\n'
+             '   "{jujucharms}mongodb-cluster/4" or\n'
+             '   "{jujucharms}openstack";\n'
+             '3) a URL ("http:" or "https:") to a YAML/JSON, e.g.\n'
+             '   "https://raw.github.com/user/my/master/bundle.yaml";\n'
+             '4) a local path to a YAML/JSON file with ".yaml" or\n'
+             '   ".json" extension, e.g. "~/bundles/django.yaml";\n'
+             '5) a legacy fully qualified bundle URL, starting with\n'
+             '   "bundle:", e.g. "bundle:mediawiki/single".\n'
              '   Non promulgated bundles can be requested providing\n'
              '   the user, e.g. "bundle:~user/mediawiki/single".\n'
              '   A specific bundle revision can also be requested,\n'
              '   e.g. "bundle:~myuser/mediawiki/42/single".\n'
-             '   If not specified, the last bundle revision is used;\n'
-             '2) a jujucharms bundle URL, starting with\n'
-             '   "{jujucharm}", e.g.\n'
-             '   "{jujucharm}~user/wiki/1/simple/".\n'
-             '   As seen above, jujucharms bundle URLs can also be\n'
-             '   shortened, e.g.\n'
-             '   "{jujucharm}mediawiki/scalable/";\n'
-             '3) a URL ("http:" or "https:") to a YAML/JSON, e.g.\n'
-             '   "https://raw.github.com/user/my/master/bundles.yaml";\n'
-             '4) a local path to a YAML/JSON file;\n'
-             '5) a path to a directory containing a "bundles.yaml"\n'
-             '   file'.format(jujucharm=settings.JUJUCHARMS_BUNDLE_URL))
+             '   If not specified, the last bundle revision is used.\n'
+             '   Note that this form is DEPRECATED, and a deprecation\n'
+             '   warning is printed suggesting the new value to use\n'
+             ''.format(jujucharms=settings.JUJUCHARMS_URL))
     parser.add_argument(
         '-e', '--environment', default=default_env_name, dest='env_name',
         help=env_help)
@@ -497,7 +468,7 @@
     _convert_options_to_unicode(options)
     # Validate and process the provided arguments.
     _setup_env(options, parser)
-    if options.bundle is not None:
+    if options.bundle_source is not None:
         _validate_bundle(options, parser)
     if options.charm_url is not None:
         _validate_charm_url(options, parser)
@@ -509,9 +480,9 @@
 def run(options):
     """Run the application."""
     print('juju quickstart v{}'.format(version))
-    if options.bundle is not None:
-        print('contents loaded for bundle {} (services: {})'.format(
-            options.bundle_name, len(options.bundle_services)))
+    if options.bundle_source is not None:
+        print('contents loaded for {} (services: {})'.format(
+            options.bundle, len(options.bundle.services())))
 
     juju_command, custom_juju = platform_support.get_juju_command(
         options.platform)
@@ -578,11 +549,11 @@
     print('environment type: {}'.format(env_type))
 
     # Inspect the environment and deploy the charm if required.
-    charm, machine, service_data, unit_data = app.check_environment(
+    charm_ref, machine, service_data, unit_data = app.check_environment(
         env, settings.JUJU_GUI_SERVICE_NAME, options.charm_url,
         env_type, bootstrap_node_series, already_bootstrapped)
     unit_name = app.deploy_gui(
-        env, settings.JUJU_GUI_SERVICE_NAME, charm.url(), machine,
+        env, settings.JUJU_GUI_SERVICE_NAME, charm_ref.id(), machine,
         service_data, unit_data)
 
     # Observe the deployment progress.
@@ -597,20 +568,22 @@
     # Connect to the GUI server WebSocket API.
     print('connecting to the Juju GUI server')
     gui_api_url = jujutools.get_api_url(
-        address + ':443', juju_version, env_uuid, prefix='ws', charm=charm)
+        address + ':443', juju_version, env_uuid,
+        prefix='ws', charm_ref=charm_ref)
     gui_env = app.connect(gui_api_url, username, password)
 
     # Handle bundle deployment.
-    if options.bundle is not None:
-        services = ', '.join(options.bundle_services)
-        print('requesting a deployment of the {} bundle with the following '
-              'services:\n  {}'.format(options.bundle_name, services))
+    if options.bundle_source is not None:
+        services = ', '.join(options.bundle.services())
+        print('requesting a deployment of {} with the following services:\n'
+              '  {}'.format(options.bundle, services))
+        if options.bundle.reference is not None:
+            print('more details about this bundle can be found at\n'
+                  '  {}'.format(options.bundle.reference.jujucharms_url()))
         # 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.
-        app.deploy_bundle(
-            gui_env, options.bundle_yaml, options.bundle_name,
-            options.bundle_id)
+        app.deploy_bundle(gui_env, options.bundle)
         print('bundle deployment request accepted\n'
               'use the GUI to check the bundle deployment progress')
 
 
=== modified file 'quickstart/models/bundles.py'
--- quickstart/models/bundles.py	2015-02-09 12:58:04 +0000
+++ quickstart/models/bundles.py	2015-02-27 18:40:58 +0000
@@ -14,105 +14,317 @@
 # You should have received a copy of the GNU Affero General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-"""Juju Quickstart bundles management."""
+"""Juju Quickstart bundles management.
+
+This module defines objects and functions that help working with bundles.
+Bundles are described by a YAML content defining a collection of services in a
+Juju topology, along with their options, relations and unit placement.
+
+Published bundles are identified by a charm store id and by the corresponding
+URL in jujucharms.com, just like regular charms. The reference object in
+"quickstart.models.references.Reference" can be used to identify a bundle.
+
+In this module, the Bundle class represents a bundle that may or may not have
+a specific reference id. For instance, a reference is not set on a bundle if
+its contents are retrieved from an arbitrary local or remote location.
+
+Juju Quickstart usually instantiates bundles using the "from_source" helper
+below, which retrieves the bundle content from all the supported sources,
+validates it and then creates a "Bundle" instance with the validated content
+and the bundle reference if avaliable.
+
+Use "parse_yaml" to parse and validate a YAML encoded string as a bundle
+content. If the YAML decoded object is already available, the same validation
+can be achieved using the "validate" function directly.
+"""
 
 from __future__ import unicode_literals
 
+import codecs
 import collections
-import re
+import logging
+import os
 
 from quickstart import (
+    netutils,
     serializers,
     settings,
 )
-
-
-# Compile the regular expression used to parse bundle URLs.
-_bundle_expression = re.compile(r"""
-    # Bundle schema or bundle URL namespace on jujucharms.com.
-    ^(?:bundle:|{})
-    (?:~([-\w]+)/)?  # Optional user name.
-    ([-\w]+)/  # Basket name.
-    (?:(\d+)/)?  # Optional bundle revision number.
-    ([-\w]+)  # Bundle name.
-    /?$  # Optional trailing slash.
-""".format(settings.JUJUCHARMS_BUNDLE_URL), re.VERBOSE)
-
-
-def convert_bundle_url(bundle_url):
-    """Return the equivalent YAML HTTPS location for the given bundle URL.
-
-    Raise a ValueError if the given URL is not a valid bundle URL.
-    """
-    match = _bundle_expression.match(bundle_url)
-    if match is None:
-        msg = 'invalid bundle URL: {}'.format(bundle_url)
-        raise ValueError(msg.encode('utf-8'))
-    user, basket, revision, name = match.groups()
-    user_part = '~charmers/' if user is None else '~{}/'.format(user)
-    revision_part = '' if revision is None else '{}/'.format(revision)
-    bundle_id = '{}{}/{}{}'.format(user_part, basket, revision_part, name)
-    return ('https://manage.jujucharms.com/bundle/{}/json'.format(bundle_id),
-            bundle_id)
-
-
-def parse_bundle(bundle_yaml, bundle_name=None):
-    """Parse the provided bundle YAML encoded contents.
-
-    Since a valid JSON is a subset of YAML this function can be used also to
-    parse JSON encoded 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 = serializers.yaml_load(bundle_yaml)
+from quickstart.models import references
+
+
+class Bundle(object):
+    """Store information about a charm store bundle entity"""
+
+    def __init__(self, data, reference=None):
+        """Initialize the bundle.
+
+        The data argument is the bundle YAML decoded content.
+        An optional entity reference can be provided as an instance of
+        "quickstart.models.references.Reference".
+        """
+        self.data = data
+        self.reference = reference
+
+    def __str__(self):
+        """Return the byte string representation of this bundle."""
+        return self.__unicode__().encode('utf-8')
+
+    def __unicode__(self):
+        """Return the unicode string representation of this bundle."""
+        parts = ['bundle']
+        if self.reference is not None:
+            parts.append(self.reference.jujucharms_id())
+        return ' '.join(parts)
+
+    def __repr__(self):
+        return b'<Bundle: {}>'.format(bytes(self))
+
+    def serialize(self):
+        """Serialize the bundle data as a YAML encoded string."""
+        return serializers.yaml_dump(self.data)
+
+    def serialize_legacy(self):
+        """Serialize the bundle data as a YAML encoded string.
+
+        The resulting string uses the legacy API version 3 format.
+        """
+        return serializers.yaml_dump({'bundle': self.data})
+
+    def services(self):
+        """Return a list of service names included in the bundle.
+
+        Service names are returned in alphabetical order.
+        """
+        return sorted(self.data['services'].keys())
+
+
+def from_source(source, name=None):
+    """Return a bundle YAML encoded string and id from the given source.
+
+    The source argument is a string, and can be provided as:
+
+        - a bundle path as shown in jujucharms.com, e.g. "mediawiki-single" or
+          "u/bigdata-dev/apache-analytics-sql";
+
+        - a bundle path as shown in jujucharms.com including the bundle
+          revision, e.g. "mediawiki-single/7" or "u/frankban/django/42";
+
+        - the two forms above with leading or trailing slashes, e.g.
+          "/mediawiki-scalable" or "/u/frankban/django/42";
+
+        - a full jujucharms.com URL, e.g. "https://jujucharms.com/django/" or
+          "https://jujucharms.com/u/bigdata-dev/apache-analytics-sql";
+
+        - a full jujucharms.com URL including the bundle revision, e.g.
+          "https://jujucharms.com/django/2/";
+
+        - a URL ("http:" or "https:") to a YAML/JSON, e.g.
+          "https://raw.github.com/user/my/master/bundles.yaml";
+
+        - a local path to a YAML/JSON file, ending with ".yaml" or ".json",
+          e.g. "mybundle.yaml" or "~/bundles/django.json";
+
+        - an old style bundle fully qualified URL, e.g.
+          "bundle:~myuser/mediawiki/42/single";
+
+        - and old style bundle URL without user and/or revision, e.g.
+          "bundle:mediawiki/single" or "bundle:~user/mediawiki/single".
+
+    Return a Bundle instance whose bundle reference attribute is None if this
+    information cannot be inferred from the given source.
+
+    Raise a ValueError if the given source is not valid.
+    Raise an IOError if the YAML content cannot be retrieved from the given
+    local or remote source.
+    """
+    if source.startswith('bundle:'):
+        # The source refers to an old style bundle URL.
+        reference = references.Reference.from_charmworld_url(source)
+        logging.warn(
+            'this bundle URL is deprecated: please use the new format: '
+            '{}'.format(reference.jujucharms_id()))
+        return _bundle_from_reference(reference)
+
+    has_extension = source.endswith('.yaml') or source.endswith('.json')
+    is_remote = source.startswith('http://') or source.startswith('https://')
+    if has_extension and not is_remote:
+        # The source refers to a local file.
+        data = _parse_and_flatten_yaml(_retrieve_from_file(source), name)
+        return Bundle(data)
+
+    try:
+        reference = references.Reference.from_jujucharms_url(source)
+    except ValueError:
+        if is_remote:
+            # The source is an arbitrary URL to a YAML/JSON content.
+            data = _parse_and_flatten_yaml(_retrieve_from_url(source), name)
+            return Bundle(data)
+        # No other options are available.
+        raise
+
+    if not reference.is_bundle():
+        raise ValueError(
+            b'expected a bundle, provided charm {}'.format(reference))
+
+    # The source refers to a bundle URL in jujucharms.com.
+    return _bundle_from_reference(reference)
+
+
+def _bundle_from_reference(reference):
+    """Retrieve bundle YAML contents from its reference in the charm store.
+
+    The path of an entity in the charm store is the fully qualified URL without
+    the schema. The schema is implicitly set to "cs" (charm store entity), e.g.
+    "vivid/django" or "~who/trusty/mediawiki-42".
+
+    Return a Bundle instance which includes the retrieved data and the given
+    reference.
+    Raise a IOError if a problem is encountered while fetching the YAML
+    content from the charm store.
+    Raise a ValueError if the bundle content is not valid.
+    """
+    url = settings.CHARMSTORE_API + reference.path() + '/archive/bundle.yaml'
+    content = _retrieve_from_url(url)
+    data = parse_yaml(content)
+    return Bundle(data, reference=reference)
+
+
+def _retrieve_from_url(url):
+    """Retrieve bundle YAML content from the given URL.
+
+    Return the bundle content as a YAML encoded string.
+    Raise a IOError if a problem is encountered while opening the URL.
+    """
+    try:
+        return netutils.urlread(url)
+    except IOError as err:
+        msg = b'cannot retrieve bundle from remote URL {}: {}'.format(
+            url.encode('utf-8'), err)
+        raise IOError(msg)
+
+
+def _retrieve_from_file(path):
+    """Retrieve bundle YAML content from the given local file path.
+
+    Return the bundle content as a YAML encoded string.
+    Raise a IOError if a problem is encountered while opening the file.
+    """
+    path = os.path.abspath(os.path.expanduser(path))
+    try:
+        return codecs.open(path.encode('utf-8'), encoding='utf-8').read()
+    except IOError as err:
+        raise IOError(
+            b'cannot retrieve bundle from local file: {}'.format(err))
+
+
+def parse_yaml(content):
+    """Parse and validate the given bundle content as a YAML encoded string.
+
+    Note that the bundle validation performed by Juju Quickstart is weak by
+    design: it just checks that the content looks like a bundle YAML. Contents
+    provided by the charm store are already known as valid. For other sources,
+    a more cogent validation is done down in the stack, when the content is
+    sent to the GUI server and then to the Juju deployer.
+
+    Return the resulting YAML decoded dictionary.
+    Raise a ValueError if:
+        - the bundle YAML contents are not parsable by YAML;
+        - the YAML contents are not properly structured;
+        - the bundle does not include services.
+    """
+    data = _open_yaml(content)
+    # Validate the bundle data.
+    validate(data)
+    return data
+
+
+def _parse_and_flatten_yaml(content, name):
+    """Parse and validate the given bundle content.
+
+    The content is provided as a YAML encoded string and can be either a new
+    style flat bundle or a legacy bundle format.
+    In both cases, the returned YAML decoded data represents a new style
+    bundle (API version 4).
+
+    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.
+    """
+    data = _open_yaml(content)
+    services = data.get('services')
+    # The internal structure of a bundle in the API version 4 does not include
+    # a wrapping namespace with the bundle name. That's why the check below,
+    # despite its ugliness, is quite effective.
+    if services and 'services' not in services:
+        # This is an API version 4 bundle.
+        validate(data)
+        return data
+    num_bundles = len(data)
+    if not num_bundles:
+        raise ValueError(b'no bundles found in the provided list of bundles')
+    names = ', '.join(sorted(data.keys()))
+    if name is None:
+        if num_bundles > 1:
+            msg = 'multiple bundles found ({}) but no bundle name specified'
+            raise ValueError(msg.format(names).encode('utf-8'))
+        data = data.values()[0]
+    else:
+        data = data.get(name)
+        if data is None:
+            msg = 'bundle {} not found in the provided list of bundles ({})'
+            raise ValueError(msg.format(name, names).encode('utf-8'))
+    validate(data)
+    return data
+
+
+def _open_yaml(content):
+    """Deserialize the given content, that must be a YAML encoded dictionary.
+
+    Raise a ValueError if the content is not valid.
+    """
+    try:
+        data = serializers.yaml_load(content)
     except Exception as err:
-        msg = b'unable to parse the bundle: {}'.format(err)
+        msg = b'unable to parse the bundle content: {}'.format(err)
         raise ValueError(msg)
-    # Ensure the bundle file is well formed and contains at least one bundle.
-    if not isinstance(bundles, collections.Mapping):
-        msg = 'invalid YAML contents: {}'.format(bundle_yaml)
+    # Ensure the bundle content is well formed.
+    if not isinstance(data, collections.Mapping):
+        msg = 'invalid YAML content: {}'.format(data)
         raise ValueError(msg.encode('utf-8'))
+    return data
+
+
+def validate(data):
+    """Validate the given YAML decoded bundle data.
+
+    Note that the bundle validation performed by Juju Quickstart is weak by
+    design: it just checks that the content looks like a bundle YAML. Contents
+    provided by the charm store are already known as valid. For other sources,
+    a more cogent validation is done down in the stack, when the content is
+    sent to the GUI server and then to the Juju deployer.
+
+    Raise a ValueError if:
+        - the YAML contents are not properly structured;
+        - the bundle does not include services.
+    """
+    # Retrieve the bundle services.
     try:
-        name_services_map = dict(
-            (key, value['services'].keys())
-            for key, value in bundles.items()
-        )
+        services = data['services'].keys()
     except (AttributeError, KeyError, TypeError):
-        msg = 'invalid YAML contents: {}'.format(bundle_yaml)
-        raise ValueError(msg.encode('utf-8'))
-    if not name_services_map:
-        raise ValueError(b'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).encode('utf-8'))
-        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).encode('utf-8'))
-    if not bundle_services:
-        msg = 'bundle {} does not include any services'.format(bundle_name)
-        raise ValueError(msg.encode('utf-8'))
-    if settings.JUJU_GUI_SERVICE_NAME in bundle_services:
-        msg = ('bundle {} contains an instance of juju-gui. quickstart will '
-               'install the latest version of the Juju GUI automatically, '
-               'please remove juju-gui from the bundle.'.format(bundle_name))
-        raise ValueError(msg.encode('utf-8'))
-    return bundle_name, bundle_services
+        content = serializers.yaml_dump(data).strip()
+        msg = 'unable to retrieve bundle services: {}'.format(content)
+        raise ValueError(msg.encode('utf-8'))
+    # Ensure at least one service is defined in the bundle.
+    if not services:
+        raise ValueError(b'no services found in the bundle')
+    # Check that the Juju GUI charm is not included as a service.
+    if settings.JUJU_GUI_SERVICE_NAME in services:
+        raise ValueError(
+            b'the provided bundle contains an instance of juju-gui. Juju '
+            b'Quickstart will install the latest version of the Juju GUI '
+            b'automatically; please remove juju-gui from the bundle')
 
=== renamed file 'quickstart/models/charms.py' => 'quickstart/models/references.py'
--- quickstart/models/charms.py	2015-02-09 14:56:32 +0000
+++ quickstart/models/references.py	2015-02-27 18:40:58 +0000
@@ -14,37 +14,203 @@
 # You should have received a copy of the GNU Affero General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-"""Juju Quickstart charms management."""
+"""Juju Quickstart charm and bundle references management."""
 
 from __future__ import unicode_literals
 
 import re
 
+from quickstart import settings
+
 
 # The following regular expressions are the same used in juju-core: see
 # http://bazaar.launchpad.net/~go-bot/juju-core/trunk/view/head:/charm/url.go.
-valid_user = re.compile(r'^[a-z0-9][a-zA-Z0-9+.-]+$').match
-valid_series = re.compile(r'^[a-z]+([a-z-]+[a-z])?$').match
-valid_name = re.compile(r'^[a-z][a-z0-9]*(-[a-z0-9]*[a-z][a-z0-9]*)*$').match
-
-
-def parse_url(url):
-    """Parse the given charm URL.
-
-    Return a tuple containing the charm URL fragments: schema, user, series,
-    name and revision. Each fragment is a string except revision (int).
+_USER_PATTERN = r'[a-z0-9][a-zA-Z0-9+.-]+'
+_SERIES_PATTERN = r'[a-z]+(?:[a-z-]+[a-z])?'
+_NAME_PATTERN = r'[a-z][a-z0-9]*(?:-[a-z0-9]*[a-z][a-z0-9]*)*'
+
+# Define the callables used to check if entity reference components are valid.
+_valid_user = re.compile(r'^{}$'.format(_USER_PATTERN)).match
+_valid_series = re.compile(r'^{}$'.format(_SERIES_PATTERN)).match
+_valid_name = re.compile(r'^{}$'.format(_NAME_PATTERN)).match
+
+# Compile the regular expression used to parse charmworld bundle URLs.
+_charmworld_url_expression = re.compile(r"""
+    ^  # Beginning of the line.
+    (?:bundle:)  # Bundle schema.
+    (?:~({user_pattern})/)?  # Optional user name.
+    ({name_pattern})/  # Basket name.
+    (?:(\d+)/)?  # Optional bundle revision number.
+    ({name_pattern})  # Bundle name.
+    /?  # Optional trailing slash.
+    $  # End of the line.
+""".format(
+    name_pattern=_NAME_PATTERN,
+    user_pattern=_USER_PATTERN,
+), re.VERBOSE)
+# Compile the regular expression used to parse new jujucharms entity URLs.
+_jujucharms_url_expression = re.compile(r"""
+    ^  # Beginning of the line.
+    (?:
+        (?:{jujucharms})?  # Optional jujucharms.com URL.
+        |
+        /?  # Optional leading slash.
+    )?
+    (?:u/({user_pattern})/)?  # Optional user name.
+    ({name_pattern})  # Bundle name.
+    (?:/({series_pattern}))?  # Optional series.
+    (?:/(\d+))?  # Optional bundle revision number.
+    /?  # Optional trailing slash.
+    $  # End of the line.
+""".format(
+    jujucharms=settings.JUJUCHARMS_URL,
+    name_pattern=_NAME_PATTERN,
+    series_pattern=_SERIES_PATTERN,
+    user_pattern=_USER_PATTERN,
+), re.VERBOSE)
+
+
+class Reference(object):
+    """Represent a charm or bundle URL reference."""
+
+    def __init__(self, schema, user, series, name, revision):
+        """Initialize the reference. Receives the URL fragments."""
+        self.schema = schema
+        self.user = user
+        self.series = series
+        self.name = name
+        if revision is not None:
+            revision = int(revision)
+        self.revision = revision
+        # XXX frankban 2015-02-26: remove the following attribute when
+        # switching to the new bundle format, and when we have a better way
+        # to increase bundle deployments count.
+        self.charmworld_id = None
+
+    @classmethod
+    def from_fully_qualified_url(cls, url):
+        """Given an entity URL as a string, create and return a Reference.
+
+        Fully qualified URLs represent the regular entity reference
+        representation in Juju, e.g.: "cs:`~who/vivid/django-42" or
+        "local:bundle/wordpress-0".
+
+        Raise a ValueError if the provided value is not a valid and fully
+        qualified URL, also including the schema and the revision.
+        """
+        return cls(*_parse_fully_qualified_url(url))
+
+    @classmethod
+    def from_charmworld_url(cls, url):
+        """Create and return a Reference from the given charmworld URL.
+
+        These kind of "bundle:basket/name" URLs were used before the release
+        of the new charm store (API version 4). Possible examples are
+        "bundle:mediawiki/single" or "bundle:~who/wordpress/42/scalable".
+        Note that charmworld URLs always represent a bundle.
+
+        Raise a ValueError if the provided URL is not valid.
+        """
+        match = _charmworld_url_expression.match(url)
+        if match is None:
+            msg = 'invalid bundle URL: {}'.format(url)
+            raise ValueError(msg.encode('utf-8'))
+        user, basket, revision, name = match.groups()
+        name = '{}-{}'.format(basket, name)
+        self = cls('cs', user, 'bundle', name, revision)
+        # XXX frankban 2015-02-26: remove this when switching to the new bundle
+        # format. Note that this is monkey patched on purpose: we don't want
+        # the legacy bundle id to be part of this class contract, and we don't
+        # want to keep track of obsolete concepts such as "basket" here.
+        self.charmworld_id = url[len('bundle:'):]
+        return self
+
+    @classmethod
+    def from_jujucharms_url(cls, url):
+        """Create and return a Reference from the given jujucharms.com URL.
+
+        These are the preferred way to refer to a charm or bundle in Juju
+        Quickstart. They basically look like the URL paths in jujucharms.com,
+        e.g. "u/who/django", "mediawiki/42" or just "mediawiki". The full HTTP
+        URL can be also provided, for instance "https://jujucharms.com/django".
+
+        Raise a ValueError if the provided URL is not valid.
+        """
+        match = _jujucharms_url_expression.match(url)
+        if match is None:
+            msg = 'invalid bundle URL: {}'.format(url)
+            raise ValueError(msg.encode('utf-8'))
+        user, name, series, revision = match.groups()
+        return cls('cs', user, series or 'bundle', name, revision)
+
+    def __str__(self):
+        """The string representation of a reference is its URL string."""
+        return self.__unicode__().encode('utf-8')
+
+    def __unicode__(self):
+        """The unicode representation of a reference is its URL string."""
+        return self.id()
+
+    def __repr__(self):
+        return b'<Reference: {}>'.format(bytes(self))
+
+    def __eq__(self, other):
+        """Two refs are equal if they have the same string representation."""
+        return isinstance(other, self.__class__) and self.id() == other.id()
+
+    def path(self):
+        """Return the reference as a string without the schema."""
+        user_part = '~{}/'.format(self.user) if self.user else ''
+        revision_part = ''
+        if self.revision is not None:
+            revision_part = '-{}'.format(self.revision)
+        return '{}{}/{}{}'.format(
+            user_part, self.series, self.name, revision_part)
+
+    def id(self):
+        """Return the reference URL as a string."""
+        return '{}:{}'.format(self.schema, self.path())
+
+    def jujucharms_id(self):
+        """Return the identifier of this reference in jujucharms.com."""
+        user_part = 'u/{}/'.format(self.user) if self.user else ''
+        series_part = '' if self.is_bundle() else '/{}'.format(self.series)
+        revision_part = ''
+        if self.revision is not None:
+            revision_part = '/{}'.format(self.revision)
+        return '{}{}{}{}'.format(
+            user_part, self.name, series_part, revision_part)
+
+    def jujucharms_url(self):
+        """Return the URL where this entity lives in jujucharms.com."""
+        return settings.JUJUCHARMS_URL + self.jujucharms_id()
+
+    def is_bundle(self):
+        """Report whether this reference refers to a bundle entity."""
+        return self.series == 'bundle'
+
+    def is_local(self):
+        """Return True if this refers to a local entity, False otherwise."""
+        return self.schema == 'local'
+
+
+def _parse_fully_qualified_url(url):
+    """Parse the given charm or bundle URL, provided as a string.
+
+    Return a tuple containing the entity reference fragments: schema, user,
+    series, name and revision. Each fragment is a string except revision (int).
 
     Raise a ValueError with a descriptive message if the given URL is not a
-    valid charm URL.
+    valid and fully qualified entity URL.
     """
     # Retrieve the schema.
     try:
         schema, remaining = url.split(':', 1)
     except ValueError:
-        msg = 'charm URL has no schema: {}'.format(url)
+        msg = 'URL has no schema: {}'.format(url)
         raise ValueError(msg.encode('utf-8'))
     if schema not in ('cs', 'local'):
-        msg = 'charm URL has invalid schema: {}'.format(schema)
+        msg = 'URL has invalid schema: {}'.format(schema)
         raise ValueError(msg.encode('utf-8'))
     # Retrieve the optional user, the series, name and revision.
     parts = remaining.split('/')
@@ -52,82 +218,37 @@
     if parts_length == 3:
         user, series, name_revision = parts
         if not user.startswith('~'):
-            msg = 'charm URL has invalid user name form: {}'.format(user)
+            msg = 'URL has invalid user name form: {}'.format(user)
             raise ValueError(msg.encode('utf-8'))
         user = user[1:]
-        if not valid_user(user):
-            msg = 'charm URL has invalid user name: {}'.format(user)
+        if not _valid_user(user):
+            msg = 'URL has invalid user name: {}'.format(user)
             raise ValueError(msg.encode('utf-8'))
         if schema == 'local':
-            msg = 'local charm URL with user name: {}'.format(url)
+            msg = 'local entity URL with user name: {}'.format(url)
             raise ValueError(msg.encode('utf-8'))
     elif parts_length == 2:
         user = ''
         series, name_revision = parts
     else:
-        msg = 'charm URL has invalid form: {}'.format(url)
+        msg = 'URL has invalid form: {}'.format(url)
         raise ValueError(msg.encode('utf-8'))
     # Validate the series.
-    if not valid_series(series):
-        msg = 'charm URL has invalid series: {}'.format(series)
+    if not _valid_series(series):
+        msg = 'URL has invalid series: {}'.format(series)
         raise ValueError(msg.encode('utf-8'))
     # Validate name and revision.
     try:
         name, revision = name_revision.rsplit('-', 1)
     except ValueError:
-        msg = 'charm URL has no revision: {}'.format(url)
+        msg = 'URL has no revision: {}'.format(url)
         raise ValueError(msg.encode('utf-8'))
-    if not valid_name(name):
-        msg = 'charm URL has invalid name: {}'.format(name)
+    if not _valid_name(name):
+        msg = 'URL has invalid name: {}'.format(name)
         raise ValueError(msg.encode('utf-8'))
     try:
         revision = int(revision)
     except ValueError:
-        msg = 'charm URL has invalid revision: {}'.format(revision)
+        msg = 'URL has invalid revision: {}'.format(revision)
         raise ValueError(msg.encode('utf-8'))
     return schema, user, series, name, revision
-
-
-class Charm(object):
-    """Represent the charm information stored in the charm URL."""
-
-    def __init__(self, schema, user, series, name, revision):
-        """Initialize the charm. Receives the URL fragments."""
-        self.schema = schema
-        self.user = user
-        self.series = series
-        self.name = name
-        self.revision = int(revision)
-
-    @classmethod
-    def from_url(cls, url):
-        """Given a charm URL, create and return a Charm instance.
-
-        Raise a ValueError if the charm URL is not valid.
-        """
-        return cls(*parse_url(url))
-
-    def __str__(self):
-        """The string representation of a charm is its URL."""
-        return self.__unicode__().encode('utf-8')
-
-    def __unicode__(self):
-        """The unicode representation of a charm is its URL."""
-        return self.url()
-
-    def __repr__(self):
-        return b'<Charm: {}>'.format(bytes(self))
-
-    def __eq__(self, other):
-        """Two charms are equal if they have the same URL."""
-        return isinstance(other, self.__class__) and self.url() == other.url()
-
-    def url(self):
-        """Return the charm URL."""
-        user_part = '~{}/'.format(self.user) if self.user else ''
-        return '{}:{}{}/{}-{}'.format(
-            self.schema, user_part, self.series, self.name, self.revision)
-
-    def is_local(self):
-        """Return True if this is a local charm, False otherwise."""
-        return self.schema == 'local'
 
=== modified file 'quickstart/netutils.py'
--- quickstart/netutils.py	2015-01-12 15:00:52 +0000
+++ quickstart/netutils.py	2015-02-27 18:40:58 +0000
@@ -69,8 +69,8 @@
     Raise an IOError if any problems occur connecting to the API endpoint.
     Raise a ValueError if the API returns invalid data.
     """
-    url = settings.CHARMSTORE_API.format(
-        series=series, charm=settings.JUJU_GUI_CHARM_NAME)
+    url = '{}{}/{}/meta/id'.format(
+        settings.CHARMSTORE_API, series, settings.JUJU_GUI_CHARM_NAME)
     data = json.loads(urlread(url))
     charm_url = data.get('Id')
     if charm_url is None:
 
=== modified file 'quickstart/settings.py'
--- quickstart/settings.py	2015-02-09 15:56:20 +0000
+++ quickstart/settings.py	2015-02-27 18:40:58 +0000
@@ -29,11 +29,8 @@
 UNKNOWN_PLATFORM = object()
 WINDOWS = object()
 
-# The base charm store API URL containing information about charms.
-# This URL must be formatted with a series and a charm name.
-CHARMSTORE_API = (
-    'https://api.jujucharms.com'
-    '/charmstore/v4/{series}/{charm}/meta/id')
+# The base charm store API URL containing information about charms and bundles.
+CHARMSTORE_API = 'https://api.jujucharms.com/charmstore/v4/'
 
 # The default Juju GUI charm URLs for each supported series. Used when it is
 # not possible to retrieve the charm URL from the charm store API, e.g. due to
@@ -47,8 +44,8 @@
 # The quickstart app short description.
 DESCRIPTION = 'set up a Juju environment (including the GUI) in very few steps'
 
-# The URL namespace for bundles in jujucharms.com.
-JUJUCHARMS_BUNDLE_URL = 'https://jujucharms.com/bundle/'
+# The URL of jujucharms.com, the home of Juju.
+JUJUCHARMS_URL = 'https://jujucharms.com/'
 
 # The path to the Juju command, based on platform.
 JUJU_CMD_PATHS = {
 
=== modified file 'quickstart/tests/functional/test_functional.py'
--- quickstart/tests/functional/test_functional.py	2015-02-05 12:19:48 +0000
+++ quickstart/tests/functional/test_functional.py	2015-02-27 18:40:58 +0000
@@ -167,7 +167,7 @@
     def test_bundle_deployment(self):
         # The application can be used to deploy bundles.
         retcode, output, error = run_quickstart(
-            self.env_name, 'bundle:mediawiki/single')
+            self.env_name, 'mediawiki-single')
         self.assertEqual(0, retcode)
         self.assertIn('bundle deployment request accepted', output)
         self.assertEqual('', error)
 
=== modified file 'quickstart/tests/helpers.py'
--- quickstart/tests/helpers.py	2015-02-09 11:22:44 +0000
+++ quickstart/tests/helpers.py	2015-02-27 18:40:58 +0000
@@ -47,15 +47,18 @@
 class BundleFileTestsMixin(object):
     """Shared methods for testing Juju bundle files."""
 
-    valid_bundle = yaml.safe_dump({
+    bundle_data = {'services': {'wordpress': {}, 'mysql': {}}}
+    bundle_content = yaml.safe_dump(bundle_data)
+    legacy_bundle_data = {
         'bundle1': {'services': {'wordpress': {}, 'mysql': {}}},
         'bundle2': {'services': {'django': {}, 'nodejs': {}}},
-    })
+    }
+    legacy_bundle_content = yaml.safe_dump(legacy_bundle_data)
 
     def _write_bundle_file(self, bundle_file, contents):
         """Parse and write contents into the given bundle file object."""
         if contents is None:
-            contents = self.valid_bundle
+            contents = self.bundle_content
         elif isinstance(contents, dict):
             contents = yaml.safe_dump(contents)
         bundle_file.write(contents)
@@ -64,31 +67,15 @@
         """Create a Juju bundle file containing the given contents.
 
         If contents is None, use the valid bundle contents defined in
-        self.valid_bundle.
+        self.bundle_content.
         Return the bundle file path.
         """
-        bundle_file = tempfile.NamedTemporaryFile(delete=False)
+        bundle_file = tempfile.NamedTemporaryFile(delete=False, suffix='.yaml')
         self.addCleanup(os.remove, bundle_file.name)
         self._write_bundle_file(bundle_file, contents)
         bundle_file.close()
         return bundle_file.name
 
-    def make_bundle_dir(self, contents=None):
-        """Create a Juju bundle directory including a bundles.yaml file.
-
-        The file will contain the given contents.
-
-        If contents is None, use the valid bundle contents defined in
-        self.valid_bundle.
-        Return the bundle directory path.
-        """
-        bundle_dir = tempfile.mkdtemp()
-        self.addCleanup(shutil.rmtree, bundle_dir)
-        bundle_path = os.path.join(bundle_dir, 'bundles.yaml')
-        with open(bundle_path, 'w') as bundle_file:
-            self._write_bundle_file(bundle_file, contents)
-        return bundle_dir
-
 
 class CallTestsMixin(object):
     """Easily use the quickstart.utils.call function."""
 
=== modified file 'quickstart/tests/models/test_bundles.py'
--- quickstart/tests/models/test_bundles.py	2015-02-09 12:58:04 +0000
+++ quickstart/tests/models/test_bundles.py	2015-02-27 18:40:58 +0000
@@ -24,231 +24,419 @@
 import yaml
 
 from quickstart import settings
-from quickstart.models import bundles
+from quickstart.models import (
+    bundles,
+    references,
+)
 from quickstart.tests import helpers
 
 
-class TestConvertBundleUrl(helpers.ValueErrorTestsMixin, unittest.TestCase):
-
-    def test_full_bundle_url(self):
-        # The HTTPS location to the YAML contents is correctly returned.
-        bundle_url = 'bundle:~myuser/wiki-bundle/42/wiki'
-        url, bundle_id = bundles.convert_bundle_url(bundle_url)
-        self.assertEqual(
-            'https://manage.jujucharms.com'
-            '/bundle/~myuser/wiki-bundle/42/wiki/json', url)
-        self.assertEqual('~myuser/wiki-bundle/42/wiki', bundle_id)
-
-    def test_bundle_url_right_strip(self):
-        # The trailing slash in the bundle URL is removed.
-        bundle_url = 'bundle:~myuser/wiki-bundle/42/wiki/'
-        url, bundle_id = bundles.convert_bundle_url(bundle_url)
-        self.assertEqual(
-            'https://manage.jujucharms.com'
-            '/bundle/~myuser/wiki-bundle/42/wiki/json', url)
-        self.assertEqual('~myuser/wiki-bundle/42/wiki', bundle_id)
-
-    def test_bundle_url_no_revision(self):
-        # The bundle revision is optional.
-        bundle_url = 'bundle:~myuser/wiki-bundle/wiki-simple'
-        url, bundle_id = bundles.convert_bundle_url(bundle_url)
-        self.assertEqual(
-            'https://manage.jujucharms.com'
-            '/bundle/~myuser/wiki-bundle/wiki-simple/json', url)
-        self.assertEqual('~myuser/wiki-bundle/wiki-simple', bundle_id)
-
-    def test_bundle_url_no_user(self):
-        # If the bundle user is not specified, the bundle is assumed to be
-        # promulgated and owned by "charmers".
-        bundle_url = 'bundle:wiki-bundle/1/wiki'
-        url, bundle_id = bundles.convert_bundle_url(bundle_url)
-        self.assertEqual(
-            'https://manage.jujucharms.com'
-            '/bundle/~charmers/wiki-bundle/1/wiki/json', url)
-        self.assertEqual('~charmers/wiki-bundle/1/wiki', bundle_id)
-
-    def test_bundle_url_short_form(self):
-        # A promulgated bundle URL can just include the basket and the name.
-        bundle_url = 'bundle:wiki-bundle/wiki'
-        url, bundle_id = bundles.convert_bundle_url(bundle_url)
-        self.assertEqual(
-            'https://manage.jujucharms.com'
-            '/bundle/~charmers/wiki-bundle/wiki/json', url)
-        self.assertEqual('~charmers/wiki-bundle/wiki', bundle_id)
-
-    def test_full_jujucharms_url(self):
-        # The HTTPS location to the YAML contents is correctly returned.
-        url, bundle_id = bundles.convert_bundle_url(
-            settings.JUJUCHARMS_BUNDLE_URL + '~myuser/wiki-bundle/42/wiki')
-        self.assertEqual(
-            'https://manage.jujucharms.com'
-            '/bundle/~myuser/wiki-bundle/42/wiki/json', url)
-        self.assertEqual('~myuser/wiki-bundle/42/wiki', bundle_id)
-
-    def test_jujucharms_url_right_strip(self):
-        # The trailing slash in the jujucharms URL is removed.
-        url, bundle_id = bundles.convert_bundle_url(
-            settings.JUJUCHARMS_BUNDLE_URL + '~charmers/mediawiki/6/scalable/')
-        self.assertEqual(
-            'https://manage.jujucharms.com'
-            '/bundle/~charmers/mediawiki/6/scalable/json', url)
-        self.assertEqual('~charmers/mediawiki/6/scalable', bundle_id)
-
-    def test_jujucharms_url_no_revision(self):
-        # The bundle revision is optional.
-        url, bundle_id = bundles.convert_bundle_url(
-            settings.JUJUCHARMS_BUNDLE_URL + '~myuser/wiki/wiki-simple/')
-        self.assertEqual(
-            'https://manage.jujucharms.com'
-            '/bundle/~myuser/wiki/wiki-simple/json', url)
-        self.assertEqual('~myuser/wiki/wiki-simple', bundle_id)
-
-    def test_jujucharms_url_no_user(self):
-        # If the bundle user is not specified, the bundle is assumed to be
-        # promulgated and owned by "charmers".
-        url, bundle_id = bundles.convert_bundle_url(
-            settings.JUJUCHARMS_BUNDLE_URL + 'mediawiki/42/single/')
-        self.assertEqual(
-            'https://manage.jujucharms.com'
-            '/bundle/~charmers/mediawiki/42/single/json', url)
-        self.assertEqual('~charmers/mediawiki/42/single', bundle_id)
-
-    def test_jujucharms_url_short_form(self):
-        # A jujucharms URL for a promulgated bundle can just include the basket
-        # and the name.
-        url, bundle_id = bundles.convert_bundle_url(
-            settings.JUJUCHARMS_BUNDLE_URL + 'wiki-bundle/wiki/')
-        self.assertEqual(
-            'https://manage.jujucharms.com'
-            '/bundle/~charmers/wiki-bundle/wiki/json', url)
-        self.assertEqual('~charmers/wiki-bundle/wiki', bundle_id)
-
-    def test_error(self):
-        # A ValueError is raised if the bundle/jujucharms URL is not valid.
-        bad_urls = (
-            'bad', 'bundle:', 'bundle:~user', 'bundle:no-such',
-            'bundle:~user/name', 'bundle:~user/basket/revision/name',
-            'bundle:basket/name//', 'bundle:basket.name/bundle.name',
-            settings.JUJUCHARMS_BUNDLE_URL,
-            settings.JUJUCHARMS_BUNDLE_URL + 'bad',
-            settings.JUJUCHARMS_BUNDLE_URL + '~user/no-such',
-            settings.JUJUCHARMS_BUNDLE_URL + '~user/basket/revision/name/',
-            settings.JUJUCHARMS_BUNDLE_URL + '~user/basket/42/name/error',
-            'https://jujucharms.com/charms/mediawiki/simple/',
-        )
-        for url in bad_urls:
-            with self.assert_value_error('invalid bundle URL: {}'.format(url)):
-                bundles.convert_bundle_url(url)
-
-
-class TestParseBundle(
+class TestBundle(helpers.BundleFileTestsMixin, unittest.TestCase):
+
+    reference = references.Reference.from_jujucharms_url('django')
+
+    def setUp(self):
+        # Create a bundle instance.
+        self.bundle = bundles.Bundle(
+            self.bundle_data, reference=self.reference)
+
+    def test_attributes(self):
+        # The bundle data and the optional reference are stored as attributes.
+        self.assertEqual(self.bundle_data, self.bundle.data)
+        self.assertEqual(self.reference, self.bundle.reference)
+
+    def test_string(self):
+        # The bundle correctly represents itself as a string.
+        self.assertEqual('bundle django', str(self.bundle))
+        # Create a bundle without a reference.
+        bundle = bundles.Bundle(self.bundle_data)
+        self.assertEqual('bundle', str(bundle))
+
+    def test_repr(self):
+        # The bundle correctly represents itself as an object.
+        self.assertEqual('<Bundle: bundle django>', repr(self.bundle))
+        # Create a bundle without a reference.
+        bundle = bundles.Bundle(self.bundle_data)
+        self.assertEqual('<Bundle: bundle>', repr(bundle))
+
+    def test_serialization(self):
+        # The bundle data is correctly serialized into a YAML encoded string.
+        content = self.bundle.serialize()
+        self.assertEqual('services:\n  mysql: {}\n  wordpress: {}\n', content)
+
+    def test_legacy_serialization(self):
+        # The bundle data can be serialized for legacy API version 3.
+        content = self.bundle.serialize_legacy()
+        self.assertEqual(
+            'bundle:\n  services:\n    mysql: {}\n    wordpress: {}\n',
+            content)
+
+    def test_services(self):
+        # Bundle services can be easily retrieved.
+        self.assertEqual(['mysql', 'wordpress'], self.bundle.services())
+
+
+class TestFromSource(
+        helpers.BundleFileTestsMixin, helpers.UrlReadTestsMixin,
+        helpers.ValueErrorTestsMixin, unittest.TestCase):
+
+    def test_charmworld_bundle(self):
+        # A bundle instance is properly returned from a charmworld id source.
+        with self.patch_urlread(contents=self.bundle_content) as mock_urlread:
+            bundle = bundles.from_source('bundle:mediawiki/single')
+        self.assertEqual(self.bundle_data, bundle.data)
+        self.assertEqual('cs:bundle/mediawiki-single', bundle.reference.id())
+        mock_urlread.assert_called_once_with(
+            settings.CHARMSTORE_API +
+            'bundle/mediawiki-single/archive/bundle.yaml')
+
+    def test_charmworld_bundle_with_user_and_revision(self):
+        # A specific revision of a user owned bundle is properly returned from
+        # a charmworld id source.
+        with self.patch_urlread(contents=self.bundle_content) as mock_urlread:
+            bundle = bundles.from_source('bundle:~who/mediawiki/42/single')
+        self.assertEqual(self.bundle_data, bundle.data)
+        self.assertEqual(
+            'cs:~who/bundle/mediawiki-single-42', bundle.reference.id())
+        mock_urlread.assert_called_once_with(
+            settings.CHARMSTORE_API +
+            '~who/bundle/mediawiki-single-42/archive/bundle.yaml')
+
+    def test_charmworld_bundle_deprecation_warning(self):
+        # A deprecation warning is printed if the no longer supported
+        # charmworld bundle identifiers are used.
+        expected_logs = [
+            'this bundle URL is deprecated: please use the new format: '
+            'mediawiki-single']
+        with self.patch_urlread(contents=self.bundle_content):
+            with helpers.assert_logs(expected_logs, 'warn'):
+                bundles.from_source('bundle:mediawiki/single')
+
+    def test_charmworld_bundle_invalid_url(self):
+        # A ValueError is raised if the provided charmworld id is not valid.
+        with self.assert_value_error('invalid bundle URL: bundle:invalid'):
+            bundles.from_source('bundle:invalid')
+
+    def test_charmworld_bundle_invalid_content(self):
+        # A ValueError is raised if the content associated with the given
+        # charmworld URL are not valid.
+        with self.patch_urlread(error=True):
+            with self.assertRaises(IOError) as ctx:
+                bundles.from_source('bundle:mediawiki/single')
+        expected_error = (
+            'cannot retrieve bundle from remote URL '
+            '{}bundle/mediawiki-single/archive/bundle.yaml: '
+            'bad wolf'.format(settings.CHARMSTORE_API))
+        self.assertEqual(expected_error, bytes(ctx.exception))
+
+    def test_charmworld_bundle_connection_error(self):
+        # An IOError is raised if a connection problem is encountered while
+        # retrieving the charmworld bundle.
+        with self.patch_urlread(contents='exterminate!'):
+            with self.assert_value_error('invalid YAML content: exterminate!'):
+                bundles.from_source('bundle:mediawiki/single')
+
+    def test_jujucharms_bundle(self):
+        # A bundle instance is properly returned from a jujucharms.com id.
+        with self.patch_urlread(contents=self.bundle_content) as mock_urlread:
+            bundle = bundles.from_source('django')
+        self.assertEqual(self.bundle_data, bundle.data)
+        self.assertEqual('cs:bundle/django', bundle.reference.id())
+        mock_urlread.assert_called_once_with(
+            settings.CHARMSTORE_API + 'bundle/django/archive/bundle.yaml')
+
+    def test_jujucharms_bundle_with_user_and_revision(self):
+        # A specific revision of a user owned bundle is properly returned from
+        # a jujucharms.com id source.
+        with self.patch_urlread(contents=self.bundle_content) as mock_urlread:
+            bundle = bundles.from_source('u/who/mediawiki-single/42')
+        self.assertEqual(self.bundle_data, bundle.data)
+        self.assertEqual(
+            'cs:~who/bundle/mediawiki-single-42', bundle.reference.id())
+        mock_urlread.assert_called_once_with(
+            settings.CHARMSTORE_API +
+            '~who/bundle/mediawiki-single-42/archive/bundle.yaml')
+
+    def test_jujucharms_bundle_charm_error(self):
+        # A ValueError is raised if the given jujucharms.com id refers to a
+        # charm and not to a bundle.
+        expected_error = 'expected a bundle, provided charm cs:trusty/django'
+        with self.assert_value_error(expected_error):
+            bundles.from_source('django/trusty')
+
+    def test_jujucharms_bundle_invalid_url(self):
+        # A ValueError is raised if the provided jujucharms.com identifier is
+        # not valid.
+        with self.assert_value_error('invalid bundle URL: u/no/such/bundle/!'):
+            bundles.from_source('u/no/such/bundle/!')
+
+    def test_jujucharms_bundle_invalid_content(self):
+        # A ValueError is raised if the content associated with the given
+        # jujucharms.com URL are not valid.
+        with self.patch_urlread(error=True):
+            with self.assertRaises(IOError) as ctx:
+                bundles.from_source('django/42')
+        expected_error = (
+            'cannot retrieve bundle from remote URL '
+            '{}bundle/django-42/archive/bundle.yaml: '
+            'bad wolf'.format(settings.CHARMSTORE_API))
+        self.assertEqual(expected_error, bytes(ctx.exception))
+
+    def test_jujucharms_bundle_connection_error(self):
+        # An IOError is raised if a connection problem is encountered while
+        # retrieving the jujucharms.com bundle.
+        with self.patch_urlread(contents='exterminate!'):
+            with self.assert_value_error('invalid YAML content: exterminate!'):
+                bundles.from_source('wordpress-scalable')
+
+    def test_local_file(self):
+        # A bundle instance can be created from a local file source.
+        # In this case, the resulting bundle does not have a reference.
+        path = self.make_bundle_file()
+        bundle = bundles.from_source(path)
+        self.assertEqual(self.bundle_data, bundle.data)
+        self.assertIsNone(bundle.reference)
+
+    def test_local_file_legacy_bundle(self):
+        # A bundle instance can be created from a local file source including
+        # a legacy version 3 bundle.
+        # In this case, the resulting bundle does not have a reference.
+        legacy_bundle_data = {
+            'bundle': {'services': {'wordpress': {}, 'mysql': {}}},
+        }
+        path = self.make_bundle_file(legacy_bundle_data)
+        bundle = bundles.from_source(path)
+        self.assertEqual(legacy_bundle_data['bundle'], bundle.data)
+        self.assertIsNone(bundle.reference)
+
+    def test_local_file_not_found(self):
+        # An IOError is raised if a local file source cannot be found.
+        with self.assertRaises(IOError) as ctx:
+            bundles.from_source('/no/such/file.yaml')
+        expected_error = (
+            'cannot retrieve bundle from local file: '
+            "[Errno 2] No such file or directory: '/no/such/file.yaml'")
+        self.assertEqual(expected_error, bytes(ctx.exception))
+
+    def test_local_file_legacy_bundle_no_bundles_error(self):
+        # A ValueError is raised if a local file contains a legacy version 3
+        # YAML content with no bundles defined.
+        path = self.make_bundle_file({})
+        expected_error = 'no bundles found in the provided list of bundles'
+        with self.assert_value_error(expected_error):
+            bundles.from_source(path)
+
+    def test_local_file_legacy_bundle_multiple_bundles_error(self):
+        # A ValueError is raised if a local file contains a legacy version 3
+        # YAML content with multiple bundles defined and the bundle name is
+        # not provided for disambiguation.
+        path = self.make_bundle_file(self.legacy_bundle_content)
+        expected_error = (
+            'multiple bundles found (bundle1, bundle2) '
+            'but no bundle name specified')
+        with self.assert_value_error(expected_error):
+            bundles.from_source(path)
+
+    def test_local_file_legacy_bundle_multiple_bundles_name_not_found(self):
+        # A ValueError is raised if a local file contains a legacy version 3
+        # YAML content with multiple bundles defined and the provided bundle
+        # name is not included in the list.
+        path = self.make_bundle_file(self.legacy_bundle_content)
+        expected_error = (
+            'bundle mybundle not found in the provided list of bundles '
+            '(bundle1, bundle2)')
+        with self.assert_value_error(expected_error):
+            bundles.from_source(path, 'mybundle')
+
+    def test_local_file_legacy_bundle_invalid_bundle_content(self):
+        # A ValueError is raised if a local file contains an invalid legacy
+        # version 3 content.
+        path = self.make_bundle_file({'bundle': '42'})
+        expected_error = "unable to retrieve bundle services: '42'"
+        with self.assert_value_error(expected_error):
+            bundles.from_source(path, 'bundle')
+
+    def test_remote_url(self):
+        # A bundle instance can be created from an arbitrary remote URL
+        # pointing to a valid YAML/JSON content.
+        # In this case, the resulting bundle does not have a reference.
+        with self.patch_urlread(contents=self.bundle_content) as mock_urlread:
+            bundle = bundles.from_source('https://1.2.3.4')
+        self.assertEqual(self.bundle_data, bundle.data)
+        self.assertIsNone(bundle.reference)
+        mock_urlread.assert_called_once_with('https://1.2.3.4')
+
+    def test_remote_url_legacy_bundle(self):
+        # A bundle instance can be created from an arbitrary remote URL
+        # pointing to a legacy version 3 content.
+        # In this case, the resulting bundle does not have a reference.
+        content = self.legacy_bundle_content
+        with self.patch_urlread(contents=content) as mock_urlread:
+            bundle = bundles.from_source('https://1.2.3.4:8000', 'bundle2')
+        self.assertEqual(self.legacy_bundle_data['bundle2'], bundle.data)
+        self.assertIsNone(bundle.reference)
+        mock_urlread.assert_called_once_with('https://1.2.3.4:8000')
+
+    def test_remote_url_not_reachable(self):
+        # An IOError is raised if a network problem is encountered while
+        # trying to reach the remote URL.
+        with self.patch_urlread(error=True):
+            with self.assertRaises(IOError) as ctx:
+                bundles.from_source('https://1.2.3.4')
+        expected_error = (
+            'cannot retrieve bundle from remote URL https://1.2.3.4: bad wolf')
+        self.assertEqual(expected_error, bytes(ctx.exception))
+
+    def test_remote_url_legacy_bundle_no_bundles_error(self):
+        # A ValueError is raised if a remote URL contains a legacy version 3
+        # YAML content with no bundles defined.
+        expected_error = 'no bundles found in the provided list of bundles'
+        with self.patch_urlread(contents='{}'):
+            with self.assert_value_error(expected_error):
+                bundles.from_source('http://1.2.3.4')
+
+    def test_remote_url_legacy_bundle_multiple_bundles_error(self):
+        # A ValueError is raised if a remote URL contains a legacy version 3
+        # YAML content with multiple bundles defined and the bundle name is
+        # not provided for disambiguation.
+        expected_error = (
+            'multiple bundles found (bundle1, bundle2) '
+            'but no bundle name specified')
+        with self.patch_urlread(contents=self.legacy_bundle_content):
+            with self.assert_value_error(expected_error):
+                bundles.from_source('http://1.2.3.4')
+
+    def test_remote_url_legacy_bundle_multiple_bundles_name_not_found(self):
+        # A ValueError is raised if a remote URL contains a legacy version 3
+        # YAML content with multiple bundles defined and the provided bundle
+        # name is not included in the list.
+        expected_error = (
+            'bundle no-such not found in the provided list of bundles '
+            '(bundle1, bundle2)')
+        with self.patch_urlread(contents=self.legacy_bundle_content):
+            with self.assert_value_error(expected_error):
+                bundles.from_source('http://1.2.3.4', 'no-such')
+
+    def test_remote_url_legacy_bundle_invalid_bundle_content(self):
+        # A ValueError is raised if a remote URL contains an invalid legacy
+        # version 3 content.
+        with self.patch_urlread(contents='bad wolf'):
+            with self.assert_value_error('invalid YAML content: bad wolf'):
+                bundles.from_source('http://1.2.3.4', 'bundle')
+
+
+class TestParseYAML(
         helpers.BundleFileTestsMixin, helpers.ValueErrorTestsMixin,
         unittest.TestCase):
 
-    def assert_bundle(
-            self, expected_name, expected_services, contents,
-            bundle_name=None):
-        """Ensure parsing the given contents returns the expected values."""
-        name, services = bundles.parse_bundle(
-            contents, bundle_name=bundle_name)
-        self.assertEqual(expected_name, name)
-        self.assertEqual(set(expected_services), set(services))
-
     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:
-            bundles.parse_bundle(':')
+        # A ValueError is raised if the bundle content is not a valid YAML.
+        with self.assertRaises(ValueError) as ctx:
+            bundles.parse_yaml(':')
         expected = 'unable to parse the bundle'
-        self.assertIn(expected, bytes(context_manager.exception))
+        self.assertIn(expected, bytes(ctx.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'):
-            bundles.parse_bundle('a-string')
+        # A ValueError is raised if the bundle content is not well formed.
+        with self.assert_value_error('invalid YAML content: a-string'):
+            bundles.parse_yaml('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}\n'
-        with self.assert_value_error(expected):
-            bundles.parse_bundle(contents)
+        # A ValueError is raised if the bundle content is not well formed.
+        contents = yaml.safe_dump('not valid')
+        with self.assert_value_error('invalid YAML content: not valid'):
+            bundles.parse_yaml(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: {}\n'
-        with self.assert_value_error(expected):
-            bundles.parse_bundle(contents)
+    def test_yaml_no_services(self):
+        # A ValueError is raised if the bundle does not include services.
+        contents = yaml.safe_dump({})
+        with self.assert_value_error('unable to retrieve bundle services: {}'):
+            bundles.parse_yaml(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: null}\n'
+        contents = yaml.safe_dump({'services': None})
+        expected = 'unable to retrieve bundle services: services: null'
         with self.assert_value_error(expected):
-            bundles.parse_bundle(contents)
+            bundles.parse_yaml(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}\n'
-        with self.assert_value_error(expected):
-            bundles.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'):
-            bundles.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):
-            bundles.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):
-            bundles.parse_bundle(self.valid_bundle, 'no-such')
+        contents = yaml.safe_dump({'services': 42})
+        expected = 'unable to retrieve bundle services: services: 42'
+        with self.assert_value_error(expected):
+            bundles.parse_yaml(contents)
 
     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):
-            bundles.parse_bundle(contents)
+        contents = yaml.safe_dump({'services': {}})
+        with self.assert_value_error('no services found in the bundle'):
+            bundles.parse_yaml(contents)
 
     def test_yaml_gui_in_services(self):
         # A ValueError is raised if the bundle contains juju-gui.
         contents = yaml.safe_dump({
-            'mybundle': {'services': {settings.JUJU_GUI_SERVICE_NAME: {}}},
-        })
-        expected = 'bundle mybundle contains an instance of juju-gui. ' \
-            'quickstart will install the latest version of the Juju GUI ' \
-            'automatically, please remove juju-gui from the bundle.'
-        with self.assert_value_error(expected):
-            bundles.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': {}}},
-        })
-        self.assert_bundle('mybundle', ['mysql', 'wordpress'], contents)
-
-    def test_success_multiple_bundles(self):
-        # The function succeeds with multiple bundles.
-        self.assert_bundle(
-            'bundle2', ['django', 'nodejs'], self.valid_bundle, 'bundle2')
+            'services': {settings.JUJU_GUI_SERVICE_NAME: {}},
+        })
+        expected_error = (
+            'the provided bundle contains an instance of juju-gui. Juju '
+            'Quickstart will install the latest version of the Juju GUI '
+            'automatically; please remove juju-gui from the bundle')
+        with self.assert_value_error(expected_error):
+            bundles.parse_yaml(contents)
+
+    def test_success(self):
+        # The function succeeds when a valid bundle content is provided.
+        data = bundles.parse_yaml(self.bundle_content)
+        self.assertEqual(self.bundle_data, data)
 
     def test_success_json(self):
         # Since JSON is a subset of YAML, the function also support JSON
         # encoded bundles.
-        contents = json.dumps({
-            'mybundle': {'services': {'wordpress': {}, 'mysql': {}}},
-        })
-        self.assert_bundle('mybundle', ['mysql', 'wordpress'], contents)
+        content = json.dumps(self.bundle_data)
+        data = bundles.parse_yaml(content)
+        self.assertEqual(self.bundle_data, data)
+
+
+class TestValidate(
+        helpers.BundleFileTestsMixin, helpers.ValueErrorTestsMixin,
+        unittest.TestCase):
+
+    def test_yaml_no_services(self):
+        # A ValueError is raised if the bundle does not include services.
+        with self.assert_value_error('unable to retrieve bundle services: {}'):
+            bundles.validate({})
+
+    def test_yaml_none_bundle_services(self):
+        # A ValueError is raised if services are None.
+        expected = 'unable to retrieve bundle services: services: null'
+        with self.assert_value_error(expected):
+            bundles.validate({'services': None})
+
+    def test_yaml_invalid_bundle_services_type(self):
+        # A ValueError is raised if services have an invalid type.
+        expected = 'unable to retrieve bundle services: services: 42'
+        with self.assert_value_error(expected):
+            bundles.validate({'services': 42})
+
+    def test_no_services(self):
+        # A ValueError is raised if the specified bundle does not contain
+        # services.
+        with self.assert_value_error('no services found in the bundle'):
+            bundles.validate({'services': {}})
+
+    def test_yaml_gui_in_services(self):
+        # A ValueError is raised if the bundle contains juju-gui.
+        expected_error = (
+            'the provided bundle contains an instance of juju-gui. Juju '
+            'Quickstart will install the latest version of the Juju GUI '
+            'automatically; please remove juju-gui from the bundle')
+        with self.assert_value_error(expected_error):
+            bundles.validate({
+                'services': {settings.JUJU_GUI_SERVICE_NAME: {}},
+            })
+
+    def test_success(self):
+        # The function succeeds when a valid bundle content is provided.
+        bundles.validate(self.bundle_data)
 
=== renamed file 'quickstart/tests/models/test_charms.py' => 'quickstart/tests/models/test_references.py'
--- quickstart/tests/models/test_charms.py	2015-02-09 18:00:33 +0000
+++ quickstart/tests/models/test_references.py	2015-02-27 18:40:58 +0000
@@ -14,222 +14,424 @@
 # You should have received a copy of the GNU Affero General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-"""Tests for the Juju Quickstart charms management."""
+"""Tests for the Juju Quickstart charm and bundle references management."""
 
 from __future__ import unicode_literals
 
 import unittest
 
-from quickstart.models import charms
+from quickstart import settings
+from quickstart.models import references
 from quickstart.tests import helpers
 
 
-class TestParseUrl(helpers.ValueErrorTestsMixin, unittest.TestCase):
+def make_reference(
+        schema='cs', user='myuser', series='precise', name='juju-gui',
+        revision=42):
+    """Create and return a Reference instance."""
+    return references.Reference(schema, user, series, name, revision)
+
+
+class TestReference(unittest.TestCase):
+
+    def test_attributes(self):
+        # All reference attributes are correctly stored.
+        ref = make_reference()
+        self.assertEqual('cs', ref.schema)
+        self.assertEqual('myuser', ref.user)
+        self.assertEqual('precise', ref.series)
+        self.assertEqual('juju-gui', ref.name)
+        self.assertEqual(42, ref.revision)
+
+    def test_revision_as_string(self):
+        # The reference revision is converted to an int.
+        ref = make_reference(revision='47')
+        self.assertEqual(47, ref.revision)
+
+    def test_string(self):
+        # The string representation of a reference is its URL.
+        tests = (
+            (make_reference(),
+             'cs:~myuser/precise/juju-gui-42'),
+            (make_reference(schema='local'),
+             'local:~myuser/precise/juju-gui-42'),
+            (make_reference(user=''),
+             'cs:precise/juju-gui-42'),
+            (make_reference(user='dalek', revision=None, series='bundle'),
+             'cs:~dalek/bundle/juju-gui'),
+            (make_reference(name='django', series='vivid', revision=0),
+             'cs:~myuser/vivid/django-0'),
+            (make_reference(user='', revision=None),
+             'cs:precise/juju-gui'),
+        )
+        for ref, expected_value in tests:
+            self.assertEqual(expected_value, bytes(ref))
+
+    def test_repr(self):
+        # A reference is correctly represented.
+        tests = (
+            (make_reference(),
+             '<Reference: cs:~myuser/precise/juju-gui-42>'),
+            (make_reference(schema='local'),
+             '<Reference: local:~myuser/precise/juju-gui-42>'),
+            (make_reference(user=''),
+             '<Reference: cs:precise/juju-gui-42>'),
+            (make_reference(user='dalek', revision=None, series='bundle'),
+             '<Reference: cs:~dalek/bundle/juju-gui>'),
+            (make_reference(name='django', series='vivid', revision=0),
+             '<Reference: cs:~myuser/vivid/django-0>'),
+            (make_reference(user='', revision=None),
+             '<Reference: cs:precise/juju-gui>'),
+        )
+        for ref, expected_value in tests:
+            self.assertEqual(expected_value, repr(ref))
+
+    def test_path(self):
+        # The reference path is properly returned as a URL string without the
+        # schema.
+        tests = (
+            (make_reference(),
+             '~myuser/precise/juju-gui-42'),
+            (make_reference(schema='local'),
+             '~myuser/precise/juju-gui-42'),
+            (make_reference(user=''),
+             'precise/juju-gui-42'),
+            (make_reference(user='dalek', revision=None, series='bundle'),
+             '~dalek/bundle/juju-gui'),
+            (make_reference(name='django', series='vivid', revision=0),
+             '~myuser/vivid/django-0'),
+            (make_reference(user='', revision=None),
+             'precise/juju-gui'),
+        )
+        for ref, expected_value in tests:
+            self.assertEqual(expected_value, ref.path())
+
+    def test_id(self):
+        # The reference id is correctly returned.
+        tests = (
+            (make_reference(),
+             'cs:~myuser/precise/juju-gui-42'),
+            (make_reference(schema='local'),
+             'local:~myuser/precise/juju-gui-42'),
+            (make_reference(user=''),
+             'cs:precise/juju-gui-42'),
+            (make_reference(user='dalek', revision=None, series='bundle'),
+             'cs:~dalek/bundle/juju-gui'),
+            (make_reference(name='django', series='vivid', revision=0),
+             'cs:~myuser/vivid/django-0'),
+            (make_reference(user='', revision=None),
+             'cs:precise/juju-gui'),
+        )
+        for ref, expected_value in tests:
+            self.assertEqual(expected_value, ref.id())
+
+    def test_jujucharms_id(self):
+        # It is possible to return the reference identifier in jujucharms.com.
+        tests = (
+            (make_reference(),
+             'u/myuser/juju-gui/precise/42'),
+            (make_reference(schema='local'),
+             'u/myuser/juju-gui/precise/42'),
+            (make_reference(user=''),
+             'juju-gui/precise/42'),
+            (make_reference(user='dalek', revision=None, series='bundle'),
+             'u/dalek/juju-gui'),
+            (make_reference(name='django', series='vivid', revision=0),
+             'u/myuser/django/vivid/0'),
+            (make_reference(user='', revision=None),
+             'juju-gui/precise'),
+            (make_reference(user='', series='bundle', revision=None),
+             'juju-gui'),
+        )
+        for ref, expected_value in tests:
+            self.assertEqual(expected_value, ref.jujucharms_id())
+
+    def test_jujucharms_url(self):
+        # The corresponding charm or bundle page in jujucharms.com is correctly
+        # returned.
+        tests = (
+            (make_reference(),
+             'u/myuser/juju-gui/precise/42'),
+            (make_reference(schema='local'),
+             'u/myuser/juju-gui/precise/42'),
+            (make_reference(user=''),
+             'juju-gui/precise/42'),
+            (make_reference(user='dalek', revision=None, series='bundle'),
+             'u/dalek/juju-gui'),
+            (make_reference(name='django', series='vivid', revision=0),
+             'u/myuser/django/vivid/0'),
+            (make_reference(user='', revision=None),
+             'juju-gui/precise'),
+            (make_reference(user='', series='bundle', revision=None),
+             'juju-gui'),
+        )
+        for ref, expected_value in tests:
+            expected_url = settings.JUJUCHARMS_URL + expected_value
+            self.assertEqual(expected_url, ref.jujucharms_url())
+
+    def test_charm_entity(self):
+        # The is_bundle method returns False for charm references.
+        ref = make_reference(series='vivid')
+        self.assertFalse(ref.is_bundle())
+
+    def test_bundle_entity(self):
+        # The is_bundle method returns True for bundle references.
+        ref = make_reference(series='bundle')
+        self.assertTrue(ref.is_bundle())
+
+    def test_charm_store_entity(self):
+        # The is_local method returns False for charm store references.
+        ref = make_reference(schema='cs')
+        self.assertFalse(ref.is_local())
+
+    def test_local_entity(self):
+        # The is_local method returns True for local references.
+        ref = make_reference(schema='local')
+        self.assertTrue(ref.is_local())
+
+    def test_equality(self):
+        # Two references are equal if they have the same URL.
+        self.assertEqual(make_reference(), make_reference())
+        self.assertEqual(make_reference(user=''), make_reference(user=''))
+        self.assertEqual(
+            make_reference(revision=None), make_reference(revision=None))
+
+    def test_equality_different_references(self):
+        # Two references with different attributes are not equal.
+        tests = (
+            (make_reference(schema='cs'),
+             make_reference(schema='local')),
+            (make_reference(user=''),
+             make_reference(user='who')),
+            (make_reference(series='trusty'),
+             make_reference(series='vivid')),
+            (make_reference(name='django'),
+             make_reference(name='rails')),
+            (make_reference(revision=0),
+             make_reference(revision=1)),
+            (make_reference(revision=None),
+             make_reference(revision=42)),
+        )
+        for ref1, ref2 in tests:
+            self.assertNotEqual(ref1, ref2)
+
+    def test_equality_different_types(self):
+        # A reference never equals a non-reference object.
+        self.assertNotEqual(make_reference(), 42)
+        self.assertNotEqual(make_reference(), True)
+        self.assertNotEqual(make_reference(), 'oranges')
+
+    def test_charmworld_id(self):
+        # By default, the reference id in charmworld is set to None.
+        # XXX frankban 2015-02-26: remove this test once we get rid of the
+        # charmworld id concept.
+        ref = make_reference()
+        self.assertIsNone(ref.charmworld_id)
+
+
+class TestReferenceFromFullyQualifiedUrl(
+        helpers.ValueErrorTestsMixin, unittest.TestCase):
 
     def test_no_schema_error(self):
         # A ValueError is raised if the URL schema is missing.
-        expected = 'charm URL has no schema: precise/juju-gui'
-        with self.assert_value_error(expected):
-            charms.parse_url('precise/juju-gui')
+        expected_error = 'URL has no schema: precise/juju-gui'
+        with self.assert_value_error(expected_error):
+            references.Reference.from_fully_qualified_url('precise/juju-gui')
 
     def test_invalid_schema_error(self):
         # A ValueError is raised if the URL schema is not valid.
-        expected = 'charm URL has invalid schema: http'
-        with self.assert_value_error(expected):
-            charms.parse_url('http:precise/juju-gui')
+        expected_error = 'URL has invalid schema: http'
+        with self.assert_value_error(expected_error):
+            references.Reference.from_fully_qualified_url(
+                'http:precise/juju-gui')
 
     def test_invalid_user_form_error(self):
         # A ValueError is raised if the user form is not valid.
-        expected = 'charm URL has invalid user name form: jean-luc'
-        with self.assert_value_error(expected):
-            charms.parse_url('cs:jean-luc/precise/juju-gui')
+        expected_error = 'URL has invalid user name form: jean-luc'
+        with self.assert_value_error(expected_error):
+            references.Reference.from_fully_qualified_url(
+                'cs:jean-luc/precise/juju-gui')
 
     def test_invalid_user_name_error(self):
         # A ValueError is raised if the user name is not valid.
-        expected = 'charm URL has invalid user name: jean:luc'
-        with self.assert_value_error(expected):
-            charms.parse_url('cs:~jean:luc/precise/juju-gui')
+        expected_error = 'URL has invalid user name: jean:luc'
+        with self.assert_value_error(expected_error):
+            references.Reference.from_fully_qualified_url(
+                'cs:~jean:luc/precise/juju-gui')
 
     def test_local_user_name_error(self):
-        # A ValueError is raised if a user is specified on a local charm.
-        expected = (
-            'local charm URL with user name: '
+        # A ValueError is raised if a user is specified on a local entity.
+        expected_error = (
+            'local entity URL with user name: '
             'local:~jean-luc/precise/juju-gui')
-        with self.assert_value_error(expected):
-            charms.parse_url('local:~jean-luc/precise/juju-gui')
+        with self.assert_value_error(expected_error):
+            references.Reference.from_fully_qualified_url(
+                'local:~jean-luc/precise/juju-gui')
 
     def test_invalid_form_error(self):
         # A ValueError is raised if the URL is not valid.
-        expected = 'charm URL has invalid form: cs:~user/series/name/what-?'
-        with self.assert_value_error(expected):
-            charms.parse_url('cs:~user/series/name/what-?')
+        expected_error = 'URL has invalid form: cs:~user/series/name/what-?'
+        with self.assert_value_error(expected_error):
+            references.Reference.from_fully_qualified_url(
+                'cs:~user/series/name/what-?')
 
     def test_invalid_series_error(self):
         # A ValueError is raised if the series is not valid.
-        expected = 'charm URL has invalid series: boo!'
-        with self.assert_value_error(expected):
-            charms.parse_url('cs:boo!/juju-gui-42')
+        expected_error = 'URL has invalid series: boo!'
+        with self.assert_value_error(expected_error):
+            references.Reference.from_fully_qualified_url(
+                'cs:boo!/juju-gui-42')
 
     def test_no_revision_error(self):
-        # A ValueError is raised if the charm revision is missing.
-        expected = 'charm URL has no revision: cs:series/name'
-        with self.assert_value_error(expected):
-            charms.parse_url('cs:series/name')
+        # A ValueError is raised if the entity revision is missing.
+        expected_error = 'URL has no revision: cs:series/name'
+        with self.assert_value_error(expected_error):
+            references.Reference.from_fully_qualified_url('cs:series/name')
 
     def test_invalid_revision_error(self):
-        # A ValueError is raised if the charm revision is not valid.
-        expected = 'charm URL has invalid revision: revision'
-        with self.assert_value_error(expected):
-            charms.parse_url('cs:series/name-revision')
+        # A ValueError is raised if the charm or bundle revision is not valid.
+        expected_error = 'URL has invalid revision: revision'
+        with self.assert_value_error(expected_error):
+            references.Reference.from_fully_qualified_url(
+                'cs:series/name-revision')
 
     def test_invalid_name_error(self):
-        # A ValueError is raised if the charm name is not valid.
-        expected = 'charm URL has invalid name: not:valid'
-        with self.assert_value_error(expected):
-            charms.parse_url('cs:precise/not:valid-42')
-
-    def test_success_with_user(self):
-        # A charm URL including the user is correctly parsed.
-        schema, user, series, name, revision = charms.parse_url(
-            'cs:~who/precise/juju-gui-42')
-        self.assertEqual('cs', schema)
-        self.assertEqual('who', user)
-        self.assertEqual('precise', series)
-        self.assertEqual('juju-gui', name)
-        self.assertEqual(42, revision)
-
-    def test_success_without_user(self):
-        # A charm URL not including the user is correctly parsed.
-        schema, user, series, name, revision = charms.parse_url(
-            'cs:trusty/django-1')
-        self.assertEqual('cs', schema)
-        self.assertEqual('', user)
-        self.assertEqual('trusty', series)
-        self.assertEqual('django', name)
-        self.assertEqual(1, revision)
-
-    def test_success_local_charm(self):
-        # A local charm URL is correctly parsed.
-        schema, user, series, name, revision = charms.parse_url(
-            'local:saucy/wordpress-100')
-        self.assertEqual('local', schema)
-        self.assertEqual('', user)
-        self.assertEqual('saucy', series)
-        self.assertEqual('wordpress', name)
-        self.assertEqual(100, revision)
-
-
-class TestCharm(helpers.ValueErrorTestsMixin, unittest.TestCase):
-
-    def make_charm(
-            self, schema='cs', user='myuser', series='precise',
-            name='juju-gui', revision=42):
-        """Create and return a Charm instance."""
-        return charms.Charm(schema, user, series, name, revision)
-
-    def test_attributes(self):
-        # All charm attributes are correctly stored.
-        charm = self.make_charm()
-        self.assertEqual('cs', charm.schema)
-        self.assertEqual('myuser', charm.user)
-        self.assertEqual('precise', charm.series)
-        self.assertEqual('juju-gui', charm.name)
-        self.assertEqual(42, charm.revision)
-
-    def test_revision_as_string(self):
-        # Revision is converted to an int.
-        charm = self.make_charm(revision='47')
-        self.assertEqual(47, charm.revision)
-
-    def test_from_url(self):
-        # A Charm can be instantiated from a charm URL.
-        charm = charms.Charm.from_url('cs:~who/trusty/django-1')
-        self.assertEqual('cs', charm.schema)
-        self.assertEqual('who', charm.user)
-        self.assertEqual('trusty', charm.series)
-        self.assertEqual('django', charm.name)
-        self.assertEqual(1, charm.revision)
-
-    def test_from_url_without_user(self):
-        # Official charm store URLs are properly handled.
-        charm = charms.Charm.from_url('cs:saucy/django-123')
-        self.assertEqual('cs', charm.schema)
-        self.assertEqual('', charm.user)
-        self.assertEqual('saucy', charm.series)
-        self.assertEqual('django', charm.name)
-        self.assertEqual(123, charm.revision)
-
-    def test_from_url_local(self):
-        # Local charms URLs are properly handled.
-        charm = charms.Charm.from_url('local:precise/my-local-charm-42')
-        self.assertEqual('local', charm.schema)
-        self.assertEqual('', charm.user)
-        self.assertEqual('precise', charm.series)
-        self.assertEqual('my-local-charm', charm.name)
-        self.assertEqual(42, charm.revision)
-
-    def test_from_url_error(self):
-        # A ValueError is raised by the from_url class method if the provided
-        # URL is not a valid charm URL.
-        expected = 'charm URL has invalid form: cs:not-a-charm-url'
-        with self.assert_value_error(expected):
-            charms.Charm.from_url('cs:not-a-charm-url')
-
-    def test_string(self):
-        # The string representation of a charm instance is its URL.
-        charm = self.make_charm()
-        self.assertEqual('cs:~myuser/precise/juju-gui-42', bytes(charm))
-
-    def test_repr(self):
-        # A charm instance is correctly represented.
-        charm = self.make_charm()
-        self.assertEqual(
-            '<Charm: cs:~myuser/precise/juju-gui-42>', repr(charm))
-
-    def test_charm_store_url(self):
-        # A charm store URL is correctly returned.
-        charm = self.make_charm(schema='cs')
-        self.assertEqual('cs:~myuser/precise/juju-gui-42', charm.url())
-
-    def test_local_url(self):
-        # A local charm URL is correctly returned.
-        charm = self.make_charm(schema='local', user='')
-        self.assertEqual('local:precise/juju-gui-42', charm.url())
-
-    def test_charm_store_charm(self):
-        # The is_local method returns False for charm store charms.
-        charm = self.make_charm(schema='cs')
-        self.assertFalse(charm.is_local())
-
-    def test_local_charm(self):
-        # The is_local method returns True for local charms.
-        charm = self.make_charm(schema='local')
-        self.assertTrue(charm.is_local())
-
-    def test_equality(self):
-        # Two charms are equal if they have the same URL.
-        self.assertEqual(self.make_charm(), self.make_charm())
-
-    def test_equality_different_name(self):
-        # Two charms with different names are not equal.
-        self.assertNotEqual(
-            self.make_charm(name='django'),
-            self.make_charm(name='rails'))
-
-    def test_equality_different_revision(self):
-        # Two charms with different revisions are not equal.
-        self.assertNotEqual(
-            self.make_charm(revision=0),
-            self.make_charm(revision=1))
-
-    def test_equality_different_user(self):
-        # Two charms with different users are not equal.
-        self.assertNotEqual(
-            self.make_charm(user=''),
-            self.make_charm(user='who'))
-
-    def test_equality_different_types(self):
-        # A charm never equals a non-charm object.
-        self.assertNotEqual(self.make_charm(), 42)
-        self.assertNotEqual(self.make_charm(), True)
-        self.assertNotEqual(self.make_charm(), 'oranges')
+        # A ValueError is raised if the entity name is not valid.
+        expected_error = 'URL has invalid name: not:valid'
+        with self.assert_value_error(expected_error):
+            references.Reference.from_fully_qualified_url(
+                'cs:precise/not:valid-42')
+
+    def test_success(self):
+        # References are correctly instantiated by parsing the fully qualified
+        # URL.
+        tests = (
+            ('cs:~myuser/precise/juju-gui-42',
+             make_reference()),
+            ('cs:trusty/juju-gui-42',
+             make_reference(user='', series='trusty')),
+            ('local:precise/juju-gui-42',
+             make_reference(schema='local', user='')),
+        )
+        for url, expected_ref in tests:
+            ref = references.Reference.from_fully_qualified_url(url)
+            self.assertEqual(expected_ref, ref)
+
+
+class TestReferenceFromCharmworldUrl(
+        helpers.ValueErrorTestsMixin, unittest.TestCase):
+
+    def test_invalid_form(self):
+        # A ValueError is raised if the URL is not valid.
+        expected_error = 'invalid bundle URL: bad wolf'
+        with self.assert_value_error(expected_error):
+            references.Reference.from_charmworld_url('bad wolf')
+
+    def test_success(self):
+        # A reference is correctly created from a charmworld identifier.
+        tests = (
+            ('bundle:~myuser/wordpress/42/single',
+             make_reference(series='bundle', name='wordpress-single')),
+            ('bundle:~myuser/wordpress/single',
+             make_reference(series='bundle', name='wordpress-single',
+                            revision=None)),
+            ('bundle:wordpress/42/single',
+             make_reference(user='', series='bundle',
+                            name='wordpress-single')),
+            ('bundle:wordpress/single',
+             make_reference(user='', series='bundle', name='wordpress-single',
+                            revision=None)),
+        )
+        for url, expected_ref in tests:
+            ref = references.Reference.from_charmworld_url(url)
+            self.assertEqual(expected_ref, ref)
+
+    def test_charmworld_id(self):
+        # The charmworld id is properly set when parsing charmworld URLs.
+        # XXX frankban 2015-02-26: remove this test once we get rid of the
+        # charmworld id concept.
+        ref = references.Reference.from_charmworld_url(
+            'bundle:wordpress/single')
+        self.assertEqual('wordpress/single', ref.charmworld_id)
+
+
+class TestReferenceFromJujucharmsUrl(
+        helpers.ValueErrorTestsMixin, unittest.TestCase):
+
+    def test_invalid_form(self):
+        # A ValueError is raised if the URL is not valid.
+        expected_error = 'invalid bundle URL: bad wolf'
+        with self.assert_value_error(expected_error):
+            references.Reference.from_jujucharms_url('bad wolf')
+
+    def test_success(self):
+        # A reference is correctly created from a jujucharms.com identifier or
+        # complete URL.
+        tests = (
+            # Check with both user and revision.
+            ('u/myuser/mediawiki/42',
+             make_reference(series='bundle', name='mediawiki')),
+            ('/u/myuser/mediawiki/42',
+             make_reference(series='bundle', name='mediawiki')),
+            ('u/myuser/django-scalable/42/',
+             make_reference(series='bundle', name='django-scalable')),
+            ('{}u/myuser/mediawiki/42'.format(settings.JUJUCHARMS_URL),
+             make_reference(series='bundle', name='mediawiki')),
+            ('{}u/myuser/mediawiki/42/'.format(settings.JUJUCHARMS_URL),
+             make_reference(series='bundle', name='mediawiki')),
+
+            # Check without revision.
+            ('u/myuser/mediawiki',
+             make_reference(series='bundle', name='mediawiki', revision=None)),
+            ('/u/myuser/wordpress',
+             make_reference(series='bundle', name='wordpress', revision=None)),
+            ('u/myuser/mediawiki/',
+             make_reference(series='bundle', name='mediawiki', revision=None)),
+            ('{}u/myuser/django'.format(settings.JUJUCHARMS_URL),
+             make_reference(series='bundle', name='django', revision=None)),
+            ('{}u/myuser/mediawiki/'.format(settings.JUJUCHARMS_URL),
+             make_reference(series='bundle', name='mediawiki', revision=None)),
+
+            # Check without the user.
+            ('rails-single/42',
+             make_reference(user='', series='bundle', name='rails-single')),
+            ('/mediawiki/42',
+             make_reference(user='', series='bundle', name='mediawiki')),
+            ('rails-scalable/42/',
+             make_reference(user='', series='bundle', name='rails-scalable')),
+            ('{}mediawiki/42'.format(settings.JUJUCHARMS_URL),
+             make_reference(user='', series='bundle', name='mediawiki')),
+            ('{}django/42/'.format(settings.JUJUCHARMS_URL),
+             make_reference(user='', series='bundle', name='django')),
+
+            # Check without user and revision.
+            ('mediawiki',
+             make_reference(user='', series='bundle', name='mediawiki',
+                            revision=None)),
+            ('/wordpress',
+             make_reference(user='', series='bundle', name='wordpress',
+                            revision=None)),
+            ('mediawiki/',
+             make_reference(user='', series='bundle', name='mediawiki',
+                            revision=None)),
+            ('{}django'.format(settings.JUJUCHARMS_URL),
+             make_reference(user='', series='bundle', name='django',
+                            revision=None)),
+            ('{}mediawiki/'.format(settings.JUJUCHARMS_URL),
+             make_reference(user='', series='bundle', name='mediawiki',
+                            revision=None)),
+
+            # Check charm entities.
+            ('mediawiki/trusty/0',
+             make_reference(user='', series='trusty', name='mediawiki',
+                            revision=0)),
+            ('/wordpress/precise',
+             make_reference(user='', series='precise', name='wordpress',
+                            revision=None)),
+            ('u/who/rails/vivid',
+             make_reference(user='who', series='vivid', name='rails',
+                            revision=None)),
+        )
+        for url, expected_ref in tests:
+            ref = references.Reference.from_jujucharms_url(url)
+            self.assertEqual(expected_ref, ref)
 
=== modified file 'quickstart/tests/test_app.py'
--- quickstart/tests/test_app.py	2015-02-09 14:56:32 +0000
+++ quickstart/tests/test_app.py	2015-02-27 18:40:58 +0000
@@ -32,7 +32,10 @@
     platform_support,
     settings,
 )
-from quickstart.models import charms
+from quickstart.models import (
+    bundles,
+    references,
+)
 from quickstart.tests import helpers
 
 
@@ -934,10 +937,11 @@
         return mock.patch(
             'quickstart.netutils.get_charm_url', mock_get_charm_url)
 
-    def assert_charm_equal(self, expected_url, charm):
-        """Ensure the given charm has the expected URL."""
-        expected_charm = charms.Charm.from_url(expected_url)
-        self.assertEqual(expected_charm, charm)
+    def assert_reference_equal(self, expected_url, ref):
+        """Ensure the given reference points to the expected URL."""
+        expected_ref = references.Reference.from_fully_qualified_url(
+            expected_url)
+        self.assertEqual(expected_ref, ref)
 
     def test_environment_just_bootstrapped(self, mock_print):
         # The function correctly retrieves the charm URL and machine, and
@@ -952,14 +956,14 @@
         check_preexisting = False
         with self.patch_get_charm_url(
                 return_value='cs:trusty/juju-gui-42') as mock_get_charm_url:
-            charm, machine, service_data, unit_data = app.check_environment(
+            ref, machine, service_data, unit_data = app.check_environment(
                 env, 'my-gui', charm_url, env_type, bootstrap_node_series,
                 check_preexisting)
         # There is no need to call status if the environment was just created.
         self.assertFalse(env.get_status.called)
         # The charm URL has been retrieved from the charm store API based on
         # the current bootstrap node series.
-        self.assert_charm_equal('cs:trusty/juju-gui-42', charm)
+        self.assert_reference_equal('cs:trusty/juju-gui-42', ref)
         mock_get_charm_url.assert_called_once_with(bootstrap_node_series)
         # Since the bootstrap node series is supported by the GUI charm, the
         # GUI unit can be deployed to machine 0.
@@ -987,14 +991,14 @@
         check_preexisting = True
         with self.patch_get_charm_url(
                 return_value='cs:precise/juju-gui-42') as mock_get_charm_url:
-            charm, machine, service_data, unit_data = app.check_environment(
+            ref, machine, service_data, unit_data = app.check_environment(
                 env, 'my-gui', charm_url, env_type, bootstrap_node_series,
                 check_preexisting)
         # The environment status has been retrieved.
         env.get_status.assert_called_once_with()
         # The charm URL has been retrieved from the charm store API based on
         # the current bootstrap node series.
-        self.assert_charm_equal('cs:precise/juju-gui-42', charm)
+        self.assert_reference_equal('cs:precise/juju-gui-42', ref)
         mock_get_charm_url.assert_called_once_with(bootstrap_node_series)
         # Since the bootstrap node series is supported by the GUI charm, the
         # GUI unit can be deployed to machine 0.
@@ -1019,13 +1023,13 @@
         bootstrap_node_series = 'precise'
         check_preexisting = True
         with self.patch_get_charm_url() as mock_get_charm_url:
-            charm, machine, service_data, unit_data = app.check_environment(
+            ref, machine, service_data, unit_data = app.check_environment(
                 env, 'my-gui', charm_url, env_type, bootstrap_node_series,
                 check_preexisting)
         # The environment status has been retrieved.
         env.get_status.assert_called_once_with()
         # The charm URL has been retrieved from the environment.
-        self.assert_charm_equal('cs:precise/juju-gui-47', charm)
+        self.assert_reference_equal('cs:precise/juju-gui-47', ref)
         self.assertFalse(mock_get_charm_url.called)
         # Since the bootstrap node series is supported by the GUI charm, the
         # GUI unit can be safely deployed to machine 0.
@@ -1044,12 +1048,12 @@
         check_preexisting = False
         with self.patch_get_charm_url(
                 return_value='cs:trusty/juju-gui-42') as mock_get_charm_url:
-            charm, machine, service_data, unit_data = app.check_environment(
+            ref, machine, service_data, unit_data = app.check_environment(
                 env, 'my-gui', charm_url, env_type, bootstrap_node_series,
                 check_preexisting)
         # The charm URL has been retrieved from the charm store API using the
         # most recent supported series.
-        self.assert_charm_equal('cs:trusty/juju-gui-42', charm)
+        self.assert_reference_equal('cs:trusty/juju-gui-42', ref)
         mock_get_charm_url.assert_called_once_with('trusty')
         # The Juju GUI unit cannot be deployed to saucy machine 0.
         self.assertIsNone(machine)
@@ -1069,11 +1073,11 @@
         bootstrap_node_series = 'trusty'
         check_preexisting = False
         with self.patch_get_charm_url(return_value='cs:trusty/juju-gui-42'):
-            charm, machine, service_data, unit_data = app.check_environment(
+            ref, machine, service_data, unit_data = app.check_environment(
                 env, 'my-gui', charm_url, env_type, bootstrap_node_series,
                 check_preexisting)
         # The charm URL has been correctly retrieved from the charm store API.
-        self.assert_charm_equal('cs:trusty/juju-gui-42', charm)
+        self.assert_reference_equal('cs:trusty/juju-gui-42', ref)
         # The Juju GUI unit cannot be deployed to localhost.
         self.assertIsNone(machine)
 
@@ -1100,11 +1104,12 @@
         bootstrap_node_series = 'precise'
         check_preexisting = False
         with self.patch_get_charm_url(side_effect=IOError('boo!')):
-            charm, machine, service_data, unit_data = app.check_environment(
+            ref, machine, service_data, unit_data = app.check_environment(
                 env, 'my-gui', charm_url, env_type, bootstrap_node_series,
                 check_preexisting)
         # The default charm URL for the given series is returned.
-        self.assert_charm_equal(settings.DEFAULT_CHARM_URLS['precise'], charm)
+        self.assert_reference_equal(
+            settings.DEFAULT_CHARM_URLS['precise'], ref)
         self.assertEqual('0', machine)
 
     def test_most_recent_default_charm_url(self, mock_print):
@@ -1117,12 +1122,12 @@
         bootstrap_node_series = 'saucy'
         check_preexisting = False
         with self.patch_get_charm_url(side_effect=IOError('boo!')):
-            charm, machine, service_data, unit_data = app.check_environment(
+            ref, machine, service_data, unit_data = app.check_environment(
                 env, 'my-gui', charm_url, env_type, bootstrap_node_series,
                 check_preexisting)
         # The default charm URL for the given series is returned.
         series = settings.JUJU_GUI_SUPPORTED_SERIES[-1]
-        self.assert_charm_equal(settings.DEFAULT_CHARM_URLS[series], charm)
+        self.assert_reference_equal(settings.DEFAULT_CHARM_URLS[series], ref)
         self.assertIsNone(machine)
 
     def test_charm_url_provided(self, mock_print):
@@ -1134,14 +1139,14 @@
         bootstrap_node_series = 'trusty'
         check_preexisting = False
         with self.patch_get_charm_url() as mock_get_charm_url:
-            charm, machine, service_data, unit_data = app.check_environment(
+            ref, machine, service_data, unit_data = app.check_environment(
                 env, 'my-gui', charm_url, env_type, bootstrap_node_series,
                 check_preexisting)
         # There is no need to call the charmword API if the charm URL is
         # provided by the user.
         self.assertFalse(mock_get_charm_url.called)
         # The provided charm URL has been correctly returned.
-        self.assert_charm_equal(charm_url, charm)
+        self.assert_reference_equal(charm_url, ref)
         # Since the provided charm series is trusty, the charm itself can be
         # safely deployed to machine 0.
         self.assertEqual('0', machine)
@@ -1161,14 +1166,14 @@
         bootstrap_node_series = 'precise'
         check_preexisting = False
         with self.patch_get_charm_url() as mock_get_charm_url:
-            charm, machine, service_data, unit_data = app.check_environment(
+            ref, machine, service_data, unit_data = app.check_environment(
                 env, 'my-gui', charm_url, env_type, bootstrap_node_series,
                 check_preexisting)
         # There is no need to call the charmword API if the charm URL is
         # provided by the user.
         self.assertFalse(mock_get_charm_url.called)
         # The provided charm URL has been correctly returned.
-        self.assert_charm_equal(charm_url, charm)
+        self.assert_reference_equal(charm_url, ref)
         # Since the provided charm series is not precise, the charm must be
         # deployed to a new machine.
         self.assertIsNone(machine)
@@ -1642,26 +1647,39 @@
 
 class TestDeployBundle(ProgramExitTestsMixin, unittest.TestCase):
 
-    name = 'mybundle'
-    yaml = 'mybundle: contents'
-    bundle_id = '~fake/basket/bundle'
+    bundle_data = {'services': {}}
+    bundle = bundles.Bundle(bundle_data)
 
     def test_bundle_deployment(self):
         # A bundle is successfully deployed.
         env = mock.Mock()
-        app.deploy_bundle(env, self.yaml, self.name, self.bundle_id)
+        app.deploy_bundle(env, self.bundle)
+        # For the time being, the bundle version 3 is deployed by default.
+        expected_yaml = yaml.safe_dump({'bundle': self.bundle_data})
         env.deploy_bundle.assert_called_once_with(
-            self.yaml, name=self.name, bundle_id=self.bundle_id)
+            expected_yaml, 3, bundle_id=None)
         self.assertFalse(env.close.called)
 
+    def test_bundle_deployment_with_id(self):
+        # If the bundle reference includes the charmworld id, it is passed when
+        # calling the GUI server API.
+        # XXX frankban 2015-02-26: remove this test once we get rid of the
+        # charmworld id concept.
+        env = mock.Mock()
+        ref = references.Reference.from_charmworld_url('bundle:django/single')
+        bundle = bundles.Bundle(self.bundle_data, reference=ref)
+        app.deploy_bundle(env, bundle)
+        env.deploy_bundle.assert_called_once_with(
+            self.bundle.serialize_legacy(), 3, bundle_id='django/single')
+
     def test_api_error(self):
         # A ProgramExit is raised if an error occurs in one of the API calls.
         env = mock.Mock()
         env.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(env, self.yaml, self.name, self.bundle_id)
+        expected_error = 'bad API server response: bundle deployment failure'
+        with self.assert_program_exit(expected_error):
+            app.deploy_bundle(env, self.bundle)
 
     def test_other_errors(self):
         # Any other errors occurred during the process are not trapped.
@@ -1669,5 +1687,5 @@
         error = ValueError('explode!')
         env.deploy_bundle.side_effect = error
         with self.assertRaises(ValueError) as context_manager:
-            app.deploy_bundle(env, self.yaml, self.name, None)
+            app.deploy_bundle(env, self.bundle)
         self.assertIs(error, context_manager.exception)
 
=== modified file 'quickstart/tests/test_juju.py'
--- quickstart/tests/test_juju.py	2015-01-30 17:47:10 +0000
+++ quickstart/tests/test_juju.py	2015-02-27 18:40:58 +0000
@@ -172,9 +172,9 @@
         mock_rpc.assert_called_once_with(expected)
 
     @patch_rpc
-    def test_deploy_bundle(self, mock_rpc):
-        # The deploy bundle call is properly generated.
-        self.env.deploy_bundle('name: contents')
+    def test_deploy_bundle_v3(self, mock_rpc):
+        # The deploy bundle call is properly generated (API v3).
+        self.env.deploy_bundle('name: contents', 3)
         expected = {
             'Type': 'Deployer',
             'Request': 'Import',
@@ -183,13 +183,13 @@
         mock_rpc.assert_called_once_with(expected)
 
     @patch_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')
+    def test_deploy_bundle_v4(self, mock_rpc):
+        # The deploy bundle call is properly generated (API v4).
+        self.env.deploy_bundle('name: contents', 4)
         expected = {
             'Type': 'Deployer',
             'Request': 'Import',
-            'Params': {'Name': 'name', 'YAML': 'name: contents'},
+            'Params': {'YAML': 'name: contents', 'Version': 4},
         }
         mock_rpc.assert_called_once_with(expected)
 
@@ -197,13 +197,16 @@
     def test_deploy_bundle_with_bundle_id(self, mock_rpc):
         # The deploy bundle call is properly generated when passing a
         # bundle_id.
-        self.env.deploy_bundle('name: contents', name='name',
-                               bundle_id='~celso/basquet/wiki')
+        self.env.deploy_bundle(
+            'name: contents', 4, bundle_id='~celso/basquet/wiki')
         expected = {
             'Type': 'Deployer',
             'Request': 'Import',
-            'Params': {'Name': 'name', 'YAML': 'name: contents',
-                       'BundleID': '~celso/basquet/wiki'},
+            'Params': {
+                'YAML': 'name: contents',
+                'Version': 4,
+                'BundleID': '~celso/basquet/wiki',
+            },
         }
         mock_rpc.assert_called_once_with(expected)
 
 
=== modified file 'quickstart/tests/test_jujutools.py'
--- quickstart/tests/test_jujutools.py	2015-02-09 15:56:20 +0000
+++ quickstart/tests/test_jujutools.py	2015-02-27 18:40:58 +0000
@@ -24,7 +24,7 @@
 import yaml
 
 from quickstart import jujutools
-from quickstart.models import charms
+from quickstart.models import references
 from quickstart.tests import helpers
 
 
@@ -69,80 +69,90 @@
     def test_new_charm_old_juju(self):
         # The old Juju API endpoints are used if and old version of Juju is in
         # use, even if the Juju GUI charm is recent.
-        charm = charms.Charm.from_url('cs:trusty/juju-gui-42')
+        ref = references.Reference.from_fully_qualified_url(
+            'cs:trusty/juju-gui-42')
         url = jujutools.get_api_url(
-            '1.2.3.4:5678', (1, 21, 7), 'env-uuid', charm=charm)
+            '1.2.3.4:5678', (1, 21, 7), 'env-uuid', charm_ref=ref)
         self.assertEqual('wss://1.2.3.4:5678', url)
 
     def test_customized_charm_unexpected_name(self):
         # If a customized Juju GUI charm is used, then we assume it supports
         # the new Juju Login API endpoint (unexpected charm name).
-        charm = charms.Charm.from_url('cs:trusty/the-amazing-gui-0')
+        ref = references.Reference.from_fully_qualified_url(
+            'cs:trusty/the-amazing-gui-0')
         url = jujutools.get_api_url(
-            'example.com:17070', (1, 22, 2), 'uuid', charm=charm)
+            'example.com:17070', (1, 22, 2), 'uuid', charm_ref=ref)
         self.assertEqual('wss://example.com:17070/environment/uuid/api', url)
 
     def test_customized_charm_unexpected_user(self):
         # If a customized Juju GUI charm is used, then we assume it supports
         # the new Juju Login API endpoint (unexpected charm user).
-        charm = charms.Charm.from_url('cs:~who/trusty/juju-gui-0')
+        ref = references.Reference.from_fully_qualified_url(
+            'cs:~who/trusty/juju-gui-0')
         url = jujutools.get_api_url(
-            'example.com:17070', (1, 22, 2), 'uuid', charm=charm)
+            'example.com:17070', (1, 22, 2), 'uuid', charm_ref=ref)
         self.assertEqual('wss://example.com:17070/environment/uuid/api', url)
 
     def test_customized_charm_unexpected_schema(self):
         # If a customized Juju GUI charm is used, then we assume it supports
         # the new Juju Login API endpoint (local charm).
-        charm = charms.Charm.from_url('local:precise/juju-gui-0')
+        ref = references.Reference.from_fully_qualified_url(
+            'local:precise/juju-gui-0')
         url = jujutools.get_api_url(
-            'example.com:17070', (1, 22, 2), 'uuid', prefix='/', charm=charm)
+            'example.com:17070', (1, 22, 2), 'uuid', prefix='/', charm_ref=ref)
         self.assertEqual('wss://example.com:17070/environment/uuid/api', url)
 
     def test_customized_charm_unexpected_series(self):
         # If a customized Juju GUI charm is used, then we assume it supports
         # the new Juju Login API endpoint (unsupported charm series).
-        charm = charms.Charm.from_url('cs:vivid/juju-gui-0')
+        ref = references.Reference.from_fully_qualified_url(
+            'cs:vivid/juju-gui-0')
         url = jujutools.get_api_url(
-            'example.com:22', (1, 22, 2), 'uuid', prefix='ws', charm=charm)
+            'example.com:22', (1, 22, 2), 'uuid', prefix='ws', charm_ref=ref)
         self.assertEqual('wss://example.com:22/ws/environment/uuid/api', url)
 
     def test_recent_precise_charm(self):
         # The new API endpoints are used if a recent precise charm is in use.
-        charm = charms.Charm.from_url('cs:precise/juju-gui-107')
+        ref = references.Reference.from_fully_qualified_url(
+            'cs:precise/juju-gui-107')
         url = jujutools.get_api_url(
-            '1.2.3.4:4747', (1, 42, 0), 'env-id', charm=charm)
+            '1.2.3.4:4747', (1, 42, 0), 'env-id', charm_ref=ref)
         self.assertEqual('wss://1.2.3.4:4747/environment/env-id/api', url)
 
     def test_recent_trusty_charm(self):
         # The new API endpoints are used if a recent trusty charm is in use.
-        charm = charms.Charm.from_url('cs:trusty/juju-gui-19')
+        ref = references.Reference.from_fully_qualified_url(
+            'cs:trusty/juju-gui-19')
         url = jujutools.get_api_url(
-            '1.2.3.4:4747', (1, 42, 0), 'env-id', charm=charm)
+            '1.2.3.4:4747', (1, 42, 0), 'env-id', charm_ref=ref)
         self.assertEqual('wss://1.2.3.4:4747/environment/env-id/api', url)
 
     def test_old_precise_charm(self):
         # The old API endpoint is returned if the precise Juju GUI charm in use
         # is outdated.
-        charm = charms.Charm.from_url('cs:precise/juju-gui-106')
+        ref = references.Reference.from_fully_qualified_url(
+            'cs:precise/juju-gui-106')
         url = jujutools.get_api_url(
-            '1.2.3.4:4747', (1, 42, 0), 'env-uuid', charm=charm)
+            '1.2.3.4:4747', (1, 42, 0), 'env-uuid', charm_ref=ref)
         self.assertEqual('wss://1.2.3.4:4747', url)
 
     def test_old_trusty_charm(self):
         # The old API endpoint is returned if the trusty Juju GUI charm in use
         # is outdated.
-        charm = charms.Charm.from_url('cs:trusty/juju-gui-18')
+        ref = references.Reference.from_fully_qualified_url(
+            'cs:trusty/juju-gui-18')
         url = jujutools.get_api_url(
-            '1.2.3.4:4747', (1, 42, 0), 'env-uuid', prefix='ws', charm=charm)
+            '1.2.3.4:4747', (1, 42, 0), 'env-uuid', prefix='ws', charm_ref=ref)
         self.assertEqual('wss://1.2.3.4:4747/ws', url)
 
     def test_recent_charm_and_prefix(self):
         # The new API endpoint is returned if a recent charm and a prefix are
         # both provided. This test exercises the real case in which the GUI
         # server API endpoint is returned.
-        charm = charms.Charm.from_url('cs:trusty/juju-gui-42')
+        ref = references.Reference.from_fully_qualified_url(
+            'cs:trusty/juju-gui-42')
         url = jujutools.get_api_url(
-            '1.2.3.4:17070', (1, 22, 0), 'env-id', prefix='ws', charm=charm)
+            '1.2.3.4:17070', (1, 22, 0), 'env-id', prefix='ws', charm_ref=ref)
         self.assertEqual('wss://1.2.3.4:17070/ws/environment/env-id/api', url)
 
 
@@ -231,25 +241,25 @@
 class TestParseGuiCharmUrl(unittest.TestCase):
 
     def test_charm_instance_returned(self):
-        # A charm instance is correctly returned.
-        charm = jujutools.parse_gui_charm_url('cs:trusty/juju-gui-42')
-        self.assertIsInstance(charm, charms.Charm)
-        self.assertEqual('cs:trusty/juju-gui-42', charm.url())
+        # A charm reference instance is correctly returned.
+        ref = jujutools.parse_gui_charm_url('cs:trusty/juju-gui-42')
+        self.assertIsInstance(ref, references.Reference)
+        self.assertEqual('cs:trusty/juju-gui-42', ref.id())
 
     def test_customized(self):
-        # A customized charm URL is properly logged.
+        # A customized charm reference is properly logged.
         expected = 'using a customized juju-gui charm'
         with helpers.assert_logs([expected], level='warn'):
             jujutools.parse_gui_charm_url('cs:~juju-gui/precise/juju-gui-28')
 
     def test_outdated(self):
-        # An outdated charm URL is properly logged.
+        # An outdated charm reference is properly logged.
         expected = 'charm is outdated and may not support bundle deployments'
         with helpers.assert_logs([expected], level='warn'):
             jujutools.parse_gui_charm_url('cs:precise/juju-gui-1')
 
     def test_unexpected(self):
-        # An unexpected charm URL is properly logged.
+        # An unexpected charm reference is properly logged.
         expected = (
             'unexpected URL for the juju-gui charm: the service may not work '
             'as expected')
 
=== modified file 'quickstart/tests/test_manage.py'
--- quickstart/tests/test_manage.py	2015-02-09 17:22:04 +0000
+++ quickstart/tests/test_manage.py	2015-02-27 18:40:58 +0000
@@ -24,7 +24,6 @@
 import os
 import shutil
 import StringIO as io
-import tempfile
 import unittest
 
 import mock
@@ -40,9 +39,10 @@
     views,
 )
 from quickstart.models import (
-    charms,
+    bundles,
     envs,
     jenv,
+    references,
 )
 from quickstart.tests import helpers
 
@@ -98,156 +98,6 @@
             self.assertEqual(argparse.SUPPRESS, ppa_help)
 
 
-class TestValidateBundle(
-        helpers.BundleFileTestsMixin, helpers.UrlReadTestsMixin,
-        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_from_file(self):
-        # The options object is correctly set up when a bundle file is passed.
-        bundle_file = self.make_bundle_file()
-        options = self.make_options(bundle_file, bundle_name='bundle1')
-        manage._validate_bundle(options, self.parser)
-        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_resulting_options_from_url(self):
-        # The options object is correctly set up when a bundle HTTP(S) URL is
-        # passed.
-        bundle_file = self.make_bundle_file()
-        url = 'http://example.com/bundle.yaml'
-        options = self.make_options(url, bundle_name='bundle1')
-        with self.patch_urlread(contents=self.valid_bundle) as mock_urlread:
-            manage._validate_bundle(options, self.parser)
-        mock_urlread.assert_called_once_with(url)
-        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_resulting_options_from_bundle_url(self):
-        # The options object is correctly set up when a "bundle:" URL is
-        # passed.
-        bundle_file = self.make_bundle_file()
-        url = 'bundle:~who/my/bundle'
-        options = self.make_options(url, bundle_name='bundle1')
-        with self.patch_urlread(contents=self.valid_bundle) as mock_urlread:
-            manage._validate_bundle(options, self.parser)
-        mock_urlread.assert_called_once_with(
-            'https://manage.jujucharms.com/bundle/~who/my/bundle/json')
-        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_resulting_options_from_jujucharms_url(self):
-        # The options object is correctly set up when a jujucharms bundle URL
-        # is passed.
-        bundle_file = self.make_bundle_file()
-        url = settings.JUJUCHARMS_BUNDLE_URL + 'my/bundle/'
-        options = self.make_options(url, bundle_name='bundle1')
-        with self.patch_urlread(contents=self.valid_bundle) as mock_urlread:
-            manage._validate_bundle(options, self.parser)
-        mock_urlread.assert_called_once_with(
-            'https://manage.jujucharms.com/bundle/~charmers/my/bundle/json')
-        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_resulting_options_from_dir(self):
-        # The options object is correctly set up when a bundle dir is passed.
-        bundle_dir = self.make_bundle_dir()
-        options = self.make_options(bundle_dir, bundle_name='bundle1')
-        manage._validate_bundle(options, self.parser)
-        self.assertEqual('bundle1', options.bundle_name)
-        self.assertEqual(
-            ['mysql', 'wordpress'], sorted(options.bundle_services))
-        expected = open(os.path.join(bundle_dir, 'bundles.yaml')).read()
-        self.assertEqual(expected, 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(self.valid_bundle, options.bundle_yaml)
-
-    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_bundle_dir_not_valid(self):
-        # A parser error is invoked if the bundle dir does not contain the
-        # bundles.yaml file.
-        bundle_dir = tempfile.mkdtemp()
-        self.addCleanup(shutil.rmtree, bundle_dir)
-        options = self.make_options(bundle_dir)
-        manage._validate_bundle(options, self.parser)
-        expected = (
-            'unable to open bundle file: '
-            "[Errno 2] No such file or directory: '{}/bundles.yaml'"
-        ).format(bundle_dir)
-        self.parser.error.assert_called_once_with(expected)
-
-    def test_url_error(self):
-        # A parser error is invoked if the bundle cannot be fetched from the
-        # provided URL.
-        url = 'http://example.com/bundle.yaml'
-        options = self.make_options(url)
-        with self.patch_urlread(error=True) as mock_urlread:
-            manage._validate_bundle(options, self.parser)
-        mock_urlread.assert_called_once_with(url)
-        self.parser.error.assert_called_once_with(
-            'unable to open bundle URL: bad wolf')
-
-    def test_bundle_url_error(self):
-        # A parser error is invoked if an invalid "bundle:" URL is provided.
-        url = 'bundle:'
-        options = self.make_options(url)
-        manage._validate_bundle(options, self.parser)
-        self.parser.error.assert_called_once_with(
-            'unable to open the bundle: invalid bundle URL: bundle:')
-
-    def test_jujucharms_url_error(self):
-        # A parser error is invoked if an invalid jujucharms URL is provided.
-        url = settings.JUJUCHARMS_BUNDLE_URL + 'no-such'
-        options = self.make_options(url)
-        manage._validate_bundle(options, self.parser)
-        self.parser.error.assert_called_once_with(
-            'unable to open the bundle: invalid bundle URL: {}'.format(url))
-
-    def test_error_parsing_bundle_contents(self):
-        # A parser error is invoked if an error occurs parsing the bundle YAML.
-        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 TestValidateCharmUrl(unittest.TestCase):
 
     def setUp(self):
@@ -255,16 +105,16 @@
 
     def make_options(self, charm_url, has_bundle=False):
         """Return a mock options object which includes the passed arguments."""
-        options = mock.Mock(charm_url=charm_url, bundle=None)
+        options = mock.Mock(charm_url=charm_url, bundle_source=None)
         if has_bundle:
-            options.bundle = 'bundle:~who/django/42/django'
+            options.bundle_source = 'u/who/django/42'
         return options
 
     def test_invalid_url_error(self):
         # A parser error is invoked if the charm URL is not valid.
         options = self.make_options('cs:invalid')
         manage._validate_charm_url(options, self.parser)
-        expected = 'charm URL has invalid form: cs:invalid'
+        expected = 'URL has invalid form: cs:invalid'
         self.parser.error.assert_called_once_with(expected)
 
     def test_local_charm_error(self):
@@ -738,14 +588,21 @@
         expected = 'juju-quickstart {}\n'.format(quickstart.get_version())
         self.assertEqual(expected, mock_stderr.getvalue())
 
-    @mock.patch('quickstart.manage._validate_bundle')
-    def test_bundle(self, mock_validate_bundle):
+    @mock.patch('quickstart.models.bundles.from_source')
+    def test_bundle(self, mock_from_source):
         # 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)
+        self.call_setup(['/path/to/bundle.yaml'], exit_called=False)
+        mock_from_source.assert_called_once_with('/path/to/bundle.yaml', None)
+
+    def test_bundle_error(self):
+        # The bundle validation process fails if an invalid bundle source is
+        # provided.
+        with mock.patch('sys.stderr', new_callable=io.StringIO) as mock_stderr:
+            self.call_setup(['invalid/bundle!'], exit_called=False)
+        expected_error = (
+            'error: unable to open the bundle: invalid bundle URL: '
+            'invalid/bundle!')
+        self.assertIn(expected_error, mock_stderr.getvalue())
 
     @mock.patch('quickstart.manage._validate_charm_url')
     def test_charm_url(self, mock_validate_charm_url):
@@ -778,15 +635,14 @@
 @mock.patch('webbrowser.open')
 @mock.patch('quickstart.manage.app')
 @mock.patch('__builtin__.print', mock.Mock())
-class TestRun(unittest.TestCase):
+class TestRun(helpers.BundleFileTestsMixin, unittest.TestCase):
 
     juju_command = '/sbin/juju'
 
     def make_options(self, **kwargs):
         """Set up the options to be passed to the run function."""
         options = {
-            'bundle': None,
-            'bundle_id': None,
+            'bundle_source': None,
             'charm_url': None,
             'debug': False,
             'env_name': 'aws',
@@ -830,7 +686,8 @@
             'connect': env,
             # The environment is then checked.
             'check_environment': (
-                charms.Charm.from_url('cs:trusty/juju-gui-42'),
+                references.Reference.from_fully_qualified_url(
+                    'cs:trusty/juju-gui-42'),
                 '0',
                 {'Name': 'juju-gui'},
                 {'Name': 'juju-gui/0'}
@@ -921,7 +778,8 @@
         # Even if the Juju version is new, the old GUI server login API is used
         # if the charm in the environment is not recent enough.
         self.configure_app(mock_app, check_environment=(
-            charms.Charm.from_url('cs:trusty/juju-gui-0'),
+            references.Reference.from_fully_qualified_url(
+                'cs:trusty/juju-gui-0'),
             '0',
             {'Name': 'juju-gui'},
             {'Name': 'juju-gui/0'}
@@ -990,15 +848,15 @@
     def test_bundle(self, mock_app, mock_open):
         # A bundle is correctly deployed by the application.
         env = self.configure_app(mock_app, create_auth_token=None)
+        bundle_source = 'mediawiki-single'
+        reference = references.Reference.from_jujucharms_url(bundle_source)
+        bundle = bundles.Bundle(self.bundle_data, reference=reference)
         # Run the application.
-        options = self.make_options(
-            bundle='/my/bundle/file.yaml', bundle_yaml='mybundle: contents',
-            bundle_name='mybundle', bundle_services=['service1', 'service2'])
+        options = self.make_options(bundle_source=bundle_source, bundle=bundle)
         with self.patch_get_juju_command():
             manage.run(options)
         # Ensure the bundle is correctly deployed.
-        mock_app.deploy_bundle.assert_called_once_with(
-            env, 'mybundle: contents', 'mybundle', None)
+        mock_app.deploy_bundle.assert_called_once_with(env, bundle)
 
     def test_local_provider(self, mock_app, mock_open):
         # The application correctly handles working with local providers with
 
=== modified file 'tox.ini'
--- tox.ini	2015-02-09 10:38:25 +0000
+++ tox.ini	2015-02-27 18:40:58 +0000
@@ -71,7 +71,7 @@
     # Dependencies present in ppa:juju/stable.
     # See https://launchpad.net/~juju/+archive/ubuntu/stable.
     websocket-client==0.18.0
-    jujuclient==0.18.4
+    jujuclient==0.50.1
     urwid==1.2.1
     # The distribution PyYAML requirement is used in this case.