RestrictedPython

https://github.com/zopefoundation/restrictedpython
Admin
RestrictedPython is a defined subset of the Python language which allows to provide a program input...
Tokens:5,579
Snippets:57
Trust Score:9.4
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install RestrictedPython via pip

Source: https://github.com/zopefoundation/restrictedpython/blob/master/docs/install/index.md

Use this command to install the package in a standalone environment.

```console
$ pip install RestrictedPython
```

--------------------------------

### Restricted Code Transformation Example

Source: https://github.com/zopefoundation/restrictedpython/blob/master/docs/usage/policy.md

Demonstrates how standard Python code is transformed into restricted code using guard functions and print collectors.

```python
def f(x):
    x.foo = x.foo + x[0]
    print x
    return printed
```

```python
def f(x):
    # Make local variables from globals.
    _print = _print_()
    _write = _write_
    _getattr = _getattr_
    _getitem = _getitem_

    # Translation of f(x) above
    _write(x).foo = _getattr(x, 'foo') + _getitem(x, 0)
    print >>_print, x
    return _print()
```

--------------------------------

### Implement AST Node Visitor

Source: https://github.com/zopefoundation/restrictedpython/blob/master/docs/contributing/index.md

Template for adding a new AST node visitor method in the transformer. All nodes without an explicit visitor are denied by default.

```python
def visit_<AST Node>(self, node):
    """Allow `<AST Node>` expressions."""
    ...  # modifications
    return self.node_contents_visit(node)
```

--------------------------------

### Execute safe code with RestrictedPython

Source: https://github.com/zopefoundation/restrictedpython/blob/master/README.rst

Demonstrates compiling and executing a simple function within a restricted environment using safe_globals.

```pycon
>>> from RestrictedPython import compile_restricted
>>> from RestrictedPython import safe_globals
>>>
>>> source_code = """
... def example():
...     return 'Hello World!'
... """
>>>
>>> loc = {}
>>> byte_code = compile_restricted(source_code, '<inline>', 'exec')
>>> exec(byte_code, safe_globals, loc)
>>>
>>> loc['example']()
'Hello World!'
```

--------------------------------

### Restricting Built-in Functions

Source: https://github.com/zopefoundation/restrictedpython/blob/master/docs/usage/policy.md

Demonstrates how to restrict access to unsafe built-in functions like open by providing a custom globals dictionary.

```pycon
>>> from RestrictedPython.Guards import safe_builtins
>>> restricted_globals = dict(__builtins__=safe_builtins)

>>> src = '''
... open('/etc/passwd')
... '''
>>> code = compile_restricted(src, '<string>', 'exec')
>>> exec(code, restricted_globals)
Traceback (most recent call last):
  ...
NameError: name 'open' is not defined
```

--------------------------------

### AST definition changes for Python 3.11

Source: https://github.com/zopefoundation/restrictedpython/blob/master/docs/contributing/changes_from310to311.md

Shows the addition of the TryStar node to the ASDL definition.

```udiff
--- /workspace/input/docs/contributing/ast/python3_10.ast
+++ /workspace/input/docs/contributing/ast/python3_11.ast
@@ -1,8 +1,8 @@
--- Python 3.10 AST
+-- Python 3.11 AST
 -- ASDL's 4 builtin types are:
 -- identifier, int, string, constant
 
-module Python version "3.10"
+module Python version "3.11"
 {
     mod = Module(stmt* body, type_ignore* type_ignores)
         | Interactive(stmt* body)
@@ -47,6 +47,7 @@
 
          | Raise(expr? exc, expr? cause)
          | Try(stmt* body, excepthandler* handlers, stmt* orelse, stmt* finalbody)
+         | TryStar(stmt* body, excepthandler* handlers, stmt* orelse, stmt* finalbody)
          | Assert(expr test, expr? msg)
 
          | Import(alias* names)
```

--------------------------------

### Implementing a Print Collector

Source: https://github.com/zopefoundation/restrictedpython/blob/master/docs/usage/policy.md

Shows how to use PrintCollector to capture output from print statements in restricted code.

```pycon
>>> from RestrictedPython.PrintCollector import PrintCollector
>>> _print_ = PrintCollector
>>> _getattr_ = getattr

>>> src = '''
... print("Hello World!")
... '''
>>> code = compile_restricted(src, '<string>', 'exec')
>>> exec(code)
```

