Document use of ... in overloads (python#10772)

Stannislav · Jul 7, 2021 · cdb2685 · cdb2685
1 parent f137f11
commit cdb2685
Showing 1 changed file with 19 additions and 0 deletions.
diff --git a/docs/source/more_types.rst b/docs/source/more_types.rst
@@ -295,6 +295,25 @@ return type by using overloads like so:
    subtypes, you can use a :ref:`value restriction
    <type-variable-value-restriction>`.
 
+The default values of a function's arguments don't affect its signature, only
+the absence or presence of a default value does. So in order to reduce
+redundancy it's possible to replace default values in overload definitions with
+`...` as a placeholder.
+
+.. code-block:: python
+
+    from typing import overload
+
+    class M: ...
+
+    @overload
+    def get_model(model_or_pk: M, flag: bool = ...) -> M: ...
+    @overload
+    def get_model(model_or_pk: int, flag: bool = ...) -> M | None: ...
+
+    def get_model(model_or_pk: int | M, flag: bool = True) -> M | None:
+        ...
+
 
 Runtime behavior
 ----------------