Skip to content

Commit

Permalink
change structure to enable a consent for this pull request
Browse files Browse the repository at this point in the history
  • Loading branch information
@loechel
loechel committed Oct 26, 2022
1 parent 9bbf308 commit 7b26144
Showing 1 changed file with 113 additions and 71 deletions.
184 changes: 113 additions & 71 deletions docs/contributing/index.rst
View file
Expand Up @@ -32,7 +32,9 @@ Preperations for Contributing
If you want to contribute to this package, please prepare a development environment that includes ``git``, ``tox``, and several Python versions available through a Python manager such as ``pyenv``.
Please read the section :ref:`understand` first.

For all commits, you must run the tests locally with ``tox`` before pushing to the central repository.
For all commits, use ``tox`` to run tests and lint, and build the docs, before pushing your commit to the remote repository.

.. _new_python_version:

Preperations for a new Python version
+++++++++++++++++++++++++++++++++++++
Expand All @@ -50,51 +52,17 @@ To do so:
* Add tests to ``/tests/``.
* Add a ``visit_<AST Node>`` to ``/src/RestrictedPython/transformer.py``.

If the new AST Node should be enabled by default, without any modification, please add a ``visit_<AST Node>`` method such as the following:
If the new AST Node should be enabled by default, with or without any modification, please add a ``visit_<AST Node>`` method such as the following:

.. code-block:: python
def visit_<AST Node>(self, node):
"""Allow `<AST Node>` expressions."""
... # modifications
return self.node_contents_visit(node)
If the new AST Node should be disabled by default, add a ``visit_<AST Node>`` method such as the following:

.. code-block:: python
def visit_<AST Node>(self, node):
"""`<AST Node>` expression currently not allowed."""
self.not_allowed(node)
Please note, that for all AST Nodes without an explicit ``visit_<AST Node>`` method, a default applies which denies the usage of this expression and functionality.
As we try to be **as explicit as possible**, all language features should have a corresponding ``visit_<AST Node>``.
That follows the Zen of Python:

.. code-block:: pycon
:emphasize-lines: 5
>>> import this
The Zen of Python, by Tim Peters
Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!
All AST Nodes without an explicit ``visit_<AST Node>`` method, are denied by default.
So the usage of this expression and functionality is not allowed.

