Improve toml typings (#7146)

Co-authored-by: Akuli <akuviljanen17@gmail.com>

stubs/toml/@tests/stubtest_allowlist.txt

@@ -1,5 +0,0 @@
-toml.TomlDecodeError.__init__
-toml.dump
-toml.dumps
-toml.load
-toml.loads

stubs/toml/toml.pyi

@@ -1,19 +0,0 @@
-import sys
-from _typeshed import StrPath, SupportsWrite
-from typing import IO, Any, Mapping, MutableMapping, Text, Union
-
-if sys.version_info >= (3, 6):
-    _PathLike = StrPath
-elif sys.version_info >= (3, 4):
-    import pathlib
-
-    _PathLike = Union[StrPath, pathlib.PurePath]
-else:
-    _PathLike = StrPath
-
-class TomlDecodeError(Exception): ...
-
-def load(f: _PathLike | list[Text] | IO[str], _dict: type[MutableMapping[str, Any]] = ...) -> MutableMapping[str, Any]: ...
-def loads(s: Text, _dict: type[MutableMapping[str, Any]] = ...) -> MutableMapping[str, Any]: ...
-def dump(o: Mapping[str, Any], f: SupportsWrite[str]) -> str: ...
-def dumps(o: Mapping[str, Any]) -> str: ...

stubs/toml/toml/__init__.pyi

@@ -0,0 +1,18 @@
+from . import decoder as decoder, encoder as encoder
+from .decoder import (
+    TomlDecodeError as TomlDecodeError,
+    TomlDecoder as TomlDecoder,
+    TomlPreserveCommentDecoder as TomlPreserveCommentDecoder,
+    load as load,
+    loads as loads,
+)
+from .encoder import (
+    TomlArraySeparatorEncoder as TomlArraySeparatorEncoder,
+    TomlEncoder as TomlEncoder,
+    TomlNumpyEncoder as TomlNumpyEncoder,
+    TomlPathlibEncoder as TomlPathlibEncoder,
+    TomlPreserveCommentEncoder as TomlPreserveCommentEncoder,
+    TomlPreserveInlineDictEncoder as TomlPreserveInlineDictEncoder,
+    dump as dump,
+    dumps as dumps,
+)

stubs/toml/toml/decoder.pyi

@@ -0,0 +1,74 @@
+import sys
+from _typeshed import SupportsRead
+from typing import Any, Callable, Generic, MutableMapping, Pattern, Text, TypeVar, overload
+
+_MutableMappingT = TypeVar("_MutableMappingT", bound=MutableMapping[str, Any])
+
+if sys.version_info >= (3, 0):
+    from pathlib import PurePath
+
+    FNFError = FileNotFoundError
+    _PathLike = str | bytes | PurePath
+else:
+    FNFError = IOError
+    _PathLike = Text
+
+TIME_RE: Pattern[str]
+
+class TomlDecodeError(ValueError):
+    msg: str
+    doc: str
+    pos: int
+    lineno: int
+    colno: int
+    def __init__(self, msg: str, doc: str, pos: int) -> None: ...
+
+class CommentValue:
+    val: Any
+    comment: str
+    def __init__(self, val: Any, comment: str, beginline: bool, _dict: type[MutableMapping[str, Any]]) -> None: ...
+    def __getitem__(self, key: Any) -> Any: ...
+    def __setitem__(self, key: Any, value: Any) -> None: ...
+    def dump(self, dump_value_func: Callable[[Any], str]) -> str: ...
+
+@overload
+def load(
+    f: _PathLike | list[Any] | SupportsRead[Text],  # list[_PathLike] is invariance
+    _dict: type[_MutableMappingT],
+    decoder: TomlDecoder[_MutableMappingT] | None = ...,
+) -> _MutableMappingT: ...
+@overload
+def load(
+    f: _PathLike | list[Any] | SupportsRead[Text],  # list[_PathLike] is invariance
+    _dict: type[dict[str, Any]] = ...,
+    decoder: TomlDecoder[dict[str, Any]] | None = ...,
+) -> dict[str, Any]: ...
+@overload
+def loads(s: Text, _dict: type[_MutableMappingT], decoder: TomlDecoder[_MutableMappingT] | None = ...) -> _MutableMappingT: ...
+@overload
+def loads(s: Text, _dict: type[dict[str, Any]] = ..., decoder: TomlDecoder[dict[str, Any]] | None = ...) -> dict[str, Any]: ...
+
+class InlineTableDict: ...
+
+class TomlDecoder(Generic[_MutableMappingT]):
+    _dict: type[_MutableMappingT]
+    @overload
+    def __init__(self, _dict: type[_MutableMappingT]) -> None: ...
+    @overload
+    def __init__(self: TomlDecoder[dict[str, Any]], _dict: type[dict[str, Any]] = ...) -> None: ...
+    def get_empty_table(self) -> _MutableMappingT: ...
+    def get_empty_inline_table(self) -> InlineTableDict: ...  # incomplete python/typing#213
+    def load_inline_object(
+        self, line: str, currentlevel: _MutableMappingT, multikey: bool = ..., multibackslash: bool = ...
+    ) -> None: ...
+    def load_line(
+        self, line: str, currentlevel: _MutableMappingT, multikey: bool | None, multibackslash: bool
+    ) -> tuple[bool | None, str, bool] | None: ...
+    def load_value(self, v: str, strictly_valid: bool = ...) -> tuple[Any, str]: ...
+    def bounded_string(self, s: str) -> bool: ...
+    def load_array(self, a: str) -> list[Any]: ...
+    def preserve_comment(self, line_no: int, key: str, comment: str, beginline: bool) -> None: ...
+    def embed_comments(self, idx: int, currentlevel: _MutableMappingT) -> None: ...
+
+class TomlPreserveCommentDecoder(TomlDecoder[_MutableMappingT]):
+    saved_comments: dict[int, tuple[str, str, bool]]

stubs/toml/toml/encoder.pyi

@@ -0,0 +1,44 @@
+from _typeshed import SupportsWrite
+from typing import Any, Callable, Generic, Iterable, Mapping, MutableMapping, TypeVar, overload
+
+_MappingT = TypeVar("_MappingT", bound=Mapping[str, Any])
+
+def dump(o: _MappingT, f: SupportsWrite[str], encoder: TomlEncoder[_MappingT] | None = ...) -> str: ...
+def dumps(o: _MappingT, encoder: TomlEncoder[_MappingT] | None = ...) -> str: ...
+
+class TomlEncoder(Generic[_MappingT]):
+    _dict: type[_MappingT]
+    preserve: bool
+    dump_funcs: MutableMapping[type[Any], Callable[[Any], str]]
+    @overload
+    def __init__(self, _dict: type[_MappingT], preserve: bool = ...) -> None: ...
+    @overload
+    def __init__(self: TomlEncoder[dict[str, Any]], _dict: type[dict[str, Any]] = ..., preserve: bool = ...) -> None: ...
+    def get_empty_table(self) -> _MappingT: ...
+    def dump_list(self, v: Iterable[object]) -> str: ...
+    def dump_inline_table(self, section: dict[str, Any] | Any) -> str: ...
+    def dump_value(self, v: Any) -> str: ...
+    def dump_sections(self, o: _MappingT, sup: str) -> tuple[str, _MappingT]: ...
+
+class TomlPreserveInlineDictEncoder(TomlEncoder[_MappingT]):
+    @overload
+    def __init__(self, _dict: type[_MappingT]) -> None: ...
+    @overload
+    def __init__(self: TomlPreserveInlineDictEncoder[dict[str, Any]], _dict: type[dict[str, Any]] = ...) -> None: ...
+
+class TomlArraySeparatorEncoder(TomlEncoder[_MappingT]):
+    separator: str
+    @overload
+    def __init__(self, _dict: type[_MappingT], preserve: bool = ..., separator: str = ...) -> None: ...
+    @overload
+    def __init__(
+        self: TomlArraySeparatorEncoder[dict[str, Any]],
+        _dict: type[dict[str, Any]] = ...,
+        preserve: bool = ...,
+        separator: str = ...,
+    ) -> None: ...
+    def dump_list(self, v: Iterable[Any]) -> str: ...
+
+class TomlNumpyEncoder(TomlEncoder[_MappingT]): ...
+class TomlPreserveCommentEncoder(TomlEncoder[_MappingT]): ...
+class TomlPathlibEncoder(TomlEncoder[_MappingT]): ...

stubs/toml/toml/ordered.pyi

@@ -0,0 +1,11 @@
+from collections import OrderedDict
+from typing import Any
+
+from .decoder import TomlDecoder
+from .encoder import TomlEncoder
+
+class TomlOrderedDecoder(TomlDecoder[OrderedDict[str, Any]]):
+    def __init__(self) -> None: ...
+
+class TomlOrderedEncoder(TomlEncoder[OrderedDict[str, Any]]):
+    def __init__(self) -> None: ...

stubs/toml/toml/tz.pyi

@@ -0,0 +1,10 @@
+from _typeshed import Self
+from datetime import datetime, timedelta, tzinfo
+from typing import Any
+
+class TomlTz(tzinfo):
+    def __init__(self, toml_offset: str) -> None: ...
+    def __deepcopy__(self: Self, memo: Any) -> Self: ...
+    def tzname(self, dt: datetime | None) -> str: ...
+    def utcoffset(self, dt: datetime | None) -> timedelta: ...
+    def dst(self, dt: datetime | None) -> timedelta: ...