Document that automatic module does not work with list comprehensions

pekkaklarck · pekkaklarck · commit adb9801b72db · 2021-02-26T17:05:26.000+02:00
Fixes robotframework#3593.
diff --git a/doc/userguide/src/Appendices/EvaluatingExpressions.rst b/doc/userguide/src/Appendices/EvaluatingExpressions.rst
@@ -70,8 +70,10 @@ can only be used if the root module automatically imports the submodule. That is
 not always the case and using such modules is not possible. An concrete example
 that is relevant in the automation context is the `selenium` module that is
 implemented, at least at the time of this writing, so that just importing
-`selenium` does not import the `selenium.webdriver` submodule. A workaround is
-using the :name:`Evaluate` keyword that accepts modules to be imported
+`selenium` does not import the `selenium.webdriver` submodule.
+Another limitation is that modules cannot be used in the expression part of
+a list comprehension when using Python 3. A workaround to both of these problems
+is using the BuiltIn_ keyword :name:`Evaluate` that accepts modules to be imported
 and added to the evaluation namespace as an argument:
 
 .. sourcecode:: robotframework
@@ -80,12 +82,19 @@ and added to the evaluation namespace as an argument:
    Does not work due to nested module structure
        Log    ${{selenium.webdriver.ChromeOptions()}}
 
-   Evaluate keyword to the rescue
+   Evaluate keyword with nested module
        ${options} =    Evaluate    selenium.webdriver.ChromeOptions()    modules=selenium.webdriver
        Log    ${options}
 
-The :name:`Evaluate` keyword also supports custom evaluation namespaces.
-See its documentation in the BuiltIn_ library for more details.
+   Does not work due to list comprehension
+       Log    ${{[json.loads(item) for item in ('1', '"b"')]}}
+
+   Evaluate keyword with list comprehension
+       ${items} =    Evaluate    [json.loads(item) for item in ('1', '"b"')]    modules=json
+       Log    ${items}
+
+The :name:`Evaluate` keyword also supports custom evaluation namespaces if further
+customization is needed. See its documentation in the BuiltIn_ library for more details.
 
 __ http://docs.python.org/library/functions.html#eval
 
diff --git a/src/robot/libraries/BuiltIn.py b/src/robot/libraries/BuiltIn.py
@@ -3024,28 +3024,35 @@ def evaluate(self, expression, modules=None, namespace=None):
         namespace as a dictionary. Possible ``modules`` are added to this
         namespace.
 
-        Starting from Robot Framework 3.2, modules used in the expression are
-        imported automatically. ``modules`` argument is still needed with
-        nested modules like ``rootmod.submod`` that are implemented so that
-        the root module does not automatically import sub modules. This is
-        illustrated by the ``selenium.webdriver`` example below.
-
         Variables used like ``${variable}`` are replaced in the expression
         before evaluation. Variables are also available in the evaluation
         namespace and can be accessed using the special ``$variable`` syntax
         as explained in the `Evaluating expressions` section.
 
+        Starting from Robot Framework 3.2, modules used in the expression are
+        imported automatically. There are, however, two cases where they need to
+        be explicitly specified using the ``modules`` argument:
+
+        - When nested modules like ``rootmod.submod`` are implemented so that
+          the root module does not automatically import sub modules. This is
+          illustrated by the ``selenium.webdriver`` example below.
+
+        - When using a module in the expression part of a list comprehension.
+          This is illustrated by the ``json`` example below.
+
         Examples (expecting ``${result}`` is number 3.14):
         | ${status} =  | Evaluate | 0 < ${result} < 10 | # Would also work with string '3.14' |
         | ${status} =  | Evaluate | 0 < $result < 10   | # Using variable itself, not string representation |
         | ${random} =  | Evaluate | random.randint(0, sys.maxsize) |
         | ${options} = | Evaluate | selenium.webdriver.ChromeOptions() | modules=selenium.webdriver |
+        | ${items} =   | Evaluate | [json.loads(item) for item in ('1', '"b"')] | modules=json |
         | ${ns} =      | Create Dictionary | x=${4}    | y=${2}              |
         | ${result} =  | Evaluate | x*10 + y           | namespace=${ns}     |
         =>
         | ${status} = True
         | ${random} = <random integer>
         | ${options} = ChromeOptions instance
+        | ${items} = [1, 'b']
         | ${result} = 42
 
         *NOTE*: Prior to Robot Framework 3.2 using ``modules=rootmod.submod``
@@ -3357,10 +3364,10 @@ class BuiltIn(_Verify, _Converter, _Variables, _RunKeyword, _Control, _Misc):
 
     `Evaluate` also allows configuring the execution namespace with a custom
     namespace and with custom modules to be imported. The latter functionality
-    is useful when using nested modules like ``rootmod.submod`` that are
-    implemented so that the root module does not automatically import sub
-    modules. Otherwise the automatic module import mechanism described earlier
-    is enough to get the needed modules imported.
+    is useful in special cases where the automatic module import does not work
+    such as when using nested modules like ``rootmod.submod`` or list
+    comprehensions. See the documentation of the `Evaluate` keyword for mode
+    details.
 
     *NOTE:* Automatic module import is a new feature in Robot Framework 3.2.
     Earlier modules needed to be explicitly taken into use when using the
