Type Annotations for RestrictedPython

Author: loechel

.meta.toml

@@ -47,7 +47,7 @@ testenv-additional = [
     "    coverage combine",
     "    coverage html",
     "    coverage report -m --fail-under=100",
-    "depends = py39,py310,py311,py311-datetime,py312,py313,py314,coverage",
+    "depends = py39,py310,py311,py312,py313,py314,py314-datetime,coverage",
     ]
 coverage-command = "pytest --cov=src --cov=tests --cov-report= tests {posargs}"
 coverage-setenv = [

setup.py

@@ -39,17 +39,20 @@ def read(*rnames):
           'Programming Language :: Python',
           'Operating System :: OS Independent',
           'Programming Language :: Python :: 3',
-          'Programming Language :: Python :: 3.9',
           'Programming Language :: Python :: 3.10',
           'Programming Language :: Python :: 3.11',
           'Programming Language :: Python :: 3.12',
           'Programming Language :: Python :: 3.13',
+          'Programming Language :: Python :: 3.14',
           'Programming Language :: Python :: Implementation :: CPython',
           'Topic :: Security',
+          'Typing :: Typed',
       ],
       keywords='restricted execution security untrusted code',
       author='Zope Foundation and Contributors',
       author_email='[email protected]',
+      maintainer='Zope Foundation, Plone Foundation and Contributors',
+      maintainer_email='[email protected]',
       project_urls={
           "Documentation": "https://restrictedpython.readthedocs.io/",
           "Source": "https://github.com/zopefoundation/RestrictedPython",
@@ -59,9 +62,10 @@ def read(*rnames):
       packages=find_packages('src'),
       package_dir={'': 'src'},
       install_requires=[],
-      python_requires=">=3.9, <3.15",
+      python_requires=">=3.10, <3.15",
       extras_require={
           'test': ['pytest', 'pytest-mock'],
+          'typecheck': ['mypy', 'typeshed'],
           'docs': ['Sphinx', 'furo'],
       },
       include_package_data=True,

src/RestrictedPython/Utilities.py

@@ -14,6 +14,7 @@
 import math
 import random
 import string
+from collections.abc import Iterable
 
 
 utility_builtins = {}
@@ -75,7 +76,8 @@ def test(*args):
 utility_builtins['test'] = test
 
 
-def reorder(s, with_=None, without=()):
+def reorder(s: Iterable, with_: Iterable | None = None,
+            without: Iterable | None = None) -> Iterable:
     # 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).

src/RestrictedPython/_compat.py

@@ -6,5 +6,7 @@
 IS_PY310_OR_GREATER = _version.major == 3 and _version.minor >= 10
 IS_PY311_OR_GREATER = _version.major == 3 and _version.minor >= 11
 IS_PY312_OR_GREATER = _version.major == 3 and _version.minor >= 12
+IS_PY313_OR_GREATER = _version.major == 3 and _version.minor >= 13
+IS_PY314_OR_GREATER = _version.major == 3 and _version.minor >= 14
 
 IS_CPYTHON = platform.python_implementation() == 'CPython'

src/RestrictedPython/compile.py

@@ -1,11 +1,19 @@
 import ast
 import warnings
 from collections import namedtuple
+from os import PathLike
+from typing import Any
+from typing import Literal
+from typing import TypeAlias
 
 from RestrictedPython._compat import IS_CPYTHON
 from RestrictedPython.transformer import RestrictingNodeTransformer
 
 
+# Temporary workaround for missing _typeshed
+ReadableBuffer: TypeAlias = bytes | bytearray
+
+
 CompileResult = namedtuple(
     'CompileResult', 'code, errors, warnings, used_names')
 syntax_error_template = (
@@ -18,12 +26,12 @@
 
 
 def _compile_restricted_mode(
-        source,
-        filename='<string>',
-        mode="exec",
-        flags=0,
-        dont_inherit=False,
-        policy=RestrictingNodeTransformer):
+        source: str | ReadableBuffer | ast.Module | ast.Expression | ast.Interactive,
+        filename: str | ReadableBuffer | PathLike[Any] = '<string>',
+        mode: Literal["exec", "eval", "single"] = "exec",
+        flags: int = 0,
+        dont_inherit: bool = False,
+        policy: ast.NodeTransformer = RestrictingNodeTransformer) -> CompileResult:
 
     if not IS_CPYTHON:
         warnings.warn_explicit(
@@ -78,11 +86,11 @@ def _compile_restricted_mode(
 
 
 def compile_restricted_exec(
-        source,
-        filename='<string>',
-        flags=0,
-        dont_inherit=False,
-        policy=RestrictingNodeTransformer):
+        source: str | ReadableBuffer | ast.Module | ast.Expression | ast.Interactive,
+        filename: str | ReadableBuffer | PathLike[Any] = '<string>',
+        flags: int = 0,
+        dont_inherit: bool = False,
+        policy: ast.NodeTransformer = RestrictingNodeTransformer) -> CompileResult:
     """Compile restricted for the mode `exec`."""
     return _compile_restricted_mode(
         source,
@@ -94,11 +102,11 @@ def compile_restricted_exec(
 
 
 def compile_restricted_eval(
-        source,
-        filename='<string>',
-        flags=0,
-        dont_inherit=False,
-        policy=RestrictingNodeTransformer):
+        source: str | ReadableBuffer | ast.Module | ast.Expression | ast.Interactive,
+        filename: str | ReadableBuffer | PathLike[Any] = '<string>',
+        flags: int = 0,
+        dont_inherit: bool = False,
+        policy: ast.NodeTransformer = RestrictingNodeTransformer) -> CompileResult:
     """Compile restricted for the mode `eval`."""
     return _compile_restricted_mode(
         source,
@@ -110,11 +118,11 @@ def compile_restricted_eval(
 
 
 def compile_restricted_single(
-        source,
-        filename='<string>',
-        flags=0,
-        dont_inherit=False,
-        policy=RestrictingNodeTransformer):
+        source: str | ReadableBuffer | ast.Module | ast.Expression | ast.Interactive,
+        filename: str | ReadableBuffer | PathLike[Any] = '<string>',
+        flags: int = 0,
+        dont_inherit: bool = False,
+        policy: ast.NodeTransformer = RestrictingNodeTransformer) -> CompileResult:
     """Compile restricted for the mode `single`."""
     return _compile_restricted_mode(
         source,
@@ -128,12 +136,12 @@ def compile_restricted_single(
 def compile_restricted_function(
         p,  # parameters
         body,
-        name,
-        filename='<string>',
+        name: str,
+        filename: str | ReadableBuffer | PathLike[Any] = '<string>',
         globalize=None,  # List of globals (e.g. ['here', 'context', ...])
-        flags=0,
-        dont_inherit=False,
-        policy=RestrictingNodeTransformer):
+        flags: int = 0,
+        dont_inherit: bool = False,
+        policy: ast.NodeTransformer = RestrictingNodeTransformer) -> CompileResult:
     """Compile a restricted code object for a function.
 
     Documentation see:
@@ -181,12 +189,12 @@ def compile_restricted_function(
 
 
 def compile_restricted(
-        source,
-        filename='<unknown>',
-        mode='exec',
-        flags=0,
-        dont_inherit=False,
-        policy=RestrictingNodeTransformer):
+        source: str | ReadableBuffer | ast.Module | ast.Expression | ast.Interactive,
+        filename: str | ReadableBuffer | PathLike[Any] = '<unknown>',
+        mode: str = 'exec',
+        flags: int = 0,
+        dont_inherit: bool = False,
+        policy: ast.NodeTransformer = RestrictingNodeTransformer) -> CompileResult:
     """Replacement for the built-in compile() function.
 
     policy ... `ast.NodeTransformer` class defining the restrictions.