first_found: clear up the skip option usage (#74816)

This commit is contained in:
Ian Wienand 2021-06-03 16:11:46 +10:00 committed by GitHub
parent be9f8c69d1
commit fe20546d36
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23

View file

@ -15,7 +15,7 @@ DOCUMENTATION = """
to the containing locations of role / play / include and so on. to the containing locations of role / play / include and so on.
- The list of files has precedence over the paths searched. - The list of files has precedence over the paths searched.
For example, A task in a role has a 'file1' in the play's relative path, this will be used, 'file2' in role's relative path will not. For example, A task in a role has a 'file1' in the play's relative path, this will be used, 'file2' in role's relative path will not.
- Either a list of files C(_terms) or a key `files` with a list of files is required for this plugin to operate. - Either a list of files C(_terms) or a key C(files) with a list of files is required for this plugin to operate.
notes: notes:
- This lookup can be used in 'dual mode', either passing a list of file names or a dictionary that has C(files) and C(paths). - This lookup can be used in 'dual mode', either passing a list of file names or a dictionary that has C(files) and C(paths).
options: options:
@ -32,27 +32,51 @@ DOCUMENTATION = """
skip: skip:
type: boolean type: boolean
default: False default: False
description: Return an empty list if no file is found, instead of an error. description:
- When C(True), return an empty list when no files are matched.
- This is useful when used with C(with_first_found), as an empty list return to C(with_) calls
causes the calling task to be skipped.
- When used as a template via C(lookup) or C(query), setting I(skip=True) will *not* cause the task to skip.
Tasks must handle the empty list return from the template.
- When C(False) and C(lookup) or C(query) specifies I(errors='ignore') all errors (including no file found,
but potentially others) return an empty string or an empty list respectively.
- When C(True) and C(lookup) or C(query) specifies I(errors='ignore'), no file found will return an empty
list and other potential errors return an empty string or empty list depending on the template call
(in other words return values of C(lookup) v C(query)).
""" """
EXAMPLES = """ EXAMPLES = """
- name: show first existing file or ignore if none do - name: Set _found_file to the first existing file, raising an error if a file is not found
debug: set_fact:
msg: "{{ lookup('first_found', findme, errors='ignore') }}" _found_file: "{{ lookup('first_found', findme) }}"
vars: vars:
findme: findme:
- /path/to/foo.txt - /path/to/foo.txt
- bar.txt # will be looked in files/ dir relative to role and/or play - bar.txt # will be looked in files/ dir relative to role and/or play
- /path/to/biz.txt - /path/to/biz.txt
- name: include tasks only if files exist. - name: Set _found_file to the first existing file, or an empty list if no files found
include_tasks: set_fact:
file: "{{ query('first_found', params) }}" _found_file: "{{ lookup('first_found', files, paths=['/extra/path'], skip=True) }}"
vars: vars:
params: files:
files: - /path/to/foo.txt
- path/tasks.yaml - /path/to/bar.txt
- path/other_tasks.yaml
- name: Include tasks only if one of the files exist, otherwise skip the task
include_tasks:
file: "{{ item }}"
with_first_found:
files:
- path/tasks.yaml
- path/other_tasks.yaml
skip: True
- name: Include tasks only if one of the files exists, otherwise skip
include_tasks: '{{ tasks_file }}'
when: tasks_file != ""
vars:
tasks_file: "{{ lookup('first_found', files=['tasks.yaml', 'other_tasks.yaml'], errors='ignore') }}"
- name: | - name: |
copy first existing file found to /some/file, copy first existing file found to /some/file,
@ -209,4 +233,4 @@ class LookupModule(LookupBase):
if skip: if skip:
# NOTE: global skip wont matter, only last 'skip' value in dict term # NOTE: global skip wont matter, only last 'skip' value in dict term
return [] return []
raise AnsibleLookupError("No file was found when using first_found. Use errors='ignore' to allow this task to be skipped if no files are found") raise AnsibleLookupError("No file was found when using first_found.")