[Python-checkins] cpython (merge 3.5 -> default): Add docs for typing.AnyStr and typing.Text. By Michael Lee. (Merge 3.5->3.6)

Mon Aug 15 18:08:29 EDT 2016

https://hg.python.org/cpython/rev/705416c5909e
changeset: 102672:705416c5909e
parent: 102671:247ecbae325c
parent: 102670:d5872d0863c8
user: Guido van Rossum <guido at dropbox.com>
date: Mon Aug 15 15:08:11 2016 -0700
summary:
 Add docs for typing.AnyStr and typing.Text. By Michael Lee. (Merge 3.5->3.6)
files:
 Doc/library/typing.rst | 27 +++++++++++++++++++++++++++
 1 files changed, 27 insertions(+), 0 deletions(-)

diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -652,6 +652,33 @@
 yield start
 start += 1
 
+.. class:: AnyStr
+
+ ``AnyStr`` is a type variable defined as
+ ``AnyStr = TypeVar('AnyStr', str, bytes)``.
+
+ It is meant to be used for functions that may accept any kind of string
+ without allowing different kinds of strings to mix. For example::
+
+ def concat(a: AnyStr, b: AnyStr) -> AnyStr:
+ return a + b
+
+ concat(u"foo", u"bar") # Ok, output has type 'unicode'
+ concat(b"foo", b"bar") # Ok, output has type 'bytes'
+ concat(u"foo", b"bar") # Error, cannot mix unicode and bytes
+
+.. class:: Text
+
+ ``Text`` is an alias for ``str``. It is provided to supply a forward
+ compatible path for Python 2 code: in Python 2, ``Text`` is an alias for
+ ``unicode``.
+
+ Use ``Text`` to indicate that a value must contain a unicode string in
+ a manner that is compatible with both Python 2 and Python 3::
+
+ def add_unicode_checkmark(text: Text) -> Text:
+ return text + u' \u2713'
+
 .. class:: io
 
 Wrapper namespace for I/O stream types.
-- 
Repository URL: https://hg.python.org/cpython
