From 93557b380886177f86869b22993eba6bcef5edfe Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Sun, 9 Jun 2024 05:52:48 -0600 Subject: [PATCH] PEP 749: Add note on signature of __annotate__ (#3831) --- peps/pep-0749.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/peps/pep-0749.rst b/peps/pep-0749.rst index 70404fbc6..11fc3f3b8 100644 --- a/peps/pep-0749.rst +++ b/peps/pep-0749.rst @@ -540,6 +540,24 @@ an instance of a private stringizer class is used instead of ``ForwardRef``. After evaluation completes, the implementation of the FORWARDREF format converts these internal objects into ``ForwardRef`` objects. +Signature of ``__annotate__`` functions +--------------------------------------- + +:pep:`649` specifies the signature of ``__annotate__`` functions as: + + ``__annotate__(format: int) -> dict`` + +However, using ``format`` as a parameter name could lead to collisions +if an annotation uses a class named ``format``. The parameter should be +positional-only and have a name that cannot be a legal identifier in order +to avoid this problem. + +The current implementation uses the name ``.format`` with a leading +dot, but the exact name should be considered an implementation detail +and cannot be relied upon. + +The documentation may still use the name ``format`` for simplicity. + Backwards Compatibility =======================