Changing the repo structure and first version of README

ispras · Jan 24, 2022 · 388a0ad · 388a0ad
1 parent 95b1b06
commit 388a0ad
Show file tree

Hide file tree

Showing 26 changed files with 99 additions and 19 deletions.
diff --git a/README.md b/README.md
@@ -1,2 +1,81 @@
 # cotea
-cotea: Ansible control tool
+
+### cotea is:
+Tool that provides Python API to run Ansible programmatically.
+
+### cotea allows:
+- **To control** Ansible execution by iterating over the Ansible plays and tasks
+- **To embed** Ansible into other systems
+- **To debug** Ansible execution by getting the values of Ansible variables and by retrieving the results of the execution of Ansible tasks/plays
+
+## Installation
+At the moment, only installation from source is possible. In the future, it is planned to install cotea using pip. 
+It is assumed that Ansible is installed in the current environment.
+
+You need just to clone this project:
+```bash
+git clone https://github.com/ispras/cotea
+```
+and use **from cotea.src.** to import any of cotea objects being in the same directory as the cotea folder. 
+
+## Quick start
+```python
+from cotea.src.runner import runner
+from cotea.src.arguments_maker import argument_maker
+
+
+inv_path = "/path/to/inventory"
+playbook_path = "/path/to/playbook"
+
+am = argument_maker()
+am.add_arg("-i", inv_path)
+
+r = runner(playbook_path, am)
+
+while r.has_next_play():
+    setup_ok = r.setup_play_for_run()
+    current_play = r.get_cur_play_name()
+    print("PLAY:", current_play)
+
+    if setup_ok:
+        while r.has_next_task():
+            next_task = r.get_next_task_name()
+            print("\tTASK:", next_task)
+
+            r.run_next_task()
+
+r.finish_ansible()
+```
+Any argument of the "ansible-playbook" command can be passed by using **argument_maker** objects.
+The launch and control of the Ansible is carried out using the **runner** object.
+
+## Debugging 
+
+```python
+# imports and object creation...
+
+specific_play = "s_play"
+specific_task = "s_task"
+s_var_name = "s_var"
+
+while r.has_next_play():
+    setup_ok = r.setup_play_for_run()
+    current_play = r.get_cur_play_name()
+
+    if setup_ok:
+        while r.has_next_task():
+            next_task = r.get_next_task_name()
+            if current_play == specific_play and next_task == specific_task:
+                # getting variable at specific execution point
+                s_var_value = r.get_variable(s_var_name)
+
+            r.run_next_task()
+
+r.finish_ansible()
+
+if r.was_error():
+    print("Ansible error was:", r.get_error_msg())
+```
+With the help of cotea one can do certain things dynamically at specific Ansible execution points. Getting the value of a specific variable at a specific execution point is shown above (the point is determined by a pair of Ansible play and task). If ansible exits with an error one can get the error message programmatically without processing a huge log file.
+
+A detailed overview of all interfaces is provided in [cotea documentation](https://github.com/ispras/cotea/blob/main/docs/cotea_docs.md).
diff --git a/docs/cotea_docs.md b/docs/cotea_docs.md
@@ -0,0 +1 @@
+# cotea documentation
diff --git a/src/__pycache__/ansible_execution_sync.cpython-38.pyc b/src/__pycache__/ansible_execution_sync.cpython-38.pyc
diff --git a/src/__pycache__/arguments_maker.cpython-38.pyc b/src/__pycache__/arguments_maker.cpython-38.pyc
diff --git a/src/__pycache__/runner.cpython-38.pyc b/src/__pycache__/runner.cpython-38.pyc
diff --git a/ansible_execution_sync.py → src/ansible_execution_sync.py b/ansible_execution_sync.py → src/ansible_execution_sync.py
diff --git a/arguments_maker.py → src/arguments_maker.py b/arguments_maker.py → src/arguments_maker.py
diff --git a/runner.py → src/runner.py b/runner.py → src/runner.py
@@ -14,16 +14,16 @@
 from ansible.plugins.strategy.linear import StrategyModule
 from ansible.executor.task_queue_manager import TaskQueueManager
 
-from cotea.ansible_execution_sync import ans_sync
-from cotea.arguments_maker import argument_maker
-from cotea.wrappers.get_batches_wrapper import get_batches_wrapper
-from cotea.wrappers.strategy_run_wrapper import strategy_run_wrapper
-from cotea.wrappers.get_next_task_wrapper import get_next_task_wrapper
-from cotea.wrappers.wait_pending_wrapper import wait_pending_wrapper
-from cotea.wrappers.tqm_run_wrapper import tqm_run_wrapper
-from cotea.wrappers.get_batch_len_wrapper import get_batch_len_wrapper
-from cotea.wrappers.pbcli_run_wrapper import pbcli_run_wrapper
-from cotea.wrappers.play_prereqs_wrapper import play_prereqs_wrapper
+from cotea.src.ansible_execution_sync import ans_sync
+from cotea.src.arguments_maker import argument_maker
+from cotea.src.wrappers.get_batches_wrapper import get_batches_wrapper
+from cotea.src.wrappers.strategy_run_wrapper import strategy_run_wrapper
+from cotea.src.wrappers.get_next_task_wrapper import get_next_task_wrapper
+from cotea.src.wrappers.wait_pending_wrapper import wait_pending_wrapper
+from cotea.src.wrappers.tqm_run_wrapper import tqm_run_wrapper
+from cotea.src.wrappers.get_batch_len_wrapper import get_batch_len_wrapper
+from cotea.src.wrappers.pbcli_run_wrapper import pbcli_run_wrapper
+from cotea.src.wrappers.play_prereqs_wrapper import play_prereqs_wrapper
 
 
 class runner:

diff --git a/src/wrappers/__pycache__/get_batch_len_wrapper.cpython-38.pyc b/src/wrappers/__pycache__/get_batch_len_wrapper.cpython-38.pyc
diff --git a/src/wrappers/__pycache__/get_batches_wrapper.cpython-38.pyc b/src/wrappers/__pycache__/get_batches_wrapper.cpython-38.pyc
diff --git a/src/wrappers/__pycache__/get_next_task_wrapper.cpython-38.pyc b/src/wrappers/__pycache__/get_next_task_wrapper.cpython-38.pyc
diff --git a/src/wrappers/__pycache__/pbcli_run_wrapper.cpython-38.pyc b/src/wrappers/__pycache__/pbcli_run_wrapper.cpython-38.pyc
diff --git a/src/wrappers/__pycache__/play_prereqs_wrapper.cpython-38.pyc b/src/wrappers/__pycache__/play_prereqs_wrapper.cpython-38.pyc
diff --git a/src/wrappers/__pycache__/strategy_run_wrapper.cpython-38.pyc b/src/wrappers/__pycache__/strategy_run_wrapper.cpython-38.pyc
diff --git a/src/wrappers/__pycache__/tqm_run_wrapper.cpython-38.pyc b/src/wrappers/__pycache__/tqm_run_wrapper.cpython-38.pyc
diff --git a/src/wrappers/__pycache__/wait_pending_wrapper.cpython-38.pyc b/src/wrappers/__pycache__/wait_pending_wrapper.cpython-38.pyc
diff --git a/src/wrappers/__pycache__/wrapper_base.cpython-38.pyc b/src/wrappers/__pycache__/wrapper_base.cpython-38.pyc
diff --git a/wrappers/get_batch_len_wrapper.py → src/wrappers/get_batch_len_wrapper.py b/wrappers/get_batch_len_wrapper.py → src/wrappers/get_batch_len_wrapper.py
@@ -1,4 +1,4 @@
-from cotea.wrappers.wrapper_base import wrapper_base
+from cotea.src.wrappers.wrapper_base import wrapper_base
 
 
 # wraps ansible.inventory.manager.InventoryManager.restrict_to_hosts()

diff --git a/wrappers/get_batches_wrapper.py → src/wrappers/get_batches_wrapper.py b/wrappers/get_batches_wrapper.py → src/wrappers/get_batches_wrapper.py
@@ -1,4 +1,4 @@
-from cotea.wrappers.wrapper_base import wrapper_base
+from cotea.src.wrappers.wrapper_base import wrapper_base
 
 
 # wraps ansible.executor.playbook_executor.PlaybookExecutor._get_serialized_batches()

diff --git a/wrappers/get_next_task_wrapper.py → src/wrappers/get_next_task_wrapper.py b/wrappers/get_next_task_wrapper.py → src/wrappers/get_next_task_wrapper.py
@@ -1,4 +1,4 @@
-from cotea.wrappers.wrapper_base import wrapper_base
+from cotea.src.wrappers.wrapper_base import wrapper_base
 
 
 # wraps ansible.plugins.strategy.linear.StrategyModule._get_next_task_lockstep()

diff --git a/wrappers/pbcli_run_wrapper.py → src/wrappers/pbcli_run_wrapper.py b/wrappers/pbcli_run_wrapper.py → src/wrappers/pbcli_run_wrapper.py
@@ -1,4 +1,4 @@
-from cotea.wrappers.wrapper_base import wrapper_base
+from cotea.src.wrappers.wrapper_base import wrapper_base
 
 
 # wraps from ansible.cli.playbook.PlaybookCLI.run()

diff --git a/wrappers/play_prereqs_wrapper.py → src/wrappers/play_prereqs_wrapper.py b/wrappers/play_prereqs_wrapper.py → src/wrappers/play_prereqs_wrapper.py
@@ -1,4 +1,4 @@
-from cotea.wrappers.wrapper_base import wrapper_base
+from cotea.src.wrappers.wrapper_base import wrapper_base
 
 
 # wraps from ansible.cli.CLI._play_prereqs()

diff --git a/wrappers/strategy_run_wrapper.py → src/wrappers/strategy_run_wrapper.py b/wrappers/strategy_run_wrapper.py → src/wrappers/strategy_run_wrapper.py
@@ -1,4 +1,4 @@
-from cotea.wrappers.wrapper_base import wrapper_base
+from cotea.src.wrappers.wrapper_base import wrapper_base
 
 
 # wraps ansible.plugins.strategy.linear.StrategyModule.run()

diff --git a/wrappers/tqm_run_wrapper.py → src/wrappers/tqm_run_wrapper.py b/wrappers/tqm_run_wrapper.py → src/wrappers/tqm_run_wrapper.py
@@ -1,4 +1,4 @@
-from cotea.wrappers.wrapper_base import wrapper_base
+from cotea.src.wrappers.wrapper_base import wrapper_base
 
 
 # wraps ansible.executor.task_queue_manager.TaskQueueManager.run()

diff --git a/wrappers/wait_pending_wrapper.py → src/wrappers/wait_pending_wrapper.py b/wrappers/wait_pending_wrapper.py → src/wrappers/wait_pending_wrapper.py
@@ -1,4 +1,4 @@
-from cotea.wrappers.wrapper_base import wrapper_base
+from cotea.src.wrappers.wrapper_base import wrapper_base
 
 
 # wraps ansible.plugins.strategy.StrategyBase._wait_on_pending_results()

diff --git a/wrappers/wrapper_base.py → src/wrappers/wrapper_base.py b/wrappers/wrapper_base.py → src/wrappers/wrapper_base.py