[Python-checkins] [3.11] gh-105578: Add more usage examples to `typing.AnyStr` docs (GH-107045) (#107504)

[AlexWaygood]

https://github.com/python/cpython/commit/3de42bbf8cf372b2e6a59bb505b1c2c1544018db
commit: 3de42bbf8cf372b2e6a59bb505b1c2c1544018db
branch: 3.11
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: AlexWaygood <Alex.Waygood at Gmail.com>
date: 2023-07-31T15:33:07Z
summary:

[3.11] gh-105578: Add more usage examples to `typing.AnyStr` docs (GH-107045) (#107504)

gh-105578: Add more usage examples to `typing.AnyStr` docs (GH-107045)

``typing.AnyStr`` has different semantics to ``str | bytes``, which often leads to user confusion
(cherry picked from commit f877b32b879f2076bb1c52826af0c28ebf1aaeed)

Co-authored-by: Michael The <michael-the1 at users.noreply.github.com>

files:
M Doc/library/typing.rst

diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index a0766690bad28..b6bb50b65db62 100644
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -801,6 +801,21 @@ using ``[]``.
       concat(b"foo", b"bar")  # OK, output has type 'bytes'
       concat("foo", b"bar")   # Error, cannot mix str and bytes
 
+   Note that, despite its name, ``AnyStr`` has nothing to do with the
+   :class:`Any` type, nor does it mean "any string". In particular, ``AnyStr``
+   and ``str | bytes`` are different from each other and have different use
+   cases::
+
+      # Invalid use of AnyStr:
+      # The type variable is used only once in the function signature,
+      # so cannot be "solved" by the type checker
+      def greet_bad(cond: bool) -> AnyStr:
+          return "hi there!" if cond else b"greetings!"
+
+      # The better way of annotating this function:
+      def greet_proper(cond: bool) -> str | bytes:
+          return "hi there!" if cond else b"greetings!"
+
 .. data:: LiteralString
 
    Special type that includes only literal strings.