```pycon
>>> src = '''
... print("Hello World!")
... result = printed
... '''
>>> code = compile_restricted(src, '<string>', 'exec')
>>> exec(code)

>>> result
'Hello World!\n'
```

--------------------------------

### Control globals for a function call

Source: https://github.com/zopefoundation/restrictedpython/blob/master/docs/usage/api.md

Shows how to regenerate a function with specific global bindings using types.FunctionType.

```pycon
>>> 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(*[], **{})
```

--------------------------------

### Execute a compiled function

Source: https://github.com/zopefoundation/restrictedpython/blob/master/docs/usage/api.md

Demonstrates how to execute code compiled via compile_restricted_function and extract the resulting function object from the local scope.

```pycon
>>> 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(*[], **{})
```

--------------------------------

### AST Definition Changes for Python 3.12

Source: https://github.com/zopefoundation/restrictedpython/blob/master/docs/contributing/changes_from311to312.md

Shows the diff of ASDL definitions reflecting the introduction of type parameters and type aliases in Python 3.12.

```udiff
--- /workspace/input/docs/contributing/ast/python3_11.ast
+++ /workspace/input/docs/contributing/ast/python3_12.ast
@@ -1,8 +1,8 @@
--- Python 3.11 AST
+-- Python 3.12 AST
 -- ASDL's 4 builtin types are:
 -- identifier, int, string, constant
 
-module Python version "3.11"
+module Python version "3.12"
 {
     mod = Module(stmt* body, type_ignore* type_ignores)
         | Interactive(stmt* body)
@@ -14,23 +14,27 @@
                        stmt* body,
                        expr* decorator_list,
                        expr? returns,
-                       string? type_comment)
+                       string? type_comment,
+                       type_param* type_params)
          | AsyncFunctionDef(identifier name,
                             arguments args,
                             stmt* body,
                             expr* decorator_list,
                             expr? returns,
-                            string? type_comment)
+                            string? type_comment,
+                            type_param* type_params)
 
          | ClassDef(identifier name,
                     expr* bases,
                     keyword* keywords,
                     stmt* body,
-                    expr* decorator_list)
+                    expr* decorator_list,
+                    type_param* type_params)
          | Return(expr? value)
 
          | Delete(expr* targets)
          | Assign(expr* targets, expr value, string? type_comment)
+         | TypeAlias(expr name, type_param* type_params, expr value)
          | AugAssign(expr target, operator op, expr value)
          -- 'simple' indicates that we annotate simple name without parens
          | AnnAssign(expr target, expr annotation, expr? value, int simple)
@@ -182,4 +186,9 @@
              attributes (int lineno, int col_offset, int end_lineno, int end_col_offset)
 
     type_ignore = TypeIgnore(int lineno, string tag)
+
+    type_param = TypeVar(identifier name, expr? bound)
+               | ParamSpec(identifier name)
+               | TypeVarTuple(identifier name)
+               attributes (int lineno, int col_offset, int end_lineno, int end_col_offset)
 }
```

--------------------------------

### AST definition changes for type parameters

Source: https://github.com/zopefoundation/restrictedpython/blob/master/docs/contributing/changes_from312to313.md

Shows the addition of default_value fields to TypeVar, ParamSpec, and TypeVarTuple in the ASDL definition.

```udiff
--- /workspace/input/docs/contributing/ast/python3_12.ast
+++ /workspace/input/docs/contributing/ast/python3_13.ast
@@ -1,8 +1,8 @@
--- Python 3.12 AST
+-- Python 3.13 AST
 -- ASDL's 4 builtin types are:
 -- identifier, int, string, constant
 
-module Python version "3.12"
+module Python version "3.13"
 {
     mod = Module(stmt* body, type_ignore* type_ignores)
         | Interactive(stmt* body)
@@ -187,8 +187,8 @@
 
     type_ignore = TypeIgnore(int lineno, string tag)
 
-    type_param = TypeVar(identifier name, expr? bound)
-               | ParamSpec(identifier name)
-               | TypeVarTuple(identifier name)
+    type_param = TypeVar(identifier name, expr? bound, expr? default_value)
+               | ParamSpec(identifier name, expr? default_value)
+               | TypeVarTuple(identifier name, expr? default_value)
                attributes (int lineno, int col_offset, int end_lineno, int end_col_offset)
 }
```

--------------------------------

### RestrictedPython.compile_restricted_exec

