From ab65150a9e3aa9f4061341007fbd785ec5d9e3b5 Mon Sep 17 00:00:00 2001
From: Matt Martz <matt@sivel.net>
Date: Fri, 17 Jun 2016 11:16:27 -0500
Subject: [PATCH] Rework the v2 API example to use a custom callback to better
 show how callbacks can be used for handling results

---
 docsite/rst/developing_api.rst | 28 +++++++++++++++++++++-------
 1 file changed, 21 insertions(+), 7 deletions(-)

diff --git a/docsite/rst/developing_api.rst b/docsite/rst/developing_api.rst
index dd71cb95ae5..21fe082ff24 100644
--- a/docsite/rst/developing_api.rst
+++ b/docsite/rst/developing_api.rst
@@ -39,13 +39,29 @@ In 2.0 things get a bit more complicated to start, but you end up with much more
 
     #!/usr/bin/env python
 
+    import json
     from collections import namedtuple
     from ansible.parsing.dataloader import DataLoader
     from ansible.vars import VariableManager
     from ansible.inventory import Inventory
     from ansible.playbook.play import Play
     from ansible.executor.task_queue_manager import TaskQueueManager
-    from ansible.plugins import callback_loader
+    from ansible.plugins.callback import CallbackBase
+
+    class ResultCallback(CallbackBase):
+        """A sample callback plugin used for performing an action as results come in
+
+        If you want to collect all results into a single object for processing at
+        the end of the execution, look into utilizing the ``json`` callback plugin
+        or writing your own custom callback plugin
+        """
+        def v2_runner_on_ok(self, result, **kwargs):
+            """Print a json representation of the result
+
+            This method could store the result in an instance attribute for retrieval later
+            """
+            host = result._host
+            print json.dumps({host.name: result._result}, indent=4)
 
     Options = namedtuple('Options', ['connection', 'module_path', 'forks', 'become', 'become_method', 'become_user', 'check'])
     # initialize needed objects
@@ -53,8 +69,9 @@ In 2.0 things get a bit more complicated to start, but you end up with much more
     loader = DataLoader()
     options = Options(connection='local', module_path='/path/to/mymodules', forks=100, become=None, become_method=None, become_user=None, check=False)
     passwords = dict(vault_pass='secret')
-    # Use the JSON callback plugin to store results
-    results_callback = callback_loader.get('json')
+
+    # Instantiate our ResultCallback for handling results as they come in
+    results_callback = ResultCallback()
 
     # create inventory and pass to var manager
     inventory = Inventory(loader=loader, variable_manager=variable_manager, host_list='localhost')
@@ -81,16 +98,13 @@ In 2.0 things get a bit more complicated to start, but you end up with much more
                   loader=loader,
                   options=options,
                   passwords=passwords,
-                  stdout_callback=results_callback,  # Use JSON callback plugin
+                  stdout_callback=results_callback,  # Use our custom callback instead of the ``default`` callback plugin
               )
         result = tqm.run(play)
     finally:
         if tqm is not None:
             tqm.cleanup()
 
-    # Print stdout from the first play, first task, of localhost
-    print(results_callback.results[0]['tasks'][0]['hosts']['localhost']['stdout'])
-
 
 .. _python_api_old: