yaml.dump(..., stream) is optional (#2289)

Depending on if a "stream" or the "encoding" is given, the functions
either return None, str/unicode or bytes.
Use @overload fix distinguish those cases.

Also fix the functions using **kwds as they delegate their work to the
more generic functions: copy their signatures.

* yaml.dump(): Drop distinguishing encoding

As far as I know it's currently impossible to use "overloads with return
types depending on optional arguments" (Issue #5621). As "encoding" is
in the middle of 11 optional arguments, it would require ~ 2^6 overloads
for each of those 6 functions.

For now just return Any and wait for Issue #5621 to get fixed.

third_party/2and3/yaml/__init__.pyi

@@ -1,4 +1,5 @@
-from typing import Optional, Any, Iterator, Sequence, Union, IO
+from typing import Any, IO, Iterator, Optional, overload, Sequence, Text, Union
+import sys
 from yaml.error import *  # noqa: F403
 from yaml.tokens import *  # noqa: F403
 from yaml.events import *  # noqa: F403
@@ -8,6 +9,13 @@ from yaml.dumper import *  # noqa: F403
 from . import resolver  # Help mypy a bit; this is implied by loader and dumper
 from .cyaml import *
 
+if sys.version_info < (3,):
+    _Str = Union[Text, str]
+else:
+    _Str = str
+# FIXME: the functions really return py2:unicode/py3:str if encoding is None, otherwise py2:str/py3:bytes. Waiting for python/mypy#5621
+_Yaml = Any
+
 __with_libyaml__: Any
 __version__: str
 
@@ -22,12 +30,37 @@ def full_load_all(stream: Union[str, IO[str]]) -> Iterator[Any]: ...
 def safe_load(stream: Union[str, IO[str]]) -> Any: ...
 def safe_load_all(stream: Union[str, IO[str]]) -> Iterator[Any]: ...
 def emit(events, stream=..., Dumper=..., canonical=..., indent=..., width=..., allow_unicode=..., line_break=...): ...
-def serialize_all(nodes, stream=..., Dumper=..., canonical=..., indent=..., width=..., allow_unicode=..., line_break=..., encoding=..., explicit_start=..., explicit_end=..., version=..., tags=...): ...
-def serialize(node, stream=..., Dumper=..., **kwds): ...
-def dump_all(documents: Sequence[Any], stream: IO[str] = ..., Dumper=..., default_style=..., default_flow_style=..., canonical=..., indent=..., width=..., allow_unicode=..., line_break=..., encoding=..., explicit_start=..., explicit_end=..., version=..., tags=...) -> Any: ...
-def dump(data: Any, stream: Optional[IO[str]] = ..., Dumper=..., **kwds) -> Any: ...
-def safe_dump_all(documents: Sequence[Any], stream: IO[str] = ..., **kwds) -> Any: ...
-def safe_dump(data: Any, stream: IO[str] = ..., **kwds) -> Any: ...
+
+@overload
+def serialize_all(nodes, stream: IO[str], Dumper=..., canonical=..., indent=..., width=..., allow_unicode=..., line_break=..., encoding=..., explicit_start=..., explicit_end=..., version=..., tags=...) -> None: ...
+@overload
+def serialize_all(nodes, stream: None = ..., Dumper=..., canonical=..., indent=..., width=..., allow_unicode=..., line_break=..., encoding: Optional[_Str] = ..., explicit_start=..., explicit_end=..., version=..., tags=...) -> _Yaml: ...
+
+@overload
+def serialize(node, stream: IO[str], Dumper=..., canonical=..., indent=..., width=..., allow_unicode=..., line_break=..., encoding=..., explicit_start=..., explicit_end=..., version=..., tags=...) -> None: ...
+@overload
+def serialize(node, stream: None = ..., Dumper=..., canonical=..., indent=..., width=..., allow_unicode=..., line_break=..., encoding: Optional[_Str] = ..., explicit_start=..., explicit_end=..., version=..., tags=...) -> _Yaml: ...
+
+@overload
+def dump_all(documents: Sequence[Any], stream: IO[str], Dumper=..., default_style=..., default_flow_style=..., canonical=..., indent=..., width=..., allow_unicode=..., line_break=..., encoding=..., explicit_start=..., explicit_end=..., version=..., tags=...) -> None: ...
+@overload
+def dump_all(documents: Sequence[Any], stream: None = ..., Dumper=..., default_style=..., default_flow_style=..., canonical=..., indent=..., width=..., allow_unicode=..., line_break=..., encoding: Optional[_Str] = ..., explicit_start=..., explicit_end=..., version=..., tags=...) -> _Yaml: ...
+
+@overload
+def dump(data: Any, stream: IO[str], Dumper=..., default_style=..., default_flow_style=..., canonical=..., indent=..., width=..., allow_unicode=..., line_break=..., encoding=..., explicit_start=..., explicit_end=..., version=..., tags=...) -> None: ...
+@overload
+def dump(data: Any, stream: None = ..., Dumper=..., default_style=..., default_flow_style=..., canonical=..., indent=..., width=..., allow_unicode=..., line_break=..., encoding: Optional[_Str] = ..., explicit_start=..., explicit_end=..., version=..., tags=...) -> _Yaml: ...
+
+@overload
+def save_dump_all(documents: Sequence[Any], stream: IO[str], default_style=..., default_flow_style=..., canonical=..., indent=..., width=..., allow_unicode=..., line_break=..., encoding=..., explicit_start=..., explicit_end=..., version=..., tags=...) -> None: ...
+@overload
+def save_dump_all(documents: Sequence[Any], stream: None = ..., default_style=..., default_flow_style=..., canonical=..., indent=..., width=..., allow_unicode=..., line_break=..., encoding: Optional[_Str] = ..., explicit_start=..., explicit_end=..., version=..., tags=...) -> _Yaml: ...
+
+@overload
+def save_dump(data: Any, stream: IO[str], default_style=..., default_flow_style=..., canonical=..., indent=..., width=..., allow_unicode=..., line_break=..., encoding=..., explicit_start=..., explicit_end=..., version=..., tags=...) -> None: ...
+@overload
+def save_dump(data: Any, stream: None = ..., default_style=..., default_flow_style=..., canonical=..., indent=..., width=..., allow_unicode=..., line_break=..., encoding: Optional[_Str] = ..., explicit_start=..., explicit_end=..., version=..., tags=...) -> _Yaml: ...
+
 def add_implicit_resolver(tag, regexp, first=..., Loader=..., Dumper=...): ...
 def add_path_resolver(tag, path, kind=..., Loader=..., Dumper=...): ...
 def add_constructor(tag, constructor, Loader=...): ...