Merge branch 'main' into restrict-compile-filename

Author: Sachaa-Thanasius

CONTRIBUTING.md

@@ -436,28 +436,24 @@ following criteria is met:
 * the upstream package was declared or appears to be unmaintained, and
   retaining the stubs causes maintenance issues in typeshed.
 
-If a package ships its own `py.typed` file, please follow these steps:
+Case 1: If a package ships its own `py.typed` file, please follow these steps:
 
-1. Open an issue with the earliest month of removal in the subject.
-2. A maintainer will add the
-   ["stubs: removal" label](https://github.com/python/typeshed/labels/%22stubs%3A%20removal%22).
-3. Open a PR that sets the `obsolete_since` field in the `METADATA.toml`
-   file to the first version of the package that shipped `py.typed`.
-4. After at least six months, open a PR to remove the stubs.
+1. Make sure **stubsabot** open a PR that sets the `obsolete_since` field in the
+   `METADATA.toml` file to the first version of the package that shipped `py.typed`.
+2. After at least six months, make sure **stubsabot** open a PR to remove the stubs.
 
-If third-party stubs should be removed for other reasons, please follow these
-steps:
+Case 2: If third-party stubs should be removed for other reasons, please follow
+these steps:
 
 1. Open an issue explaining why the stubs should be removed.
 2. A maintainer will add the
    ["stubs: removal" label](https://github.com/python/typeshed/labels/%22stubs%3A%20removal%22).
 3. Open a PR that sets the `no_longer_updated` field in the `METADATA.toml`
    file to `true`.
-4. When a new version of the package was automatically uploaded to PyPI
-   (which can take up to a day), open a PR to remove the stubs.
+4. When a new version of the package was automatically uploaded to PyPI (which
+   can take up to a day), make sure **stubsabot** open a PR to remove the stubs.
 
-Don't forget to make sure the library is not in the [`pyrightconfig.stricter.json`](./pyrightconfig.stricter.json)
-exclusion list. If feeling kindly, please update [mypy](https://github.com/python/mypy/blob/master/mypy/stubinfo.py)
+If feeling kindly, please update [mypy](https://github.com/python/mypy/blob/master/mypy/stubinfo.py)
 for any stub obsoletions or removals.
 
 ### Marking PRs as "deferred"

stdlib/@tests/test_cases/check_SupportsGetItem.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from _typeshed import SupportsDunderGT, SupportsDunderLT, SupportsGetItem
+from collections.abc import Callable
+from operator import itemgetter
+from typing import Any, TypeVar
+from typing_extensions import assert_type
+
+_T = TypeVar("_T")
+
+
+# This should be equivalent to itemgetter().__call__
+def standalone_call(obj: SupportsGetItem[Any, _T]) -> _T: ...
+
+
+# Expected type of itemgetter(1).__call__
+expected_type_itemgetter_call: Callable[[SupportsGetItem[int, _T]], _T]  # pyright: ignore[reportGeneralTypeIssues]
+
+# Expecting itemgetter(1) to be assignable to this
+# based on the example below: min({"first": 1, "second": 2}.items(), key=itemgetter(1))
+# That example and assigning to this variable are what failed in https://github.com/python/mypy/issues/14032
+expected_assignable_to: Callable[[tuple[str, int]], SupportsDunderLT[Any] | SupportsDunderGT[Any]]
+
+
+# Regression tests for https://github.com/python/mypy/issues/14032
+# assert_type(itemgetter("first")({"first": 1, "second": 2}), int) # See comment on itemgetter.__call__
+assert_type(min({"first": 1, "second": 2}, key=itemgetter(1)), str)
+assert_type(min({"first": 1, "second": 2}.items(), key=itemgetter(1)), tuple[str, int])
+assert_type(standalone_call({"first": 1, "second": 2}), int)
+assert_type(min({"first": 1, "second": 2}, key=standalone_call), str)
+assert_type(min({"first": 1, "second": 2}.items(), key=standalone_call), tuple[str, int])
+
+expected_itemgetter_call_type = itemgetter(1).__call__
+expected_itemgetter_call_type = itemgetter(1)
+expected_assignable_to = itemgetter(1)
+
+expected_itemgetter_call_type = standalone_call
+expected_assignable_to = standalone_call

stdlib/operator.pyi

@@ -205,8 +205,10 @@ class itemgetter(Generic[_T_co]):
     #   "tuple[int, int]" is incompatible with protocol "SupportsIndex"
     # preventing [_T_co, ...] instead of [Any, ...]
     #
-    # A suspected mypy issue prevents using [..., _T] instead of [..., Any] here.
-    # https://github.com/python/mypy/issues/14032
+    # If we can't infer a literal key from __new__ (ie: `itemgetter[Literal[0]]` for `itemgetter(0)`),
+    # then we can't annotate __call__'s return type or it'll break on tuples
+    #
+    # These issues are best demonstrated by the `itertools.check_itertools_recipes.unique_justseen` test.
     def __call__(self, obj: SupportsGetItem[Any, Any]) -> Any: ...
 
 @final

stdlib/types.pyi

@@ -65,7 +65,7 @@ if sys.version_info >= (3, 13):
 
 _T1 = TypeVar("_T1")
 _T2 = TypeVar("_T2")
-_KT = TypeVar("_KT")
+_KT_co = TypeVar("_KT_co", covariant=True)
 _VT_co = TypeVar("_VT_co", covariant=True)
 
 # Make sure this class definition stays roughly in line with `builtins.function`
@@ -309,27 +309,27 @@ class CodeType:
         __replace__ = replace
 
 @final
-class MappingProxyType(Mapping[_KT, _VT_co]):
+class MappingProxyType(Mapping[_KT_co, _VT_co]):  # type: ignore[type-var]  # pyright: ignore[reportInvalidTypeArguments]
     __hash__: ClassVar[None]  # type: ignore[assignment]
-    def __new__(cls, mapping: SupportsKeysAndGetItem[_KT, _VT_co]) -> Self: ...
-    def __getitem__(self, key: _KT, /) -> _VT_co: ...
-    def __iter__(self) -> Iterator[_KT]: ...
+    def __new__(cls, mapping: SupportsKeysAndGetItem[_KT_co, _VT_co]) -> Self: ...
+    def __getitem__(self, key: _KT_co, /) -> _VT_co: ...  # type: ignore[misc]  # pyright: ignore[reportGeneralTypeIssues]
+    def __iter__(self) -> Iterator[_KT_co]: ...
     def __len__(self) -> int: ...
     def __eq__(self, value: object, /) -> bool: ...
-    def copy(self) -> dict[_KT, _VT_co]: ...
-    def keys(self) -> KeysView[_KT]: ...
+    def copy(self) -> dict[_KT_co, _VT_co]: ...
+    def keys(self) -> KeysView[_KT_co]: ...
     def values(self) -> ValuesView[_VT_co]: ...
-    def items(self) -> ItemsView[_KT, _VT_co]: ...
+    def items(self) -> ItemsView[_KT_co, _VT_co]: ...
     @overload
-    def get(self, key: _KT, /) -> _VT_co | None: ...
+    def get(self, key: _KT_co, /) -> _VT_co | None: ...  # type: ignore[misc]  # pyright: ignore[reportGeneralTypeIssues] # Covariant type as parameter
     @overload
-    def get(self, key: _KT, default: _VT_co, /) -> _VT_co: ...  # type: ignore[misc] # pyright: ignore[reportGeneralTypeIssues] # Covariant type as parameter
+    def get(self, key: _KT_co, default: _VT_co, /) -> _VT_co: ...  # type: ignore[misc] # pyright: ignore[reportGeneralTypeIssues] # Covariant type as parameter
     @overload
-    def get(self, key: _KT, default: _T2, /) -> _VT_co | _T2: ...
+    def get(self, key: _KT_co, default: _T2, /) -> _VT_co | _T2: ...  # type: ignore[misc]  # pyright: ignore[reportGeneralTypeIssues] # Covariant type as parameter
     def __class_getitem__(cls, item: Any, /) -> GenericAlias: ...
-    def __reversed__(self) -> Iterator[_KT]: ...
-    def __or__(self, value: Mapping[_T1, _T2], /) -> dict[_KT | _T1, _VT_co | _T2]: ...
-    def __ror__(self, value: Mapping[_T1, _T2], /) -> dict[_KT | _T1, _VT_co | _T2]: ...
+    def __reversed__(self) -> Iterator[_KT_co]: ...
+    def __or__(self, value: Mapping[_T1, _T2], /) -> dict[_KT_co | _T1, _VT_co | _T2]: ...
+    def __ror__(self, value: Mapping[_T1, _T2], /) -> dict[_KT_co | _T1, _VT_co | _T2]: ...
 
 if sys.version_info >= (3, 12):
     @disjoint_base

stdlib/typing.pyi

@@ -1133,28 +1133,23 @@ if sys.version_info >= (3, 10):
 def _type_repr(obj: object) -> str: ...
 
 if sys.version_info >= (3, 12):
+    _TypeParameter: typing_extensions.TypeAlias = (
+        TypeVar
+        | typing_extensions.TypeVar
+        | ParamSpec
+        | typing_extensions.ParamSpec
+        | TypeVarTuple
+        | typing_extensions.TypeVarTuple
+    )
+
     def override(method: _F, /) -> _F: ...
     @final
     class TypeAliasType:
-        def __new__(
-            cls,
-            name: str,
-            value: Any,
-            *,
-            type_params: tuple[
-                TypeVar
-                | typing_extensions.TypeVar
-                | ParamSpec
-                | typing_extensions.ParamSpec
-                | TypeVarTuple
-                | typing_extensions.TypeVarTuple,
-                ...,
-            ] = (),
-        ) -> Self: ...
+        def __new__(cls, name: str, value: Any, *, type_params: tuple[_TypeParameter, ...] = ()) -> Self: ...
         @property
         def __value__(self) -> Any: ...  # AnnotationForm
         @property
-        def __type_params__(self) -> tuple[TypeVar | ParamSpec | TypeVarTuple, ...]: ...
+        def __type_params__(self) -> tuple[_TypeParameter, ...]: ...
         @property
         def __parameters__(self) -> tuple[Any, ...]: ...  # AnnotationForm
         @property

stdlib/xml/etree/ElementTree.pyi

@@ -93,7 +93,7 @@ class Element(Generic[_Tag]):
     def __init__(self, tag: _Tag, attrib: dict[str, str] = {}, **extra: str) -> None: ...
     def append(self, subelement: Element[Any], /) -> None: ...
     def clear(self) -> None: ...
-    def extend(self, elements: Iterable[Element], /) -> None: ...
+    def extend(self, elements: Iterable[Element[Any]], /) -> None: ...
     def find(self, path: str, namespaces: dict[str, str] | None = None) -> Element | None: ...
     def findall(self, path: str, namespaces: dict[str, str] | None = None) -> list[Element]: ...
     @overload
@@ -104,7 +104,7 @@ class Element(Generic[_Tag]):
     def get(self, key: str, default: None = None) -> str | None: ...
     @overload
     def get(self, key: str, default: _T) -> str | _T: ...
-    def insert(self, index: int, subelement: Element, /) -> None: ...
+    def insert(self, index: int, subelement: Element[Any], /) -> None: ...
     def items(self) -> ItemsView[str, str]: ...
     def iter(self, tag: str | None = None) -> Generator[Element, None, None]: ...
     @overload
@@ -115,7 +115,7 @@ class Element(Generic[_Tag]):
     def keys(self) -> dict_keys[str, str]: ...
     # makeelement returns the type of self in Python impl, but not in C impl
     def makeelement(self, tag: _OtherTag, attrib: dict[str, str], /) -> Element[_OtherTag]: ...
-    def remove(self, subelement: Element, /) -> None: ...
+    def remove(self, subelement: Element[Any], /) -> None: ...
     def set(self, key: str, value: str, /) -> None: ...
     def __copy__(self) -> Element[_Tag]: ...  # returns the type of self in Python impl, but not in C impl
     def __deepcopy__(self, memo: Any, /) -> Element: ...  # Only exists in C impl
@@ -128,15 +128,15 @@ class Element(Generic[_Tag]):
     # Doesn't actually exist at runtime, but instance of the class are indeed iterable due to __getitem__.
     def __iter__(self) -> Iterator[Element]: ...
     @overload
-    def __setitem__(self, key: SupportsIndex, value: Element, /) -> None: ...
+    def __setitem__(self, key: SupportsIndex, value: Element[Any], /) -> None: ...
     @overload
-    def __setitem__(self, key: slice, value: Iterable[Element], /) -> None: ...
+    def __setitem__(self, key: slice, value: Iterable[Element[Any]], /) -> None: ...
 
     # Doesn't really exist in earlier versions, where __len__ is called implicitly instead
     @deprecated("Testing an element's truth value is deprecated.")
     def __bool__(self) -> bool: ...
 
-def SubElement(parent: Element, tag: str, attrib: dict[str, str] = ..., **extra: str) -> Element: ...
+def SubElement(parent: Element[Any], tag: str, attrib: dict[str, str] = ..., **extra: str) -> Element: ...
 def Comment(text: str | None = None) -> Element[_ElementCallable]: ...
 def ProcessingInstruction(target: str, text: str | None = None) -> Element[_ElementCallable]: ...
 
@@ -155,7 +155,7 @@ class QName:
 _Root = TypeVar("_Root", Element, Element | None, default=Element | None)
 
 class ElementTree(Generic[_Root]):
-    def __init__(self, element: Element | None = None, file: _FileRead | None = None) -> None: ...
+    def __init__(self, element: Element[Any] | None = None, file: _FileRead | None = None) -> None: ...
     def getroot(self) -> _Root: ...
     def parse(self, source: _FileRead, parser: XMLParser | None = None) -> Element: ...
     def iter(self, tag: str | None = None) -> Generator[Element, None, None]: ...
@@ -186,7 +186,7 @@ HTML_EMPTY: Final[set[str]]
 def register_namespace(prefix: str, uri: str) -> None: ...
 @overload
 def tostring(
-    element: Element,
+    element: Element[Any],
     encoding: None = None,
     method: Literal["xml", "html", "text", "c14n"] | None = None,
     *,
@@ -196,7 +196,7 @@ def tostring(
 ) -> bytes: ...
 @overload
 def tostring(
-    element: Element,
+    element: Element[Any],
     encoding: Literal["unicode"],
     method: Literal["xml", "html", "text", "c14n"] | None = None,
     *,
@@ -206,7 +206,7 @@ def tostring(
 ) -> str: ...
 @overload
 def tostring(
-    element: Element,
+    element: Element[Any],
     encoding: str,
     method: Literal["xml", "html", "text", "c14n"] | None = None,
     *,
@@ -216,7 +216,7 @@ def tostring(
 ) -> Any: ...
 @overload
 def tostringlist(
-    element: Element,
+    element: Element[Any],
     encoding: None = None,
     method: Literal["xml", "html", "text", "c14n"] | None = None,
     *,
@@ -226,7 +226,7 @@ def tostringlist(
 ) -> list[bytes]: ...
 @overload
 def tostringlist(
-    element: Element,
+    element: Element[Any],
     encoding: Literal["unicode"],
     method: Literal["xml", "html", "text", "c14n"] | None = None,
     *,
@@ -236,16 +236,16 @@ def tostringlist(
 ) -> list[str]: ...
 @overload
 def tostringlist(
-    element: Element,
+    element: Element[Any],
     encoding: str,
     method: Literal["xml", "html", "text", "c14n"] | None = None,
     *,
     xml_declaration: bool | None = None,
     default_namespace: str | None = None,
     short_empty_elements: bool = True,
 ) -> list[Any]: ...
-def dump(elem: Element | ElementTree[Any]) -> None: ...
-def indent(tree: Element | ElementTree[Any], space: str = "  ", level: int = 0) -> None: ...
+def dump(elem: Element[Any] | ElementTree[Any]) -> None: ...
+def indent(tree: Element[Any] | ElementTree[Any], space: str = "  ", level: int = 0) -> None: ...
 def parse(source: _FileRead, parser: XMLParser[Any] | None = None) -> ElementTree[Element]: ...
 
 # This class is defined inside the body of iterparse

stubs/docker/METADATA.toml

@@ -1,3 +1,3 @@
 version = "7.1.*"
 upstream_repository = "https://github.com/docker/docker-py"
-requires = ["types-requests", "urllib3>=2"]
+requires = ["types-paramiko", "types-requests", "urllib3>=2"]

stubs/docker/docker/api/image.pyi

@@ -1,7 +1,7 @@
-from _typeshed import Incomplete
+import logging
 from typing import Any
 
-log: Incomplete
+log: logging.Logger
 
 class ImageApiMixin:
     def get_image(self, image: str, chunk_size: int | None = 2097152): ...

stubs/docker/docker/api/swarm.pyi

@@ -1,9 +1,12 @@
-from _typeshed import Incomplete
+import logging
+from typing import Literal
 
-log: Incomplete
+from docker.types.swarm import SwarmSpec
+
+log: logging.Logger
 
 class SwarmApiMixin:
-    def create_swarm_spec(self, *args, **kwargs): ...
+    def create_swarm_spec(self, *args, **kwargs) -> SwarmSpec: ...
     def get_unlock_key(self): ...
     def init_swarm(
         self,
@@ -20,17 +23,17 @@ class SwarmApiMixin:
     def inspect_node(self, node_id): ...
     def join_swarm(
         self, remote_addrs, join_token, listen_addr: str = "0.0.0.0:2377", advertise_addr=None, data_path_addr=None
-    ): ...
-    def leave_swarm(self, force: bool = False): ...
+    ) -> Literal[True]: ...
+    def leave_swarm(self, force: bool = False) -> Literal[True]: ...
     def nodes(self, filters=None): ...
-    def remove_node(self, node_id, force: bool = False): ...
-    def unlock_swarm(self, key): ...
-    def update_node(self, node_id, version, node_spec=None): ...
+    def remove_node(self, node_id, force: bool = False) -> Literal[True]: ...
+    def unlock_swarm(self, key) -> Literal[True]: ...
+    def update_node(self, node_id, version, node_spec=None) -> Literal[True]: ...
     def update_swarm(
         self,
         version,
         swarm_spec=None,
         rotate_worker_token: bool = False,
         rotate_manager_token: bool = False,
         rotate_manager_unlock_key: bool = False,
-    ): ...
+    ) -> Literal[True]: ...

stubs/docker/docker/credentials/store.pyi

@@ -1,10 +1,10 @@
 from _typeshed import Incomplete
 
 class Store:
-    program: Incomplete
-    exe: Incomplete
+    program: str
+    exe: str | None
     environment: Incomplete
-    def __init__(self, program, environment=None) -> None: ...
+    def __init__(self, program: str, environment=None) -> None: ...
     def get(self, server): ...
     def store(self, server, username, secret): ...
     def erase(self, server) -> None: ...