Add action example and docs

[osm/N2VC.git] / docs / narrative / unit.rst

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)