RestrictedPython 7.2a1.dev0__tar.gz → 7.4__tar.gz

restrictedpython-7.4/.pre-commit-config.yaml

@@ -0,0 +1,28 @@
+# Generated from:
+# https://github.com/zopefoundation/meta/tree/master/config/pure-python
+minimum_pre_commit_version: '3.6'
+repos:
+  - repo: https://github.com/pycqa/isort
+    rev: "5.13.2"
+    hooks:
+    - id: isort
+  - repo: https://github.com/hhatto/autopep8
+    rev: "v2.3.1"
+    hooks:
+    - id: autopep8
+      args: [--in-place, --aggressive, --aggressive]
+  - repo: https://github.com/asottile/pyupgrade
+    rev: v3.17.0
+    hooks:
+    - id: pyupgrade
+      args: [--py38-plus]
+  - repo: https://github.com/isidentical/teyit
+    rev: 0.4.3
+    hooks:
+    - id: teyit
+  - repo: https://github.com/PyCQA/flake8
+    rev: "7.1.1"
+    hooks:
+    - id: flake8
+      additional_dependencies:
+        - flake8-debugger == 4.1.2

{RestrictedPython-7.2a1.dev0 → restrictedpython-7.4}/CHANGES.rst

@@ -1,11 +1,39 @@
 Changes
 =======
 
-7.2a1.dev0 (2024-03-14)
------------------------
+7.4 (2024-10-09)
+----------------
+
+- Allow to use the package with Python 3.13.
+
+- Drop support for Python 3.7.
+
+- Provide new function ``RestrictedPython.Guards.safer_getattr_raise``.
+  It is similar to ``safer_getattr`` but handles its parameter
+  ``default`` like ``getattr``, i.e. it raises ``AttributeError``
+  if the attribute lookup fails and this parameter is not provided,
+  fixes `#287 <https://github.com/zopefoundation/RestrictedPython/issues/287>`_.
+
+
+7.3 (2024-09-30)
+----------------
+
+- Increase the safety level of ``safer_getattr`` allowing applications to use
+  it as ``getattr`` implementation. Such use should now follow the same policy
+  and give the same level of protection as direct attribute access in an
+  environment based on ``RestrictedPython``'s ``safe_builtints``.
+- Prevent information leakage via ``AttributeError.obj``
+  and the ``string`` module. (CVE-2024-47532)
+
+
+7.2 (2024-08-02)
+----------------
 
-- Allow to use the package with Python 3.13 -- Caution: No security
-  audit has been done so far.
+- Remove unneeded setuptools fossils that may cause installation problems
+  with recent setuptools versions.
+- Add support for single mode statements / execution.
+- Fix a potential breakout capability in the provided ``safer_getattr`` method
+  that is part of the ``safer_builtins``.
 
 
 7.1 (2024-03-14)

{RestrictedPython-7.2a1.dev0 → restrictedpython-7.4}/MANIFEST.in

@@ -5,6 +5,7 @@ include *.rst
 include *.txt
 include buildout.cfg
 include tox.ini
+include .pre-commit-config.yaml
 
 recursive-include docs *.py
 recursive-include docs *.rst

{RestrictedPython-7.2a1.dev0 → restrictedpython-7.4}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.1
 Name: RestrictedPython
-Version: 7.2a1.dev0
+Version: 7.4
 Summary: RestrictedPython is a defined subset of the Python language which allows to provide a program input into a trusted environment.
 Home-page: https://github.com/zopefoundation/RestrictedPython
 Author: Zope Foundation and Contributors
-Author-email: zope-dev@zope.org
+Author-email: zope-dev@zope.dev
 License: ZPL 2.1
 Project-URL: Documentation, https://restrictedpython.readthedocs.io/
 Project-URL: Source, https://github.com/zopefoundation/RestrictedPython
@@ -15,15 +15,15 @@ Classifier: License :: OSI Approved :: Zope Public License
 Classifier: Programming Language :: Python
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.7
 Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Topic :: Security
-Requires-Python: >=3.7, <3.14
+Requires-Python: >=3.8, <3.14
 Description-Content-Type: text/x-rst
 License-File: LICENSE.txt
 Provides-Extra: test
