Skip to content

Add default argument values to builtin types #14824

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Oct 2, 2025
Merged

Add default argument values to builtin types #14824

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c8663fc
Add default argument values to builtin types
srittau Oct 2, 2025
6be65c8
Change default for float.__new__ to match runtime
srittau Oct 2, 2025
1c7bdfc
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Oct 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
117 changes: 62 additions & 55 deletions stdlib/builtins.pyi
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -252,7 +252,7 @@ _LiteralInteger = _PositiveInteger | _NegativeInteger | Literal[0] # noqa: Y026
@disjoint_base
class int:
@overload
def __new__(cls, x: ConvertibleToInt = ..., /) -> Self: ...
def __new__(cls, x: ConvertibleToInt = 0, /) -> Self: ...
@overload
def __new__(cls, x: str | bytes | bytearray, /, base: SupportsIndex) -> Self: ...
def as_integer_ratio(self) -> tuple[int, Literal[1]]: ...
Expand Down Expand Up @@ -362,7 +362,7 @@ class int:

@disjoint_base
class float:
def __new__(cls, x: ConvertibleToFloat = ..., /) -> Self: ...
def __new__(cls, x: ConvertibleToFloat = 0, /) -> Self: ...
def as_integer_ratio(self) -> tuple[int, int]: ...
def hex(self) -> str: ...
def is_integer(self) -> bool: ...
Expand Down Expand Up @@ -432,8 +432,8 @@ class complex:
@overload
def __new__(
cls,
real: complex | SupportsComplex | SupportsFloat | SupportsIndex = ...,
imag: complex | SupportsFloat | SupportsIndex = ...,
real: complex | SupportsComplex | SupportsFloat | SupportsIndex = 0,
imag: complex | SupportsFloat | SupportsIndex = 0,
) -> Self: ...
@overload
def __new__(cls, real: str | SupportsComplex | SupportsFloat | SupportsIndex | complex) -> Self: ...
Expand Down Expand Up @@ -477,9 +477,9 @@ class _TranslateTable(Protocol):
@disjoint_base
class str(Sequence[str]):
@overload
def __new__(cls, object: object = ...) -> Self: ...
def __new__(cls, object: object = "") -> Self: ...
@overload
def __new__(cls, object: ReadableBuffer, encoding: str = ..., errors: str = ...) -> Self: ...
def __new__(cls, object: ReadableBuffer, encoding: str = "utf-8", errors: str = "strict") -> Self: ...
@overload
def capitalize(self: LiteralString) -> LiteralString: ...
@overload
Expand All @@ -492,22 +492,22 @@ class str(Sequence[str]):
def center(self: LiteralString, width: SupportsIndex, fillchar: LiteralString = " ", /) -> LiteralString: ...
@overload
def center(self, width: SupportsIndex, fillchar: str = " ", /) -> str: ... # type: ignore[misc]
def count(self, sub: str, start: SupportsIndex | None = ..., end: SupportsIndex | None = ..., /) -> int: ...
def count(self, sub: str, start: SupportsIndex | None = None, end: SupportsIndex | None = None, /) -> int: ...
def encode(self, encoding: str = "utf-8", errors: str = "strict") -> bytes: ...
def endswith(
self, suffix: str | tuple[str, ...], start: SupportsIndex | None = ..., end: SupportsIndex | None = ..., /
self, suffix: str | tuple[str, ...], start: SupportsIndex | None = None, end: SupportsIndex | None = None, /
) -> bool: ...
@overload
def expandtabs(self: LiteralString, tabsize: SupportsIndex = 8) -> LiteralString: ...
@overload
def expandtabs(self, tabsize: SupportsIndex = 8) -> str: ... # type: ignore[misc]
def find(self, sub: str, start: SupportsIndex | None = ..., end: SupportsIndex | None = ..., /) -> int: ...
def find(self, sub: str, start: SupportsIndex | None = None, end: SupportsIndex | None = None, /) -> int: ...
@overload
def format(self: LiteralString, *args: LiteralString, **kwargs: LiteralString) -> LiteralString: ...
@overload
def format(self, *args: object, **kwargs: object) -> str: ...
def format_map(self, mapping: _FormatMapMapping, /) -> str: ...
def index(self, sub: str, start: SupportsIndex | None = ..., end: SupportsIndex | None = ..., /) -> int: ...
def index(self, sub: str, start: SupportsIndex | None = None, end: SupportsIndex | None = None, /) -> int: ...
def isalnum(self) -> bool: ...
def isalpha(self) -> bool: ...
def isascii(self) -> bool: ...
Expand Down Expand Up @@ -563,8 +563,8 @@ class str(Sequence[str]):
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 rfind(self, sub: str, start: SupportsIndex | None = None, end: SupportsIndex | None = None, /) -> int: ...
def rindex(self, sub: str, start: SupportsIndex | None = None, end: SupportsIndex | None = None, /) -> int: ...
@overload
def rjust(self: LiteralString, width: SupportsIndex, fillchar: LiteralString = " ", /) -> LiteralString: ...
@overload
Expand All @@ -590,7 +590,7 @@ class str(Sequence[str]):
@overload
def splitlines(self, keepends: bool = False) -> list[str]: ... # type: ignore[misc]
def startswith(
self, prefix: str | tuple[str, ...], start: SupportsIndex | None = ..., end: SupportsIndex | None = ..., /
self, prefix: str | tuple[str, ...], start: SupportsIndex | None = None, end: SupportsIndex | None = None, /
) -> bool: ...
@overload
def strip(self: LiteralString, chars: LiteralString | None = None, /) -> LiteralString: ...
Expand Down Expand Up @@ -664,29 +664,29 @@ class bytes(Sequence[int]):
@overload
def __new__(cls, o: Iterable[SupportsIndex] | SupportsIndex | SupportsBytes | ReadableBuffer, /) -> Self: ...
@overload
def __new__(cls, string: str, /, encoding: str, errors: str = ...) -> Self: ...
def __new__(cls, string: str, /, encoding: str, errors: str = "strict") -> Self: ...
@overload
def __new__(cls) -> Self: ...
def capitalize(self) -> bytes: ...
def center(self, width: SupportsIndex, fillchar: bytes = b" ", /) -> bytes: ...
def count(
self, sub: ReadableBuffer | SupportsIndex, start: SupportsIndex | None = ..., end: SupportsIndex | None = ..., /
self, sub: ReadableBuffer | SupportsIndex, start: SupportsIndex | None = None, end: SupportsIndex | None = None, /
) -> int: ...
def decode(self, encoding: str = "utf-8", errors: str = "strict") -> str: ...
def endswith(
self,
suffix: ReadableBuffer | tuple[ReadableBuffer, ...],
start: SupportsIndex | None = ...,
end: SupportsIndex | None = ...,
start: SupportsIndex | None = None,
end: SupportsIndex | None = None,
/,
) -> bool: ...
def expandtabs(self, tabsize: SupportsIndex = 8) -> bytes: ...
def find(
self, sub: ReadableBuffer | SupportsIndex, start: SupportsIndex | None = ..., end: SupportsIndex | None = ..., /
self, sub: ReadableBuffer | SupportsIndex, start: SupportsIndex | None = None, end: SupportsIndex | None = None, /
) -> int: ...
def hex(self, sep: str | bytes = ..., bytes_per_sep: SupportsIndex = ...) -> str: ...
def hex(self, sep: str | bytes = ..., bytes_per_sep: SupportsIndex = 1) -> str: ...
def index(
self, sub: ReadableBuffer | SupportsIndex, start: SupportsIndex | None = ..., end: SupportsIndex | None = ..., /
self, sub: ReadableBuffer | SupportsIndex, start: SupportsIndex | None = None, end: SupportsIndex | None = None, /
) -> int: ...
def isalnum(self) -> bool: ...
def isalpha(self) -> bool: ...
Expand All @@ -705,10 +705,10 @@ class bytes(Sequence[int]):
def removeprefix(self, prefix: ReadableBuffer, /) -> bytes: ...
def removesuffix(self, suffix: ReadableBuffer, /) -> bytes: ...
def rfind(
self, sub: ReadableBuffer | SupportsIndex, start: SupportsIndex | None = ..., end: SupportsIndex | None = ..., /
self, sub: ReadableBuffer | SupportsIndex, start: SupportsIndex | None = None, end: SupportsIndex | None = None, /
) -> int: ...
def rindex(
self, sub: ReadableBuffer | SupportsIndex, start: SupportsIndex | None = ..., end: SupportsIndex | None = ..., /
self, sub: ReadableBuffer | SupportsIndex, start: SupportsIndex | None = None, end: SupportsIndex | None = None, /
) -> int: ...
def rjust(self, width: SupportsIndex, fillchar: bytes | bytearray = b" ", /) -> bytes: ...
def rpartition(self, sep: ReadableBuffer, /) -> tuple[bytes, bytes, bytes]: ...
Expand All @@ -719,8 +719,8 @@ class bytes(Sequence[int]):
def startswith(
self,
prefix: ReadableBuffer | tuple[ReadableBuffer, ...],
start: SupportsIndex | None = ...,
end: SupportsIndex | None = ...,
start: SupportsIndex | None = None,
end: SupportsIndex | None = None,
/,
) -> bool: ...
def strip(self, bytes: ReadableBuffer | None = None, /) -> bytes: ...
Expand Down Expand Up @@ -765,30 +765,30 @@ class bytearray(MutableSequence[int]):
@overload
def __init__(self, ints: Iterable[SupportsIndex] | SupportsIndex | ReadableBuffer, /) -> None: ...
@overload
def __init__(self, string: str, /, encoding: str, errors: str = ...) -> None: ...
def __init__(self, string: str, /, encoding: str, errors: str = "strict") -> None: ...
def append(self, item: SupportsIndex, /) -> None: ...
def capitalize(self) -> bytearray: ...
def center(self, width: SupportsIndex, fillchar: bytes = b" ", /) -> bytearray: ...
def count(
self, sub: ReadableBuffer | SupportsIndex, start: SupportsIndex | None = ..., end: SupportsIndex | None = ..., /
self, sub: ReadableBuffer | SupportsIndex, start: SupportsIndex | None = None, end: SupportsIndex | None = None, /
) -> int: ...
def copy(self) -> bytearray: ...
def decode(self, encoding: str = "utf-8", errors: str = "strict") -> str: ...
def endswith(
self,
suffix: ReadableBuffer | tuple[ReadableBuffer, ...],
start: SupportsIndex | None = ...,
end: SupportsIndex | None = ...,
start: SupportsIndex | None = None,
end: SupportsIndex | None = None,
/,
) -> bool: ...
def expandtabs(self, tabsize: SupportsIndex = 8) -> bytearray: ...
def extend(self, iterable_of_ints: Iterable[SupportsIndex], /) -> None: ...
def find(
self, sub: ReadableBuffer | SupportsIndex, start: SupportsIndex | None = ..., end: SupportsIndex | None = ..., /
self, sub: ReadableBuffer | SupportsIndex, start: SupportsIndex | None = None, end: SupportsIndex | None = None, /
) -> int: ...
def hex(self, sep: str | bytes = ..., bytes_per_sep: SupportsIndex = ...) -> str: ...
def hex(self, sep: str | bytes = ..., bytes_per_sep: SupportsIndex = 1) -> str: ...
def index(
self, sub: ReadableBuffer | SupportsIndex, start: SupportsIndex | None = ..., end: SupportsIndex | None = ..., /
self, sub: ReadableBuffer | SupportsIndex, start: SupportsIndex | None = None, end: SupportsIndex | None = None, /
) -> int: ...
def insert(self, index: SupportsIndex, item: SupportsIndex, /) -> None: ...
def isalnum(self) -> bool: ...
Expand All @@ -810,10 +810,10 @@ class bytearray(MutableSequence[int]):
def removesuffix(self, suffix: ReadableBuffer, /) -> bytearray: ...
def replace(self, old: ReadableBuffer, new: ReadableBuffer, count: SupportsIndex = -1, /) -> bytearray: ...
def rfind(
self, sub: ReadableBuffer | SupportsIndex, start: SupportsIndex | None = ..., end: SupportsIndex | None = ..., /
self, sub: ReadableBuffer | SupportsIndex, start: SupportsIndex | None = None, end: SupportsIndex | None = None, /
) -> int: ...
def rindex(
self, sub: ReadableBuffer | SupportsIndex, start: SupportsIndex | None = ..., end: SupportsIndex | None = ..., /
self, sub: ReadableBuffer | SupportsIndex, start: SupportsIndex | None = None, end: SupportsIndex | None = None, /
) -> int: ...
def rjust(self, width: SupportsIndex, fillchar: bytes | bytearray = b" ", /) -> bytearray: ...
def rpartition(self, sep: ReadableBuffer, /) -> tuple[bytearray, bytearray, bytearray]: ...
Expand All @@ -824,8 +824,8 @@ class bytearray(MutableSequence[int]):
def startswith(
self,
prefix: ReadableBuffer | tuple[ReadableBuffer, ...],
start: SupportsIndex | None = ...,
end: SupportsIndex | None = ...,
start: SupportsIndex | None = None,
end: SupportsIndex | None = None,
/,
) -> bool: ...
def strip(self, bytes: ReadableBuffer | None = None, /) -> bytearray: ...
Expand Down Expand Up @@ -939,7 +939,7 @@ class memoryview(Sequence[_I]):
def tolist(self) -> list[int]: ...
def toreadonly(self) -> memoryview: ...
def release(self) -> None: ...
def hex(self, sep: str | bytes = ..., bytes_per_sep: SupportsIndex = ...) -> str: ...
def hex(self, sep: str | bytes = ..., bytes_per_sep: SupportsIndex = 1) -> str: ...
def __buffer__(self, flags: int, /) -> memoryview: ...
def __release_buffer__(self, buffer: memoryview, /) -> None: ...

