API overview

compile_restricted methods

RestrictedPython.compile_restricted(source, filename, mode, flags, dont_inherit, policy)

Compiles source code into interpretable byte code.

Parameters:

  • source (str or unicode text or ast.AST) – (required). the source code that should be compiled

  • filename (str or unicode text) – (optional). defaults to '<unknown>'

  • mode (str or unicode text) – (optional). Use 'exec', 'eval', 'single' or 'function'. defaults to 'exec'

  • flags (int) – (optional). defaults to 0

  • dont_inherit (int) – (optional). defaults to False

  • policy (RestrictingNodeTransformer class) – (optional). defaults to RestrictingNodeTransformer

Returns:

Python code object

RestrictedPython.compile_restricted_exec(source, filename, flags, dont_inherit, policy)

Compiles source code into interpretable byte code with mode='exec'. Use mode 'exec' if the source contains a sequence of statements. The meaning and defaults of the parameters are the same as in compile_restricted.

Returns:

CompileResult (a namedtuple with code, errors, warnings, used_names)

RestrictedPython.compile_restricted_eval(source, filename, flags, dont_inherit, policy)

Compiles source code into interpretable byte code with mode='eval'. Use mode 'eval' if the source contains a single expression. The meaning and defaults of the parameters are the same as in compile_restricted.

Returns:

CompileResult (a namedtuple with code, errors, warnings, used_names)

RestrictedPython.compile_restricted_single(source, filename, flags, dont_inherit, policy)

Compiles source code into interpretable byte code with mode='eval'. Use mode 'single' if the source contains a single interactive statement. The meaning and defaults of the parameters are the same as in compile_restricted.

Returns:

CompileResult (a namedtuple with code, errors, warnings, used_names)

RestrictedPython.compile_restricted_function(p, body, name, filename, globalize=None)

Compiles source code into interpretable byte code with mode='function'. Use mode 'function' for full functions.

Parameters:

  • p (str or unicode text) – (required). a string representing the function parameters

  • body (str or unicode text) – (required). the function body

  • name (str or unicode text) – (required). the function name

  • filename (str or unicode text) – (optional). defaults to '<string>'

  • globalize (None or list) – (optional). list of globals. defaults to None

  • flags (int) – (optional). defaults to 0

  • dont_inherit (int) – (optional). defaults to False

  • policy (RestrictingNodeTransformer class) – (optional). defaults to RestrictingNodeTransformer

Returns:

byte code

The globalize argument, if specified, is a list of variable names to be treated as globals (code is generated as if each name in the list appeared in a global statement at the top of the function). This allows to inject global variables into the generated function that feel like they are local variables, so the programmer who uses this doesn’t have to understand that his code is executed inside a function scope instead of the global scope of a module.

To actually get an executable function, you need to execute this code and pull out the defined function out of the locals like this:

>>> from RestrictedPython import compile_restricted_function
>>> compiled = compile_restricted_function('', 'pass', 'function_name')
>>> safe_locals = {}
>>> safe_globals = {}
>>> exec(compiled.code, safe_globals, safe_locals)
>>> compiled_function = safe_locals['function_name']
>>> result = compiled_function(*[], **{})

Then if you want to control the globals for a specific call to this function, you can regenerate the function like this:

>>> my_call_specific_global_bindings = dict(foo='bar')
>>> safe_globals = safe_globals.copy()
>>> safe_globals.update(my_call_specific_global_bindings)
>>> import types
>>> new_function = types.FunctionType(
...     compiled_function.__code__,
...     safe_globals,
...     '<function_name>',
...     compiled_function.__defaults__ or ())
>>> result = new_function(*[], **{})

restricted builtins

  • safe_globals

  • safe_builtins

  • limited_builtins

  • utility_builtins

helper modules

  • PrintCollector

RestrictingNodeTransformer

RestrictingNodeTransformer provides the base policy used by RestrictedPython itself.

It is a subclass of a NodeTransformer which has a set of visit_<AST_Elem> methods and a generic_visit method.

generic_visit is a predefined method of any NodeVisitor which sequentially visits all sub nodes. In RestrictedPython this behaviour is overwritten to always call a new internal method not_allowed(node). This results in an implicit blacklisting of all not allowed AST elements.

Any possibly new introduced AST element in Python (new language element) will implicitly be blocked and not allowed in RestrictedPython.

So, if new elements should be introduced, an explicit visit_<new AST elem> is necessary.