@@ -31,7 +31,7 @@ Requires-Dist: pytest; extra == "test"
 Requires-Dist: pytest-mock; extra == "test"
 Provides-Extra: docs
 Requires-Dist: Sphinx; extra == "docs"
-Requires-Dist: sphinx_rtd_theme; extra == "docs"
+Requires-Dist: furo; extra == "docs"
 
 .. image:: https://github.com/zopefoundation/RestrictedPython/actions/workflows/tests.yml/badge.svg
     :target: https://github.com/zopefoundation/RestrictedPython/actions/workflows/tests.yml
@@ -124,11 +124,39 @@ the documentation `Contributing page
 Changes
 =======
 
-7.2a1.dev0 (2024-03-14)
------------------------
+7.4 (2024-10-09)
+----------------
+
+- Allow to use the package with Python 3.13.
+
+- Drop support for Python 3.7.
+
+- Provide new function ``RestrictedPython.Guards.safer_getattr_raise``.
+  It is similar to ``safer_getattr`` but handles its parameter
+  ``default`` like ``getattr``, i.e. it raises ``AttributeError``
+  if the attribute lookup fails and this parameter is not provided,
+  fixes `#287 <https://github.com/zopefoundation/RestrictedPython/issues/287>`_.
+
+
+7.3 (2024-09-30)
+----------------
+
+- Increase the safety level of ``safer_getattr`` allowing applications to use
+  it as ``getattr`` implementation. Such use should now follow the same policy
+  and give the same level of protection as direct attribute access in an
+  environment based on ``RestrictedPython``'s ``safe_builtints``.
+- Prevent information leakage via ``AttributeError.obj``
+  and the ``string`` module. (CVE-2024-47532)
+
+
+7.2 (2024-08-02)
+----------------
 
-- Allow to use the package with Python 3.13 -- Caution: No security
-  audit has been done so far.
+- Remove unneeded setuptools fossils that may cause installation problems
+  with recent setuptools versions.
+- Add support for single mode statements / execution.
+- Fix a potential breakout capability in the provided ``safer_getattr`` method
+  that is part of the ``safer_builtins``.
 
 
 7.1 (2024-03-14)

restrictedpython-7.4/docs/_build/doctest/output.txt

@@ -0,0 +1,35 @@
+Results of doctest builder run on 2024-10-09 09:56:01
+=====================================================
+
+Document: usage/api
+-------------------
+1 items passed all tests:
+  13 tests in default
+13 tests in 1 items.
+13 passed and 0 failed.
+Test passed.
+
+Document: usage/basic_usage
+---------------------------
+2 items passed all tests:
+   6 tests in default
+   1 tests in single
+7 tests in 2 items.
+7 passed and 0 failed.
+Test passed.
+
+Document: usage/framework_usage
+-------------------------------
+2 items passed all tests:
+   1 tests in default
+   2 tests in own_policy
+3 tests in 2 items.
+3 passed and 0 failed.
+Test passed.
+
+Doctest summary
+===============
+   23 tests
+    0 failures in tests
+    0 failures in setup code
+    0 failures in cleanup code

restrictedpython-7.4/docs/_build/html/_sources/contributing/changes_from312to313.rst.txt

@@ -0,0 +1,5 @@
+Changes from Python 3.12 to Python 3.13
+---------------------------------------
+
+.. literalinclude:: ast/python3_13.ast
+   :diff: ast/python3_12.ast

restrictedpython-7.4/docs/_build/html/_sources/contributing/index.rst.txt