Expand All @@ -952,7 +952,7 @@ class memoryview(Sequence[_I]):

@final
class bool(int):
def __new__(cls, o: object = ..., /) -> Self: ...
def __new__(cls, o: object = False, /) -> Self: ...
# The following overloads could be represented more elegantly with a TypeVar("_B", bool, int),
# however mypy has a bug regarding TypeVar constraints (https://github.com/python/mypy/issues/11880).
@overload
Expand Down Expand Up @@ -1025,7 +1025,7 @@ class slice(Generic[_StartT_co, _StopT_co, _StepT_co]):

@disjoint_base
class tuple(Sequence[_T_co]):
def __new__(cls, iterable: Iterable[_T_co] = ..., /) -> Self: ...
def __new__(cls, iterable: Iterable[_T_co] = (), /) -> Self: ...
def __len__(self) -> int: ...
def __contains__(self, key: object, /) -> bool: ...
@overload
Expand Down Expand Up @@ -1325,7 +1325,7 @@ class range(Sequence[int]):
@overload
def __new__(cls, stop: SupportsIndex, /) -> Self: ...
@overload
def __new__(cls, start: SupportsIndex, stop: SupportsIndex, step: SupportsIndex = ..., /) -> Self: ...
def __new__(cls, start: SupportsIndex, stop: SupportsIndex, step: SupportsIndex = 1, /) -> Self: ...
def count(self, value: int, /) -> int: ...
def index(self, value: int, /) -> int: ... # type: ignore[override]
def __len__(self) -> int: ...
Expand All @@ -1350,10 +1350,10 @@ class property:

