diff --git a/README.rst b/README.rst index 594534f..9cfec96 100644 --- a/README.rst +++ b/README.rst @@ -2,6 +2,49 @@ RestrictedPython ================ -RestrictedPython is a defined subset of the Python language which allows to provide a program input into a trusted environment. +RestrictedPython is a tool that helps to define a subset of the Python language which allows to provide a program input into a trusted environment. +RestrictedPython is not a sandbox system or a secured environment, but it helps to define a trusted environment and execute untrusted code inside of it. For full documentation please see  http://restrictedpython.readthedocs.io/ or the local ``docs/index``. + +Example +======= + +To give a basic understanding what RestrictedPython does here two examples: + +An unproblematic code example +----------------------------- + +Python allows you to execute a large set of commands. +This would not harm any system. + + >>> from RestrictedPython import compile_restricted + >>> from RestrictedPython import safe_builtins + >>> + >>> source_code = """ + ... def example(): + ... return 'Hello World!' + ... """ + >>> + >>> loc = {} + >>> byte_code = compile_restricted(source_code, '', 'exec') + >>> exec(byte_code, safe_builtins, loc) + >>> + >>> loc['example']() + 'Hello World!' + +Problematic code example +------------------------ + +This example directly executed in Python could harm your system. + + >>> from RestrictedPython import compile_restricted + >>> from RestrictedPython import safe_builtins + >>> + >>> source_code = """ + ... import os + ... + ... os.listdir('/') + ... """ + >>> byte_code = compile_restricted(source_code, '', 'exec') + >>> # exec(byte_code, safe_builtins, {}) diff --git a/docs/CHANGES.rst b/docs/CHANGES.rst index 6c3fab1..cc305df 100644 --- a/docs/CHANGES.rst +++ b/docs/CHANGES.rst @@ -4,7 +4,10 @@ Changes 4.0a2 (unreleased) ------------------ +- Modified README and setup.py to provide a better desciption test for PyPI. + [loechel] - Drop support for long-deprecated ``sets`` module. + [tseaver] 4.0a1 (2017-05-05) diff --git a/setup.py b/setup.py index 28a2352..3e99621 100644 --- a/setup.py +++ b/setup.py @@ -27,8 +27,9 @@ def read(*rnames): version='4.0a2.dev0', url='http://pypi.python.org/pypi/RestrictedPython', license='ZPL 2.1', - description='RestrictedPython provides a restricted execution ' - 'environment for Python, e.g. for running untrusted code.', + description='RestrictedPython is a defined subset of the Python ' + 'language which allows to provide a program input into ' + 'a trusted environment.', long_description=(read('README.rst') + '\n' + read('docs', 'CHANGES.rst')), classifiers=[ diff --git a/tests/test_imports.py b/tests/test_imports.py new file mode 100644 index 0000000..7176b21 --- /dev/null +++ b/tests/test_imports.py @@ -0,0 +1,32 @@ +""" +Tests about imports +""" + +from RestrictedPython import safe_builtins +from tests import c_exec +from tests import e_exec + +import pytest + + +OS_IMPORT_EXAMPLE = """ +import os + +os.listdir('/') +""" + + +@pytest.mark.parametrize(*c_exec) +@pytest.mark.parametrize(*e_exec) +def test_os_import(c_exec, e_exec): + """Test that import should not work out of the box. + TODO: Why does this work. + """ + result = c_exec(OS_IMPORT_EXAMPLE, safe_builtins) + # TODO: there is a tests/__init__.py problem, as it seems to pass the + # safe_builtins into the compile function instead of the source. + assert result.code is None + # assert result.errors == () + + with pytest.raises(NameError): + e_exec(OS_IMPORT_EXAMPLE, safe_builtins)