From fddf2f33d21740124a8c142ce6cbda2d76b149cd Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Mon, 14 Jul 2025 17:00:45 +0100 Subject: [PATCH] [ty] Provide docstrings for stdlib APIs when hovering over them in an IDE (#19311) --- .github/workflows/sync_typeshed.yaml | 31 ++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/.github/workflows/sync_typeshed.yaml b/.github/workflows/sync_typeshed.yaml index c384d8868a..4f7bade41b 100644 --- a/.github/workflows/sync_typeshed.yaml +++ b/.github/workflows/sync_typeshed.yaml @@ -36,9 +36,40 @@ jobs: run: | git config --global user.name typeshedbot git config --global user.email '<>' + - uses: astral-sh/setup-uv@bd01e18f51369d5a26f1651c3cb451d3417e3bba # v6.3.1 - name: Sync typeshed id: sync run: | + docstring_adder="git+https://github.com/astral-sh/docstring-adder.git@6de51c5f44aea11fe8c8f2d30f9ee0683682c3d2" + + # Run with the full matrix of Python versions supported by typeshed, + # so that we codemod in docstrings that only exist on certain versions. + # + # The codemod will only add docstrings to functions/classes that do not + # already have docstrings. We run with Python 3.14 before running with + # any other Python version so that we get the Python 3.14 version of the + # docstring for a definition that exists on all Python versions: if we + # ran with Python 3.9 first, then the later runs with Python 3.10+ would + # not modify the docstring that had already been added using the old version of Python. + # + # TODO: In order to add docstrings for platform-specific APIs, we would also + # need to run the codemod on Windows. We get the runtime docstrings by inspecting + # the docstrings at runtime, so if an API doesn't exist at runtime (because e.g. + # it's Windows-specific and we're running on Linux), then we won't add a docstring to it. + # + uvx --python=3.14 --force-reinstall --from="${docstring_adder}" add-docstrings --stdlib-path ./typeshed/stdlib + uvx --python=3.13 --force-reinstall --from="${docstring_adder}" add-docstrings --stdlib-path ./typeshed/stdlib + uvx --python=3.12 --force-reinstall --from="${docstring_adder}" add-docstrings --stdlib-path ./typeshed/stdlib + uvx --python=3.11 --force-reinstall --from="${docstring_adder}" add-docstrings --stdlib-path ./typeshed/stdlib + uvx --python=3.10 --force-reinstall --from="${docstring_adder}" add-docstrings --stdlib-path ./typeshed/stdlib + uvx --python=3.9 --force-reinstall --from="${docstring_adder}" add-docstrings --stdlib-path ./typeshed/stdlib + + # Here we just reformat the codemodded stubs so that they are + # consistent with the other typeshed stubs around them. + # Typeshed formats code using black in their CI, so we just invoke + # black on the stubs the same way that typeshed does. + uvx --directory=typeshed pre-commit run -a black + rm -rf ruff/crates/ty_vendored/vendor/typeshed mkdir ruff/crates/ty_vendored/vendor/typeshed cp typeshed/README.md ruff/crates/ty_vendored/vendor/typeshed