def __init__(
self,
fget: Callable[[Any], Any] | None = ...,
fset: Callable[[Any, Any], None] | None = ...,
fdel: Callable[[Any], None] | None = ...,
doc: str | None = ...,
fget: Callable[[Any], Any] | None = None,
fset: Callable[[Any, Any], None] | None = None,
fdel: Callable[[Any], None] | None = None,
doc: str | None = None,
) -> None: ...
def getter(self, fget: Callable[[Any], Any], /) -> property: ...
def setter(self, fset: Callable[[Any, Any], None], /) -> property: ...
Expand Down Expand Up @@ -1940,18 +1940,25 @@ def vars(object: Any = ..., /) -> dict[str, Any]: ...
class zip(Generic[_T_co]):
if sys.version_info >= (3, 10):
@overload
def __new__(cls, *, strict: bool = ...) -> zip[Any]: ...
def __new__(cls, *, strict: bool = False) -> zip[Any]: ...
@overload
def __new__(cls, iter1: Iterable[_T1], /, *, strict: bool = ...) -> zip[tuple[_T1]]: ...
def __new__(cls, iter1: Iterable[_T1], /, *, strict: bool = False) -> zip[tuple[_T1]]: ...
@overload
def __new__(cls, iter1: Iterable[_T1], iter2: Iterable[_T2], /, *, strict: bool = ...) -> zip[tuple[_T1, _T2]]: ...
def __new__(cls, iter1: Iterable[_T1], iter2: Iterable[_T2], /, *, strict: bool = False) -> zip[tuple[_T1, _T2]]: ...
@overload
def __new__(
cls, iter1: Iterable[_T1], iter2: Iterable[_T2], iter3: Iterable[_T3], /, *, strict: bool = ...
cls, iter1: Iterable[_T1], iter2: Iterable[_T2], iter3: Iterable[_T3], /, *, strict: bool = False
) -> zip[tuple[_T1, _T2, _T3]]: ...
@overload
def __new__(
cls, iter1: Iterable[_T1], iter2: Iterable[_T2], iter3: Iterable[_T3], iter4: Iterable[_T4], /, *, strict: bool = ...
cls,
iter1: Iterable[_T1],
iter2: Iterable[_T2],
iter3: Iterable[_T3],
iter4: Iterable[_T4],
/,
*,
strict: bool = False,
) -> zip[tuple[_T1, _T2, _T3, _T4]]: ...
@overload
def __new__(
Expand All @@ -1963,7 +1970,7 @@ class zip(Generic[_T_co]):
iter5: Iterable[_T5],
/,
*,
strict: bool = ...,
strict: bool = False,
) -> zip[tuple[_T1, _T2, _T3, _T4, _T5]]: ...
@overload
def __new__(
Expand All @@ -1976,7 +1983,7 @@ class zip(Generic[_T_co]):
iter6: Iterable[Any],
/,
*iterables: Iterable[Any],
strict: bool = ...,
strict: bool = False,
) -> zip[tuple[Any, ...]]: ...
else:
@overload
Expand Down Expand Up @@ -2090,8 +2097,8 @@ class AssertionError(Exception): ...
if sys.version_info >= (3, 10):
@disjoint_base
class AttributeError(Exception):
def __init__(self, *args: object, name: str | None = ..., obj: object = ...) -> None: ...
name: str
def __init__(self, *args: object, name: str | None = None, obj: object = None) -> None: ...
name: str | None
obj: object

else:
Expand All @@ -2102,7 +2109,7 @@ class EOFError(Exception): ...

@disjoint_base
class ImportError(Exception):
def __init__(self, *args: object, name: str | None = ..., path: str | None = ...) -> None: ...
def __init__(self, *args: object, name: str | None = None, path: str | None = None) -> None: ...
name: str | None
path: str | None
msg: str # undocumented
Expand All @@ -2115,8 +2122,8 @@ class MemoryError(Exception): ...
if sys.version_info >= (3, 10):
@disjoint_base
class NameError(Exception):
def __init__(self, *args: object, name: str | None = ...) -> None: ...
name: str
def __init__(self, *args: object, name: str | None = None) -> None: ...
name: str | None

else:
class NameError(Exception): ...
Expand Down