Source: https://github.com/zopefoundation/restrictedpython/blob/master/docs/usage/api.md

Compiles source code into interpretable byte code with mode='exec'.

```APIDOC
## RestrictedPython.compile_restricted_exec(source, filename, flags, dont_inherit, policy)

### Description
Compiles source code into interpretable byte code with mode='exec'. Use this if the source contains a sequence of statements.

### Returns
- CompileResult (namedtuple with code, errors, warnings, used_names)
```

--------------------------------

### Execute restricted byte code

Source: https://github.com/zopefoundation/restrictedpython/blob/master/docs/usage/basic_usage.md

The standard pattern for executing compiled byte code using restricted globals and locals dictionaries.

```python
byte_code = <code>
exec(byte_code, { ... }, { ... })
```

--------------------------------

### RestrictedPython.compile_restricted_single

Source: https://github.com/zopefoundation/restrictedpython/blob/master/docs/usage/api.md

Compiles source code into interpretable byte code with mode='single'.

```APIDOC
## RestrictedPython.compile_restricted_single(source, filename, flags, dont_inherit, policy)

### Description
Compiles source code into interpretable byte code with mode='single'. Use this if the source contains a single interactive statement.

### Returns
- CompileResult (namedtuple with code, errors, warnings, used_names)
```

--------------------------------

### Update ASDL AST definitions for Python 3.14

Source: https://github.com/zopefoundation/restrictedpython/blob/master/docs/contributing/changes_from313to314.md

Reflects changes in the AST structure including the updated Dict definition and new expression types.

```udiff
--- /workspace/input/docs/contributing/ast/python3_13.ast
+++ /workspace/input/docs/contributing/ast/python3_14.ast
@@ -1,8 +1,8 @@
--- Python 3.13 AST
+-- Python 3.14 AST
 -- ASDL's 4 builtin types are:
 -- identifier, int, string, constant
 
-module Python version "3.13"
+module Python version "3.14"
 {
     mod = Module(stmt* body, type_ignore* type_ignores)
         | Interactive(stmt* body)
@@ -74,7 +74,7 @@
          | UnaryOp(unaryop op, expr operand)
          | Lambda(arguments args, expr body)
          | IfExp(expr test, expr body, expr orelse)
-         | Dict(expr* keys, expr* values)
+         | Dict(expr?* keys, expr* values)
          | Set(expr* elts)
          | ListComp(expr elt, comprehension* generators)
          | SetComp(expr elt, comprehension* generators)
@@ -89,7 +89,9 @@
          | Compare(expr left, cmpop* ops, expr* comparators)
          | Call(expr func, expr* args, keyword* keywords)
          | FormattedValue(expr value, int conversion, expr? format_spec)
+         | Interpolation(expr value, constant str, int conversion, expr? format_spec)
          | JoinedStr(expr* values)
+         | TemplateStr(expr* values)
          | Constant(constant value, string? kind)
 
          -- the following expression can appear in assignment context
```

--------------------------------

### AST Definition Changes

Source: https://github.com/zopefoundation/restrictedpython/blob/master/docs/contributing/changes_from39to310.md

Unified diff showing the addition of Match nodes and updates to FormattedValue and alias attributes in the ASDL definition.