* Add a corresponding changelog entry.
* Additionally modify ``.meta.toml`` and run the ``meta/config`` script (for details see: https://github.com/mgedmin/check-python-versions) to update the following files:
Expand Down Expand Up @@ -122,11 +90,27 @@ To enable a certain functionality in RestrictedPython, do the following:
* icemac
* loechel

Differences between different Python versions
---------------------------------------------

Todos
-----
A (modified style) Copy of all Abstract Grammar Definitions for the Python versions does live in this Documentation (ast Subfolder) to help finding difference quicker by comparing files.

.. todolist::
.. toctree::
:maxdepth: 2

changes_from26to27
changes_from30to31
changes_from31to32
changes_from32to33
changes_from33to34
changes_from34to35
changes_from35to36
changes_from36to37
changes_from37to38
changes_from38to39
changes_from39to310
changes_from310to311
changes_from311to312

.. _understand:

Expand Down Expand Up @@ -174,14 +158,90 @@ The ``ast`` module consists of four areas:
A ``NodeVisitor`` is a class of a node / AST consumer, it reads the data by stepping through the tree without modifying it.
In contrast, a ``NodeTransformer`` (which inherits from a ``NodeVisitor``) is allowed to modify the tree and nodes.

Technical decissions on how to implement / maintain RestrictedPython (Design, Structure, Tools, ...)
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

RestrictedPython is a core Package of the Zope & Plone Stack.
Until Version 3.6 RestrictedPython was Python 2 only, and a critical blocker for Zope & Plone.
With RestrictedPython 4.0 an API compatible rewrite has happend, which supports modern Python Versions.

* Use modern python tool stack for maintainance and tests

* tox
* pytest
* black
* linting tools: flake8

* Use clear package Structure

* ``/src`` - Source Code
* ``/tests`` - separated tests
* ``/docs`` - Documentation

Tests and documentation are distributed within released packages.

.. todo::

Resolve discussion about how RestrictedPython should be treat new expressions / ``ast.Nodes``.
This belongs to :ref:`new_python_version`.

**Option 1 - reduce maintainance burden (prefered by icemac)**


All AST Nodes without an explicit ``visit_<AST Node>`` method, are denied by default.
So the usage of this expression and functionality is not allowed.

*This is currently the promoted version.*

**Option 2 - be as explicite as possible (prefered by loechel)**

If the new AST Node should be disabled by default, add a ``visit_<AST Node>`` method such as the following:

.. code-block:: python
def visit_<AST Node>(self, node):
"""`<AST Node>` expression currently not allowed."""
self.not_allowed(node)
Please note, that for all AST Nodes without an explicit ``visit_<AST Node>`` method, a default applies which denies the usage of this expression and functionality.
As we try to be **as explicit as possible**, all language features should have a corresponding ``visit_<AST Node>``.

That follows the Zen of Python:

.. code-block:: pycon
:emphasize-lines: 5
>>> import this
The Zen of Python, by Tim Peters
Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!
Technical Backgrounds - Links to External Documentation
+++++++++++++++++++++++++++++++++++++++++++++++++++++++

* `Concept of Immutable Types and Python Example`_
* `Python 3 Standard Library Documentation on AST module`_

* AST Grammar of Python
* AST Grammar of Python (`Status of Python Versions`_)

* `Python 3.12 AST`_ (development branch - EOL 2028-10)
* `Python 3.11 AST`_ (in bugfix phase - EOL 2027-10)
Expand All @@ -199,37 +259,19 @@ Technical Backgrounds - Links to External Documentation
* `Python 2.7 AST`_ (obsolete - EOL 2020-01-01)
* `Python 2.6 AST`_ (obsolete - EOL 2013-10.29)

* `AST NodeVistiors Class`_ (https://docs.python.org/3.9/library/ast.html#ast.NodeVisitor)
* `AST NodeTransformer Class`_ (https://docs.python.org/3.9/library/ast.html#ast.NodeTransformer)
* `AST dump method`_ (https://docs.python.org/3.9/library/ast.html#ast.dump)
* `AST NodeVistiors Class`_
* `AST NodeTransformer Class`_
* `AST dump method`_

* `In detail Documentation on the Python AST module (Green Tree Snakes)`_
* `Example how to Instrumenting the Python AST`_
* `Status of Python Versions`_

Differences between different Python versions
---------------------------------------------

A (modified style) Copy of all Abstract Grammar Definitions for the Python versions does live in this Documentation (ast Subfolder) to help finding difference quicker by comparing files.

.. toctree::
:maxdepth: 2
Todos
-----

changes_from26to27
changes_from30to31
changes_from31to32
changes_from32to33
changes_from33to34
changes_from34to35
changes_from35to36
changes_from36to37
changes_from37to38
changes_from38to39
changes_from39to310
changes_from310to311
changes_from311to312
.. todolist::

.. Links
.. Links:
.. _`What's new in Python`: https://docs.python.org/3/whatsnew/

Expand Down Expand Up @@ -297,11 +339,11 @@ A (modified style) Copy of all Abstract Grammar Definitions for the Python versi

.. _`Python 2.6 AST`: https://docs.python.org/2.6/library/ast.html#abstract-grammar

.. _`AST NodeVistiors Class`: https://docs.python.org/3.5/library/ast.html#ast.NodeVisitor
.. _`AST NodeVistiors Class`: https://docs.python.org/3/library/ast.html#ast.NodeVisitor

.. _`AST NodeTransformer Class`: https://docs.python.org/3.5/library/ast.html#ast.NodeTransformer
.. _`AST NodeTransformer Class`: https://docs.python.org/3/library/ast.html#ast.NodeTransformer

.. _`AST dump method`: https://docs.python.org/3.5/library/ast.html#ast.dump
.. _`AST dump method`: https://docs.python.org/3/library/ast.html#ast.dump

.. _`In detail Documentation on the Python AST module (Green Tree Snakes)`: https://greentreesnakes.readthedocs.org/en/latest/

Expand Down

0 comments on commit 7b26144

Please sign in to comment.