PEP 671: Describe the WIP reference implementation

pep-0671.rst

@@ -140,9 +140,50 @@ Open Issues
   function definition.
 
 
+Implementation details
+======================
+
+The following relates to the reference implementation, and is not necessarily
+part of the specification.
+
+An **argument default**, rather than being an arbitrary value, is now a tuple
+of 1-2 values. The first value is descriptive text and may be ``None``; the
+compiler is free to put the source code for the default here, or None, on any
+basis. (The reference implementation omits them from early-bound defaults, and
+retains them for late-bound ones.) If there is a second value, it is an early
+bound default value and will be used as the function parameter when none is
+given.
+
+When there is no second value in the tuple, and the parameter is omitted, the
+function will begin with the parameter unbound. The function begins by testing
+for each parameter with a late-bound default, and if unbound, evaluates the
+original expression.
+
+Inspecting the function (eg ``help()``) will use the provided description
+where available, falling back on the repr of the value, or if there is none,
+report "=> <calculated>".
+
+Costs
+-----
+
+Every function default argument must now be wrapped in a tuple. This adds 56
+bytes (CPython 3.11, 64-bit Linux), but where the same value is used in many
+places (eg ``None``), this tuple can be shared.
+
+Mapping arguments to parameters incurs the cost of tuple unpacking.
+
+Constructing functions manually using FunctionType requires additional checks.
+
+Backward incompatibility
+------------------------
+
+Inspecting ``spam.__defaults__`` shows a tuple of tuples rather than a tuple
+of values. Similarly, ``spam.__kwdefaults__`` is a dict of tuples.
+
 References
 ==========
 
+https://github.com/rosuav/cpython/tree/pep-671
 
 Copyright
 =========