```udiff
--- /workspace/input/docs/contributing/ast/python3_9.ast
+++ /workspace/input/docs/contributing/ast/python3_10.ast
@@ -1,8 +1,8 @@
--- Python 3.9 AST
+-- Python 3.10 AST
 -- ASDL's 4 builtin types are:
 -- identifier, int, string, constant
 
-module Python version "3.9"
+module Python version "3.10"
 {
     mod = Module(stmt* body, type_ignore* type_ignores)
         | Interactive(stmt* body)
@@ -43,6 +43,8 @@
          | With(withitem* items, stmt* body, string? type_comment)
          | AsyncWith(withitem* items, stmt* body, string? type_comment)
 
+         | Match(expr subject, match_case* cases)
+
          | Raise(expr? exc, expr? cause)
          | Try(stmt* body, excepthandler* handlers, stmt* orelse, stmt* finalbody)
          | Assert(expr test, expr? msg)
@@ -81,7 +83,7 @@
          -- x < 4 < 3 and (x < 4) < 3
          | Compare(expr left, cmpop* ops, expr* comparators)
          | Call(expr func, expr* args, keyword* keywords)
-         | FormattedValue(expr value, int? conversion, expr? format_spec)
+         | FormattedValue(expr value, int conversion, expr? format_spec)
          | JoinedStr(expr* values)
          | Constant(constant value, string? kind)
 
@@ -158,8 +160,25 @@
 
     -- import name with optional 'as' alias.
     alias = (identifier name, identifier? asname)
+            attributes (int lineno, int col_offset, int? end_lineno, int? end_col_offset)
 
     withitem = (expr context_expr, expr? optional_vars)
 
+    match_case = (pattern pattern, expr? guard, stmt* body)
+
+    pattern = MatchValue(expr value)
+            | MatchSingleton(constant value)
+            | MatchSequence(pattern* patterns)
+            | MatchMapping(expr* keys, pattern* patterns, identifier? rest)
+            | MatchClass(expr cls, pattern* patterns, identifier* kwd_attrs, pattern* kwd_patterns)
+
+            | MatchStar(identifier? name)
+            -- The optional "rest" MatchMapping parameter handles capturing extra mapping keys
+
+            | MatchAs(pattern? pattern, identifier? name)
+            | MatchOr(pattern* patterns)
+
+             attributes (int lineno, int col_offset, int end_lineno, int end_col_offset)
+
     type_ignore = TypeIgnore(int lineno, string tag)
 }
```

--------------------------------

### Standard Python compile function signature

Source: https://github.com/zopefoundation/restrictedpython/blob/master/docs/idea.md

The standard Python built-in function used to compile source code into byte code.

```python
compile(source, filename, mode [, flags [, dont_inherit]])
```

--------------------------------

### RestrictedPython.compile_restricted

Source: https://github.com/zopefoundation/restrictedpython/blob/master/docs/usage/api.md

Compiles source code into interpretable byte code using a specified policy.

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

### Description
Compiles source code into interpretable byte code.

### Parameters
- **source** (str/bytes/bytearray/ast) - Required - The source code to be compiled.
- **filename** (str/bytes/os.PathLike) - Optional - Defaults to '<unknown>'.
- **mode** (str) - Optional - Use 'exec', 'eval' or 'single'. Defaults to 'exec'.
- **flags** (int) - Optional - Defaults to 0.
- **dont_inherit** (int) - Optional - Defaults to False.
- **policy** (RestrictingNodeTransformer) - Optional - Defaults to RestrictingNodeTransformer.

### Returns
- Python code object
```

--------------------------------

### RestrictedPython.compile_restricted_function

Source: https://github.com/zopefoundation/restrictedpython/blob/master/docs/usage/api.md

Compiles source code into interpretable byte code with mode='function'.

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

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

### Parameters
- **p** (str) - Required - A string representing the function parameters.
- **body** (str/bytes/bytearray/ast) - Required - The function body.
- **name** (str) - Required - The function name.
- **filename** (str/bytes/os.PathLike) - Optional - Defaults to '<string>'.
- **globalize** (list) - Optional - List of variable names to be treated as globals.

### Returns
- byte code
```

--------------------------------

### RestrictedPython.compile_restricted_eval

Source: https://github.com/zopefoundation/restrictedpython/blob/master/docs/usage/api.md

Compiles source code into interpretable byte code with mode='eval'.

```APIDOC
## RestrictedPython.compile_restricted_eval(source, filename, flags, dont_inherit, policy)

### Description
Compiles source code into interpretable byte code with mode='eval'. Use this if the source contains a single expression.

### Returns
- CompileResult (namedtuple with code, errors, warnings, used_names)
```

--------------------------------

### Prevent problematic code execution

Source: https://github.com/zopefoundation/restrictedpython/blob/master/README.rst

Shows how RestrictedPython blocks unauthorized imports, such as the os module, by raising an ImportError.

```pycon
>>> from RestrictedPython import compile_restricted
>>> from RestrictedPython import safe_globals
>>>
>>> source_code = """
... import os
... 
... os.listdir('/')
... """
>>> byte_code = compile_restricted(source_code, '<inline>', 'exec')
>>> exec(byte_code, safe_globals, {})
Traceback (most recent call last):
ImportError: __import__ not found
```

--------------------------------

### RestrictedPython compile_restricted function signature

Source: https://github.com/zopefoundation/restrictedpython/blob/master/docs/idea.md

The replacement function provided by RestrictedPython to safely compile source code.

```python
RestrictedPython.compile_restricted(source, filename, mode [, flags [, dont_inherit]])
```
Tokens:
Raw