Type Annotations for RestrictedPython

.github/workflows/tests.yml

@@ -25,7 +25,6 @@ jobs:
         config:
         # [Python version, tox env]
         - ["3.11", "release-check"]
-        - ["3.9", "py39"]
         - ["3.10", "py310"]
         - ["3.11", "py311"]
         - ["3.12", "py312"]

.meta.toml

@@ -2,7 +2,7 @@
 # https://github.com/zopefoundation/meta/tree/master/config/pure-python
 [meta]
 template = "pure-python"
-commit-id = "72252845"
+commit-id = "9d049229"
 
 [python]
 with-pypy = false
@@ -11,6 +11,7 @@ with-sphinx-doctests = true
 with-windows = true
 with-future-python = true
 with-macos = false
+oldest-python = "3.10"
 
 [tox]
 use-flake8 = true
@@ -47,7 +48,7 @@ testenv-additional = [
     "    coverage combine",
     "    coverage html",
     "    coverage report -m --fail-under=100",
-    "depends = py39,py310,py311,py311-datetime,py312,py313,py314,coverage",
+    "depends = py310,py311,py311-datetime,py312,py313,py314,coverage",
     ]
 coverage-command = "pytest --cov=src --cov=tests --cov-report= tests {posargs}"
 coverage-setenv = [

.pre-commit-config.yaml

@@ -15,7 +15,7 @@ repos:
     rev: v3.21.0
     hooks:
     - id: pyupgrade
-      args: [--py39-plus]
+      args: [--py310-plus]
   - repo: https://github.com/isidentical/teyit
     rev: 0.4.3
     hooks:

CHANGES.rst

@@ -4,7 +4,9 @@ Changes
 8.2 (unreleased)
 ----------------
 
-- Nothing changed yet.
+- Add type annotations to the package code.
+  For clarification, restricted Python code does not support type annotations.
+
 
 8.1 (2025-10-19)
 ----------------

docs/contributing/index.rst

@@ -241,7 +241,6 @@ Technical Backgrounds - Links to External Documentation
     * `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)
 
   * `AST NodeVistiors Class`_
   * `AST NodeTransformer Class`_

setup.py

@@ -39,18 +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='zope-dev@zope.dev',
+      maintainer='Zope Foundation, Plone Foundation and Contributors',
+      maintainer_email='security@plone.org',
       project_urls={
           "Documentation": "https://restrictedpython.readthedocs.io/",
           "Source": "https://github.com/zopefoundation/RestrictedPython",
@@ -60,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 = ()) -> 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,11 +1,24 @@
+from __future__ import annotations
+
 import ast
 import warnings
+from ast import Expression
+from ast import Interactive
+from ast import Module
+from ast import NodeTransformer
 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 +31,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: NodeTransformer = RestrictingNodeTransformer,
+) -> CompileResult:
 
     if not IS_CPYTHON:
         warnings.warn_explicit(
@@ -39,13 +53,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 +92,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: NodeTransformer = RestrictingNodeTransformer,
+) -> CompileResult:
     """Compile restricted for the mode `exec`."""
     return _compile_restricted_mode(
         source,
@@ -94,11 +109,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: NodeTransformer = RestrictingNodeTransformer,
+) -> CompileResult:
     """Compile restricted for the mode `eval`."""
     return _compile_restricted_mode(
         source,
@@ -110,11 +126,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: NodeTransformer = RestrictingNodeTransformer,
+) -> CompileResult:
     """Compile restricted for the mode `single`."""
     return _compile_restricted_mode(
         source,
@@ -128,12 +145,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: ast.NodeTransformer = RestrictingNodeTransformer,
+) -> CompileResult:
     """Compile a restricted code object for a function.
 
     Documentation see:
@@ -181,12 +199,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: NodeTransformer = RestrictingNodeTransformer,
+) -> CompileResult:
     """Replacement for the built-in compile() function.
 
     policy ... `ast.NodeTransformer` class defining the restrictions.