Adjust import code conventions in setup.cfg[isort] and applied

.coveragerc

@@ -12,4 +12,7 @@ omit =
     #src/RestrictedPython/tests/*.py
 
 [report]
-precision = 3
+precision = 2
+
+[html]
+directory = reports/coverage

.gitignore

@@ -21,7 +21,7 @@ pyvenv.cfg
 /eggs
 /fake-eggs
 /htmlcov
-/report-*.html
+/reports
 /include
 /lib
 /share

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!'
+    ... """
+    >>>
+    >>> locals = {}
+    >>> byte_code = compile_restricted(source_code, '<inline>', 'exec')
+    >>> exec(byte_code, safe_builtins, locals)
+    >>>
+    >>> locals['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, '<inline>', 'exec')
+  >>> # exec(byte_code, safe_builtins, {})

setup.cfg

@@ -30,10 +30,34 @@ isort_ignore =
 
 
 [isort]
-force_alphabetical_sort = True
+force_alphabetical_sort = False
 force_single_line = True
-lines_after_imports = 2
+force_to_top = False
+from_first = True
+
+sections = FUTURE,STDLIB,COMPATLIBS,TESTLIBS,FIRSTPARTY,THIRDPARTY,ZOPE,LOCALFOLDER,TESTINTERNALS
+
+known_compatlibs = six
+known_testlibs = pytest
+known_firstparty =
+known_thirdparty =
+known_zope = zope,Products,zc,z3c,ExtensionClass,Acquisition,Persistence,RestrictedPython
+known_localfolder = RestrictedPython
+known_testinternals = tests
+
+import_heading_future_library = Future imports
+import_heading_stdlib = Standard library imports
+import_heading_compatlibs = Python 2 / 3 compatibility helper libraries
+import_heading_testlibs = Test framework imports
+import_heading_firstparty =
+import_heading_thirdparty =
+import_heading_zope = Zope imports
+import_heading_localfolder = RestrictedPython internal imports
+import_heading_testinternals = Test internals (fixures and helpers)
+
 line_length = 200
+lines_after_imports = 2
+
 skip =
     bootstrap.py
 not_skip =
@@ -43,7 +67,7 @@ not_skip =
 exclude =
     bootstrap.py,
     src/RestrictedPython/tests,
-    src/RestrictedPython/SelectCompiler.py,
+    #src/RestrictedPython/SelectCompiler.py,
 
 ignore =
     N801,

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=[

src/RestrictedPython/Eval.py

@@ -12,11 +12,13 @@
 ##############################################################################
 """Restricted Python Expressions."""
 
-from ._compat import IS_PY2
-from .compile import compile_restricted_eval
-
+# Standard library imports
 import ast
 
+# RestrictedPython internal imports
+from RestrictedPython._compat import IS_PY2
+from RestrictedPython.compile import compile_restricted_eval
+
 
 if IS_PY2:
     from string import maketrans

src/RestrictedPython/Guards.py

@@ -15,7 +15,8 @@
 # AccessControl.ZopeGuards contains a large set of wrappers for builtins.
 # DocumentTemplate.DT_UTil contains a few.
 
-from ._compat import IS_PY2
+# RestrictedPython internal imports
+from RestrictedPython._compat import IS_PY2
 
 
 if IS_PY2:

src/RestrictedPython/MutatingWalker.py

@@ -11,8 +11,8 @@
 #
 ##############################################################################
 
+# Standard library imports
 from compiler import ast
-
 import warnings
 
 

src/RestrictedPython/PrintCollector.py

@@ -10,6 +10,7 @@
 # FOR A PARTICULAR PURPOSE
 #
 ##############################################################################
+
 from __future__ import print_function
 
 

src/RestrictedPython/RCompile.py

@@ -14,24 +14,26 @@
 Python standard library.
 """
 
-from compile import CompileResult
+# Standard library imports
 from compiler import ast
 from compiler import misc
 from compiler import parse
 from compiler import pycodegen
 from compiler import syntax
 from compiler.pycodegen import AbstractCompileMode
 from compiler.pycodegen import Expression
-from compiler.pycodegen import findOp
 from compiler.pycodegen import FunctionCodeGenerator  # noqa
 from compiler.pycodegen import Interactive
 from compiler.pycodegen import Module
 from compiler.pycodegen import ModuleCodeGenerator
-from RestrictionMutator import RestrictionMutator
-
-import MutatingWalker
+from compiler.pycodegen import findOp
 import warnings
 
