python · ashishpatel26 · Jun 22, 2026
diff --git a/conformance/results/mypy/generics_defaults.toml b/conformance/results/mypy/generics_defaults.toml
@@ -2,6 +2,8 @@ conformant = "Partial"
 notes = """
 Does not detect a `TypeVar` with a default used after a `TypeVarTuple`.
 Does not fully support defaults on `TypeVarTuple` and `ParamSpec`.
+Incorrectly rejects a valid generic function definition where a TypeVar's
+default matches the default value of the corresponding parameter.
 """
 output = """
 generics_defaults.py:24: error: "T" cannot appear after "DefaultStrT" in type parameter list because it has no default type  [misc]
@@ -13,6 +15,9 @@ generics_defaults.py:177: error: Expression is of type "int", not "Any"  [assert
 generics_defaults.py:203: error: Can only replace ParamSpec with a parameter types list or another ParamSpec, got "str"  [valid-type]
 generics_defaults.py:204: error: Expression is of type "tuple[Any, ...]", not "tuple[int, str]"  [assert-type]
 generics_defaults.py:205: error: Expression is of type "def (*Any, **Any) -> None", not "Callable[[float, bool], None]"  [assert-type]
+generics_defaults.py:239: error: Incompatible default for parameter "default" (default has type "None", parameter has type "S8")  [assignment]
+generics_defaults.py:239: note: PEP 484 prohibits implicit Optional. Accordingly, mypy has changed its default to no_implicit_optional=True
+generics_defaults.py:239: note: Use https://github.com/hauntsaninja/no_implicit_optional to automatically upgrade your codebase
 """
 conformance_automated = "Fail"
 errors_diff = """
@@ -21,4 +26,5 @@ Line 139: Unexpected errors ['generics_defaults.py:139: error: Expression is of
 Line 203: Unexpected errors ['generics_defaults.py:203: error: Can only replace ParamSpec with a parameter types list or another ParamSpec, got "str"  [valid-type]']
 Line 204: Unexpected errors ['generics_defaults.py:204: error: Expression is of type "tuple[Any, ...]", not "tuple[int, str]"  [assert-type]']
 Line 205: Unexpected errors ['generics_defaults.py:205: error: Expression is of type "def (*Any, **Any) -> None", not "Callable[[float, bool], None]"  [assert-type]']
+Line 239: Unexpected errors ['generics_defaults.py:239: error: Incompatible default for parameter "default" (default has type "None", parameter has type "S8")  [assignment]']
 """
diff --git a/conformance/results/results.html b/conformance/results/results.html
diff --git a/conformance/results/ty/generics_defaults.toml b/conformance/results/ty/generics_defaults.toml
@@ -3,6 +3,8 @@ conformant = "Partial"
 notes = """
 Does not forbid a `TypeVar` immediately following a `TypeVarTuple` in a parameter list from having a default.
 Does not support `TypeVarTuple`.
+Incorrectly rejects a valid generic function definition where a TypeVar's
+default matches the default value of the corresponding parameter.
 """
 errors_diff = """
 Line 188: Expected 1 errors
@@ -13,6 +15,7 @@ Line 204: Unexpected errors ['generics_defaults.py:204:5: error[type-assertion-f
 Line 205: Unexpected errors ['generics_defaults.py:205:5: error[type-assertion-failure] Type `@Todo` does not match asserted type `(int | float, bool, /) -> None`']
 Line 207: Unexpected errors ['generics_defaults.py:207:5: error[type-assertion-failure] Type `@Todo` does not match asserted type `tuple[int, str]`']
 Line 208: Unexpected errors ['generics_defaults.py:208:5: error[type-assertion-failure] Type `@Todo` does not match asserted type `(bytes, /) -> None`']
+Line 239: Unexpected errors ['generics_defaults.py:239:19: error[invalid-parameter-default] Default value of type `None` is not assignable to annotated parameter type `S8@get`']
 """
 output = """
 generics_defaults.py:24:40: error[invalid-generic-class] Type parameter `T` without a default cannot follow earlier parameter `DefaultStrT` with a default
@@ -27,4 +30,5 @@ generics_defaults.py:204:5: error[type-assertion-failure] Type `@Todo` does not
 generics_defaults.py:205:5: error[type-assertion-failure] Type `@Todo` does not match asserted type `(int | float, bool, /) -> None`
 generics_defaults.py:207:5: error[type-assertion-failure] Type `@Todo` does not match asserted type `tuple[int, str]`
 generics_defaults.py:208:5: error[type-assertion-failure] Type `@Todo` does not match asserted type `(bytes, /) -> None`
+generics_defaults.py:239:19: error[invalid-parameter-default] Default value of type `None` is not assignable to annotated parameter type `S8@get`
 """
