From 283fee90a796659755531b4c6b316622e652378f Mon Sep 17 00:00:00 2001 From: Jiri Tyr Date: Wed, 22 Nov 2017 22:05:29 +0000 Subject: [PATCH] Unifying wording and formatting of all include and import modules (#31938) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Unifying wording and formatting of all include and import modules * Changes based on comments from dharmabumstead * Removed instances of the term ‘Ansible Engine’ * Removed instances of term ‘Ansible Engine’ * Updated term * Updated wording * Updated wording * Removed the term ‘Ansible Engine’ --- .../modules/utilities/logic/_include.py | 57 +++++++------- .../utilities/logic/import_playbook.py | 35 ++++----- .../modules/utilities/logic/import_role.py | 41 +++++----- .../modules/utilities/logic/import_tasks.py | 35 ++++----- .../modules/utilities/logic/include_role.py | 50 +++++++------ .../modules/utilities/logic/include_tasks.py | 31 ++++---- .../modules/utilities/logic/include_vars.py | 74 ++++++++++--------- 7 files changed, 169 insertions(+), 154 deletions(-) diff --git a/lib/ansible/modules/utilities/logic/_include.py b/lib/ansible/modules/utilities/logic/_include.py index e232b28bd63..9afc17ad980 100644 --- a/lib/ansible/modules/utilities/logic/_include.py +++ b/lib/ansible/modules/utilities/logic/_include.py @@ -7,71 +7,74 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -ANSIBLE_METADATA = {'metadata_version': '1.1', - 'status': ['deprecated'], - 'supported_by': 'core'} +ANSIBLE_METADATA = { + 'metadata_version': '1.1', + 'status': ['deprecated'], + 'supported_by': 'core' +} DOCUMENTATION = ''' --- -author: - - "Ansible Core Team (@ansible)" +author: Ansible Core Team (@ansible) module: include -short_description: include a play or task list. +short_description: Include a play or task list deprecated: - The include action was too confusing, dealing with both plays and tasks, being both dynamic and static. This module will be removed in version 2.8. - As alternatives use include_tasks, import_playbook, import_tasks. + The include action was too confusing, dealing with both plays and tasks, being both dynamic and static. This module + will be removed in version 2.8. As alternatives use M(include_tasks), M(import_playbook), M(import_tasks). description: - - Includes a file with a list of plays or tasks to be executed in the current playbook. - - Files with a list of plays can only be included at the top level, lists of tasks can only be included where tasks normally run (in play). - - Before 2.0 all includes were 'static', executed at play compile time. - - Static includes are not subject to most directives, for example, loops or conditionals, they are applied instead to each inherited task. - - Since 2.0 task includes are dynamic and behave more like real tasks. This means they can be looped, skipped and use variables from any source. - Ansible tries to auto detect this, use the `static` directive (new in 2.1) to bypass autodetection. - - This module is also supported for Windows targets. + - Includes a file with a list of plays or tasks to be executed in the current playbook. + - Files with a list of plays can only be included at the top level. Lists of tasks can only be included where tasks + normally run (in play). + - Before Ansible version 2.0, all includes were 'static' and were executed when the play was compiled. + - Static includes are not subject to most directives. For example, loops or conditionals are applied instead to each + inherited task. + - Since Ansible 2.0, task includes are dynamic and behave more like real tasks. This means they can be looped, + skipped and use variables from any source. Ansible tries to auto detect this, but you can use the `static` + directive (which was added in Ansible 2.1) to bypass autodetection. + - This module is also supported for Windows targets. version_added: "0.6" options: free-form: description: - - This module allows you to specify the name of the file directly w/o any other options. + - This module allows you to specify the name of the file directly without any other options. notes: - - This is really not a module, though it appears as such, this is a feature of the Ansible Engine, as such it cannot be overridden the same way a - module can. - - This module is also supported for Windows targets. + - This is a core feature of Ansible, rather than a module, and cannot be overridden like a module. + - This module is also supported for Windows targets. ''' EXAMPLES = """ -# include a play after another play - hosts: localhost tasks: - debug: - msg: "play1" + msg: play1 -- include: otherplays.yml +- name: Include a play after another play + include: otherplays.yaml -# include task list in play - hosts: all tasks: - debug: msg: task1 - - include: stuff.yml + - name: Include task list in play + include: stuff.yaml - debug: msg: task10 -# dyanmic include task list in play - hosts: all tasks: - debug: msg: task1 - - include: "{{ hostvar }}.yml" + - name: Include task list in play only if the condition is true + include: "{{ hostvar }}.yaml" static: no when: hostvar is defined """ RETURN = """ -# this module does not return anything except plays or tasks to execute +# This module does not return anything except plays or tasks to execute. """ diff --git a/lib/ansible/modules/utilities/logic/import_playbook.py b/lib/ansible/modules/utilities/logic/import_playbook.py index b3e0b932457..4609fbab21d 100644 --- a/lib/ansible/modules/utilities/logic/import_playbook.py +++ b/lib/ansible/modules/utilities/logic/import_playbook.py @@ -7,37 +7,38 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -ANSIBLE_METADATA = {'metadata_version': '1.1', - 'status': ['preview'], - 'supported_by': 'core'} +ANSIBLE_METADATA = { + 'metadata_version': '1.1', + 'status': ['preview'], + 'supported_by': 'core' +} DOCUMENTATION = ''' --- -author: - - "Ansible Core Team (@ansible)" +author: Ansible Core Team (@ansible) module: import_playbook -short_description: import a playbook. +short_description: Import a playbook description: - - Includes a file with a list of plays to be executed. - - Files with a list of plays can only be included at the top level, you cannot use this action inside a Play. + - Includes a file with a list of plays to be executed. + - Files with a list of plays can only be included at the top level. You cannot use this action inside a play. version_added: "2.4" options: free-form: description: - - This action allows you to specify the name of the file directly w/o any other options. + - The name of the imported playbook is specified directly without any other option. notes: - - This is really not a module, this is a feature of the Ansible Engine, as such it cannot be overridden the same way a module can. + - This is a core feature of Ansible, rather than a module, and cannot be overridden like a module. ''' EXAMPLES = """ -- name: include a play after another play - hosts: localhost +- hosts: localhost tasks: - debug: - msg: "play1" + msg: play1 -- import_playbook: otherplays.yml +- name: Include a play after another play + import_playbook: otherplays.yaml - name: This DOES NOT WORK @@ -46,10 +47,10 @@ EXAMPLES = """ - debug: msg: task1 - - name: This failes because I'm inside a play already - import_playbook: stuff.yml + - name: This fails because I'm inside a play already + import_playbook: stuff.yaml """ RETURN = """ -# this module does not return anything except plays to execute +# This module does not return anything except plays to execute. """ diff --git a/lib/ansible/modules/utilities/logic/import_role.py b/lib/ansible/modules/utilities/logic/import_role.py index 36df8a1e90b..b123f4416b4 100644 --- a/lib/ansible/modules/utilities/logic/import_role.py +++ b/lib/ansible/modules/utilities/logic/import_role.py @@ -7,21 +7,23 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -ANSIBLE_METADATA = {'metadata_version': '1.1', - 'status': ['preview'], - 'supported_by': 'core'} +ANSIBLE_METADATA = { + 'metadata_version': '1.1', + 'status': ['preview'], + 'supported_by': 'core' +} DOCUMENTATION = ''' --- -author: - - "Ansible Core Team (@ansible)" +author: Ansible Core Team (@ansible) module: import_role short_description: Import a role into a play description: - - Mostly like the `roles:` keyword this action loads a role, but it allows you to control when the tasks run in between other playbook tasks. - - Most keywords, loops and conditionals will not be applied to this action, but to the imported tasks instead. - If you want the opposite behaviour, use M(include_role) instead. + - Much like the `roles:` keyword, this task loads a role, but it allows you to control it when the role tasks run in + between other tasks of the play. + - Most keywords, loops and conditionals will only be applied to the imported tasks, not to this statement itself. If + you want the opposite behaviour, use M(include_role) instead. version_added: "2.4" options: name: @@ -30,19 +32,19 @@ options: required: True tasks_from: description: - - "File to load from a Role's tasks/ directory." + - File to load from a role's C(tasks/) directory. required: False - default: 'main' + default: main vars_from: description: - - "File to load from a Role's vars/ directory." + - File to load from a role's C(vars/) directory. required: False - default: 'main' + default: main defaults_from: description: - - "File to load from a Role's defaults/ directory." + - File to load from a role's C(defaults/) directory. required: False - default: 'main' + default: main allow_duplicates: description: - Overrides the role's metadata setting to allow using a role more than once with the same parameters. @@ -50,10 +52,11 @@ options: default: True private: description: - - If True the variables from defaults/ and vars/ in a role will not be made available to the rest of the play. + - If C(True) the variables from C(defaults/) and C(vars/) in a role will not be made available to the rest of the + play. default: None notes: - - Handlers are made available to the whole play. + - Handlers are made available to the whole play. ''' EXAMPLES = """ @@ -62,7 +65,7 @@ EXAMPLES = """ - import_role: name: myrole - - name: Run tasks/other.yml instead of 'main' + - name: Run tasks/other.yaml instead of 'main' import_role: name: myrole tasks_from: other @@ -71,7 +74,7 @@ EXAMPLES = """ import_role: name: myrole vars: - rolevar1: 'value from task' + rolevar1: value from task - name: Apply loop to each task in role import_role: @@ -89,5 +92,5 @@ EXAMPLES = """ """ RETURN = """ -# this module does not return anything except tasks to execute +# This module does not return anything except tasks to execute. """ diff --git a/lib/ansible/modules/utilities/logic/import_tasks.py b/lib/ansible/modules/utilities/logic/import_tasks.py index 25aa51fffbc..d107c5e02e3 100644 --- a/lib/ansible/modules/utilities/logic/import_tasks.py +++ b/lib/ansible/modules/utilities/logic/import_tasks.py @@ -7,52 +7,53 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -ANSIBLE_METADATA = {'metadata_version': '1.1', - 'status': ['preview'], - 'supported_by': 'core'} +ANSIBLE_METADATA = { + 'metadata_version': '1.1', + 'status': ['preview'], + 'supported_by': 'core' +} DOCUMENTATION = ''' --- -author: - - "Ansible Core Team (@ansible)" +author: Ansible Core Team (@ansible) module: import_tasks -short_description: import a task list. +short_description: Import a task list description: - - Imports a list of tasks to be added to the current playbook for subsequent execution. + - Imports a list of tasks to be added to the current playbook for subsequent execution. version_added: "2.4" options: free-form: description: - - This action allows you to specify the name of the file directly w/o any other options. - - Any loops, conditionals and most other keywords will be applied to the included tasks, not to this statement itself. - - If you need any of those to apply to this action, use M(include_tasks) instead. + - The name of the imported file is specified directly without any other option. + - Most keywords, including loops and conditionals, only applied to the imported tasks, not to this statement + itself. If you need any of those to apply, use M(include_tasks) instead. notes: - - This is really not a module, this is a feature of the Ansible Engine, as such it cannot be overridden the same way a module can. + - This is a core feature of Ansible, rather than a module, and cannot be overridden like a module. ''' EXAMPLES = """ -# include task list in play - hosts: all tasks: - debug: msg: task1 - - import_tasks: stuff.yml + - name: Include task list in play + import_tasks: stuff.yaml - debug: msg: task10 -# apply conditional to all imported tasks -- hosts: all + hosts: all tasks: - debug: msg: task1 - - import_tasks: stuff.yml + - name: Apply conditional to all imported tasks + import_tasks: stuff.yaml when: hostvar is defined """ RETURN = """ -# this module does not return anything except tasks to execute +# This module does not return anything except tasks to execute. """ diff --git a/lib/ansible/modules/utilities/logic/include_role.py b/lib/ansible/modules/utilities/logic/include_role.py index 0ff592ac3c9..862d8773364 100644 --- a/lib/ansible/modules/utilities/logic/include_role.py +++ b/lib/ansible/modules/utilities/logic/include_role.py @@ -7,20 +7,23 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -ANSIBLE_METADATA = {'metadata_version': '1.1', - 'status': ['preview'], - 'supported_by': 'core'} +ANSIBLE_METADATA = { + 'metadata_version': '1.1', + 'status': ['preview'], + 'supported_by': 'core' +} DOCUMENTATION = ''' --- -author: - - "Ansible Core Team (@ansible)" +author: Ansible Core Team (@ansible) module: include_role short_description: Load and execute a role description: - - Loads and executes a role as a task, this frees roles from the `role:` directive and allows them to be treated more as tasks. - - This module is also supported for Windows targets. + - Loads and executes a role as a task dynamically. This frees roles from the `roles:` directive and allows them to be + treated more as tasks. + - Unlike M(import_role), most keywords, including loops and conditionals, apply to this statement. + - This module is also supported for Windows targets. version_added: "2.2" options: name: @@ -29,19 +32,19 @@ options: required: True tasks_from: description: - - "File to load from a Role's tasks/ directory." + - File to load from a role's C(tasks/) directory. required: False - default: 'main' + default: main vars_from: description: - - "File to load from a Role's vars/ directory." + - File to load from a role's C(vars/) directory. required: False - default: 'main' + default: main defaults_from: description: - - "File to load from a Role's defaults/ directory." + - File to load from a role's C(defaults/) directory. required: False - default: 'main' + default: main allow_duplicates: description: - Overrides the role's metadata setting to allow using a role more than once with the same parameters. @@ -49,21 +52,22 @@ options: default: True private: description: - - If True the variables from defaults/ and vars/ in a role will not be made available to the rest of the play. + - If C(True) the variables from C(defaults/) and C(vars/) in a role will not be made available to the rest of the + play. default: None notes: - - Handlers are made available to the whole play. - - Before 2.4, as with C(include), this task could be static or dynamic, If static it implied that it won't need templating nor loops nor conditionals - and will show included tasks in the --list options. - Ansible would try to autodetect what is needed, but you can set `static` to `yes` or `no` at task level to control this. - - After 2.4, you can use M(import_role) for 'static' behaviour and this action for 'dynamic' one. + - Handlers are made available to the whole play. + - Before Ansible 2.4, as with C(include), this task could be static or dynamic, If static, it implied that it won't + need templating, loops or conditionals and will show included tasks in the `--list` options. Ansible would try to + autodetect what is needed, but you can set `static` to `yes` or `no` at task level to control this. + - After Ansible 2.4, you can use M(import_role) for 'static' behaviour and this action for 'dynamic' one. ''' EXAMPLES = """ - include_role: name: myrole -- name: Run tasks/other.yml instead of 'main' +- name: Run tasks/other.yaml instead of 'main' include_role: name: myrole tasks_from: other @@ -72,7 +76,7 @@ EXAMPLES = """ include_role: name: myrole vars: - rolevar1: 'value from task' + rolevar1: value from task - name: Use role in loop include_role: @@ -83,12 +87,12 @@ EXAMPLES = """ loop_control: loop_var: roleinputvar -- name: conditional role +- name: Conditional role include_role: name: myrole when: not idontwanttorun """ RETURN = """ -# this module does not return anything except tasks to execute +# This module does not return anything except tasks to execute. """ diff --git a/lib/ansible/modules/utilities/logic/include_tasks.py b/lib/ansible/modules/utilities/logic/include_tasks.py index 2eaa9bdade9..67a8681eb41 100644 --- a/lib/ansible/modules/utilities/logic/include_tasks.py +++ b/lib/ansible/modules/utilities/logic/include_tasks.py @@ -7,51 +7,52 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -ANSIBLE_METADATA = {'metadata_version': '1.1', - 'status': ['preview'], - 'supported_by': 'core'} +ANSIBLE_METADATA = { + 'metadata_version': '1.1', + 'status': ['preview'], + 'supported_by': 'core' +} DOCUMENTATION = ''' --- -author: - - "Ansible Core Team (@ansible)" +author: Ansible Core Team (@ansible) module: include_tasks -short_description: dynamically include a task list. +short_description: Dynamically include a task list description: - - Includes a file with a list of tasks to be executed in the current playbook. + - Includes a file with a list of tasks to be executed in the current playbook. version_added: "2.4" options: free-form: description: - - This action allows you to specify the name of the file directly w/o any other options. - - Unlike M(import_tasks) this action will be affected by most keywords, including loops and conditionals. + - The name of the imported file is specified directly without any other option. + - Unlike M(import_tasks), most keywords, including loops and conditionals, apply to this statement. notes: - - This is really not a module, this is a feature of the Ansible Engine, as such it cannot be overridden the same way a module can. + - This is a core feature of the Ansible, rather than a module, and cannot be overridden like a module. ''' EXAMPLES = """ -# include task list in play - hosts: all tasks: - debug: msg: task1 - - include_tasks: stuff.yml + - name: Include task list in play + include_tasks: stuff.yaml - debug: msg: task10 -# dyanmic include task list in play - hosts: all tasks: - debug: msg: task1 - - include_tasks: "{{ hostvar }}.yml" + - name: Include task list in play only if the condition is true + include_tasks: "{{ hostvar }}.yaml" when: hostvar is defined """ RETURN = """ -# this module does not return anything except tasks to execute +# This module does not return anything except tasks to execute. """ diff --git a/lib/ansible/modules/utilities/logic/include_vars.py b/lib/ansible/modules/utilities/logic/include_vars.py index e82e76e2b69..921ca1e8e5e 100644 --- a/lib/ansible/modules/utilities/logic/include_vars.py +++ b/lib/ansible/modules/utilities/logic/include_vars.py @@ -5,27 +5,29 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -ANSIBLE_METADATA = {'metadata_version': '1.1', - 'status': ['stableinterface'], - 'supported_by': 'core'} +ANSIBLE_METADATA = { + 'metadata_version': '1.1', + 'status': ['stableinterface'], + 'supported_by': 'core' +} DOCUMENTATION = ''' --- -author: "Allen Sanabria (@linuxdynasty)" +author: Allen Sanabria (@linuxdynasty) module: include_vars -short_description: Load variables from files, dynamically within a task. +short_description: Load variables from files, dynamically within a task description: - - Loads variables from a YAML/JSON files dynamically from within a file or from a directory recursively during task runtime. If loading a directory, - the files are sorted alphabetically before being loaded. - - This module is also supported for Windows targets. + - Loads variables from a YAML/JSON files dynamically from within a file or from a directory recursively during task + runtime. If loading a directory, the files are sorted alphabetically before being loaded. + - This module is also supported for Windows targets. version_added: "1.4" options: file: version_added: "2.2" description: - - The file name from which variables should be loaded. - - If the path is relative, it will look for the file in vars/ subdirectory of a role or relative to playbook. + - The file name from which variables should be loaded. + - If the path is relative, it will look for the file in vars/ subdirectory of a role or relative to playbook. dir: version_added: "2.2" description: @@ -35,13 +37,13 @@ options: name: version_added: "2.2" description: - - The name of a variable into which assign the included vars, if omitted (null) they will be made top level vars. + - The name of a variable into which assign the included vars. If omitted (null) they will be made top level vars. default: null depth: version_added: "2.2" description: - - When using C(dir), this module will, by default, recursively go through each sub directory and load up the variables. - By explicitly setting the depth, this module will only go as deep as the depth. + - When using C(dir), this module will, by default, recursively go through each sub directory and load up the + variables. By explicitly setting the depth, this module will only go as deep as the depth. default: 0 files_matching: version_added: "2.2" @@ -57,65 +59,65 @@ options: version_added: "2.3" description: - List of file extensions to read when using C(dir). - default: ['yaml', 'yml', 'json'] + default: [yaml, yml, json] required: False free-form: description: - - This module allows you to specify the 'file' option directly w/o any other options. - There is no 'free-form' option, this is just an indicator, see example below. + - This module allows you to specify the 'file' option directly without any other options. + There is no 'free-form' option, this is just an indicator, see example below. notes: - - This module is also supported for Windows targets. + - This module is also supported for Windows targets. ''' EXAMPLES = """ -- name: Include vars of stuff.yml into the 'stuff' variable (2.2). +- name: Include vars of stuff.yaml into the 'stuff' variable (2.2). include_vars: - file: stuff.yml + file: stuff.yaml name: stuff - name: Conditionally decide to load in variables into 'plans' when x is 0, otherwise do not. (2.2) include_vars: - file: contingency_plan.yml + file: contingency_plan.yaml name: plans when: x == 0 - name: Load a variable file based on the OS type, or a default if not found. Using free-form to specify the file. include_vars: "{{ item }}" with_first_found: - - "{{ ansible_distribution }}.yml" - - "{{ ansible_os_family }}.yml" - - "default.yml" + - "{{ ansible_distribution }}.yaml" + - "{{ ansible_os_family }}.yaml" + - default.yaml -- name: bare include (free-form) - include_vars: myvars.yml +- name: Bare include (free-form) + include_vars: myvars.yaml - name: Include all .json and .jsn files in vars/all and all nested directories (2.3) include_vars: - dir: 'vars/all' + dir: vars/all extensions: - json - jsn - name: Include all default extension files in vars/all and all nested directories and save the output in test. (2.2) include_vars: - dir: 'vars/all' + dir: vars/all name: test - name: Include default extension files in vars/services (2.2) include_vars: - dir: 'vars/services' + dir: vars/services depth: 1 -- name: Include only files matching bastion.yml (2.2) +- name: Include only files matching bastion.yaml (2.2) include_vars: - dir: 'vars' - files_matching: 'bastion.yml' + dir: vars + files_matching: bastion.yaml -- name: Include all .yml files except bastion.yml (2.3) +- name: Include all .yaml files except bastion.yaml (2.3) include_vars: - dir: 'vars' - ignore_files: 'bastion.yml' - extensions: ['yml'] + dir: vars + ignore_files: bastion.yaml + extensions: [yaml] """ RETURN = ''' @@ -128,6 +130,6 @@ ansible_included_var_files: description: A list of files that were successfully included returned: success type: list - sample: [ '/path/to/file.yml', '/path/to/file.json' ] + sample: [ '/path/to/file.yaml', '/path/to/file.json' ] version_added: 2.4 '''