+# RestrictedPython internal imports
+from RestrictedPython.compile import CompileResult
+from RestrictedPython.MutatingWalker import walk
+from RestrictedPython.RestrictionMutator import RestrictionMutator
+
 
 warnings.warn(
     "This Module (RestrictedPython.RCompile) is deprecated"
@@ -74,7 +76,7 @@ def parse(self):
 
     def _get_tree(self):
         tree = self.parse()
-        MutatingWalker.walk(tree, self.rm)
+        walk(tree, self.rm)
         if self.rm.errors:
             raise SyntaxError(self.rm.errors[0])
         misc.set_filename(self.filename, tree)

src/RestrictedPython/README.rst

@@ -1,5 +1,7 @@
 .. contents::
 
+.. TODO:: move this documentation into docs
+
 Overview
 ========
 

src/RestrictedPython/RestrictionMutator.py

@@ -17,12 +17,12 @@
 code in various ways before sending it to pycodegen.
 """
 
+# Standard library imports
 from compiler import ast
 from compiler.consts import OP_APPLY
 from compiler.consts import OP_ASSIGN
 from compiler.consts import OP_DELETE
 from compiler.transformer import parse
-
 import warnings
 
 

src/RestrictedPython/SelectCompiler.py

@@ -13,20 +13,23 @@
 """Compiler selector.
 """
 
+# flake8: NOQA: 401
+# isort: skip
+
+# Standard library imports
 from compiler import ast
 from compiler.consts import OP_APPLY
 from compiler.consts import OP_ASSIGN
 from compiler.consts import OP_DELETE
 from compiler.transformer import parse
+import compiler
+import warnings
+
 from RCompile import compile_restricted
 from RCompile import compile_restricted_eval
 from RCompile import compile_restricted_exec
 from RCompile import compile_restricted_function
 
-# Use the compiler from the standard library.
-import compiler
-import warnings
-
 
 warnings.warn(
     "This Module (RestrictedPython.SelectCompiler) is deprecated"

src/RestrictedPython/Utilities.py

@@ -11,6 +11,7 @@
 #
 ##############################################################################
 
+# Standard library imports
 import math
 import random
 import string

src/RestrictedPython/__init__.py

@@ -13,9 +13,10 @@
 """RestrictedPython package."""
 
 # flake8: NOQA: E401
+# isort: skip
 
 # This is a file to define public API in the base namespace of the package.
-# use: isor:skip to supress all isort related warnings / errors,
+# use: isort:skip to supress all isort related warnings / errors,
 # as this file should be logically grouped imports
 
 
@@ -25,25 +26,22 @@
 # from RestrictedPython.RCompile import compile_restricted_exec
 # from RestrictedPython.RCompile import compile_restricted_function
 
+# RestrictedPython internal imports
 # new API Style
 # compile_restricted methods:
-from RestrictedPython.compile import compile_restricted  # isort:skip
-from RestrictedPython.compile import compile_restricted_eval  # isort:skip
-from RestrictedPython.compile import compile_restricted_exec  # isort:skip
-from RestrictedPython.compile import compile_restricted_function  # isort:skip
-from RestrictedPython.compile import compile_restricted_single  # isort:skip
-
+from RestrictedPython.compile import CompileResult
+from RestrictedPython.compile import compile_restricted
+from RestrictedPython.compile import compile_restricted_eval
+from RestrictedPython.compile import compile_restricted_exec
+from RestrictedPython.compile import compile_restricted_function
+from RestrictedPython.compile import compile_restricted_single
+#
+from RestrictedPython.Eval import RestrictionCapableEval
 # predefined builtins
-from RestrictedPython.Guards import safe_builtins  # isort:skip
-from RestrictedPython.Limits import limited_builtins  # isort:skip
-from RestrictedPython.Utilities import utility_builtins  # isort:skip
-
+from RestrictedPython.Guards import safe_builtins
+from RestrictedPython.Limits import limited_builtins
 # Helper Methods
-from RestrictedPython.PrintCollector import PrintCollector  # isort:skip
-from RestrictedPython.compile import CompileResult  # isort:skip
-
+from RestrictedPython.PrintCollector import PrintCollector
 # Policy
-from RestrictedPython.transformer import RestrictingNodeTransformer  # isort:skip
-
-#
-from RestrictedPython.Eval import RestrictionCapableEval
+from RestrictedPython.transformer import RestrictingNodeTransformer
+from RestrictedPython.Utilities import utility_builtins

src/RestrictedPython/_compat.py

@@ -1,3 +1,5 @@
+
+# Standard library imports
 import sys
 
 

src/RestrictedPython/compile.py

@@ -1,10 +1,13 @@
-from collections import namedtuple
-from RestrictedPython._compat import IS_PY2
-from RestrictedPython.transformer import RestrictingNodeTransformer
 
+# Standard library imports
+from collections import namedtuple
 import ast
 import warnings
 
+# RestrictedPython internal imports
+from RestrictedPython._compat import IS_PY2
+from RestrictedPython.transformer import RestrictingNodeTransformer
+
 
 CompileResult = namedtuple(
     'CompileResult', 'code, errors, warnings, used_names')

src/RestrictedPython/tests/restricted_module.py

@@ -1,3 +1,5 @@
+
+# Standard library imports
 import sys
 
 

src/RestrictedPython/tests/testCompile.py

@@ -12,11 +12,14 @@
 #
 ##############################################################################
 
-from RestrictedPython.RCompile import niceParse
-
+# Standard library imports
+# Standard Library Imports
 import compiler.ast
 import unittest
 
+# RestrictedPython internal imports
+from RestrictedPython.RCompile import niceParse
+
 
 class CompileTests(unittest.TestCase):
 

src/RestrictedPython/tests/testREADME.py

@@ -13,8 +13,9 @@
 ##############################################################################
 """Run tests in README.txt
 """
+# Standard library imports
+# Standard Library Imports
 from doctest import DocFileSuite
-
 import unittest