some cleanup for readabitlity of docs

zopefoundation · Feb 21, 2017 · f5910e7 · f5910e7
1 parent d1ef607
commit f5910e7
Show file tree

Hide file tree

Showing 2 changed files with 22 additions and 6 deletions.
diff --git a/docs/usage/basic_usage.rst b/docs/usage/basic_usage.rst
@@ -25,7 +25,9 @@ With RestrictedPython that workflow should be as straight forward as possible:
         pass
     """
 
-    byte_code = compile_restricted(source_code, filename='<inline code>', mode='exec')
+    byte_code = compile_restricted(source_code,
+                                   filename='<inline code>',
+                                   mode='exec')
     exec(byte_code)
     do_something()
 
@@ -78,9 +80,12 @@ So you normally end up using:
     """
 
     try:
-        byte_code = compile_restricted(source_code, filename='<inline code>', mode='exec')
+        byte_code = compile_restricted(source_code,
+                                       filename='<inline code>',
+                                       mode='exec')
 
-        # used_builtins = ..._builtins + { <additionl elems> } # Whitelisting additional elements
+        # Whitelisting additional elements (modules and methods) if needed:
+        # used_builtins = ..._builtins + { <additional elements> }
         used_builtins = safe_builtins
         exec(byte_code, used_builtins, None)
     except SyntaxError as e:

diff --git a/docs/usage/framework_usage.rst b/docs/usage/framework_usage.rst
@@ -39,10 +39,13 @@ A policy is basically a special ``NodeTransformer`` that could be instantiated w
 
     from RestrictedPython import compile_restricted
     from RestrictedPython import RestrictingNodeTransformer
+
     class OwnRestrictingNodeTransformer(RestrictingNodeTransformer):
         pass
 
-    policy = OwnRestrictingNodeTransformer(errors=[], warnings=[], used_names=[])
+    policy_instance = OwnRestrictingNodeTransformer(errors=[],
+                                                    warnings=[],
+                                                    used_names=[])
 
 All ``compile_restricted*`` methods do have a optional parameter ``policy``, where a specific policy could be provided.
 
@@ -55,7 +58,11 @@ All ``compile_restricted*`` methods do have a optional parameter ``policy``, whe
 
     policy = OwnRestrictingNodeTransformer
 
-    byte_code = compile_restricted(source_code, filename='<inline code>', mode='exec', policy=policy)
+    byte_code = compile_restricted(source_code,
+                                   filename='<inline code>',
+                                   mode='exec',
+                                   policy=policy # Policy Class
+                                   )
     # exec(byte_code, { ... }, { ... })
     exec(byte_code, globals(), None)
 
@@ -69,5 +76,9 @@ That special case would be written as:
         pass
     """
 
-    byte_code = compile_restricted(source_code, filename='<inline code>', mode='exec', policy=None)
+    byte_code = compile_restricted(source_code,
+                                   filename='<inline code>',
+                                   mode='exec',
+                                   policy=None # Null-Policy -> unrestricted
+                                   )
     exec(byte_code, globals(), None)