enable single mode (#272)

Co-authored-by: Michael Howitz <[email protected]>

Author: loechel

CHANGES.rst

@@ -6,6 +6,7 @@ Changes
 
 - Allow to use the package with Python 3.13 -- Caution: No security
   audit has been done so far.
+- Add support for single mode statements / execution.
 
 
 7.1 (2024-03-14)

docs/usage/basic_usage.rst

@@ -94,6 +94,62 @@ One common advanced usage would be to define an own restricted builtin dictionar
 
 There is a shortcut for ``{'__builtins__': safe_builtins}`` named ``safe_globals`` which can be imported from ``RestrictedPython``.
 
+Other Usages
+------------
+
+RestrictedPython has similar to normal Python multiple modes:
+
+* exec
+* eval
+* single
+* function
+
+you can use it by:
+
+.. testcode::
+
+    from RestrictedPython import compile_restricted
+
+    source_code = """
+    def do_something():
+        pass
+    """
+
+    byte_code = compile_restricted(
+        source_code,
+        filename='<inline code>',
+        mode='exec'
+    )
+    exec(byte_code)
+    do_something()
+
+.. testcode::
+
+    from RestrictedPython import compile_restricted
+
+    byte_code = compile_restricted(
+        "2 + 2",
+        filename='<inline code>',
+        mode='eval'
+    )
+    eval(byte_code)
+
+
+.. testcode:: single
+
+    from RestrictedPython import compile_restricted
+
+    byte_code = compile_restricted(
+        "2 + 2",
+        filename='<inline code>',
+        mode='single'
+    )
+    exec(byte_code)
+
+.. testoutput:: single
+
+    4
+
 Necessary setup
 ---------------
 

src/RestrictedPython/transformer.py

@@ -593,6 +593,10 @@ def visit_NameConstant(self, node):
             """
             return self.node_contents_visit(node)
 
+    def visit_Interactive(self, node):
+        """Allow single mode without restrictions."""
+        return self.node_contents_visit(node)
+
     def visit_List(self, node):
         """Allow list literals without restrictions."""
         return self.node_contents_visit(node)

tests/test_compile.py

@@ -160,13 +160,24 @@ def test_compile__compile_restricted_eval__used_names():
     assert result.used_names == {'a': True, 'b': True, 'x': True, 'func': True}
 
 
-def test_compile__compile_restricted_csingle():
+def test_compile__compile_restricted_single__1():
     """It compiles code as an Interactive."""
-    result = compile_restricted_single('4 * 6')
-    assert result.code is None
-    assert result.errors == (
-        'Line None: Interactive statements are not allowed.',
-    )
+    result = compile_restricted_single('x = 4 * 6')
+
+    assert result.errors == ()
+    assert result.warnings == []
+    assert result.code is not None
+    locals = {}
+    exec(result.code, {}, locals)
+    assert locals["x"] == 24
+
+
+def test_compile__compile_restricted__2():
+    """It compiles code as an Interactive."""
+    code = compile_restricted('x = 4 * 6', filename="<string>", mode="single")
+    locals = {}
+    exec(code, {}, locals)
+    assert locals["x"] == 24
 
 
 PRINT_EXAMPLE = """