Merge pull request #873 from cderici/cleaning-tidying-up

#873

#### Description

Small change that updates the example in the readme and adds some docstrings for `model.py` and `bundle.py`.

#### QA Steps

No change in any functionality, so no QA is needed. Just some proof read, maybe.

Author: jujubot

docs/readme.rst

@@ -48,7 +48,7 @@ ubuntu charm, then exits:
   import logging
   import sys
 
-  from juju import jasyncio
+  from juju import asyncio
   from juju.model import Model
 
 
@@ -58,21 +58,20 @@ ubuntu charm, then exits:
       model = Model()
 
       # Connect to the currently active Juju model
-      await model.connect_current()
+      await model.connect()
 
       try:
           # Deploy a single unit of the ubuntu charm, using the latest revision
           # from the stable channel of the Charm Store.
           ubuntu_app = await model.deploy(
             'ubuntu',
             application_name='ubuntu',
-            series='xenial',
-            channel='stable',
           )
 
           if '--wait' in sys.argv:
               # optionally block until the application is ready
-              await model.block_until(lambda: ubuntu_app.status == 'active')
+              await model.wait_for_idle(status = 'active')
+
       finally:
           # Disconnect from the api server and cleanup.
           await model.disconnect()
@@ -87,7 +86,7 @@ ubuntu charm, then exits:
 
       # Run the deploy coroutine in an asyncio event loop, using a helper
       # that abstracts loop creation and teardown.
-      jasyncio.run(deploy())
+      asyncio.run(deploy())
 
 
   if __name__ == '__main__':

juju/bundle.py

@@ -223,9 +223,24 @@ def _resolve_include_file_config(self, bundle_dir):
 
         return self.bundle, self.overlays
 
-    async def fetch_plan(self, charm_url, origin, overlays=[]):
-        entity_id = charm_url.path()
-        is_local = Schema.LOCAL.matches(charm_url.schema)
+    async def fetch_plan(self, bundle_url, origin, overlays=[]):
+        """fetch_plan is called by the model.deploy(). It gathers the information about the
+        bundle to be deployed (whether local or CharmHub), straightens it up, applies overlays
+        if any overlays are given. Validates the bundle against known issues. Resolves and adds
+        local charms if there's any in the bundle. Resolves and adds --include-file configs if
+        there's any. Finally it calls the BundleFacade.GetChanges() to get the plan for the
+        bundle to be handed to the execute_plan() by the model.deploy(). Note that it doesn't
+        return the plan, just saves it in the self (BundleHandler) to be used later.
+
+        :param client.URL bundle_url: the url of the bundle to be deployed
+        :param client.CharmOrigin origin: the origin of the bundle to be deployed
+        :param [string] overlays: paths for the yaml files containing overlays to be applied to
+        the bundle during deployment
+
+        :returns: None
+        """
+        entity_id = bundle_url.path()
+        is_local = Schema.LOCAL.matches(bundle_url.schema)
         bundle_dir = None
 
         if is_local and os.path.isfile(entity_id):
@@ -235,8 +250,8 @@ async def fetch_plan(self, charm_url, origin, overlays=[]):
             bundle_yaml = (Path(entity_id) / "bundle.yaml").read_text()
             bundle_dir = Path(entity_id)
 
-        if Schema.CHARM_HUB.matches(charm_url.schema):
-            bundle_yaml = await self._download_bundle(charm_url, origin)
+        if Schema.CHARM_HUB.matches(bundle_url.schema):
+            bundle_yaml = await self._download_bundle(bundle_url, origin)
 
         if not bundle_yaml:
             raise JujuError('empty bundle, nothing to deploy')

juju/model.py

@@ -1675,17 +1675,15 @@ async def deploy(
             '24/lxd/3' - place in container 3 on machine 24
 
             If None, a new machine is provisioned.
+        :param devices: charm device constraints
         :param bool trust: Trust signifies that the charm should be deployed
             with access to trusted credentials. Hooks run by the charm can access
             cloud credentials and other trusted access credentials.
 
         :param str[] attach_storage: Existing storage to attach to the deployed unit
             (not available on k8s models)
-        TODO::
-
-            - support local file resources
-
         """
+
         if storage:
             storage = {
                 k: client.Constraints(**v)
@@ -1817,6 +1815,15 @@ async def deploy(
             )
 
     async def _add_charm(self, charm_url, origin):
+        """_add_charm sends the given origin and the url to the Juju API too add the charm to the
+        state. Either calls the CharmsFacade.AddCharm for (> version 2), or the
+        ClientFacade.AddCharm (for older versions).
+
+        :param str charm_url: the url of the charm to be added
+        :param client.CharmOrigin origin: the origin for the charm to be added
+
+        :returns client.CharmOriginResult
+        """
         # client facade is deprecated with in Juju, and smaller, more focused
         # facades have been created and we'll use that if it's available.
         charms_cls = client.CharmsFacade
@@ -1880,6 +1887,12 @@ async def _resolve_charm(self, url, origin, force=False, series=None, model_conf
         return str(charm_url), resolved_origin
 
     async def _resolve_architecture(self, url):
+        """_resolve_architecture returns the architecture for a given charm url.
+        :param str url: the client.URL to determine the arch for
+
+        :returns str architecture for the given url
+        """
+
         if url.architecture:
             return url.architecture
 
@@ -1893,6 +1906,16 @@ async def _add_charmhub_resources(self, application,
                                       entity_url,
                                       origin,
                                       overrides=None):
+        """_add_charmhub_resources is called by the deploy to add pending resources requested by
+        the charm being deployed. It calls the ResourcesFacade.AddPendingResources.
+
+        :param str application: the name of the application
+        :param client.CharmURL entity_url: url for the charm that we add resources for
+        :param client.CharmOrigin origin: origin for the charm that we add resources for
+
+        :returns [string]string resource_map that is a map of resources to their assigned
+        pendingIDs.
+        """
         charm_facade = client.CharmsFacade.from_connection(self.connection())
         res = await charm_facade.CharmInfo(entity_url)
 
@@ -1936,6 +1959,20 @@ async def _add_charmhub_resources(self, application,
         return resource_map
 
     async def add_local_resources(self, application, entity_url, metadata, resources):
+        """_add_local_resources is called by the deploy to add pending local  resources requested by
+        the charm being deployed. It calls the ResourcesFacade.AddPendingResources. After getting
+        the pending IDs from the controller it sends an HTTP PUT request to actually upload local
+        resources.
+
+        :param str application: the name of the application
+        :param client.CharmURL entity_url: url for the charm that we add resources for
+        :param [string]string metadata: metadata for the charm that we add resources for
+        :param [string] resources: the paths for the local files (or oci-images) to be added as
+        local resources
+
+        :returns [string]string resource_map that is a map of resources to their assigned
+        pendingIDs.
+        """
         if not resources:
             return None