Merge branch 'main' into pywin32--Add-win32gui._TrackMouseEvent

Author: Avasam

.github/workflows/daily.yml

@@ -35,7 +35,7 @@ jobs:
     strategy:
       matrix:
         os: ["ubuntu-latest", "windows-latest", "macos-latest"]
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14-dev"]
       fail-fast: false
 
     steps:

.github/workflows/stubtest_stdlib.yml

@@ -31,7 +31,7 @@ jobs:
     strategy:
       matrix:
         os: ["ubuntu-latest", "windows-latest", "macos-latest"]
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14-dev"]
       fail-fast: false
 
     steps:

.github/workflows/tests.yml

@@ -61,7 +61,8 @@ jobs:
     strategy:
       matrix:
         platform: ["linux", "win32", "darwin"]
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        # TODO (2025-05-10) "3.13.2" should be "3.14-dev", see below.
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.13.2"]
       fail-fast: false
     steps:
       - uses: actions/checkout@v4
@@ -70,7 +71,25 @@ jobs:
           python-version: ${{ matrix.python-version }}
       - run: curl -LsSf https://astral.sh/uv/install.sh | sh
       - run: uv pip install -r requirements-tests.txt --system
-      - run: python ./tests/mypy_test.py --platform=${{ matrix.platform }} --python-version=${{ matrix.python-version }}
+      - name: Install required APT packages
+        run: |
+          DEPENDENCIES=$( python tests/get_external_apt_dependencies.py )
+          if [ -n "$DEPENDENCIES" ]; then
+              printf "Installing APT packages:\n  $(echo $DEPENDENCIES | sed 's/ /\n  /g')\n"
+              sudo apt-get install -qy $DEPENDENCIES
+          fi
+      - name: Run mypy_test.py
+        run: |
+          # TODO: (2025-05-10) This is a bad hack to work around mypy crashing
+          # when running on Python 3.14. See https://github.com/python/mypy/pull/19020.
+          if [[ "${{ matrix.python-version }}" == "3.13.2" ]]; then
+              MYPY_PY_VERSION="3.14"
+          else
+            # python-version can sometimes be pinned to a specific version or to "-dev", but
+            # mypy understands only X.Y version numbers.
+            MYPY_PY_VERSION=$(echo ${{ matrix.python-version }} | cut -d - -f 1 | cut -d . -f 1-2)
+          fi
+          python ./tests/mypy_test.py --platform=${{ matrix.platform }} --python-version=${MYPY_PY_VERSION}
 
   regression-tests:
     name: "mypy: Run test cases"
@@ -92,7 +111,7 @@ jobs:
     strategy:
       matrix:
         python-platform: ["Linux", "Windows", "Darwin"]
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
       fail-fast: false
     steps:
       - uses: actions/checkout@v4
@@ -103,6 +122,13 @@ jobs:
       - name: Install typeshed test-suite requirements
         # Install these so we can run `get_external_stub_requirements.py`
         run: uv pip install -r requirements-tests.txt --system
+      - name: Install required APT packages
+        run: |
+          DEPENDENCIES=$( python tests/get_external_apt_dependencies.py )
+          if [ -n "$DEPENDENCIES" ]; then
+              printf "Installing APT packages:\n  $(echo $DEPENDENCIES | sed 's/ /\n  /g')\n"
+              sudo apt-get install -qy $DEPENDENCIES
+          fi
       - name: Create an isolated venv for testing
         run: uv venv .venv
       - name: Install 3rd-party stub dependencies

CONTRIBUTING.md

