From: Tim Van Steenburgh <tvansteenburgh@gmail.com>
Date: Mon, 19 Dec 2016 18:33:16 +0000 (-0500)
Subject: Add action example and docs
X-Git-Tag: 0.1.0~6
X-Git-Url: https://osm.etsi.org/gitweb/?p=osm%2FN2VC.git;a=commitdiff_plain;h=51e09af5d8c07e7454cd03b8bf30487a593efa61

Add action example and docs
---

diff --git a/docs/narrative/unit.rst b/docs/narrative/unit.rst
index 8267df7..d7da412 100644
--- 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
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()