Add 'default' to 'env' lookup (#76327)

* Add 'default' to 'env' lookup

Co-authored-by: Sloane Hertel <19572925+s-hertel@users.noreply.github.com>

changelogs/fragments/evn_default.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - env lookup, add default option

lib/ansible/plugins/lookup/env.py

@@ -17,24 +17,36 @@ DOCUMENTATION = """
         description:
           - Environment variable or list of them to lookup the values for.
         required: True
+      default:
+        description: What return when the variable is undefined
+        type: raw
+        default: ''
+        version_added: '2.13'
     notes:
-      - The module returns an empty string if the environment variable is not
-        defined. This makes it impossible to differentiate between the case the
-        variable is not defined and the case the variable is defined but it
-        contains an empty string.
-      - The C(default) filter requires second parameter to be set to C(True)
-        in order to set a default value in the case the variable is not
-        defined (see examples).
+        - You can pass the `Undefined` object as C(default) to force an undefined error
 """
 
 EXAMPLES = """
 - name: Basic usage
   debug:
-    msg: "'{{ lookup('env', 'HOME') }}' is the HOME environment variable."
+    msg: "{{ lookup('env', 'HOME') }} is the HOME environment variable."
 
-- name: Example how to set default value if the variable is not defined
+- name: Before 2.13, how to set default value if the variable is not defined.
+        This cannot distinguish between USR undefined and USR=''.
   debug:
-    msg: "'{{ lookup('env', 'USR') | default('nobody', True) }}' is the user."
+    msg: "{{ lookup('env', 'USR')|default('nobody', True) }} is the user."
+
+- name: Example how to set default value if the variable is not defined, ignores USR=''
+  debug:
+    msg: "{{ lookup('env', 'USR', default='nobody') }} is the user."
+
+- name: Set default value to Undefined, if the variable is not defined
+  debug:
+    msg: "{{ lookup('env', 'USR', default=Undefined) }} is the user."
+
+- name: Set default value to undef(), if the variable is not defined
+  debug:
+    msg: "{{ lookup('env', 'USR', default=undef()) }} is the user."
 """
 
 RETURN = """
@@ -44,17 +56,24 @@ RETURN = """
     type: list
 """
 
+from jinja2.runtime import Undefined
 
+from ansible.errors import AnsibleUndefinedVariable
 from ansible.plugins.lookup import LookupBase
 from ansible.utils import py3compat
 
 
 class LookupModule(LookupBase):
     def run(self, terms, variables, **kwargs):
-        ret = []
 
+        self.set_options(var_options=variables, direct=kwargs)
+
+        ret = []
+        d = self.get_option('default')
         for term in terms:
             var = term.split()[0]
-            ret.append(py3compat.environ.get(var, ''))
-
+            val = py3compat.environ.get(var, d)
+            if isinstance(val, Undefined):
+                raise AnsibleUndefinedVariable('The "env" lookup, found an undefined variable: %s' % var)
+            ret.append(val)
         return ret

test/integration/targets/lookup_env/runme.sh

@@ -0,0 +1,12 @@
+#!/bin/sh
+
+set -ex
+
+unset USR
+# this should succeed and return 'nobody' as var is undefined
+ansible -m debug -a msg="{{ lookup('env', 'USR', default='nobody')}}" localhost |grep nobody
+# var is defined but empty, so should return empty
+USR='' ansible -m debug -a msg="{{ lookup('env', 'USR', default='nobody')}}" localhost |grep -v nobody
+
+# this should fail with undefined
+ansible -m debug -a msg="{{ lookup('env', 'USR', default=Undefined)}}" localhost && exit 1 || exit 0