Add PEP 675 LiteralString overloads to str class (#7725)

Co-authored-by: Sebastian Rittau <srittau@rittau.biz> Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
2025-12-08 21:14:48 +08:00 · 2022-05-31 21:09:34 -07:00
parent e8f20bbb56
commit 8c434e05d6
1 changed files with 123 additions and 31 deletions
--- a/stdlib/builtins.pyi
+++ b/stdlib/builtins.pyi
@@ -53,7 +53,7 @@ from typing import (  # noqa: Y027
    TypeVar,
    overload,
 )
-from typing_extensions import Literal, SupportsIndex, TypeAlias, TypeGuard, final
+from typing_extensions import Literal, LiteralString, SupportsIndex, TypeAlias, TypeGuard, final

 if sys.version_info >= (3, 9):
    from types import GenericAlias
@@ -399,21 +399,39 @@ class str(Sequence[str]):
    def __new__(cls: type[Self], object: object = ...) -> Self: ...
    @overload
    def __new__(cls: type[Self], object: ReadableBuffer, encoding: str = ..., errors: str = ...) -> Self: ...
-    def capitalize(self) -> str: ...
-    def casefold(self) -> str: ...
-    def center(self, __width: SupportsIndex, __fillchar: str = ...) -> str: ...
+    @overload
+    def capitalize(self: LiteralString) -> LiteralString: ...
+    @overload
+    def capitalize(self) -> str: ...  # type: ignore[misc]
+    @overload
+    def casefold(self: LiteralString) -> LiteralString: ...
+    @overload
+    def casefold(self) -> str: ...  # type: ignore[misc]
+    @overload
+    def center(self: LiteralString, __width: SupportsIndex, __fillchar: LiteralString = ...) -> LiteralString: ...
+    @overload
+    def center(self, __width: SupportsIndex, __fillchar: str = ...) -> str: ...  # type: ignore[misc]
    def count(self, x: str, __start: SupportsIndex | None = ..., __end: SupportsIndex | None = ...) -> int: ...
    def encode(self, encoding: str = ..., errors: str = ...) -> bytes: ...
    def endswith(
        self, __suffix: str | tuple[str, ...], __start: SupportsIndex | None = ..., __end: SupportsIndex | None = ...
    ) -> bool: ...
    if sys.version_info >= (3, 8):
-        def expandtabs(self, tabsize: SupportsIndex = ...) -> str: ...
+        @overload
+        def expandtabs(self: LiteralString, tabsize: SupportsIndex = ...) -> LiteralString: ...
+        @overload
+        def expandtabs(self, tabsize: SupportsIndex = ...) -> str: ...  # type: ignore[misc]
    else:
-        def expandtabs(self, tabsize: int = ...) -> str: ...
+        @overload
+        def expandtabs(self: LiteralString, tabsize: int = ...) -> LiteralString: ...
+        @overload
+        def expandtabs(self, tabsize: int = ...) -> str: ...  # type: ignore[misc]

    def find(self, __sub: str, __start: SupportsIndex | None = ..., __end: SupportsIndex | None = ...) -> int: ...
-    def format(self, *args: object, **kwargs: object) -> str: ...
+    @overload
+    def format(self: LiteralString, *args: LiteralString, **kwargs: LiteralString) -> LiteralString: ...
+    @overload
+    def format(self, *args: object, **kwargs: object) -> str: ...  # type: ignore[misc]
    def format_map(self, map: _FormatMapMapping) -> str: ...
    def index(self, __sub: str, __start: SupportsIndex | None = ..., __end: SupportsIndex | None = ...) -> int: ...
    def isalnum(self) -> bool: ...
@@ -430,40 +448,102 @@ class str(Sequence[str]):
    def isspace(self) -> bool: ...
    def istitle(self) -> bool: ...
    def isupper(self) -> bool: ...
-    def join(self, __iterable: Iterable[str]) -> str: ...
-    def ljust(self, __width: SupportsIndex, __fillchar: str = ...) -> str: ...
-    def lower(self) -> str: ...
-    def lstrip(self, __chars: str | None = ...) -> str: ...
-    def partition(self, __sep: str) -> tuple[str, str, str]: ...
-    def replace(self, __old: str, __new: str, __count: SupportsIndex = ...) -> str: ...
+    @overload
+    def join(self: LiteralString, __iterable: Iterable[LiteralString]) -> LiteralString: ...
+    @overload
+    def join(self, __iterable: Iterable[str]) -> str: ...  # type: ignore[misc]
+    @overload
+    def ljust(self: LiteralString, __width: SupportsIndex, __fillchar: LiteralString = ...) -> LiteralString: ...
+    @overload
+    def ljust(self, __width: SupportsIndex, __fillchar: str = ...) -> str: ...  # type: ignore[misc]
+    @overload
+    def lower(self: LiteralString) -> LiteralString: ...
+    @overload
+    def lower(self) -> str: ...  # type: ignore[misc]
+    @overload
+    def lstrip(self: LiteralString, __chars: LiteralString | None = ...) -> LiteralString: ...
+    @overload
+    def lstrip(self, __chars: str | None = ...) -> str: ...  # type: ignore[misc]
+    @overload
+    def partition(self: LiteralString, __sep: LiteralString) -> tuple[LiteralString, LiteralString, LiteralString]: ...
+    @overload
+    def partition(self, __sep: str) -> tuple[str, str, str]: ...  # type: ignore[misc]
+    @overload
+    def replace(
+        self: LiteralString, __old: LiteralString, __new: LiteralString, __count: SupportsIndex = ...
+    ) -> LiteralString: ...
+    @overload
+    def replace(self, __old: str, __new: str, __count: SupportsIndex = ...) -> str: ...  # type: ignore[misc]
    if sys.version_info >= (3, 9):
-        def removeprefix(self, __prefix: str) -> str: ...
-        def removesuffix(self, __suffix: str) -> str: ...
+        @overload
+        def removeprefix(self: LiteralString, __prefix: LiteralString) -> LiteralString: ...
+        @overload
+        def removeprefix(self, __prefix: str) -> str: ...  # type: ignore[misc]
+        @overload
+        def removesuffix(self: LiteralString, __suffix: LiteralString) -> LiteralString: ...
+        @overload
+        def removesuffix(self, __suffix: str) -> str: ...  # type: ignore[misc]

    def rfind(self, __sub: str, __start: SupportsIndex | None = ..., __end: SupportsIndex | None = ...) -> int: ...
    def rindex(self, __sub: str, __start: SupportsIndex | None = ..., __end: SupportsIndex | None = ...) -> int: ...
-    def rjust(self, __width: SupportsIndex, __fillchar: str = ...) -> str: ...
-    def rpartition(self, __sep: str) -> tuple[str, str, str]: ...
-    def rsplit(self, sep: str | None = ..., maxsplit: SupportsIndex = ...) -> list[str]: ...
-    def rstrip(self, __chars: str | None = ...) -> str: ...
-    def split(self, sep: str | None = ..., maxsplit: SupportsIndex = ...) -> list[str]: ...
-    def splitlines(self, keepends: bool = ...) -> list[str]: ...
+    @overload
+    def rjust(self: LiteralString, __width: SupportsIndex, __fillchar: LiteralString = ...) -> LiteralString: ...
+    @overload
+    def rjust(self, __width: SupportsIndex, __fillchar: str = ...) -> str: ...  # type: ignore[misc]
+    @overload
+    def rpartition(self: LiteralString, __sep: LiteralString) -> tuple[LiteralString, LiteralString, LiteralString]: ...
+    @overload
+    def rpartition(self, __sep: str) -> tuple[str, str, str]: ...  # type: ignore[misc]
+    @overload
+    def rsplit(self: LiteralString, sep: LiteralString | None = ..., maxsplit: SupportsIndex = ...) -> list[LiteralString]: ...
+    @overload
+    def rsplit(self, sep: str | None = ..., maxsplit: SupportsIndex = ...) -> list[str]: ...  # type: ignore[misc]
+    @overload
+    def rstrip(self: LiteralString, __chars: LiteralString | None = ...) -> LiteralString: ...
+    @overload
+    def rstrip(self, __chars: str | None = ...) -> str: ...  # type: ignore[misc]
+    @overload
+    def split(self: LiteralString, sep: LiteralString | None = ..., maxsplit: SupportsIndex = ...) -> list[LiteralString]: ...
+    @overload
+    def split(self, sep: str | None = ..., maxsplit: SupportsIndex = ...) -> list[str]: ...  # type: ignore[misc]
+    @overload
+    def splitlines(self: LiteralString, keepends: bool = ...) -> list[LiteralString]: ...
+    @overload
+    def splitlines(self, keepends: bool = ...) -> list[str]: ...  # type: ignore[misc]
    def startswith(
        self, __prefix: str | tuple[str, ...], __start: SupportsIndex | None = ..., __end: SupportsIndex | None = ...
    ) -> bool: ...
-    def strip(self, __chars: str | None = ...) -> str: ...
-    def swapcase(self) -> str: ...
-    def title(self) -> str: ...
+    @overload
+    def strip(self: LiteralString, __chars: LiteralString | None = ...) -> LiteralString: ...
+    @overload
+    def strip(self, __chars: str | None = ...) -> str: ...  # type: ignore[misc]
+    @overload
+    def swapcase(self: LiteralString) -> LiteralString: ...
+    @overload
+    def swapcase(self) -> str: ...  # type: ignore[misc]
+    @overload
+    def title(self: LiteralString) -> LiteralString: ...
+    @overload
+    def title(self) -> str: ...  # type: ignore[misc]
    def translate(self, __table: Mapping[int, int | str | None] | Sequence[int | str | None]) -> str: ...
-    def upper(self) -> str: ...
-    def zfill(self, __width: SupportsIndex) -> str: ...
+    @overload
+    def upper(self: LiteralString) -> LiteralString: ...
+    @overload
+    def upper(self) -> str: ...  # type: ignore[misc]
+    @overload
+    def zfill(self: LiteralString, __width: SupportsIndex) -> LiteralString: ...
+    @overload
+    def zfill(self, __width: SupportsIndex) -> str: ...  # type: ignore[misc]
    @staticmethod
    @overload
    def maketrans(__x: dict[int, _T] | dict[str, _T] | dict[str | int, _T]) -> dict[int, _T]: ...
    @staticmethod
    @overload
    def maketrans(__x: str, __y: str, __z: str | None = ...) -> dict[int, int | None]: ...
-    def __add__(self, __s: str) -> str: ...
+    @overload
+    def __add__(self: LiteralString, __s: LiteralString) -> LiteralString: ...
+    @overload
+    def __add__(self, __s: str) -> str: ...  # type: ignore[misc]
    # Incompatible with Sequence.__contains__
    def __contains__(self, __o: str) -> bool: ...  # type: ignore[override]
    def __eq__(self, __x: object) -> bool: ...
@@ -471,14 +551,26 @@ class str(Sequence[str]):
    def __getitem__(self, __i: SupportsIndex | slice) -> str: ...
    def __gt__(self, __x: str) -> bool: ...
    def __hash__(self) -> int: ...
-    def __iter__(self) -> Iterator[str]: ...
+    @overload
+    def __iter__(self: LiteralString) -> Iterator[LiteralString]: ...
+    @overload
+    def __iter__(self) -> Iterator[str]: ...  # type: ignore[misc]
    def __le__(self, __x: str) -> bool: ...
    def __len__(self) -> int: ...
    def __lt__(self, __x: str) -> bool: ...
-    def __mod__(self, __x: Any) -> str: ...
-    def __mul__(self, __n: SupportsIndex) -> str: ...
+    @overload
+    def __mod__(self: LiteralString, __x: LiteralString | tuple[LiteralString, ...]) -> LiteralString: ...
+    @overload
+    def __mod__(self, __x: Any) -> str: ...  # type: ignore[misc]
+    @overload
+    def __mul__(self: LiteralString, __n: SupportsIndex) -> LiteralString: ...
+    @overload
+    def __mul__(self, __n: SupportsIndex) -> str: ...  # type: ignore[misc]
    def __ne__(self, __x: object) -> bool: ...
-    def __rmul__(self, __n: SupportsIndex) -> str: ...
+    @overload
+    def __rmul__(self: LiteralString, __n: SupportsIndex) -> LiteralString: ...
+    @overload
+    def __rmul__(self, __n: SupportsIndex) -> str: ...  # type: ignore[misc]
    def __getnewargs__(self) -> tuple[str]: ...

 class bytes(ByteString):