Add action example and docs

diff --git a/docs/narrative/unit.rst b/docs/narrative/unit.rst
index 8267df7..d7da412 100644 (file)
--- a/docs/narrative/unit.rst
+++ b/docs/narrative/unit.rst
@@ -16,7 +16,7 @@ returns a :class:`juju.action.Action` instance.
   model = Model()
   await model.connect_current()
 
-  ubuntu_app = await model.deploy(
+  app = await model.deploy(
       'ubuntu',
       application_name='ubuntu',
       series='trusty',
@@ -31,3 +31,33 @@ returns a :class:`juju.action.Action` instance.
       print(action.results)
 
 
+Running Actions
+---------------
+Run actions on a unit with the
+:meth:`juju.unit.Unit.run_action` method. This method
+returns a :class:`juju.action.Action` instance immediately. To block until
+the action completes, use the :meth:`juju.action.Action.wait` method, as
+in the example below.
+
+
+.. code:: python
+
+  from juju.model import Model
+
+  model = Model()
+  await model.connect_current()
+
+  app = await model.deploy(
+      'git',
+      application_name='git',
+      series='trusty',
+      channel='stable',
+  )
+
+  for unit in app.units:
+      # run the 'add-repo' action, passing a 'repo' param
+      action = await unit.run_action('add-repo', repo='myrepo')
+      # wait for the action to complete
+      action = await action.wait()
+
+      print(action.results)

diff --git a/examples/action.py b/examples/action.py
new file mode 100644 (file)
index 0000000..7897a8b
--- /dev/null
+++ b/examples/action.py
@@ -0,0 +1,52 @@
+"""
+This example:
+
+1. Connects to current model and resets it.
+2. Deploys a git unit.
+3. Runs an action against the unit.
+4. Waits for the action results to come back, then exits.
+
+"""
+import asyncio
+import logging
+
+from juju.model import Model
+
+
+async def run_action(unit):
+    logging.debug('Running action on unit %s', unit.name)
+
+    # unit.run() returns a juju.action.Action instance
+    action = await unit.run_action('add-repo', repo='myrepo')
+    # wait for the action to complete
+    action = await action.wait()
+
+    logging.debug("Action results: %s", action.results)
+
+
+async def run():
+    model = Model()
+    await model.connect_current()
+    await model.reset(force=True)
+
+    app = await model.deploy(
+        'git',
+        application_name='git',
+        series='trusty',
+        channel='stable',
+    )
+
+    for unit in app.units:
+        await run_action(unit)
+
+    await model.disconnect()
+    model.loop.stop()
+
+
+logging.basicConfig(level=logging.DEBUG)
+ws_logger = logging.getLogger('websockets.protocol')
+ws_logger.setLevel(logging.INFO)
+loop = asyncio.get_event_loop()
+loop.set_debug(False)
+loop.create_task(run())
+loop.run_forever()