RestrictedPython 8.3__tar.gz → 8.4__tar.gz

{restrictedpython-8.3 → restrictedpython-8.4}/.pre-commit-config.yaml

@@ -27,3 +27,8 @@ repos:
     - id: flake8
       additional_dependencies:
         - flake8-debugger == 4.1.2
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v2.1.0
+    hooks:
+      - id: mypy
+        pass_filenames: false

{restrictedpython-8.3 → restrictedpython-8.4}/CHANGES.rst

@@ -1,6 +1,19 @@
 Changes
 =======
 
+8.4 (2026-07-10)
+----------------
+
+- Add type annotations to the package code.
+  For clarification, restricted Python code does not support type annotations.
+
+- Allow ``ast.Module``, ``ast.Expression`` and ``ast.Interactive`` as body in compile_restricted_function
+
+- Disallow ``mode="function"`` in ``compile_restricted`` (it never worked).
+
+- Prevent access to ``string.Formatter`` and its unsafe traversal methods via
+  ``safer_getattr``.
+
 8.3 (2026-06-16)
 ----------------
 

{restrictedpython-8.3 → restrictedpython-8.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: RestrictedPython
-Version: 8.3
+Version: 8.4
 Summary: RestrictedPython is a defined subset of the Python language which allows to provide a program input into a trusted environment.
 Author-email: Zope Foundation and contributors <zope-dev@zope.dev>
 Maintainer-email: Plone Foundation and contributors <zope-dev@zope.dev>
@@ -21,6 +21,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Topic :: Security
+Classifier: Typing :: Typed
 Requires-Python: <3.16,>=3.10
 Description-Content-Type: text/x-rst
 License-File: LICENSE.txt
@@ -30,6 +31,8 @@ Requires-Dist: pytest-mock; extra == "test"
 Provides-Extra: docs
 Requires-Dist: Sphinx; extra == "docs"
 Requires-Dist: furo; extra == "docs"
+Provides-Extra: typecheck
+Requires-Dist: mypy; extra == "typecheck"
 Dynamic: license-file
 
 .. image:: https://github.com/zopefoundation/RestrictedPython/actions/workflows/tests.yml/badge.svg
@@ -123,6 +126,19 @@ the documentation `Contributing page
 Changes
 =======
 
+8.4 (2026-07-10)
+----------------
+
+- Add type annotations to the package code.
+  For clarification, restricted Python code does not support type annotations.
+
+- Allow ``ast.Module``, ``ast.Expression`` and ``ast.Interactive`` as body in compile_restricted_function
+
+- Disallow ``mode="function"`` in ``compile_restricted`` (it never worked).
+
+- Prevent access to ``string.Formatter`` and its unsafe traversal methods via
+  ``safer_getattr``.
+
 8.3 (2026-06-16)
 ----------------
 

{restrictedpython-8.3 → restrictedpython-8.4}/docs/usage/api.rst

@@ -11,13 +11,13 @@ API overview
 
     :param source: (required). the source code that should be compiled
     :param filename: (optional). defaults to ``'<unknown>'``
-    :param mode: (optional). Use ``'exec'``, ``'eval'``, ``'single'`` or ``'function'``. defaults to ``'exec'``
+    :param mode: (optional). Use ``'exec'``, ``'eval'`` or ``'single'``. defaults to ``'exec'``
     :param flags: (optional). defaults to ``0``
     :param dont_inherit: (optional). defaults to ``False``
     :param policy: (optional). defaults to ``RestrictingNodeTransformer``
-    :type source: str or unicode text or ``ast.AST``
-    :type filename: str or unicode text
-    :type mode: str or unicode text
+    :type source: str or bytes or bytearray or ``ast.Module`` or ``ast.Expression`` or ``ast.Interactive``
+    :type filename: str or bytes or os.PathLike[typing.Any]
+    :type mode: str
     :type flags: int
     :type dont_inherit: int
     :type policy: RestrictingNodeTransformer class
@@ -67,10 +67,10 @@ API overview
     :param flags: (optional). defaults to ``0``
     :param dont_inherit: (optional). defaults to ``False``
     :param policy: (optional). defaults to ``RestrictingNodeTransformer``
-    :type p: str or unicode text
-    :type body: str or unicode text
-    :type name: str or unicode text
-    :type filename: str or unicode text
+    :type p: str
+    :type body: str or bytes or bytearray or ``ast.Module`` or ``ast.Expression`` or ``ast.Interactive``
+    :type name: str
+    :type filename: str or bytes or os.PathLike[typing.Any]
     :type globalize: None or list
     :type flags: int
     :type dont_inherit: int

{restrictedpython-8.3 → restrictedpython-8.4}/pyproject.toml

@@ -9,7 +9,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "RestrictedPython"
-version = "8.3"
+version = "8.4"
 description = "RestrictedPython is a defined subset of the Python language which allows to provide a program input into a trusted environment."
 license = "ZPL-2.1"
 classifiers = [
@@ -24,6 +24,7 @@ classifiers = [
     "Programming Language :: Python :: 3.14",
     "Programming Language :: Python :: Implementation :: CPython",
     "Topic :: Security",
+    "Typing :: Typed",
 ]
 dynamic = ["readme"]
 requires-python = ">=3.10, <3.16"
@@ -50,6 +51,9 @@ docs = [
     "Sphinx",
     "furo",
 ]
+typecheck = [
+    "mypy",
+]
 
 [project.urls]
 Documentation = "https://restrictedpython.readthedocs.io/"
@@ -57,6 +61,7 @@ Issues = "https://github.com/zopefoundation/RestrictedPython/issues"
 Source = "https://github.com/zopefoundation/RestrictedPython"
 Changelog = "https://github.com/zopefoundation/RestrictedPython/blob/master/CHANGES.rst"
 
+
 [tool.coverage.run]
 branch = true
 source = ["RestrictedPython"]
@@ -84,6 +89,28 @@ directory = "parts/htmlcov"
 readme = {file = ["README.rst", "CHANGES.rst"]}
 
 
+[tool.mypy]
+mypy_path = "src"
+packages = ["RestrictedPython"]
+python_version = "3.10"
+warn_unreachable = true
+implicit_reexport = false
+strict = true
+
+[[tool.mypy.overrides]]
+module = ["DateTime"]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = ["RestrictedPython.Guards"]
+check_untyped_defs = false
+disallow_untyped_defs = false
+
+[[tool.mypy.overrides]]
+module = ["RestrictedPython.transformer"]
+warn_no_return = false
+
+
 [tool.zest-releaser]
 create-wheel = false
 upload-pypi = false

{restrictedpython-8.3 → restrictedpython-8.4}/src/RestrictedPython/Eval.py

@@ -13,8 +13,12 @@
 """Restricted Python Expressions."""
 
 import ast
+import collections
+import types
+import typing
 
-from .compile import compile_restricted_eval
+from RestrictedPython._types import cast_not_none
+from RestrictedPython.compile import compile_restricted_eval
 
 
 nltosp = str.maketrans('\r\n', '  ')
@@ -22,13 +26,21 @@ nltosp = str.maketrans('\r\n', '  ')
 # No restrictions.
 default_guarded_getattr = getattr
 
+_T = typing.TypeVar('_T')
+_TK = typing.TypeVar('_TK', contravariant=True)
+_TV = typing.TypeVar('_TV', covariant=True)
 
-def default_guarded_getitem(ob, index):
+
+class _GetItem(typing.Protocol[_TK, _TV]):
+    def __getitem__(self, key: _TK) -> _TV: ...
+
+
+def default_guarded_getitem(ob: _GetItem[_TK, _TV], index: _TK) -> _TV:
     # No restrictions.
     return ob[index]
 
 
-def default_guarded_getiter(ob):
+def default_guarded_getiter(ob: _T) -> _T:
     # No restrictions.
     return ob
 
@@ -36,17 +48,18 @@ def default_guarded_getiter(ob):
 class RestrictionCapableEval:
     """A base class for restricted code."""
 
-    globals = {'__builtins__': None}
+    globals: dict[str, typing.Any] = {'__builtins__': None}
+
     # restricted
-    rcode = None
+    rcode: types.CodeType | None = None
 
     # unrestricted
-    ucode = None
+    ucode: types.CodeType | None = None
 
     # Names used by the expression
-    used = None
+    used: tuple[str, ...] | None = None
 
-    def __init__(self, expr):
+    def __init__(self, expr: str):
         """Create a restricted expression
 
         where:
@@ -60,7 +73,7 @@ class RestrictionCapableEval:
         # Catch syntax errors.
         self.prepUnrestrictedCode()
 
-    def prepRestrictedCode(self):
+    def prepRestrictedCode(self) -> None:
         if self.rcode is None:
             result = compile_restricted_eval(self.expr, '<string>')
             if result.errors:
@@ -68,13 +81,12 @@ class RestrictionCapableEval:
             self.used = tuple(result.used_names)
             self.rcode = result.code
 
-    def prepUnrestrictedCode(self):
+    def prepUnrestrictedCode(self) -> None:
         if self.ucode is None:
-            exp_node = compile(
+            exp_node = ast.parse(
                 self.expr,
                 '<string>',
-                'eval',
-                ast.PyCF_ONLY_AST)
+                'eval')
 
             co = compile(exp_node, '<string>', 'eval')
 
@@ -90,7 +102,9 @@ class RestrictionCapableEval:
 
             self.ucode = co
 
-    def eval(self, mapping):
+    def eval(self,
+             mapping: collections.abc.Mapping[str,
+                                              typing.Any]) -> typing.Any:
         # This default implementation is probably not very useful. :-(
         # This is meant to be overridden.
         self.prepRestrictedCode()
@@ -103,11 +117,11 @@ class RestrictionCapableEval:
 
         global_scope.update(self.globals)
 
-        for name in self.used:
+        for name in cast_not_none(self.used):
             if (name not in global_scope) and (name in mapping):
                 global_scope[name] = mapping[name]
 
-        return eval(self.rcode, global_scope)
+        return eval(cast_not_none(self.rcode), global_scope)
 
-    def __call__(self, **kw):
+    def __call__(self, **kw: typing.Any) -> typing.Any:
         return self.eval(kw)

{restrictedpython-8.3 → restrictedpython-8.4}/src/RestrictedPython/Guards.py

@@ -16,6 +16,7 @@
 # DocumentTemplate.DT_UTil contains a few.
 
 import builtins
+import string
 
 from RestrictedPython.transformer import INSPECT_ATTRIBUTES
 
@@ -220,7 +221,7 @@ def _full_write_guard():
     return guard
 
 
-full_write_guard = _full_write_guard()
+full_write_guard = _full_write_guard()  # type: ignore[no-untyped-call]
 
 
 def guarded_setattr(object, name, value):
@@ -238,6 +239,8 @@ safe_builtins['delattr'] = guarded_delattr
 
 
 raise_ = object()
+_FORMATTER_UNSAFE_METHODS = frozenset(('format', 'get_field', 'get_value',
+                                       'vformat'))
 
 
 def safer_getattr(object, name, default=None, getattr=getattr):
@@ -254,6 +257,14 @@ def safer_getattr(object, name, default=None, getattr=getattr):
             (isinstance(object, type) and issubclass(object, str))):
         raise NotImplementedError(
             'Using the format*() methods of `str` is not safe')
+    if object is string and name == 'Formatter':
+        raise NotImplementedError('string.Formatter is not safe')
+    if name in _FORMATTER_UNSAFE_METHODS and (
+            isinstance(object, string.Formatter) or
+            (isinstance(object, type) and
+             issubclass(object, string.Formatter))):
+        raise NotImplementedError(
+            'Using string.Formatter methods is not safe')
     if name in INSPECT_ATTRIBUTES:
         raise AttributeError(
             f'"{name}" is a restricted name,'

{restrictedpython-8.3 → restrictedpython-8.4}/src/RestrictedPython/Limits.py

@@ -10,11 +10,28 @@
 # FOR A PARTICULAR PURPOSE
 #
 ##############################################################################
+import collections.abc
+import typing
 
-limited_builtins = {}
 
+limited_builtins: dict[str, typing.Any] = {}
 
-def limited_range(iFirst, *args):
+
+@typing.overload
+def limited_range(iFirst: int) -> collections.abc.Sequence[int]: ...
+
+
+@typing.overload
+def limited_range(iStart: int, iEnd: int, /
+                  ) -> collections.abc.Sequence[int]: ...
+
+
+@typing.overload
+def limited_range(iStart: int, iEnd: int, iStep: int, /
+                  ) -> collections.abc.Sequence[int]: ...
+
+
+def limited_range(iFirst: int, *args: int) -> collections.abc.Sequence[int]:
     # limited range function from Martijn Pieters
     RANGELIMIT = 1000
     if not len(args):
@@ -41,8 +58,10 @@ def limited_range(iFirst, *args):
 
 limited_builtins['range'] = limited_range
 
+_T = typing.TypeVar('_T')
+
 
-def limited_list(seq):
+def limited_list(seq: collections.abc.Iterable[_T]) -> list[_T]:
     if isinstance(seq, str):
         raise TypeError('cannot convert string to list')
     return list(seq)
@@ -51,7 +70,7 @@ def limited_list(seq):
 limited_builtins['list'] = limited_list
 
 
-def limited_tuple(seq):
+def limited_tuple(seq: collections.abc.Iterable[_T]) -> tuple[_T, ...]:
     if isinstance(seq, str):
         raise TypeError('cannot convert string to tuple')
     return tuple(seq)

{restrictedpython-8.3 → restrictedpython-8.4}/src/RestrictedPython/PrintCollector.py

@@ -15,17 +15,17 @@
 class PrintCollector:
     """Collect written text, and return it when called."""
 
-    def __init__(self, _getattr_=None):
+    def __init__(self, _getattr_=None):  # type: ignore[no-untyped-def]
         self.txt = []
         self._getattr_ = _getattr_
 
-    def write(self, text):
+    def write(self, text: str) -> None:
         self.txt.append(text)
 
-    def __call__(self):
+    def __call__(self) -> str:
         return ''.join(self.txt)
 
-    def _call_print(self, *objects, **kwargs):
+    def _call_print(self, *objects, **kwargs):  # type: ignore[no-untyped-def]
         if kwargs.get('file', None) is None:
             kwargs['file'] = self
         else:

{restrictedpython-8.3 → restrictedpython-8.4}/src/RestrictedPython/Utilities.py

@@ -11,21 +11,24 @@
 #
 ##############################################################################
 
+import collections.abc
 import math
 import random
 import string
+import types
+import typing
 
 
-utility_builtins = {}
+utility_builtins: dict[str, typing.Any] = {}
 
 
 class _AttributeDelegator:
-    def __init__(self, mod, *excludes):
+    def __init__(self, mod: types.ModuleType, *excludes: str):
         """delegate attribute lookups outside *excludes* to module *mod*."""
         self.__mod = mod
         self.__excludes = excludes
 
-    def __getattr__(self, attr):
+    def __getattr__(self, attr: str) -> typing.Any:
         if attr in self.__excludes:
             raise NotImplementedError(
                 f"{self.__mod.__name__}.{attr} is not safe")
@@ -50,7 +53,7 @@ except ImportError:
     pass
 
 
-def same_type(arg1, *args):
+def same_type(arg1: object, *args: object) -> bool:
     """Compares the class or type of two or more objects."""
     t = getattr(arg1, '__class__', type(arg1))
     for arg in args:
@@ -61,8 +64,10 @@ def same_type(arg1, *args):
 
 utility_builtins['same_type'] = same_type
 
+_T = typing.TypeVar('_T')
 
-def test(*args):
+
+def test(*args: _T) -> _T | None:
     length = len(args)
     for i in range(1, length, 2):
         if args[i - 1]:
@@ -70,12 +75,22 @@ def test(*args):
 
     if length % 2:
         return args[-1]
+    return None
 
 
 utility_builtins['test'] = test
 
+_TK = typing.TypeVar('_TK')
+_TV = typing.TypeVar('_TV')
+_T_in: typing.TypeAlias = collections.abc.Iterable[_TK | tuple[_TK, _TV]]
+_T_out: typing.TypeAlias = list[tuple[_TK, _TK | _TV]]
+
 
-def reorder(s, with_=None, without=()):
+def reorder(
+        s: _T_in[_TK, _TV],
+        with_: collections.abc.Iterable[typing.Any] | None = None,
+        without: collections.abc.Iterable[typing.Any] = ()
+) -> _T_out[_TK, _TV]:
     # s, with_, and without are sequences treated as sets.
     # The result is subtract(intersect(s, with_), without),
     # unless with_ is None, in which case it is subtract(s, without).

restrictedpython-8.4/src/RestrictedPython/_types.py

@@ -0,0 +1,25 @@
+import ast
+import sys
+import typing
+
+
+_T = typing.TypeVar('_T')
+
+
+def cast_not_none(var: _T | None) -> _T:
+    return typing.cast(_T, var)
+
+
+# T_pos_ast are subtypes of ast.AST that have a position
+# (have attributes: lineno, end_lineno, col_offset, and end_col_offset).
+#
+# ast.type_param is a new type in python 3.12 that has a position.
+# TODO: Remove `else` when Support for Python 3.11 is dropped.
+if sys.version_info >= (3, 12):
+    T_pos_ast: typing.TypeAlias = (
+        ast.stmt | ast.expr | ast.excepthandler | ast.arg | ast.keyword
+        | ast.alias | ast.pattern | ast.type_param)
+else:
+    T_pos_ast: typing.TypeAlias = (
+        ast.stmt | ast.expr | ast.excepthandler | ast.arg | ast.keyword
+        | ast.alias | ast.pattern)