From ad529c56c8224712d921a8dba3b9683985c8da04 Mon Sep 17 00:00:00 2001
From: Ivan Levkivskyi <levkivskyi@gmail.com>
Date: Thu, 26 Feb 2026 22:00:44 +0000
Subject: [PATCH] Document semantics of funciton argument redefinition

---
 docs/source/command_line.rst | 12 ++++++++++++
 docs/source/config_file.rst  | 12 ++++++++++++
 2 files changed, 24 insertions(+)

diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst
index 906495d02902c..b1505d7d96687 100644
--- a/docs/source/command_line.rst
+++ b/docs/source/command_line.rst
@@ -631,6 +631,18 @@ of the above sections.
                 # Type of "x" is "str" here.
                 ...
 
+    Function arguments are special, changing their type within function body
+    is allowed even if they are annotated, but that annotation is used to infer
+    types of r.h.s. of all subsequent assignments. Such middle-ground semantics
+    provides good balance for majority of common use cases. For example:
+
+    .. code-block:: python
+
+        def process(values: list[float]) -> None:
+            if not values:
+                values = [0, 0, 0]
+            reveal_type(values)  # Revealed type is list[float]
+
     Note: We are planning to turn this flag on by default in a future mypy
     release, along with :option:`--local-partial-types <mypy --local-partial-types>`.
     The feature is still experimental, and the semantics may still change.
diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst
index 72597728870f9..50f0da62de986 100644
--- a/docs/source/config_file.rst
+++ b/docs/source/config_file.rst
@@ -748,6 +748,18 @@ section of the command line docs.
                 # Type of "x" is "str" here.
                 ...
 
+    Function arguments are special, changing their type within function body
+    is allowed even if they are annotated, but that annotation is used to infer
+    types of r.h.s. of all subsequent assignments. Such middle-ground semantics
+    provides good balance for majority of common use cases. For example:
+
+    .. code-block:: python
+
+        def process(values: list[float]) -> None:
+            if not values:
+                values = [0, 0, 0]
+            reveal_type(values)  # Revealed type is list[float]
+
     Note: We are planning to turn this flag on by default in a future mypy
     release, along with :confval:`local_partial_types`.