xml.etree.ElementTree: use literal type for a more precise return value for tostring() (#3120)

stdlib/2and3/xml/etree/ElementTree.pyi

@@ -1,6 +1,7 @@
 # Stubs for xml.etree.ElementTree
 
-from typing import Any, Callable, Dict, Generator, IO, ItemsView, Iterable, Iterator, KeysView, List, MutableSequence, Optional, overload, Sequence, Text, Tuple, TypeVar, Union, overload
+from typing import Any, Callable, Dict, Generator, IO, ItemsView, Iterable, Iterator, KeysView, List, MutableSequence, Optional, overload, Sequence, Text, Tuple, TypeVar, Union
+from typing_extensions import Literal
 import io
 import sys
 
@@ -26,20 +27,15 @@ _parser_input_type = Union[bytes, Text]
 # there is a 'name' attribute.)
 _str_argument_type = Union[str, Text]
 
-# Type for return values from individual tag/attr/text values and serialization
+# Type for return values from individual tag/attr/text values
 if sys.version_info >= (3,):
     # note: in python3, everything comes out as str, yay:
     _str_result_type = str
-    # unfortunately, tostring and tostringlist can return either bytes or str
-    # depending on the value of `encoding` parameter. Client code knows best:
-    _tostring_result_type = Any
 else:
     # in python2, if the tag/attribute/text wasn't decode-able as ascii, it
     # comes out as a unicode string; otherwise it comes out as str. (see
     # _fixtext function in the source). Client code knows best:
     _str_result_type = Any
-    # On the bright side, tostring and tostringlist always return bytes:
-    _tostring_result_type = bytes
 
 class Element(MutableSequence[Element]):
     tag: _str_result_type
@@ -121,12 +117,22 @@ class ElementTree:
     def write_c14n(self, file: _file_or_filename) -> None: ...
 
 def register_namespace(prefix: _str_argument_type, uri: _str_argument_type) -> None: ...
-if sys.version_info >= (3, 4):
-    def tostring(element: Element, encoding: Optional[str] = ..., method: Optional[str] = ..., *, short_empty_elements: bool = ...) -> _tostring_result_type: ...
-    def tostringlist(element: Element, encoding: Optional[str] = ..., method: Optional[str] = ..., *, short_empty_elements: bool = ...) -> List[_tostring_result_type]: ...
+if sys.version_info >= (3,):
+    @overload
+    def tostring(element: Element, encoding: None = ..., method: Optional[str] = ..., *, short_empty_elements: bool = ...) -> bytes: ...
+    @overload
+    def tostring(element: Element, encoding: Literal["unicode"], method: Optional[str] = ..., *, short_empty_elements: bool = ...) -> str: ...
+    @overload
+    def tostring(element: Element, encoding: str, method: Optional[str] = ..., *, short_empty_elements: bool = ...) -> Any: ...
+    @overload
+    def tostringlist(element: Element, encoding: None = ..., method: Optional[str] = ..., *, short_empty_elements: bool = ...) -> List[bytes]: ...
+    @overload
+    def tostringlist(element: Element, encoding: Literal["unicode"], method: Optional[str] = ..., *, short_empty_elements: bool = ...) -> List[str]: ...
+    @overload
+    def tostringlist(element: Element, encoding: str, method: Optional[str] = ..., *, short_empty_elements: bool = ...) -> List[Any]: ...
 else:
-    def tostring(element: Element, encoding: Optional[str] = ..., method: Optional[str] = ...) -> _tostring_result_type: ...
-    def tostringlist(element: Element, encoding: Optional[str] = ..., method: Optional[str] = ...) -> List[_tostring_result_type]: ...
+    def tostring(element: Element, encoding: Optional[str] = ..., method: Optional[str] = ...) -> bytes: ...
+    def tostringlist(element: Element, encoding: Optional[str] = ..., method: Optional[str] = ...) -> List[bytes]: ...
 def dump(elem: Element) -> None: ...
 def parse(source: _file_or_filename, parser: Optional[XMLParser] = ...) -> ElementTree: ...
 def iterparse(source: _file_or_filename, events: Optional[Sequence[str]] = ..., parser: Optional[XMLParser] = ...) -> Iterator[Tuple[str, Any]]: ...