diff --git a/conformance/results/zuban/generics_defaults.toml b/conformance/results/zuban/generics_defaults.toml
@@ -1,5 +1,11 @@
-conformance_automated = "Pass"
+conformant = "Partial"
+notes = """
+Incorrectly rejects a valid generic function definition where a TypeVar's
+default matches the default value of the corresponding parameter.
+"""
+conformance_automated = "Fail"
 errors_diff = """
+Line 239: Unexpected errors ['generics_defaults.py:239: error: Incompatible default for parameter "default" (default has type "None", parameter has type "S8 = None")  [assignment]']
 """
 output = """
 generics_defaults.py:24: error: "T" cannot appear after "DefaultStrT" in type parameter list because it has no default type  [misc]
@@ -8,4 +14,7 @@ generics_defaults.py:152: error: TypeVar default must be a subtype of the bound
 generics_defaults.py:159: error: TypeVar default must be one of the constraint types  [misc]
 generics_defaults.py:177: error: Expression is of type "int", not "Any"  [misc]
 generics_defaults.py:188: error: TypeVar defaults are ambiguous after a TypeVarTuple  [misc]
+generics_defaults.py:239: error: Incompatible default for parameter "default" (default has type "None", parameter has type "S8 = None")  [assignment]
+generics_defaults.py:239: note: PEP 484 prohibits implicit Optional. Accordingly, mypy has changed its default to no_implicit_optional=True
+generics_defaults.py:239: note: Use https://github.com/hauntsaninja/no_implicit_optional to automatically upgrade your codebase
 """
diff --git a/conformance/tests/generics_defaults.py b/conformance/tests/generics_defaults.py
@@ -222,3 +222,27 @@ def meth(self, /) -> Self:
 foo7 = Foo7()
 assert_type(Foo7.meth(foo7), Foo7[int])
 assert_type(Foo7().attr, int)
+
+
+# > When a type parameter ``S`` with default ``D`` is used as the declared type
+# > of exactly one parameter ``p`` and that parameter also has a default
+# > argument value whose type is assignable to ``D``:
+# > 1. The function definition is valid.
+# > 2. A call that omits ``p`` should be type-checked as if ``p`` were passed
+# >    its default value.  Type checkers must infer ``S = D`` in this case.
+
+T8 = TypeVar("T8")
+S8 = TypeVar("S8", default=None)
+
+
+class Getter(Generic[T8]):
+    def get(self, default: S8 = None) -> T8 | S8:  # OK
+        raise NotImplementedError
+
+
+class GetterStr(Getter[str]): ...
+
+
+getter = GetterStr()
+assert_type(getter.get(), str | None)      # S8 = None (omitted → default value)
+assert_type(getter.get(None), str | None)  # S8 = None (explicit)
diff --git a/docs/spec/generics.rst b/docs/spec/generics.rst
@@ -2071,17 +2071,40 @@ Function Defaults
 
 In generic functions, type checkers may use a type parameter's default when the
 type parameter cannot be solved to anything. We leave the semantics of this
-usage unspecified, as ensuring the ``default`` is returned in every code path
-where the type parameter can go unsolved may be too hard to implement. Type
-checkers are free to either disallow this case or experiment with implementing
-support.
+usage unspecified for the general case, as ensuring the ``default`` is returned
+in every code path where the type parameter can go unsolved may be too hard to
+implement. Type checkers are free to either disallow this case or experiment
+with implementing support.
 
 ::
 
    T = TypeVar('T', default=int)
    def func(x: int | set[T]) -> T: ...
    reveal_type(func(0))  # a type checker may reveal T's default of int here
 
+However, a specific and important case **is** specified: when a type parameter
+``S`` with default ``D`` is used as the declared type of exactly one parameter
+``p`` and that parameter also has a default argument value whose type is
+assignable to ``D``, the following rules apply:
+
+1. **Function validity**: the function definition is valid.  The default
+   argument value is checked for assignability against ``D`` (the TypeVar's
+   default), not against the free TypeVar ``S`` itself.
+
+2. **Call-site inference**: a call that omits ``p`` should be type-checked as
+   if ``p`` were passed its default value.  Type checkers must infer ``S = D``
+   in this case.
+
+::
+
+   class Getter[T]:
+       def get[S = None](self, default: S = None) -> T | S: ...  # Valid
+
+   getter: Getter[str]
+   assert_type(getter.get(), str | None)      # S = None (omitted → default value)
+   assert_type(getter.get(None), str | None)  # S = None (explicit)
+   assert_type(getter.get(42), str | int)     # S = int
+
 Defaults following ``TypeVarTuple``
 """""""""""""""""""""""""""""""""""