Type Annotations for RestrictedPython

CHANGES.rst

@@ -4,7 +4,8 @@ Changes
 8.3 (unreleased)
 ----------------
 
-- Nothing changed yet.
+- Add type annotations to the package code.
+  For clarification, restricted Python code does not support type annotations.
 
 
 8.3a1.dev0 (2026-05-29)

pyproject.toml

@@ -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,10 @@ docs = [
     "Sphinx",
     "furo",
 ]
+typecheck = [
+    "mypy",
+    "typeshed",
+]
 
 [project.urls]
 Documentation = "https://restrictedpython.readthedocs.io/"

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 = ()) -> 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/compile.py

@@ -1,13 +1,35 @@
+from __future__ import annotations
+
 import ast
 import warnings
-from collections import namedtuple
+from ast import Expression
+from ast import Interactive
+from ast import Module
+from ast import NodeTransformer
+from collections.abc import Mapping
+from collections.abc import Sequence
+from os import PathLike
+from types import CodeType
+from typing import Any
+from typing import Literal
+from typing import NamedTuple
+from typing import TypeAlias
 
 from RestrictedPython._compat import IS_CPYTHON
 from RestrictedPython.transformer import RestrictingNodeTransformer
 
 
-CompileResult = namedtuple(
-    'CompileResult', 'code, errors, warnings, used_names')
+# Temporary workaround for missing _typeshed
+ReadableBuffer: TypeAlias = bytes | bytearray
+
+
+class CompileResult(NamedTuple):
+    code: CodeType | None
+    errors: Sequence[str]
+    warnings: Sequence[str]
+    used_names: Mapping[str, bool]
+
+
 syntax_error_template = (
     'Line {lineno}: {type}: {msg} at statement: {statement!r}')
 
@@ -18,12 +40,13 @@
 
 
 def _compile_restricted_mode(
-        source,
-        filename='<string>',
-        mode="exec",
-        flags=0,
-        dont_inherit=False,
-        policy=RestrictingNodeTransformer):
+        source: str | ReadableBuffer | Module | Expression | Interactive,
+        filename: str | ReadableBuffer | PathLike[Any] = '<string>',
+        mode: Literal["exec", "eval", "single"] = "exec",
+        flags: int = 0,
+        dont_inherit: bool = False,
+        policy: type[NodeTransformer] | None = RestrictingNodeTransformer,
+) -> CompileResult:
 
     if not IS_CPYTHON:
         warnings.warn_explicit(
@@ -39,13 +62,13 @@ def _compile_restricted_mode(
                             dont_inherit=dont_inherit)
     elif issubclass(policy, RestrictingNodeTransformer):
         c_ast = None
-        allowed_source_types = [str, ast.Module]
+        allowed_source_types = [str, Module]
         if not issubclass(type(source), tuple(allowed_source_types)):
             raise TypeError('Not allowed source type: '
                             '"{0.__class__.__name__}".'.format(source))
         c_ast = None
         # workaround for pypy issue https://bitbucket.org/pypy/pypy/issues/2552
-        if isinstance(source, ast.Module):
+        if isinstance(source, Module):
             c_ast = source
         else:
             try:
@@ -78,11 +101,12 @@ def _compile_restricted_mode(
 
 
 def compile_restricted_exec(
-        source,
-        filename='<string>',
-        flags=0,
-        dont_inherit=False,
-        policy=RestrictingNodeTransformer):
+        source: str | ReadableBuffer | Module | Expression | Interactive,
+        filename: str | ReadableBuffer | PathLike[Any] = '<string>',
+        flags: int = 0,
+        dont_inherit: bool = False,
+        policy: type[NodeTransformer] | None = RestrictingNodeTransformer,
+) -> CompileResult:
     """Compile restricted for the mode `exec`."""
     return _compile_restricted_mode(
         source,
@@ -94,11 +118,12 @@ def compile_restricted_exec(
 
 
 def compile_restricted_eval(
-        source,
-        filename='<string>',
-        flags=0,
-        dont_inherit=False,
-        policy=RestrictingNodeTransformer):
+        source: str | ReadableBuffer | Module | Expression | Interactive,
+        filename: str | ReadableBuffer | PathLike[Any] = '<string>',
+        flags: int = 0,
+        dont_inherit: bool = False,
+        policy: type[NodeTransformer] | None = RestrictingNodeTransformer,
+) -> CompileResult:
     """Compile restricted for the mode `eval`."""
     return _compile_restricted_mode(
         source,
@@ -110,11 +135,12 @@ def compile_restricted_eval(
 
 
 def compile_restricted_single(
-        source,
-        filename='<string>',
-        flags=0,
-        dont_inherit=False,
-        policy=RestrictingNodeTransformer):
+        source: str | ReadableBuffer | Module | Expression | Interactive,
+        filename: str | ReadableBuffer | PathLike[Any] = '<string>',
+        flags: int = 0,
+        dont_inherit: bool = False,
+        policy: type[NodeTransformer] | None = RestrictingNodeTransformer,
+) -> CompileResult:
     """Compile restricted for the mode `single`."""
     return _compile_restricted_mode(
         source,
@@ -128,12 +154,13 @@ 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: type[NodeTransformer] | None = RestrictingNodeTransformer,
+) -> CompileResult:
     """Compile a restricted code object for a function.
 
     Documentation see:
@@ -149,7 +176,7 @@ def compile_restricted_function(
             msg=v.msg,
             statement=v.text.strip() if v.text else None)
         return CompileResult(
-            code=None, errors=(error,), warnings=(), used_names=())
+            code=None, errors=(error,), warnings=(), used_names={})
 
     # The compiled code is actually executed inside a function
     # (that is called when the code is called) so reading and assigning to a
@@ -181,12 +208,13 @@ def compile_restricted_function(
 
 
 def compile_restricted(
-        source,
-        filename='<unknown>',
-        mode='exec',
-        flags=0,
-        dont_inherit=False,
-        policy=RestrictingNodeTransformer):
+    source: str | ReadableBuffer | Module | Expression | Interactive,
+    filename: str | ReadableBuffer | PathLike[Any] = '<unknown>',
+    mode: str = 'exec',
+    flags: int = 0,
+    dont_inherit: bool = False,
+    policy: type[NodeTransformer] | None = RestrictingNodeTransformer,
+) -> CodeType:
     """Replacement for the built-in compile() function.
 
     policy ... `ast.NodeTransformer` class defining the restrictions.