[3.11] Improve assert_type phrasing (GH-104081) (#104084)

Improve assert_type phrasing (GH-104081)

I'd like to make the fact that this does nothing at runtime
really obvious, since I suspect this is unintuitive for users who are
unfamiliar with static type checking.

I thought of this because of
https://discuss.python.org/t/add-arg-check-type-to-types/26384
wherein I'm skeptical that the user really did want `assert_type`.
(cherry picked from commit 82ba6ce303d04a7b21034e38d220e23ca9f1dc0a)

Co-authored-by: Shantanu <12621235+hauntsaninja@users.noreply.github.com>

diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index 60f49d7029df9f2995dec5ee2308bb89b9804afe..00d74f7dc31e86a03e273ebb129ed9fdc1afd55b 100644 (file)
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -2438,15 +2438,16 @@ Functions and decorators
 
    Ask a static type checker to confirm that *val* has an inferred type of *typ*.
 
-   When the type checker encounters a call to ``assert_type()``, it
+   At runtime this does nothing: it returns the first argument unchanged with no
+   checks or side effects, no matter the actual type of the argument.
+
+   When a static type checker encounters a call to ``assert_type()``, it
    emits an error if the value is not of the specified type::
 
        def greet(name: str) -> None:
            assert_type(name, str)  # OK, inferred type of `name` is `str`
            assert_type(name, int)  # type checker error
 
-   At runtime this returns the first argument unchanged with no side effects.
-
    This function is useful for ensuring the type checker's understanding of a
    script is in line with the developer's intentions::
 

diff --git a/Lib/typing.py b/Lib/typing.py
index 7a50e06035376493682bb02920f7758f52f791dc..2db354017a8b034a4c877f665ca58463aa145875 100644 (file)
--- a/Lib/typing.py
+++ b/Lib/typing.py
@@ -2250,15 +2250,16 @@ def cast(typ, val):
 def assert_type(val, typ, /):
     """Ask a static type checker to confirm that the value is of the given type.
 
-    When the type checker encounters a call to assert_type(), it
+    At runtime this does nothing: it returns the first argument unchanged with no
+    checks or side effects, no matter the actual type of the argument.
+
+    When a static type checker encounters a call to assert_type(), it
     emits an error if the value is not of the specified type::
 
         def greet(name: str) -> None:
             assert_type(name, str)  # ok
             assert_type(name, int)  # type checker error
 
-    At runtime this returns the first argument unchanged and otherwise
-    does nothing.
     """
     return val