@@ -0,0 +1,308 @@
+Contributing
+============
+
+
+Contributing to RestrictedPython
+--------------------------------
+
+Legal requirements to contribute to RestrictedPython
+++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+The projects under the zopefoundation GitHub organization are open source, including RestrictedPython.
+We welcome contributions in different forms:
+
+* bug reports
+* code improvements and bug fixes
+* documentation improvements
+* pull request reviews
+
+For any changes in the repository besides trivial typo fixes, you are required to sign the contributor agreement.
+See https://www.zope.dev/developer/becoming-a-committer.html for details.
+
+Please visit our `Developer Guidelines`_ if you'd like to contribute code changes and our `guidelines for reporting bugs`_ if you want to file a bug report.
+
+
+.. _`Developer Guidelines`: https://www.zope.dev/developer/guidelines.html
+.. _`guidelines for reporting bugs`: https://www.zope.dev/developer/reporting-bugs.html
+
+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, 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
++++++++++++++++++++++++++++++++++++++
+
+RestrictedPython should be updated for each new version of Python.
+To do so:
+
+* Read the changelog (`What's new in Python`_).
+* Copy and adjust the new AST Grammar (found under: `Python 3 AST`_) to ``/docs/contributing/ast/python<version>.ast``.
+* Add a new file ``changes_from<old_version>to<new_version>.rst`` in the directory ``/docs/contributing/``.
+  If the changes are significant, especially if related to security, then add a description of the changes in that file.
+* Add those files to the ``toctree`` directive in ``index.rst``.
+* For each new **AST Node** or functionality:
+
+  * Add tests to ``/tests/``.
+  * Add a ``visit_<AST Node>`` to ``/src/RestrictedPython/transformer.py``.
+
+    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)
+
+    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.
+
+* Check the documentation for `inspect <https://docs.python.org/3/library/inspect.html>`_ and adjust the ``transformer.py:INSPECT_ATTRIBUTES`` list.
+* 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:
+
+  * ``/setup.py`` - Check that the new Python version classifier has been added ``"Programming Language :: Python :: <version>",``, and that the ``python_requires`` section has been updated correctly.
+  * ``/tox.ini`` - Check that a ``testenv`` entry is added to the general ``envlist`` statement.
+  * ``/.github/workflows/tests.yml`` - Check that a corresponding Python version entry has been added to the matrix definition.
+  * ``/docs/conf.py`` - Add the Python version to the ``intersphinx_mapping`` list.
+
+* On your local environment, use ``tox`` to run tests and lint, and build the docs, before pushing your commit to the remote repository.
+* Create a pull request.
+
+Enable a Python Feature in RestrictedPython
++++++++++++++++++++++++++++++++++++++++++++
+
+To enable a certain functionality in RestrictedPython, do the following:
+
+* `Create a new issue on GitHub <https://github.com/zopefoundation/RestrictedPython/issues/new/choose>`__, requesting the new feature, for discussion.
+* In ``/src/RestrictedPython/transformer.py``, change the corresponding ``visit_<AST Node>`` method.
+* In ``/tests/``, add or change the corresponding tests for this functionality.
+* Add a changelog entry.
+* On your local environment, use ``tox`` to run tests and lint, and build the docs, before pushing your commit to the remote repository.
+* Create a pull request and request a review by a core maintainer, e.g.:
+
+  * icemac
+  * loechel
+
+Differences between 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
+
+   changes_from37to38
+   changes_from38to39
+   changes_from39to310
+   changes_from310to311
+   changes_from311to312
+   changes_from312to313
+
+.. _understand:
+
+Understanding How RestrictedPython works internally
+---------------------------------------------------
+
+RestrictedPython is a classic approach of compiler construction to create a limited subset of an existing programming language.
+
+Defining a programming language requires a regular grammar (`Chomsky 3`_ / `EBNF`_) definition.
+This grammar will be implemented in an abstract syntax tree (AST), which will be passed on to a code generator to produce a machine-readable version.
+
+.. _`_sec_code_generation`:
+
+Code generation
++++++++++++++++
+
+As Python is a platform independent programming language, this machine readable version is a byte code which will be translated on the fly by an interpreter into machine code.
+This machine code then gets executed on the specific CPU architecture, with the standard operating system restrictions.
+
+The byte code produced must be compatible with the execution environment that the Python interpreter is running in, so we do not generate the byte code directly from ``compile_restricted`` and the other ``compile_restricted_*`` methods manually, it may not match what the interpreter expects.
+
+Thankfully, the Python ``compile()`` function introduced the capability to compile ``ast.AST`` code into byte code in Python 2.6, so we can return the platform-independent AST and keep byte code generation delegated to the interpreter.
+
+``ast`` module (Abstract Syntax Trees)
+++++++++++++++++++++++++++++++++++++++
+
+The ``ast`` module consists of four areas:
+
+* ``AST`` (Basis of all Nodes) + all node class implementations
+* ``NodeVisitor`` and ``NodeTransformer`` (tool to consume and modify the AST)
+* Helper methods
+
+  * ``parse``
+  * ``walk``
+  * ``dump``
+
+* Constants
+
+  * ``PyCF_ONLY_AST``
+
+
+``NodeVisitor`` & ``NodeTransformer``
++++++++++++++++++++++++++++++++++++++
+
+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 decisions 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 happened, which supports modern Python Versions.
+
+* Use modern python tool stack for maintenance 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 maintenance burden (preferred 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 explicit as possible (preferred 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 (`Status of Python Versions`_)
+
+    * `Python 3.12 AST`_ (EOL 2028-10)
+    * `Python 3.11 AST`_ (EOL 2027-10)
+    * `Python 3.10 AST`_ (EOL 2026-10)
+    * `Python 3.9 AST`_ (EOL 2025-10)
+    * `Python 3.8 AST`_ (EOL 2024-10)
+    * `Python 3.7 AST`_ (EOL 2023-06-27)
+
+  * `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`_
+
+Todos
+-----
+
+.. todolist::
+
+.. Links:
+
+.. _`What's new in Python`: https://docs.python.org/3/whatsnew/
+
+.. _`What's new in Python 3.12`: https://docs.python.org/3.12/whatsnew/3.12.html
+
+.. _`What's new in Python 3.11`: https://docs.python.org/3.11/whatsnew/3.11.html
+
+.. _`What's new in Python 3.10`: https://docs.python.org/3.10/whatsnew/3.10.html
+
+.. _`What's new in Python 3.9`: https://docs.python.org/3.9/whatsnew/3.9.html
+
+.. _`What's new in Python 3.8`: https://docs.python.org/3.8/whatsnew/3.8.html
+
+.. _`What's new in Python 3.7`: https://docs.python.org/3.7/whatsnew/3.7.html
+
+.. _`Status of Python Versions`: https://devguide.python.org/versions/
+
+.. _`Concept of Immutable Types and Python Example`: https://en.wikipedia.org/wiki/Immutable_object#Python
+
+.. _`Python 3 Standard Library Documentation on AST module`: https://docs.python.org/3/library/ast.html
+
+.. _`CamelCase`: https://en.wikipedia.org/wiki/Camel_case
+
+.. _`EBNF`: https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form
+
+.. _`Chomsky 3`: https://en.wikipedia.org/wiki/Chomsky_hierarchy#Type-3_grammars
+
+.. _`Python 3 AST`: https://docs.python.org/3/library/ast.html#abstract-grammar
+
+.. _`Python 3.12 AST`: https://docs.python.org/3.12/library/ast.html#abstract-grammar
+
+.. _`Python 3.11 AST`: https://docs.python.org/3.11/library/ast.html#abstract-grammar
+
+.. _`Python 3.10 AST`: https://docs.python.org/3.10/library/ast.html#abstract-grammar
+
+.. _`Python 3.9 AST`: https://docs.python.org/3.9/library/ast.html#abstract-grammar
+
+.. _`Python 3.8 AST`: https://docs.python.org/3.8/library/ast.html#abstract-grammar
+
+.. _`Python 3.7 AST`: https://docs.python.org/3.7/library/ast.html#abstract-grammar
+
+.. _`AST NodeVistiors Class`: https://docs.python.org/3/library/ast.html#ast.NodeVisitor
+
+.. _`AST NodeTransformer Class`: https://docs.python.org/3/library/ast.html#ast.NodeTransformer
+
+.. _`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/
+
+.. _`Example how to Instrumenting the Python AST`: http://www.dalkescientific.com/writings/diary/archive/2010/02/22/instrumenting_the_ast.html

restrictedpython-7.4/docs/_build/html/_sources/index.rst.txt

@@ -0,0 +1,42 @@
+.. RestrictedPython documentation master file, created by
+   sphinx-quickstart on Thu May 19 12:43:20 2016.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+.. image:: logo.jpg
+
+============================================
+Welcome to RestrictedPython's documentation!
+============================================
+
+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.
+
+Supported Python versions
+=========================
+
+RestrictedPython supports CPython 3.7 up to 3.12.
+It does _not_ support PyPy or other alternative Python implementations.
+
+Contents
+========
+
+.. toctree::
+   :maxdepth: 2
+
+   idea
+   install/index
+   usage/index
+   usage/api
+
+   roadmap/index
+   contributing/index
+
+   changes
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`