From 15df17098a947fa38649e43130bb9cba2cb866aa Mon Sep 17 00:00:00 2001
From: Sebastian Rittau <srittau@rittau.biz>
Date: Mon, 22 May 2023 16:40:04 +0200
Subject: [PATCH] [PyYAML] Improve dump/serialize types (#10196)

* Add overloads to return `str` or `bytes`, instead of `Any`.
* Mark some arguments as keyword-only.
* Add missing default values.
---
 stubs/PyYAML/@tests/stubtest_allowlist.txt |   6 +
 stubs/PyYAML/yaml/__init__.pyi             | 352 ++++++++++++++-------
 2 files changed, 238 insertions(+), 120 deletions(-)

diff --git a/stubs/PyYAML/@tests/stubtest_allowlist.txt b/stubs/PyYAML/@tests/stubtest_allowlist.txt
index abc7ed918..50728cc41 100644
--- a/stubs/PyYAML/@tests/stubtest_allowlist.txt
+++ b/stubs/PyYAML/@tests/stubtest_allowlist.txt
@@ -1,2 +1,8 @@
 # yaml._yaml is for backwards compatibility so none of it matters anyway
 yaml._yaml.__test__
+
+# Some arguments to these functions are technically positional or keyword
+# arguments at runtime, but according to the documentation and other,
+# similar functions, it's safer to treat them as keyword-only arguments.
+yaml.dump_all
+yaml.serialize_all
diff --git a/stubs/PyYAML/yaml/__init__.pyi b/stubs/PyYAML/yaml/__init__.pyi
index 14dc7b537..883492c73 100644
--- a/stubs/PyYAML/yaml/__init__.pyi
+++ b/stubs/PyYAML/yaml/__init__.pyi
@@ -1,7 +1,6 @@
 from collections.abc import Callable, Iterable, Iterator, Mapping
 from re import Pattern
 from typing import Any, TypeVar, overload
-from typing_extensions import TypeAlias
 
 from . import resolver as resolver  # Help mypy a bit; this is implied by loader and dumper
 from .constructor import BaseConstructor
@@ -20,9 +19,6 @@ from .representer import BaseRepresenter
 from .resolver import BaseResolver
 from .tokens import *
 
-# FIXME: the functions really return str if encoding is None, otherwise bytes. Waiting for python/mypy#5621
-_Yaml: TypeAlias = Any
-
 _T = TypeVar("_T")
 _Constructor = TypeVar("_Constructor", bound=BaseConstructor)
 _Representer = TypeVar("_Representer", bound=BaseRepresenter)
@@ -58,6 +54,7 @@ def serialize_all(
     nodes,
     stream: _WriteStream[Any],
     Dumper=...,
+    *,
     canonical: bool | None = None,
     indent: int | None = None,
     width: int | _Inf | None = None,
@@ -74,6 +71,41 @@ def serialize_all(
     nodes,
     stream: None = None,
     Dumper=...,
+    *,
+    canonical: bool | None = None,
+    indent: int | None = None,
+    width: int | _Inf | None = None,
+    allow_unicode: bool | None = None,
+    line_break: str | None = None,
+    encoding: None = None,
+    explicit_start: bool | None = None,
+    explicit_end: bool | None = None,
+    version: tuple[int, int] | None = None,
+    tags: Mapping[str, str] | None = None,
+) -> str: ...
+@overload
+def serialize_all(
+    nodes,
+    stream: None = None,
+    Dumper=...,
+    *,
+    canonical: bool | None = None,
+    indent: int | None = None,
+    width: int | _Inf | None = None,
+    allow_unicode: bool | None = None,
+    line_break: str | None = None,
+    encoding: str,
+    explicit_start: bool | None = None,
+    explicit_end: bool | None = None,
+    version: tuple[int, int] | None = None,
+    tags: Mapping[str, str] | None = None,
+) -> bytes: ...
+@overload
+def serialize(
+    node,
+    stream: _WriteStream[Any],
+    Dumper=...,
+    *,
     canonical: bool | None = None,
     indent: int | None = None,
     width: int | _Inf | None = None,
@@ -84,23 +116,6 @@ def serialize_all(
     explicit_end: bool | None = None,
     version: tuple[int, int] | None = None,
     tags: Mapping[str, str] | None = None,
-) -> _Yaml: ...
-@overload
-def serialize(
-    node,
-    stream: _WriteStream[Any],
-    Dumper=...,
-    *,
-    canonical: bool | None = ...,
-    indent: int | None = ...,
-    width: int | _Inf | None = ...,
-    allow_unicode: bool | None = ...,
-    line_break: str | None = ...,
-    encoding: str | None = ...,
-    explicit_start: bool | None = ...,
-    explicit_end: bool | None = ...,
-    version: tuple[int, int] | None = ...,
-    tags: Mapping[str, str] | None = ...,
 ) -> None: ...
 @overload
 def serialize(
@@ -108,22 +123,40 @@ def serialize(
     stream: None = None,
     Dumper=...,
     *,
-    canonical: bool | None = ...,
-    indent: int | None = ...,
-    width: int | _Inf | None = ...,
-    allow_unicode: bool | None = ...,
-    line_break: str | None = ...,
-    encoding: str | None = ...,
-    explicit_start: bool | None = ...,
-    explicit_end: bool | None = ...,
-    version: tuple[int, int] | None = ...,
-    tags: Mapping[str, str] | None = ...,
-) -> _Yaml: ...
+    canonical: bool | None = None,
+    indent: int | None = None,
+    width: int | _Inf | None = None,
+    allow_unicode: bool | None = None,
+    line_break: str | None = None,
+    encoding: None = None,
+    explicit_start: bool | None = None,
+    explicit_end: bool | None = None,
+    version: tuple[int, int] | None = None,
+    tags: Mapping[str, str] | None = None,
+) -> str: ...
+@overload
+def serialize(
+    node,
+    stream: None = None,
+    Dumper=...,
+    *,
+    canonical: bool | None = None,
+    indent: int | None = None,
+    width: int | _Inf | None = None,
+    allow_unicode: bool | None = None,
+    line_break: str | None = None,
+    encoding: str,
+    explicit_start: bool | None = None,
+    explicit_end: bool | None = None,
+    version: tuple[int, int] | None = None,
+    tags: Mapping[str, str] | None = None,
+) -> bytes: ...
 @overload
 def dump_all(
     documents: Iterable[Any],
     stream: _WriteStream[Any],
     Dumper=...,
+    *,
     default_style: str | None = None,
     default_flow_style: bool | None = False,
     canonical: bool | None = None,
@@ -143,6 +176,47 @@ def dump_all(
     documents: Iterable[Any],
     stream: None = None,
     Dumper=...,
+    *,
+    default_style: str | None = None,
+    default_flow_style: bool | None = False,
+    canonical: bool | None = None,
+    indent: int | None = None,
+    width: int | _Inf | None = None,
+    allow_unicode: bool | None = None,
+    line_break: str | None = None,
+    encoding: None = None,
+    explicit_start: bool | None = None,
+    explicit_end: bool | None = None,
+    version: tuple[int, int] | None = None,
+    tags: Mapping[str, str] | None = None,
+    sort_keys: bool = True,
+) -> str: ...
+@overload
+def dump_all(
+    documents: Iterable[Any],
+    stream: None = None,
+    Dumper=...,
+    *,
+    default_style: str | None = None,
+    default_flow_style: bool | None = False,
+    canonical: bool | None = None,
+    indent: int | None = None,
+    width: int | _Inf | None = None,
+    allow_unicode: bool | None = None,
+    line_break: str | None = None,
+    encoding: str,
+    explicit_start: bool | None = None,
+    explicit_end: bool | None = None,
+    version: tuple[int, int] | None = None,
+    tags: Mapping[str, str] | None = None,
+    sort_keys: bool = True,
+) -> bytes: ...
+@overload
+def dump(
+    data: Any,
+    stream: _WriteStream[Any],
+    Dumper=...,
+    *,
     default_style: str | None = None,
     default_flow_style: bool | None = False,
     canonical: bool | None = None,
@@ -156,26 +230,6 @@ def dump_all(
     version: tuple[int, int] | None = None,
     tags: Mapping[str, str] | None = None,
     sort_keys: bool = True,
-) -> _Yaml: ...
-@overload
-def dump(
-    data: Any,
-    stream: _WriteStream[Any],
-    Dumper=...,
-    *,
-    default_style: str | None = ...,
-    default_flow_style: bool | None = ...,
-    canonical: bool | None = ...,
-    indent: int | None = ...,
-    width: int | _Inf | None = ...,
-    allow_unicode: bool | None = ...,
-    line_break: str | None = ...,
-    encoding: str | None = ...,
-    explicit_start: bool | None = ...,
-    explicit_end: bool | None = ...,
-    version: tuple[int, int] | None = ...,
-    tags: Mapping[str, str] | None = ...,
-    sort_keys: bool = ...,
 ) -> None: ...
 @overload
 def dump(
@@ -183,96 +237,154 @@ def dump(
     stream: None = None,
     Dumper=...,
     *,
-    default_style: str | None = ...,
-    default_flow_style: bool | None = ...,
-    canonical: bool | None = ...,
-    indent: int | None = ...,
-    width: int | _Inf | None = ...,
-    allow_unicode: bool | None = ...,
-    line_break: str | None = ...,
-    encoding: str | None = ...,
-    explicit_start: bool | None = ...,
-    explicit_end: bool | None = ...,
-    version: tuple[int, int] | None = ...,
-    tags: Mapping[str, str] | None = ...,
-    sort_keys: bool = ...,
-) -> _Yaml: ...
+    default_style: str | None = None,
+    default_flow_style: bool | None = False,
+    canonical: bool | None = None,
+    indent: int | None = None,
+    width: int | _Inf | None = None,
+    allow_unicode: bool | None = None,
+    line_break: str | None = None,
+    encoding: None = None,
+    explicit_start: bool | None = None,
+    explicit_end: bool | None = None,
+    version: tuple[int, int] | None = None,
+    tags: Mapping[str, str] | None = None,
+    sort_keys: bool = True,
+) -> str: ...
+@overload
+def dump(
+    data: Any,
+    stream: None = None,
+    Dumper=...,
+    *,
+    default_style: str | None = None,
+    default_flow_style: bool | None = False,
+    canonical: bool | None = None,
+    indent: int | None = None,
+    width: int | _Inf | None = None,
+    allow_unicode: bool | None = None,
+    line_break: str | None = None,
+    encoding: str,
+    explicit_start: bool | None = None,
+    explicit_end: bool | None = None,
+    version: tuple[int, int] | None = None,
+    tags: Mapping[str, str] | None = None,
+    sort_keys: bool = True,
+) -> bytes: ...
 @overload
 def safe_dump_all(
     documents: Iterable[Any],
     stream: _WriteStream[Any],
     *,
-    default_style: str | None = ...,
-    default_flow_style: bool | None = ...,
-    canonical: bool | None = ...,
-    indent: int | None = ...,
-    width: int | _Inf | None = ...,
-    allow_unicode: bool | None = ...,
-    line_break: str | None = ...,
-    encoding: str | None = ...,
-    explicit_start: bool | None = ...,
-    explicit_end: bool | None = ...,
-    version: tuple[int, int] | None = ...,
-    tags: Mapping[str, str] | None = ...,
-    sort_keys: bool = ...,
+    default_style: str | None = None,
+    default_flow_style: bool | None = False,
+    canonical: bool | None = None,
+    indent: int | None = None,
+    width: int | _Inf | None = None,
+    allow_unicode: bool | None = None,
+    line_break: str | None = None,
+    encoding: str | None = None,
+    explicit_start: bool | None = None,
+    explicit_end: bool | None = None,
+    version: tuple[int, int] | None = None,
+    tags: Mapping[str, str] | None = None,
+    sort_keys: bool = True,
 ) -> None: ...
 @overload
 def safe_dump_all(
     documents: Iterable[Any],
     stream: None = None,
     *,
-    default_style: str | None = ...,
-    default_flow_style: bool | None = ...,
-    canonical: bool | None = ...,
-    indent: int | None = ...,
-    width: int | _Inf | None = ...,
-    allow_unicode: bool | None = ...,
-    line_break: str | None = ...,
-    encoding: str | None = ...,
-    explicit_start: bool | None = ...,
-    explicit_end: bool | None = ...,
-    version: tuple[int, int] | None = ...,
-    tags: Mapping[str, str] | None = ...,
-    sort_keys: bool = ...,
-) -> _Yaml: ...
+    default_style: str | None = None,
+    default_flow_style: bool | None = False,
+    canonical: bool | None = None,
+    indent: int | None = None,
+    width: int | _Inf | None = None,
+    allow_unicode: bool | None = None,
+    line_break: str | None = None,
+    encoding: None = None,
+    explicit_start: bool | None = None,
+    explicit_end: bool | None = None,
+    version: tuple[int, int] | None = None,
+    tags: Mapping[str, str] | None = None,
+    sort_keys: bool = True,
+) -> str: ...
+@overload
+def safe_dump_all(
+    documents: Iterable[Any],
+    stream: None = None,
+    *,
+    default_style: str | None = None,
+    default_flow_style: bool | None = False,
+    canonical: bool | None = None,
+    indent: int | None = None,
+    width: int | _Inf | None = None,
+    allow_unicode: bool | None = None,
+    line_break: str | None = None,
+    encoding: str,
+    explicit_start: bool | None = None,
+    explicit_end: bool | None = None,
+    version: tuple[int, int] | None = None,
+    tags: Mapping[str, str] | None = None,
+    sort_keys: bool = True,
+) -> bytes: ...
 @overload
 def safe_dump(
     data: Any,
     stream: _WriteStream[Any],
     *,
-    default_style: str | None = ...,
-    default_flow_style: bool | None = ...,
-    canonical: bool | None = ...,
-    indent: int | None = ...,
-    width: int | _Inf | None = ...,
-    allow_unicode: bool | None = ...,
-    line_break: str | None = ...,
-    encoding: str | None = ...,
-    explicit_start: bool | None = ...,
-    explicit_end: bool | None = ...,
-    version: tuple[int, int] | None = ...,
-    tags: Mapping[str, str] | None = ...,
-    sort_keys: bool = ...,
+    default_style: str | None = None,
+    default_flow_style: bool | None = False,
+    canonical: bool | None = None,
+    indent: int | None = None,
+    width: int | _Inf | None = None,
+    allow_unicode: bool | None = None,
+    line_break: str | None = None,
+    encoding: str | None = None,
+    explicit_start: bool | None = None,
+    explicit_end: bool | None = None,
+    version: tuple[int, int] | None = None,
+    tags: Mapping[str, str] | None = None,
+    sort_keys: bool = True,
 ) -> None: ...
 @overload
 def safe_dump(
     data: Any,
     stream: None = None,
     *,
-    default_style: str | None = ...,
-    default_flow_style: bool | None = ...,
-    canonical: bool | None = ...,
-    indent: int | None = ...,
-    width: int | _Inf | None = ...,
-    allow_unicode: bool | None = ...,
-    line_break: str | None = ...,
-    encoding: str | None = ...,
-    explicit_start: bool | None = ...,
-    explicit_end: bool | None = ...,
-    version: tuple[int, int] | None = ...,
-    tags: Mapping[str, str] | None = ...,
-    sort_keys: bool = ...,
-) -> _Yaml: ...
+    default_style: str | None = None,
+    default_flow_style: bool | None = False,
+    canonical: bool | None = None,
+    indent: int | None = None,
+    width: int | _Inf | None = None,
+    allow_unicode: bool | None = None,
+    line_break: str | None = None,
+    encoding: None = None,
+    explicit_start: bool | None = None,
+    explicit_end: bool | None = None,
+    version: tuple[int, int] | None = None,
+    tags: Mapping[str, str] | None = None,
+    sort_keys: bool = True,
+) -> str: ...
+@overload
+def safe_dump(
+    data: Any,
+    stream: None = None,
+    *,
+    default_style: str | None = None,
+    default_flow_style: bool | None = False,
+    canonical: bool | None = None,
+    indent: int | None = None,
+    width: int | _Inf | None = None,
+    allow_unicode: bool | None = None,
+    line_break: str | None = None,
+    encoding: str,
+    explicit_start: bool | None = None,
+    explicit_end: bool | None = None,
+    version: tuple[int, int] | None = None,
+    tags: Mapping[str, str] | None = None,
+    sort_keys: bool = True,
+) -> bytes: ...
 def add_implicit_resolver(
     tag: str,
     regexp: Pattern[str],