8000 stdlib: more deprecations (#11009) · python/typeshed@bba8cbd · GitHub
[go: up one dir, main page]
Skip to content

Commit bba8cbd

Browse files
JelleZijlstraAlexWaygood
JelleZijlstra
and
AlexWaygood
authored
stdlib: more deprecations (#11009)
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
1 parent 46b2635 commit bba8cbd

File tree

13 files changed

+119
-28
lines changed

13 files changed

+119
-28
lines changed

‎stdlib/argparse.pyi

Lines changed: 27 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ from _typeshed import sentinel
33
from collections.abc import Callable, Generator, Iterable, Sequence
44
from re import Pattern
55
from typing import IO, Any, Generic, Literal, NewType, NoReturn, Protocol, TypeVar, overload
6-
from typing_extensions import Self, TypeAlias
6+
from typing_extensions import Self, TypeAlias, deprecated
77

88
__all__ = [
99
"ArgumentParser",
@@ -339,11 +339,23 @@ class Action(_AttributeHolder):
339339

340340
if sys.version_info >= (3, 12):
341341
class BooleanOptionalAction(Action):
342+
@overload
342343
def __init__(
343344
self,
344345
option_strings: Sequence[str],
345346
dest: str,
346-
default: _T | str | None = None,
347+
default: bool | None = None,
348+
*,
349+
required: bool = False,
350+
help: str | None = None,
351+
) -> None: ...
352+
@overload
353+
@deprecated("The `type`, `choices`, and `metavar` parameters are ignored and will be removed in Python 3.14.")
354+
def __init__(
355+
self,
356+
option_strings: Sequence[str],
357+
dest: str,
358+
default: _T | bool | None = None,
347359
type: Callable[[str], _T] | FileType | None = sentinel,
348360
choices: Iterable[_T] | None = sentinel,
349361
required: bool = False,
@@ -353,11 +365,23 @@ if sys.version_info >= (3, 12):
353365

354366
elif sys.version_info >= (3, 9):
355367
class BooleanOptionalAction(Action):
368+
@overload
369+
def __init__(
370+
self,
371+
option_strings: Sequence[str],
372+
dest: str,
373+
default: bool | None = None,
374+
*,
375+
required: bool = False,
376+
help: str | None = None,
377+
) -> None: ...
378+
@overload
379+
@deprecated("The `type`, `choices`, and `metavar` parameters are ignored and will be removed in Python 3.14.")
356380
def __init__(
357381
self,
358382
option_strings: Sequence[str],
359383
dest: str,
360-
default: _T | str | None = None,
384+
default: _T | bool | None = None,
361385
type: Callable[[str], _T] | FileType | None = None,
362386
choices: Iterable[_T] | None = None,
363387
required: bool = False,

‎stdlib/asyncio/events.pyi

Lines changed: 12 additions & 4 deletions
def new_event_loop(self) -> AbstractEventLoop: ...
Original file line numberDiff line numberDiff line change
@@ -543,10 +543,18 @@ class AbstractEventLoopPolicy:
543543
@abstractmethod
544544
545545
# Child processes handling (Unix only).
546-
@abstractmethod
547-
def get_child_watcher(self) -> AbstractChildWatcher: ...
548-
@abstractmethod
549-
def set_child_watcher(self, watcher: AbstractChildWatcher) -> None: ...
546+
if sys.version_info >= (3, 12):
547+
@abstractmethod
548+
@deprecated("Deprecated as of Python 3.12; will be removed in Python 3.14")
549+
def get_child_watcher(self) -> AbstractChildWatcher: ...
550+
@abstractmethod
551+
@deprecated("Deprecated as of Python 3.12; will be removed in Python 3.14")
552+
def set_child_watcher(self, watcher: AbstractChildWatcher) -> None: ...
553+
else:
554+
@abstractmethod
555+
def get_child_watcher(self) -> AbstractChildWatcher: ...
556+
@abstractmethod
557+
def set_child_watcher(self, watcher: AbstractChildWatcher) -> None: ...
550558

551559
class BaseDefaultEventLoopPolicy(AbstractEventLoopPolicy, metaclass=ABCMeta):
552560
def get_event_loop(self) -> AbstractEventLoop: ...

‎stdlib/datetime.pyi

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ import sys
22
from abc import abstractmethod
33
from time import struct_time
44
from typing import ClassVar, Literal, NamedTuple, NoReturn, SupportsIndex, TypeVar, final, overload
5-
from typing_extensions import Self, TypeAlias
5+
from typing_extensions import Self, TypeAlias, deprecated
66

77
if sys.version_info >= (3, 11):
88
__all__ = ("date", "datetime", "time", "timedelta", "timezone", "tzinfo", "MINYEAR", "MAXYEAR", "UTC")
@@ -251,10 +251,12 @@ class datetime(date):
251251
def fromtimestamp(cls, __timestamp: float, tz: _TzInfo | None = ...) -> Self: ...
252252

253253
@classmethod
254+
@deprecated("Use timezone-aware objects to represent datetimes in UTC; e.g. by calling .fromtimestamp(datetime.UTC)")
254255
def utcfromtimestamp(cls, __t: float) -> Self: ...
255256
@ 10000 classmethod
256257
def now(cls, tz: _TzInfo | None = None) -> Self: ...
257258
@classmethod
259+
@deprecated("Use timezone-aware objects to represent datetimes in UTC; e.g. by calling .now(datetime.UTC)")
258260
def utcnow(cls) -> Self: ...
259261
@classmethod
260262
def combine(cls, date: _Date, time: _Time, tzinfo: _TzInfo | None = ...) -> Self: ...

‎stdlib/email/utils.pyi

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ from _typeshed import Unused
44
from email import _ParamType
55
from email.charset import Charset
66
from typing import overload
7-
from typing_extensions import TypeAlias
7+
from typing_extensions import TypeAlias, deprecated
88

99
__all__ = [
1010
"collapse_rfc2231_value",
@@ -54,6 +54,10 @@ def formatdate(timeval: float | None = None, localtime: bool = False, usegmt: bo
5454
def format_datetime(dt: datetime.datetime, usegmt: bool = False) -> str: ...
5555

5656
if sys.version_info >= (3, 12):
57+
@overload
58+
def localtime(dt: datetime.datetime | None = None) -> datetime.datetime: ...
59+
@overload
60+
@deprecated("The `isdst` parameter does nothing and will be removed in Python 3.14.")
5761
def localtime(dt: datetime.datetime | None = None, isdst: Unused = None) -> datetime.datetime: ...
5862

5963
else:

‎stdlib/os/__init__.pyi

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ from typing import (
4040
overload,
4141
runtime_checkable,
4242
)
43-
from typing_extensions import Self, TypeAlias, Unpack
43+
from typing_extensions import Self, TypeAlias, Unpack, deprecated
4444

4545
from . import path as _path
4646< 4 /td> 10BC0

@@ -361,8 +361,16 @@ class stat_result(structseq[float], tuple[int, int, int, int, int, int, int, flo
361361
@property
362362
def st_mtime(self) -> float: ... # time of most recent content modification,
363363
# platform dependent (time of most recent metadata change on Unix, or the time of creation on Windows)
364-
@property
365-
def st_ctime(self) -> float: ...
364+
if sys.version_info >= (3, 12) and sys.platform == "win32":
365+
@property
366+
@deprecated(
367+
"Use st_birthtime instead to retrieve the file creation time. In the future, this property will contain the last metadata change time."
368+
)
369+
def st_ctime(self) -> float: ...
370+
else:
371+
@property
372+
def st_ctime(self) -> float: ...
373+
366374
@property
367375
def st_atime_ns(self) -> int: ... # time of most recent access, in nanoseconds
368376
@property

‎stdlib/shutil.pyi

Lines changed: 5 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ from _typeshed import BytesPath, FileDescriptorOrPath, StrOrBytesPath, StrPath,
44
from collections.abc import Callable, Iterable, Sequence
55
from tarfile import _TarfileFilter
66
from typing import Any, AnyStr, NamedTuple, Protocol, TypeVar, overload
7-
from typing_extensions import TypeAlias
7+
from typing_extensions import TypeAlias, deprecated
88

99
__all__ = [
1010
"copyfileobj",
@@ -78,24 +78,20 @@ class _RmtreeType(Protocol):
7878
avoids_symlink_attacks: bool
7979
if sys.version_info >= (3, 12):
8080
@overload
81+
def __call__(self, path: StrOrBytesPath, ignore_errors: bool = False, *, dir_fd: int | None = None) -> None: ...
82+
@overload
83+
@deprecated("The `onerror` parameter is deprecated and will be removed in Python 3.14. Use `onexc` instead.")
8184
def __call__(
8285
self,
8386
path: StrOrBytesPath,
8487
ignore_errors: bool = False,
8588
onerror: _OnErrorCallback | None = None,
8689
*,
87-
onexc: None = None,
8890
dir_fd: int | None = None,
8991
) -> None: ...
9092
@overload
9193
def __call__(
92-
self,
93-
path: StrOrBytesPath,
94-
ignore_errors: bool = False,
95-
onerror: None = None,
96-
*,
97-
onexc: _OnExcCallback,
98-
dir_fd: int | None = None,
94+
self, path: StrOrBytesPath, ignore_errors: bool = False, *, onexc: _OnExcCallback, dir_fd: int | None = None
9995
) -> None: ...
10096
elif sys.version_info >= (3, 11):
10197
def __call__(

‎stdlib/tarfile.pyi

Lines changed: 30 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ from collections.abc import Callable, Iterable, Iterator, Mapping
77
from gzip import _ReadableFileobj as _GzipReadableFileobj, _WritableFileobj as _GzipWritableFileobj
88
from types import TracebackType
99
from typing import IO, ClassVar, Literal, Protocol, overload
10-
from typing_extensions import Self, TypeAlias
10+
from typing_extensions import Self, TypeAlias, deprecated
1111

1212
__all__ = [
1313
"TarFile",
@@ -292,22 +292,49 @@ class TarFile:
292292
def getnames(self) -> _list[str]: ...
293293
def list(self, verbose: bool = True, *, members: _list[TarInfo] | None = None) -> None: ...
294294
def next(self) -> TarInfo | None: ...
295+
@overload
296+
@deprecated(
297+
"Extracting tar archives without specifying `filter` is deprecated until Python 3.14, when 'data' filter will become the default."
298+
)
299+
def extractall(
300+
self,
301+
path: StrOrBytesPath = ".",
302+
members: Iterable[TarInfo] | None = None,
303+
*,
304+
numeric_owner: bool = False,
305+
filter: None = ...,
306+
) -> None: ...
307+
@overload
295308
def extractall(
296309
self,
297310
path: StrOrBytesPath = ".",
298311
members: Iterable[TarInfo] | None = None,
299312
*,
300313
numeric_owner: bool = False,
301-
filter: _TarfileFilter | None = ...,
314+
filter: _TarfileFilter,
302315
) -> None: ...
316+
@overload
317+
@deprecated(
318+
"Extracting tar archives without specifying `filter` is deprecated until Python 3.14, when 'data' filter will become the default."
319+
)
320+
def extract(
321+
self,
322+
member: str | TarInfo,
323+
path: StrOrBytesPath = "",
324+
set_attrs: bool = True,
325+
*,
326+
numeric_owner: bool = False,
327+
filter: None = ...,
328+
) -> None: ...
329+
@overload
303330
def extract(
304331
self,
305332
member: str | TarInfo,
306333
path: StrOrBytesPath = "",
307334
set_attrs: bool = True,
308335
*,
309336
numeric_owner: bool = False,
310-
filter: _TarfileFilter | None = ...,
337+
filter: _TarfileFilter,
311338
) -> None: ...
312339
def _extract_member(
313340
self, tarinfo: TarInfo, targetpath: str, set_attrs: bool = True, numeric_owner: bool = False

‎stdlib/types.pyi

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ from importlib.machinery import ModuleSpec
1717

1818
# pytype crashes if types.MappingProxyType inherits from collections.abc.Mapping instead of typing.Mapping
1919
from typing import Any, ClassVar, Literal, Mapping, Protocol, TypeVar, final, overload # noqa: Y022
20-
from typing_extensions import ParamSpec, Self, TypeVarTuple
20+
from typing_extensions import ParamSpec, Self, TypeVarTuple, deprecated
2121

2222
__all__ = [
2323
"FunctionType",
@@ -138,8 +138,14 @@ class CodeType:
138138
def co_name(self) -> str: ...
139139
@property
140140
def co_firstlineno(self) -> int: ...
141-
@property
142-
def co_lnotab(self) -> bytes: ...
141+
if sys.version_info >= (3, 10):
142+
@property
143+
@deprecated("Will be removed in Python 3.14. Use the co_lines() method instead.")
144+
def co_lnotab(self) -> bytes: ...
145+
else:
146+
@property
147+
def co_lnotab(self) -> bytes: ...
148+
143149
@property
144150
def co_freevars(self) -> tuple[str, ...]: ...
145151
@property

‎stdlib/xml/etree/ElementTree.pyi

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ from _collections_abc import dict_keys
33
from _typeshed import FileDescriptorOrPath, ReadableBuffer, SupportsRead, SupportsWrite
44
from collections.abc import Callable, Generator, ItemsView, Iterable, Iterator, Mapping, Sequence
55
from typing import Any, Literal, SupportsIndex, TypeVar, overload
6-
from typing_extensions import TypeAlias, TypeGuard
6+
from typing_extensions import TypeAlias, TypeGuard, deprecated
77

88
__all__ = [
99
"C14NWriterTarget",
@@ -121,6 +121,10 @@ class Element:
121121
def __setitem__(self, __key: SupportsIndex, __value: Element) -> None: ...
122122
@overload
123123
def __setitem__(self, __key: slice, __value: Iterable[Element]) -> None: ...
124+
125+
# Doesn't really exist in earlier versions, where __len__ is called implicitly instead
126+
@deprecated("Testing an element's truth value is deprecated.")
127+
def __bool__(self) -> bool: ...
124128
if sys.version_info < (3, 9):
125129
def getchildren(self) -> list[Element]: ...
126130
def getiterator(self, tag: str | None = None) -> list[Element]: ...

‎tests/stubtest_allowlists/py310.txt

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,9 @@ typing._SpecialForm.__mro_entries__
2525
weakref.ProxyType.__reversed__ # Doesn't really exist
2626
builtins.ellipsis # type is not exposed anywhere
2727

28+
xml.etree.ElementTree.Element.__bool__ # Doesn't really exist; see comments in stub
29+
xml.etree.cElementTree.Element.__bool__ # Doesn't really exist; see comments in stub
30+
2831
# Runtime definition of protocol is incorrect
2932
importlib.metadata._meta.SimplePath.__truediv__
3033
importlib.metadata._meta.SimplePath.joinpath

‎tests/stubtest_allowlists/py311.txt

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,9 @@ tkinter._VersionInfoType.__doc__
1818
typing.NewType.__mro_entries__
1919
builtins.ellipsis # type is not exposed anywhere
2020

21+
xml.etree.ElementTree.Element.__bool__ # Doesn't really exist; see comments in stub
22+
xml.etree.cElementTree.Element.__bool__ # Doesn't really exist; see comments in stub
23+
2124
# Runtime definition of protocol is incorrect
2225
importlib.metadata._meta.SimplePath.__truediv__
2326
importlib.metadata._meta.SimplePath.joinpath

‎tests/stubtest_allowlists/py38.txt

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,9 @@ xml.etree.ElementTree.TreeBuilder.start # Discrepancy between Python and C modu
5252
xml.etree.cElementTree.TreeBuilder.start # bpo-39495
5353
xxsubtype # module missing from the stubs
5454 AC3F

55+
xml.etree.ElementTree.Element.__bool__ # Doesn't really exist; see comments in stub
56+
xml.etree.cElementTree.Element.__bool__ # Doesn't really exist; see comments in stub
57+
5558
# Exist at runtime for internal reasons, no need to put them in the stub
5659
typing_extensions\.TypeAliasType\.__call__
5760
typing_extensions\.TypeAliasType\.__init_subclass__

‎tests/stubtest_allowlists/py39.txt

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,9 @@ types.GenericAlias.__call__ # Would be complicated to fix properly, Any could s
3939
weakref.ProxyType.__reversed__ # Doesn't really exist
4040
xxsubtype # module missing from the stubs
4141

42+
xml.etree.ElementTree.Element.__bool__ # Doesn't really exist; see comments in stub
43+
xml.etree.cElementTree.Element.__bool__ # Doesn't really exist; see comments in stub
44+
4245
# Exist at runtime for internal reasons, no need to put them in the stub
4346
typing_extensions\.TypeAliasType\.__call__
4447
typing_extensions\.TypeAliasType\.__init_subclass__

0 commit comments

Comments
 (0)
0