[backport][2.9][PR #70446] Refactor Python API examples and docs (#70851)

* Add boilerplate snippet into `examples/`

It is a partial backport of #70224

(partially cherry picked from commit 4816bb4f43ee22f20fa7d75a79db659cc1cdeaf3)

* Refactor Python API examples and docs

PR #70446: it's a follow-up for #70445.

It includes a merge of `examples/scripts/uptime.py` and a similar
code snippet from `docs/docsite/rst/dev_guide/developing_api.rst`.

This patch also changes the docs RST file to include contents of
the example file instead of holding a copy of a similar code.

(cherry picked from commit 20bb91509279ff91bf8410972827a95e1af55075)

1 files changed, 3 insertions, 85 deletions

diff --git a/docs/docsite/rst/dev_guide/developing_api.rst b/docs/docsite/rst/dev_guide/developing_api.rst
index 5e08c7cc60..c7505a747b 100644
--- a/docs/docsite/rst/dev_guide/developing_api.rst
+++ b/docs/docsite/rst/dev_guide/developing_api.rst
@@ -23,92 +23,10 @@ or have access control and logging demands, please see the `Ansible Tower docume
 Python API example
 ==================
 
-This example is a simple demonstration that shows how to minimally run a couple of tasks::
-
-    #!/usr/bin/env python
-
-    import json
-    import shutil
-    from ansible.module_utils.common.collections import ImmutableDict
-    from ansible.parsing.dataloader import DataLoader
-    from ansible.vars.manager import VariableManager
-    from ansible.inventory.manager import InventoryManager
-    from ansible.playbook.play import Play
-    from ansible.executor.task_queue_manager import TaskQueueManager
-    from ansible.plugins.callback import CallbackBase
-    from ansible import context
-    import ansible.constants as C
-
-    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))
-
-    # since the API is constructed for CLI it expects certain options to always be set in the context object
-    context.CLIARGS = ImmutableDict(connection='local', module_path=['/to/mymodules'], forks=10, become=None,
-                                    become_method=None, become_user=None, check=False, diff=False)
-
-    # initialize needed objects
-    loader = DataLoader() # Takes care of finding and reading yaml, json and ini files
-    passwords = dict(vault_pass='secret')
-
-    # Instantiate our ResultCallback for handling results as they come in. Ansible expects this to be one of its main display outlets
-    results_callback = ResultCallback()
-
-    # create inventory, use path to host config file as source or hosts in a comma separated string
-    inventory = InventoryManager(loader=loader, sources='localhost,')
-
-    # variable manager takes care of merging all the different sources to give you a unified view of variables available in each context
-    variable_manager = VariableManager(loader=loader, inventory=inventory)
-
-    # Instantiate task queue manager, which takes care of forking
-    # and setting up all objects to iterate over host list and tasks.
-    # IMPORTANT: This also adds library dirs paths to the module loader
-    # IMPORTANT: and so it must be initialized before calling `Play.load()`.
-    tqm = TaskQueueManager(
-        inventory=inventory,
-        variable_manager=variable_manager,
-        loader=loader,
-        passwords=passwords,
-        stdout_callback=results_callback,  # Use our custom callback instead of the ``default`` callback plugin, which prints to stdout
-    )
-
-    # create data structure that represents our play, including tasks, this is basically what our YAML loader does internally.
-    play_source =  dict(
-            name = "Ansible Play",
-            hosts = 'localhost',
-            gather_facts = 'no',
-            tasks = [
-                dict(action=dict(module='shell', args='ls'), register='shell_out'),
-                dict(action=dict(module='debug', args=dict(msg='{{shell_out.stdout}}')))
-             ]
-        )
-
-    # Create play object, playbook objects use .load instead of init or new methods,
-    # this will also automatically create the task objects from the info provided in play_source
-    play = Play().load(play_source, variable_manager=variable_manager, loader=loader)
-
-    # Actually run it
-    try:
-        result = tqm.run(play) # most interesting data for a play is actually sent to the callback's methods
-    finally:
-        # we always need to cleanup child procs and the structures we use to communicate with them
-        if tqm is not None:
-            tqm.cleanup()
-
-        # Remove ansible tmpdir
-        shutil.rmtree(C.DEFAULT_LOCAL_TMP, True)
+This example is a simple demonstration that shows how to minimally run a couple of tasks:
 
+.. literalinclude:: ../../../../examples/scripts/uptime.py
+   :language: python
 
 .. note:: Ansible emits warnings and errors via the display object, which prints directly to stdout, stderr and the Ansible log.