@@ -9,7 +9,7 @@ are important to the project's success.
 
 1. [Prepare your environment](#preparing-the-environment).
 2. Find out [where to make your changes](#where-to-make-changes).
-3. [Prepare your changes](#preparing-changes):
+3. [Making your changes](#making-changes):
     * Small fixes and additions can be submitted directly as pull requests,
       but [contact us](README.md#discussion) before starting significant work.
     * Create your stubs, considering [what to include](#what-to-include) and
@@ -112,29 +112,6 @@ as it's currently excluded from the requirements file:
 </tr>
 </table>
 
-## Code formatting
-
-The code is formatted using [`Black`](https://github.com/psf/black).
-Various other autofixes and lint rules are
-also performed by [`Ruff`](https://github.com/astral-sh/ruff) and
-[`Flake8`](https://github.com/pycqa/flake8),
-with plugin [`flake8-pyi`](https://github.com/pycqa/flake8-pyi).
-
-The repository is equipped with a [pre-commit.ci](https://pre-commit.ci/)
-configuration file. This means that you don't *need* to do anything yourself to
-run the code formatters or linters. When you push a commit, a bot will run
-those for you right away and add any autofixes to your PR. Anything
-that can't be autofixed will show up as a CI failure, hopefully with an error
-message that will make it clear what's gone wrong.
-
-That being said, if you *want* to run the formatters and linters locally
-when you commit, you're free to do so. To use the same configuration as we use
-in CI, we recommend doing this via pre-commit:
-
-```bash
-(.venv)$ pre-commit run --all-files
-```
-
 ## Where to make changes
 
 ### Standard library stubs
@@ -252,6 +229,12 @@ This has the following keys:
   If not specified, stubtest is run only on `linux`.
   Only add extra OSes to the test
   if there are platform-specific branches in a stubs package.
+* `mypy_plugins` (default: `[]`): A list of Python modules to use as mypy plugins
+when running stubtest. For example: `mypy_plugins = ["mypy_django_plugin.main"]`
+* `mypy_plugins_config` (default: `{}`): A dictionary mapping plugin names to their
+configuration dictionaries for use by mypy plugins. For example:
+`mypy_plugins_config = {"django-stubs" = {"django_settings_module" = "@tests.django_settings"}}`
+
 
 `*_dependencies` are usually packages needed to `pip install` the implementation
 distribution.
@@ -260,7 +243,7 @@ The format of all `METADATA.toml` files can be checked by running
 `python3 ./tests/check_typeshed_structure.py`.
 
 
-## Preparing Changes
+## Making Changes
 
 ### Before you begin
 
@@ -275,6 +258,27 @@ Each Python module is represented by a .pyi "stub file". This is a syntactically
 
 Typeshed follows the standard type system guidelines for [stub content](https://typing.readthedocs.io/en/latest/guides/writing_stubs.html#stub-content) and [coding style](https://typing.readthedocs.io/en/latest/guides/writing_stubs.html#style-guide).
 
+The code is formatted using [`Black`](https://github.com/psf/black).
+Various other autofixes and lint rules are
+also performed by [`Ruff`](https://github.com/astral-sh/ruff) and
+[`Flake8`](https://github.com/pycqa/flake8),
+with plugin [`flake8-pyi`](https://github.com/pycqa/flake8-pyi).
+
+The repository is equipped with a [pre-commit.ci](https://pre-commit.ci/)
+configuration file. This means that you don't *need* to do anything yourself to
+run the code formatters or linters. When you push a commit, a bot will run
+those for you right away and add any autofixes to your PR. Anything
+that can't be autofixed will show up as a CI failure, hopefully with an error
+message that will make it clear what's gone wrong.
+
+That being said, if you *want* to run the formatters and linters locally
+when you commit, you're free to do so. To use the same configuration as we use
+in CI, we recommend doing this via pre-commit:
+
+```bash
+(.venv)$ pre-commit run --all-files
+```
+
 ### What to include
 
 Stubs should include the complete interface (classes, functions,

README.md

@@ -21,7 +21,7 @@ the project the stubs are for, but instead report them here to typeshed.**
 Further documentation on stub files, typeshed, and Python's typing system in
 general, can also be found at https://typing.readthedocs.io/en/latest/.
 
-Typeshed supports Python versions 3.9 to 3.13.
+Typeshed supports Python versions 3.9 to 3.14.
 
 ## Using
 

lib/ts_utils/metadata.py

@@ -11,7 +11,7 @@
 from collections.abc import Mapping
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Annotated, Final, NamedTuple, final
+from typing import Annotated, Any, Final, NamedTuple, final
 from typing_extensions import TypeGuard
 
 import tomli
@@ -42,8 +42,12 @@ def _is_list_of_strings(obj: object) -> TypeGuard[list[str]]:
     return isinstance(obj, list) and all(isinstance(item, str) for item in obj)
 
 
+def _is_nested_dict(obj: object) -> TypeGuard[dict[str, dict[str, Any]]]:
+    return isinstance(obj, dict) and all(isinstance(k, str) and isinstance(v, dict) for k, v in obj.items())
+
+
 @functools.cache
-def _get_oldest_supported_python() -> str:
+def get_oldest_supported_python() -> str:
     with PYPROJECT_PATH.open("rb") as config:
         val = tomli.load(config)["tool"]["typeshed"]["oldest_supported_python"]
     assert type(val) is str
@@ -71,6 +75,8 @@ class StubtestSettings:
     ignore_missing_stub: bool
     platforms: list[str]
     stubtest_requirements: list[str]
+    mypy_plugins: list[str]
+    mypy_plugins_config: dict[str, dict[str, Any]]
 
     def system_requirements_for_platform(self, platform: str) -> list[str]:
         assert platform in _STUBTEST_PLATFORM_MAPPING, f"Unrecognised platform {platform!r}"
@@ -93,6 +99,8 @@ def read_stubtest_settings(distribution: str) -> StubtestSettings:
     ignore_missing_stub: object = data.get("ignore_missing_stub", False)
     specified_platforms: object = data.get("platforms", ["linux"])
     stubtest_requirements: object = data.get("stubtest_requirements", [])
+    mypy_plugins: object = data.get("mypy_plugins", [])
+    mypy_plugins_config: object = data.get("mypy_plugins_config", {})
 
     assert type(skip) is bool
     assert type(ignore_missing_stub) is bool
@@ -104,6 +112,8 @@ def read_stubtest_settings(distribution: str) -> StubtestSettings:
     assert _is_list_of_strings(choco_dependencies)
     assert _is_list_of_strings(extras)
     assert _is_list_of_strings(stubtest_requirements)
+    assert _is_list_of_strings(mypy_plugins)
+    assert _is_nested_dict(mypy_plugins_config)
 
     unrecognised_platforms = set(specified_platforms) - _STUBTEST_PLATFORM_MAPPING.keys()
     assert not unrecognised_platforms, f"Unrecognised platforms specified for {distribution!r}: {unrecognised_platforms}"
@@ -124,6 +134,8 @@ def read_stubtest_settings(distribution: str) -> StubtestSettings:
         ignore_missing_stub=ignore_missing_stub,
         platforms=specified_platforms,
         stubtest_requirements=stubtest_requirements,
+        mypy_plugins=mypy_plugins,
+        mypy_plugins_config=mypy_plugins_config,
     )
 
 
@@ -166,6 +178,7 @@ def is_obsolete(self) -> bool:
         "tool",
         "partial_stub",
         "requires_python",
+        "mypy-tests",
     }
 )
 _KNOWN_METADATA_TOOL_FIELDS: Final = {
@@ -178,6 +191,8 @@ def is_obsolete(self) -> bool:
         "ignore_missing_stub",
         "platforms",
         "stubtest_requirements",
+        "mypy_plugins",
+        "mypy_plugins_config",
     }
 }
 _DIST_NAME_RE: Final = re.compile(r"^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$", re.IGNORECASE)
@@ -261,7 +276,7 @@ def read_metadata(distribution: str) -> StubMetadata:
     partial_stub: object = data.get("partial_stub", True)
     assert type(partial_stub) is bool
     requires_python_str: object = data.get("requires_python")
-    oldest_supported_python = _get_oldest_supported_python()
+    oldest_supported_python = get_oldest_supported_python()
     oldest_supported_python_specifier = Specifier(f">={oldest_supported_python}")
     if requires_python_str is None:
         requires_python = oldest_supported_python_specifier

lib/ts_utils/mypy.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from collections.abc import Generator, Iterable
+from contextlib import contextmanager
+from typing import Any, NamedTuple
+
+import tomli
+
+from ts_utils.metadata import StubtestSettings, metadata_path
+from ts_utils.utils import NamedTemporaryFile, TemporaryFileWrapper
+
+
+class MypyDistConf(NamedTuple):
+    module_name: str
+    values: dict[str, dict[str, Any]]
+
+
+# The configuration section in the metadata file looks like the following, with multiple module sections possible
+# [mypy-tests]
+# [mypy-tests.yaml]
+# module_name = "yaml"
+# [mypy-tests.yaml.values]
+# disallow_incomplete_defs = true
+# disallow_untyped_defs = true
+
+
+def mypy_configuration_from_distribution(distribution: str) -> list[MypyDistConf]:
+    with metadata_path(distribution).open("rb") as f:
+        data = tomli.load(f)
+
+    # TODO: This could be added to ts_utils.metadata
+    mypy_tests_conf: dict[str, dict[str, Any]] = data.get("mypy-tests", {})
+    if not mypy_tests_conf:
+        return []
+
+    def validate_configuration(section_name: str, mypy_section: dict[str, Any]) -> MypyDistConf:
+        assert isinstance(mypy_section, dict), f"{section_name} should be a section"
+        module_name = mypy_section.get("module_name")
+
+        assert module_name is not None, f"{section_name} should have a module_name key"
+        assert isinstance(module_name, str), f"{section_name} should be a key-value pair"
+
+        assert "values" in mypy_section, f"{section_name} should have a values section"
+        values: dict[str, dict[str, Any]] = mypy_section["values"]
+        assert isinstance(values, dict), "values should be a section"
+        return MypyDistConf(module_name, values.copy())
+
+    assert isinstance(mypy_tests_conf, dict), "mypy-tests should be a section"
+    return [validate_configuration(section_name, mypy_section) for section_name, mypy_section in mypy_tests_conf.items()]
+
+
+@contextmanager
+def temporary_mypy_config_file(
+    configurations: Iterable[MypyDistConf], stubtest_settings: StubtestSettings | None = None
+) -> Generator[TemporaryFileWrapper[str]]:
+    temp = NamedTemporaryFile("w+")
+    try:
+        for dist_conf in configurations:
+            temp.write(f"[mypy-{dist_conf.module_name}]\n")
+            for k, v in dist_conf.values.items():
+                temp.write(f"{k} = {v}\n")
+        temp.write("[mypy]\n")
+
+        if stubtest_settings:
+            if stubtest_settings.mypy_plugins:
+                temp.write(f"plugins = {'.'.join(stubtest_settings.mypy_plugins)}\n")
+
+            if stubtest_settings.mypy_plugins_config:
+                for plugin_name, plugin_dict in stubtest_settings.mypy_plugins_config.items():
+                    temp.write(f"[mypy.plugins.{plugin_name}]\n")
+                    for k, v in plugin_dict.items():
+                        temp.write(f"{k} = {v}\n")
+
+        temp.flush()
+        yield temp
+    finally:
+        temp.close()

lib/ts_utils/paths.py

@@ -11,6 +11,7 @@
 
 PYPROJECT_PATH: Final = TS_BASE_PATH / "pyproject.toml"
 REQUIREMENTS_PATH: Final = TS_BASE_PATH / "requirements-tests.txt"
+GITIGNORE_PATH: Final = TS_BASE_PATH / ".gitignore"
 
 TESTS_DIR: Final = "@tests"
 TEST_CASES_DIR: Final = "test_cases"