document lookup errors optoin (#39645)

* document lookup errors optoin

* changed to doc

* updated as per feedback

(cherry picked from commit 32c2aae258)

changelogs/fragments/lkp_doics.yml

@@ -0,0 +1,2 @@
+- docs:
+    - added docs on new lookup option that allows users to controll errors

docs/docsite/rst/plugins/lookup.rst

@@ -65,6 +65,46 @@ You can combine lookups with :ref:`playbooks_filters`, :ref:`playbooks_tests` an
         - "{{lookup('sequence', 'end=42 start=2 step=2')|map('log', 4)|list)}}"
         - ['a', 'c', 'd', 'c']
 
+.. versionadded:: 2.5
+
+You can now control how errors behave in all lookup plugins by setting ``errors`` to ``ignore``, ``warn``, or ``strict``. The default setting is ``strict``, which causes the task to fail. For example:
+
+To ignore errors::
+
+    - name: file doesnt exist, but i dont care .. file plugin itself warns anyways ...
+      debug: msg="{{ lookup('file', '/idontexist', errors='ignore') }}"
+
+    [WARNING]: Unable to find '/idontexist' in expected paths (use -vvvvv to see paths)
+
+    ok: [localhost] => {
+        "msg": ""
+    }
+
+
+To get a warning instead of a failure::
+
+    - name: file doesnt exist, let me know, but continue
+      debug: msg="{{ lookup('file', '/idontexist', errors='warn') }}"
+
+    [WARNING]: Unable to find '/idontexist' in expected paths (use -vvvvv to see paths)
+
+    [WARNING]: An unhandled exception occurred while running the lookup plugin 'file'. Error was a <class 'ansible.errors.AnsibleError'>, original message: could not locate file in lookup: /idontexist
+
+    ok: [localhost] => {
+        "msg": ""
+    }
+
+
+Fatal error (the default)::
+
+    - name: file doesnt exist, FAIL (this is the default)
+      debug: msg="{{ lookup('file', '/idontexist', errors='strict') }}"
+
+    [WARNING]: Unable to find '/idontexist' in expected paths (use -vvvvv to see paths)
+
+    fatal: [localhost]: FAILED! => {"msg": "An unhandled exception occurred while running the lookup plugin 'file'. Error was a <class 'ansible.errors.AnsibleError'>, original message: could not locate file in lookup: /idontexist"}
+
+
 .. _query:
 
 query

docs/docsite/rst/porting_guides/porting_guide_2.5.rst

@@ -75,6 +75,7 @@ Included file:
 
 The relevant change in those examples is, that in Ansible 2.5, the included file defines the tag ``distro_include`` again. The tag is not inherited automatically.
 
+
 Deprecated
 ==========
 
@@ -219,6 +220,12 @@ Filter
 The lookup plugin API now throws an error if a non-iterable value is returned from a plugin. Previously, numbers or
 other non-iterable types returned by a plugin were accepted without error or warning. This change was made because plugins should always return a list. Please note that plugins that return strings and other non-list iterable values will not throw an error, but may cause unpredictable behavior. If you have a custom lookup plugin that does not return a list, you should modify it to wrap the return values in a list.
 
+Lookup
+-------
+
+A new option was added to lookup plugins globally named ``error`` which allows you to control how errors produced by the lookup are handled, before this option they were always fatal. Valid values for this option are ``warn``, ``ignore`` and ``strict``. See the :doc:`lookup <../plugins/lookup>` page for more details.
+
+
 Porting custom scripts
 ======================