From 8aca5190344dea43352b4d242291d729e3aa2328 Mon Sep 17 00:00:00 2001
From: Tim Van Steenburgh <tvansteenburgh@gmail.com>
Date: Thu, 15 Dec 2016 12:08:55 -0500
Subject: [PATCH] Unit.run() docs

---
 docs/narrative/application.rst | 16 ++++++++--------
 docs/narrative/index.rst       |  1 +
 docs/narrative/unit.rst        | 33 +++++++++++++++++++++++++++++++++
 examples/unitrun.py            | 30 +++++++++++++-----------------
 juju/unit.py                   |  4 +++-
 5 files changed, 58 insertions(+), 26 deletions(-)
 create mode 100644 docs/narrative/unit.rst

diff --git a/docs/narrative/application.rst b/docs/narrative/application.rst
index 630ce85..044807d 100644
--- a/docs/narrative/application.rst
+++ b/docs/narrative/application.rst
@@ -39,14 +39,14 @@ added units (:class:`~juju.unit.Unit` objects) is returned.
 
 .. code:: python
 
-    ubuntu_app = await model.deploy(
-        'ubuntu',
-        application_name='ubuntu',
-        series='trusty',
-        channel='stable',
-    )
-
-    unit_a, unit_b = await ubuntu_app.add_units(count=2)
+  ubuntu_app = await model.deploy(
+      'ubuntu',
+      application_name='ubuntu',
+      series='trusty',
+      channel='stable',
+  )
+
+  unit_a, unit_b = await ubuntu_app.add_units(count=2)
 
 
 Updating Config and Constraints
diff --git a/docs/narrative/index.rst b/docs/narrative/index.rst
index ac5b816..eb77e4c 100644
--- a/docs/narrative/index.rst
+++ b/docs/narrative/index.rst
@@ -8,3 +8,4 @@ Narrative Docs
    controller
    model
    application
+   unit
diff --git a/docs/narrative/unit.rst b/docs/narrative/unit.rst
new file mode 100644
index 0000000..8267df7
--- /dev/null
+++ b/docs/narrative/unit.rst
@@ -0,0 +1,33 @@
+Units
+=====
+
+Running Commands
+----------------
+Run arbitrary commands on a unit with the
+:meth:`juju.unit.Unit.run` method. This method blocks
+the current coroutine until a result is available, and
+returns a :class:`juju.action.Action` instance.
+
+
+.. code:: python
+
+  from juju.model import Model
+
+  model = Model()
+  await model.connect_current()
+
+  ubuntu_app = await model.deploy(
+      'ubuntu',
+      application_name='ubuntu',
+      series='trusty',
+      channel='stable',
+  )
+
+  for unit in app.units:
+      action = await unit.run('unit-get public-address')
+      print(action.results)
+
+      action = await unit.run('uname -a')
+      print(action.results)
+
+
diff --git a/examples/unitrun.py b/examples/unitrun.py
index 0436259..9d4e5d7 100644
--- a/examples/unitrun.py
+++ b/examples/unitrun.py
@@ -10,39 +10,35 @@ This example:
 import asyncio
 import logging
 
-from juju.model import Model, ModelObserver
+from juju.model import Model
 
-async def run_stuff_on_unit(unit):
-    print('Running command on unit', unit.name)
-
-    # unit.run() returns a client.ActionResults instance
-    action = await unit.run('unit-get public-address')
-
-    print("Action results: {}".format(action.results))
-
-    # Inform asyncio that we're done.
-    await unit.model.disconnect()
-    unit.model.loop.stop()
 
+async def run_command(unit):
+    logging.debug('Running command on unit %s', unit.name)
 
-class MyModelObserver(ModelObserver):
-    async def on_unit_add(self, delta, old, new, model):
-        loop.create_task(run_stuff_on_unit(new))
+    # unit.run() returns a juju.action.Action instance
+    action = await unit.run('unit-get public-address')
+    logging.debug("Action results: %s", action.results)
 
 
 async def run():
     model = Model()
     await model.connect_current()
     await model.reset(force=True)
-    model.add_observer(MyModelObserver())
 
-    await model.deploy(
+    app = await model.deploy(
         'ubuntu-0',
         application_name='ubuntu',
         series='trusty',
         channel='stable',
     )
 
+    for unit in app.units:
+        await run_command(unit)
+
+    await model.disconnect()
+    model.loop.stop()
+
 
 logging.basicConfig(level=logging.DEBUG)
 ws_logger = logging.getLogger('websockets.protocol')
diff --git a/juju/unit.py b/juju/unit.py
index ab9d1d0..ea51345 100644
--- a/juju/unit.py
+++ b/juju/unit.py
@@ -106,6 +106,7 @@ class Unit(model.ModelEntity):
 
         :param str command: The command to run
         :param int timeout: Time to wait before command is considered failed
+        :returns: A :class:`juju.action.Action` instance.
 
         Returns a tuple containing the stdout, stderr, and return code
         from the command.
@@ -131,11 +132,12 @@ class Unit(model.ModelEntity):
 
         :param str action_name: Name of action to run
         :param \*\*params: Action parameters
-        :returns: An `juju.action.Action` instance.
+        :returns: A :class:`juju.action.Action` instance.
 
         Note that this only enqueues the action.  You will need to call
         ``action.wait()`` on the resulting `Action` instance if you wish
         to block until the action is complete.
+
         """
         action_facade = client.ActionFacade()
         action_facade.connect(self.connection)
-- 
2.17.1