Promote usage of uv run (no more python vs python3)

.gitignore

@@ -68,8 +68,10 @@ analyze.py
 # Mypy cache
 .mypy_cache/
 
-# pyenv local python version
+# pyenv and uv local python version
 .python-version
+# we don't use uv's lock as we're not actually a project
+uv.lock
 
 # deliberately local test configuration files
 stdlib/@tests/stubtest_allowlists/*.local

CONTRIBUTING.md

@@ -300,14 +300,13 @@ Typeshed includes `scripts/create_baseline_stubs.py`.
 It generates stubs automatically using a tool called
 [stubgen](https://mypy.readthedocs.io/en/latest/stubgen.html) that comes with mypy.
 
-To get started, fork typeshed, clone your fork, and then
-[create a virtualenv](#-or-create-a-local-development-environment).
+To get started, fork typeshed, clone your fork, and then [prepare your environment](#preparing-the-environment).
 You can then install the library with `pip` into the virtualenv and run the script below,
 replacing `$INSERT_LIBRARY_NAME_HERE` with the name of the library:
 
 ```bash
 (.venv)$ pip install $INSERT_LIBRARY_NAME_HERE
-(.venv)$ python3 scripts/create_baseline_stubs.py $INSERT_LIBRARY_NAME_HERE
+(.venv)$ uv run scripts/create_baseline_stubs.py $INSERT_LIBRARY_NAME_HERE
 ```
 
 When the script has finished running, it will print instructions telling you what to do next.

pyproject.toml

@@ -1,3 +1,9 @@
+[project]
+# This section is needed to avoid writing --no-project everytime https://github.com/astral-sh/uv/issues/8666
+name = "typeshed"
+version = "0"
+requires-python = ">=3.9" # Minimum version to run tests, used by uv run
+
 [tool.black]
 line-length = 130
 target-version = ["py310"]

scripts/create_baseline_stubs.py

@@ -1,9 +1,9 @@
-#!/usr/bin/env python3
+#!/usr/bin/env -S uv run
 
 """Script to generate unannotated baseline stubs using stubgen.
 
 Basic usage:
-$ python3 scripts/create_baseline_stubs.py <project on PyPI>
+$ uv run scripts/create_baseline_stubs.py <project on PyPI>
 
 Run with -h for more help.
 """

scripts/stubsabot.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python3
+#!/usr/bin/env -S uv run
 from __future__ import annotations
 
 import argparse

scripts/sync_protobuf/google_protobuf.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python3
+#!/usr/bin/env -S uv run
 """
 Generates the protobuf stubs for the given protobuf version using mypy-protobuf.
 Generally, new minor versions are a good time to update the stubs.

scripts/sync_protobuf/s2clientprotocol.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python3
+#!/usr/bin/env -S uv run
 """
 Generates the protobuf stubs for the given s2clientprotocol version using mypy-protobuf.
 Generally, new minor versions are a good time to update the stubs.

scripts/sync_protobuf/tensorflow.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python3
+#!/usr/bin/env -S uv run
 """
 Generates the protobuf stubs for the given tensorflow version using mypy-protobuf.
 Generally, new minor versions are a good time to update the stubs.

tests/README.md

@@ -24,17 +24,17 @@ may require extra dependencies external to typeshed to be installed in your virt
 prior to running the test.
 You can list or install all of a stubs package's external dependencies using the following script:
 ```bash
-(.venv3)$ python tests/get_external_stub_requirements.py <third_party_stub>  # List external dependencies for <third_party_stub>
-(.venv3)$ python tests/get_external_stub_requirements.py <third_party_stub1> <third_party_stub2>  # List external dependencies for <third_party_stub1> and <third_party_stub2>
-(.venv3)$ python tests/get_external_stub_requirements.py  # List external dependencies for all third-party stubs in typeshed
-(.venv3)$ python scripts/install_all_third_party_dependencies.py  # Install external dependencies for all third-party stubs in typeshed
+(.venv)$ uv run tests/get_external_stub_requirements.py <third_party_stub>  # List external dependencies for <third_party_stub>
+(.venv)$ uv run tests/get_external_stub_requirements.py <third_party_stub1> <third_party_stub2>  # List external dependencies for <third_party_stub1> and <third_party_stub2>
+(.venv)$ uv run tests/get_external_stub_requirements.py  # List external dependencies for all third-party stubs in typeshed
+(.venv)$ uv run scripts/install_all_third_party_dependencies.py  # Install external dependencies for all third-party stubs in typeshed
 ```
 
 ## Run all tests for a specific stub
 
 Run using:
 ```bash
-(.venv3)$ python3 tests/runtests.py <stdlib-or-stubs>/<stub-to-test>
+(.venv)$ uv run tests/runtests.py <stdlib-or-stubs>/<stub-to-test>
 ```
 
 This script will run all tests below for a specific typeshed directory. If a
@@ -44,7 +44,7 @@ be selected. A summary of the results will be printed to the terminal.
 You must provide a single argument which is a path to the stubs to test, like
 so: `stdlib/os` or `stubs/requests`.
 
-Run `python tests/runtests.py --help` for information on the various configuration options
+Run `uv run tests/runtests.py --help` for information on the various configuration options
 for this script. Note that if you use the `--run-stubtest` flag with the stdlib stubs,
 whether or not the test passes will depend on the exact version of Python
 you're using, as well as various other details regarding your local environment.
@@ -54,7 +54,7 @@ For more information, see the docs on [`stubtest_stdlib.py`](#stubtest_stdlibpy)
 
 Run using:
 ```bash
-(.venv3)$ python3 tests/mypy_test.py
+(.venv)$ uv run tests/mypy_test.py
 ```
 
 The test has two parts: running mypy on the stdlib stubs,
@@ -64,7 +64,7 @@ This test is shallow — it verifies that all stubs can be
 imported but doesn't check whether stubs match their implementation
 (in the Python standard library or a third-party package).
 
-Run `python tests/mypy_test.py --help` for information on the various configuration options
+Run `uv run tests/mypy_test.py --help` for information on the various configuration options
 for this script.
 
 ## pytype\_test.py
@@ -74,7 +74,7 @@ Python 3.13 and above.
 
 Run using:
 ```bash
-(.venv3)$ python3 tests/pytype_test.py
+(.venv)$ uv run tests/pytype_test.py
 ```
 
 This test works similarly to `mypy_test.py`, except it uses `pytype`.
@@ -85,9 +85,9 @@ This test requires [Node.js](https://nodejs.org) to be installed. Although
 typeshed runs pyright in CI, it does not currently use this script. However,
 this script uses the same pyright version and configuration as the CI.
 ```bash
-(.venv3)$ python3 tests/pyright_test.py                                # Check all files
-(.venv3)$ python3 tests/pyright_test.py stdlib/sys.pyi                 # Check one file
-(.venv3)$ python3 tests/pyright_test.py -p pyrightconfig.stricter.json # Check with the stricter config.
+(.venv)$ uv run tests/pyright_test.py                                # Check all files
+(.venv)$ uv run tests/pyright_test.py stdlib/sys.pyi                 # Check one file
+(.venv)$ uv run tests/pyright_test.py -p pyrightconfig.stricter.json # Check with the stricter config.
 ```
 
 `pyrightconfig.stricter.json` is a stricter configuration that enables additional
@@ -101,7 +101,7 @@ This test runs mypy against the test cases for typeshed's stdlib and third-party
 stubs. See [the REGRESSION.md document](./REGRESSION.md)
 in this directory
 for more information about what
-these test cases are for and how they work. Run `python tests/regr_test.py --help`
+these test cases are for and how they work. Run `uv run tests/regr_test.py --help`
 for information on the various configuration options.
 
 ## check\_typeshed\_structure.py
@@ -110,14 +110,14 @@ This checks that typeshed's directory structure and metadata files are correct.
 
 Run using:
 ```bash
-$ python3 tests/check_typeshed_structure.py
+$ uv run tests/check_typeshed_structure.py
 ```
 
 ## stubtest\_stdlib.py
 
 Run using
 ```bash
-(.venv3)$ python3 tests/stubtest_stdlib.py
+(.venv)$ uv run tests/stubtest_stdlib.py
 ```
 
 This test compares the stdlib stubs against the objects at runtime. Because of
@@ -152,21 +152,21 @@ stubtest on.
 
 Run using
 ```bash
-(.venv3)$ python3 tests/stubtest_third_party.py
+(.venv)$ uv run tests/stubtest_third_party.py
 ```
 
 Similar to `stubtest_stdlib.py`, but tests the third party stubs. By default,
 it checks all third-party stubs, but you can provide the distributions to
 check on the command line:
 
 ```bash
-(.venv3)$ python3 tests/stubtest_third_party.py requests toml  # check stubs/requests and stubs/toml
+(.venv)$ uv run tests/stubtest_third_party.py requests toml  # check stubs/requests and stubs/toml
 ```
 
 If you have the runtime package installed in your local virtual environment, you can also run stubtest
 directly, with
 ```bash
-(.venv3)$ MYPYPATH=<path-to-module-stubs> python3 -m mypy.stubtest \
+(.venv)$ MYPYPATH=<path-to-module-stubs> uv run -m mypy.stubtest \
   --custom-typeshed-dir <path-to-typeshed> \
   <third-party-module>
 ```
@@ -200,9 +200,9 @@ for missing objects rather than trying to match the runtime in every detail.
 
 Run using
 ```bash
-(.venv3)$ python3 tests/typecheck_typeshed.py
+(.venv)$ uv run tests/typecheck_typeshed.py
 ```
 
 This is a small wrapper script that uses mypy to typecheck typeshed's own code in the
-`scripts` and `tests` directories. Run `python tests/typecheck_typeshed.py --help` for
+`scripts` and `tests` directories. Run `uv run tests/typecheck_typeshed.py --help` for
 information on the various configuration options.

tests/REGRESSION.md

@@ -33,15 +33,15 @@ false-positive errors for idiomatic usage of these classes.
 ## Running the tests
 
 To verify the stdlib test cases pass with mypy, run
-`python tests/regr_test.py stdlib` from the root of the typeshed repository.
+`uv run tests/regr_test.py stdlib` from the root of the typeshed repository.
 This assumes that the development environment has been set up as described in
 the [CONTRIBUTING.md](../CONTRIBUTING.md) document.
 
 For third-party-library stubs, pass the name of the runtime library the stubs
 are for. For example, to run the tests for our `requests` stubs, run
-`python tests/regr_test.py requests`.
+`uv run tests/regr_test.py requests`.
 
-Run `python tests/regr_test.py -h` for the full range of CLI options this script
+Run `uv run tests/regr_test.py -h` for the full range of CLI options this script
 supports. There is no equivalent script for pyright currently; for pyright, the
 tests are checked in CI using a GitHub Action.
 

tests/check_typeshed_structure.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python3
+#!/usr/bin/env -S uv run
 
 """
 Check that the typeshed repository contains the correct files in the

tests/get_external_stub_requirements.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python3
+#!/usr/bin/env -S uv run
 
 # TODO: It should be possible to specify the Python version and platform
 # and limit the output to the packages that are compatible with that version

tests/get_stubtest_system_requirements.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python3
+#!/usr/bin/env -S uv run
 import sys
 
 from ts_utils.requirements import get_stubtest_system_requirements

tests/mypy_test.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python3
+#!/usr/bin/env -S uv run
 """Run mypy on typeshed's stdlib and third-party stubs."""
 
 from __future__ import annotations

tests/pyright_test.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python3
+#!/usr/bin/env -S uv run
 
 import os
 import shutil

tests/pytype_test.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python3
+#!/usr/bin/env -S uv run
 # Lack of pytype typing
 # pyright: reportUnknownVariableType=false, reportUnknownMemberType=false, reportUnknownArgumentType=false, reportMissingTypeStubs=false
 """Test runner for typeshed.

tests/regr_test.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python3
+#!/usr/bin/env -S uv run
 """Run mypy on the test cases for the stdlib and third-party stubs."""
 
 from __future__ import annotations

tests/runtests.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python3
+#!/usr/bin/env -S uv run
 from __future__ import annotations
 
 import argparse

tests/stubtest_stdlib.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python3
+#!/usr/bin/env -S uv run
 """Test typeshed's stdlib using stubtest.
 
 stubtest is a script in the mypy project that compares stubs to the actual objects at runtime.

tests/stubtest_third_party.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python3
+#!/usr/bin/env -S uv run
 """Test typeshed's third party stubs using stubtest."""
 
 from __future__ import annotations

tests/typecheck_typeshed.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python3
+#!/usr/bin/env -S uv run
 """Run mypy on the "tests" and "scripts" directories."""
 
 from __future__ import annotations