Update Documentation

.gitignore

@@ -10,6 +10,7 @@
 /local.cfg
 .coverage
 /*.egg-info
+/src/*.egg-info
 /.installed.cfg
 *.pyc
 /.Python

docs_de/RestrictedPython3/index.rst

@@ -0,0 +1,41 @@
+RestrictedPython 3.6.x and before
+=================================
+
+
+Technical foundation of RestrictedPython
+........................................
+
+RestrictedPython is based on the Python 2 only standard library module ``compiler`` (https://docs.python.org/2.7/library/compiler.html).
+RestrictedPython based on the
+
+* compiler.ast
+* compiler.parse
+* compiler.pycodegen
+
+With Python 2.6 the compiler module with all its sub modules has been declared deprecated with no direct upgrade Path or recommendations for a replacement.
+
+
+Version Support of RestrictedPython 3.6.x
+.........................................
+
+RestrictedPython 3.6.x aims on supporting Python versions:
+
+* 2.0
+* 2.1
+* 2.2
+* 2.3
+* 2.4
+* 2.5
+* 2.6
+* 2.7
+
+Even if the README claims that Compatibility Support is form Python 2.3 - 2.7 I found some Code in RestricedPython and related Packages which test if Python 1 is used.
+
+Due to this approach to support all Python 2 Versions the code uses only statements that are compatible with all of those versions.
+
+So oldstyle classes and newstyle classes are mixed,
+
+The following language elements are statements and not functions:
+
+* exec
+* print

docs_de/RestrictedPython4/index.rst

@@ -0,0 +1,28 @@
+RestrictedPython 4+
+===================
+
+RestrictedPython 4.0.0 und aufwärts ist ein komplett Rewrite für Python 3 Kompatibilität.
+
+Da das ``compiler`` Package in Python 2.6 als depricated erklärt und in 3.0 bereits entfernt wurde und somit in allen Python 3 Versionen nicht verfügbar ist, muss die Grundlage neu geschaffen werden.
+
+Ziele des Rewrite
+-----------------
+
+Wir wollen RestrictedPython weiter führen, da es eine Core-Dependency für den Zope2 Applikations-Server ist und somit auch eine wichtige Grundlage für das CMS Plone.
+Zope2 soll Python 3 kompatibel werden.
+
+Eine der Kernfunktionalitäten von Zope2 und damit für Plone ist die Möglichkeit Python Skripte und Templates TTW (through the web) zu schreiben und zu modifizieren.
+
+
+
+Targeted Versions to support
+----------------------------
+
+For a RestrictedPython 4.0.0+ Update we aim to support only current Python Versions (under active Security Support):
+
+* 2.6
+* 2.7
+* 3.2
+* 3.3
+* 3.4
+* 3.5

docs_de/grundlagen/index.rst

@@ -0,0 +1,54 @@
+Grundlagen von RestrictedPython und der Sicherheitskonzepte von Zope2
+=====================================================================
+
+
+Motivation für RestrictedPython
+-------------------------------
+
+Python ist eine moderne und heute sehr beliebte Programmiersprache.
+Viele Bereiche nutzen heute Python ganz selbstverständlich.
+Waren am Anfang gerade Systemadministratoren die via  Python-Skripte ihre Systeme pflegten, ist heute die PyData Community eine der größten Nutzergruppen.
+Auch wird Python gerne als Lehrsprache verwendet.
+
+Ein Nutzungsbereich von Python unterscheidet sich fundamental: *Python-Web* bzw. *Applikations-Server die Fremdcode aufnehmen*.
+Zope gehörte zu den ersten großen und erfolgreichen Python-Web-Projekten und hat sich mit als erster um dieses Thema gekümmert.
+
+Während in der klassischen Software-Entwicklung aber auch in der Modelierung und Analyse von Daten drei Aspekte relevant sind:
+
+* Verständlichkeit des Programms (--> Siehe PEP 20 "The Zen of Python" https://www.python.org/dev/peps/pep-0020/)
+* die Effizienz der Programmiersprache und der Ausführungsumgebung
+* Verfügbarkeit der Ausführungsumgebung
+
+ist ein grundlegender Aspekt, die Mächtigkeit der Programmiersprache, selten von Relevanz.
+Dies liegt auch daran, dass alle gängigen Programmiersprachen die gleiche Mächtigkeit besitzten: Turing-Vollständig.
+Die Theoretische Informatik kennt mehrere Stufen der Mächtigkeit einer Programmiersprache, diese bilden die Grundlage der Berechenbarkeitstheorie.
+Für klassische Software-Entwicklung ist eine Turing-vollständige Programmiersprache entsprechend die richtige Wahl.
+
+In der klassischen Software-Welt gelten in der Regel folgende Bedingungen:
+
+* man bekommt eine fertige Software und führt diese aus (Beispiel: Betriebssysteme, Anwendungen und Frameworks)
+* man schreibt eine Software / Skript
+* man verarbeitet Daten zur Berechung und Visualisierung, ohne ein vollumfängliches Programm zu entwickeln (Beispiel: MatLab, Jupyter-Notebooks)
+
+Da hierbei erstmal keine Unterscheidung zwischen Open Source und Closed Source Software gemacht werden soll, da die relevante Frage eher eine Frage des Vertrauen ist.
+
+Die zentrale Frage ist:
+
+ Vertraue ich der Software, bzw. den Entwicklern der Software und führe diese aus.
+
+
+
+
+Python ist eine Turing-vollständige Prgrammiersprache.
+Somit haben Entwickler grundsätzlich erstmal keine Limitierungen beim programmieren.
+
+
+
+und können somit potentiell die Applikation und den Server selber schaden.
+
+RestrictedPython und AccessControl zielen auf diese Besonderheit und versuchen einen reduzierten Subset der Programmiersprache Python zur verfügung zu stellen.
+Hierzu werden erstmal alle Funktionen die potentiel das System schaden können verboten.
+Genauer gesagt muss jede Funktion, egal ob eine der Python ``__builtin__``-Funktionen, der Python Standard-Library oder beliebiger Zusatz-Modulen / (Python-Eggs) explizit freigegeben werden.
+Wie sprechen hier von White-Listing.
+
+Damit dies funktioniert, muss neben der ``restricted_compile``-Funktion auch eine API für die explizite Freigabe von Modulen und Funktionen existieren.

docs_de/idee.rst

@@ -27,3 +27,17 @@ Diese ist für RestrictedPython durch folgende Funktion ersetzt:
 .. code:: Python
 
     compile_restriced(source, filename, mode [, flags [, dont_inherit]])
+
+
+The primary param ``source`` has been restriced to be an ASCII string or ``unicode`` string.
+
+
+
+Also RestrictedPython provides a way to define Policies, by redefining restricted versions of ``print``, ``getattr``, ``setattr``, ``import``, etc..
+As shortcutes it offers three stripped down versions of Pythons ``__builtins__``:
+
+* ``safe_builtins`` (by Guards.py)
+* ``limited_builtins`` (by Limits.py), which provides restriced sequence types
+* ``utilities_builtins`` (by Utilities.py), which provides access for standard modules math, random, string and for sets.
+
+There is also a guard function for making attributes immutable --> ``full_write_guard`` (write and delete protected)