From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Sun, 5 Aug 2018 17:22:47 +0000 (-0700)
Subject: bpo-34336: Don't promote possibility to leave out typing.Optional (GH-8677)
X-Git-Tag: v3.6.7rc1~125
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=02c4eae35cd24ab71c12b5e61ec22e993ac4839b;p=thirdparty%2FPython%2Fcpython.git

bpo-34336: Don't promote possibility to leave out typing.Optional (GH-8677)

(cherry picked from commit 336c945858055059a65134d4c501a85037d70d99)

Co-authored-by: Ville Skyttä <ville.skytta@iki.fi>
---

diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index bd6f3a95fe62..91d8a5fcf788 100644
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -992,10 +992,18 @@ The module defines the following classes, functions and decorators:
 
    Note that this is not the same concept as an optional argument,
    which is one that has a default.  An optional argument with a
-   default needn't use the ``Optional`` qualifier on its type
-   annotation (although it is inferred if the default is ``None``).
-   A mandatory argument may still have an ``Optional`` type if an
-   explicit value of ``None`` is allowed.
+   default does not require the ``Optional`` qualifier on its type
+   annotation just because it is optional. For example::
+
+      def foo(arg: int = 0) -> None:
+          ...
+
+   On the other hand, if an explicit value of ``None`` is allowed, the
+   use of ``Optional`` is appropriate, whether the argument is optional
+   or not. For example::
+
+      def foo(arg: Optional[int] = None) -> None:
+          ...
 
 .. data:: Tuple