fix issue where an outdated version of typeshed can be installed when installing the project if the docstubs have already been generated

.github/workflows/build_and_release.yml

@@ -7,6 +7,8 @@ env:
   VSIX_DIR: packages/vscode-pyright
   NPM_PACKAGE_DIR: packages/pyright
   BROWSER_NPM_PACKAGE_DIR: packages/browser-pyright
+  # prevent uv from constantly reinstalling the project and overwriting docstubs
+  UV_NO_SYNC: true
 
 on: push
 
@@ -87,7 +89,7 @@ jobs:
           name: docstubs
           path: docstubs
 
-      - run: ./pw uv sync
+      - run: ./pw uv sync --config-setting regenerate_docstubs=false
 
       # using relative path for npm scripts because it needs to work in the package directories too
       - name: add pyprojectx and npm scripts to PATH
@@ -177,7 +179,7 @@ jobs:
         run: npm version ${{ steps.current-version.outputs.CURRENT_UPSTREAM_VERSION }} --workspaces --no-git-tag-version
 
       - name: build package - pypi
-        run: uv build
+        run: uv build --config-setting regenerate_docstubs=false
       - uses: actions/upload-artifact@v4
         with:
           name: dist

.vscode/tasks.json

@@ -80,7 +80,8 @@
           "label": "install dependencies",
           "type": "shell",
           "command": "./pw",
-          "args": ["uv", "sync"],
+          // need to always reinstall the current project because docstubs may be outdated
+          "args": ["uv", "sync", "--reinstall-package", "basedpyright"],
           "presentation": {
             "clear": true
           },

based_build/__init__.py

@@ -1,3 +1,4 @@
-"""this folder only exists because the `build` folder has upstream code full of basedpyright and
+"""
+this folder only exists because the `build` folder has upstream code full of basedpyright and
 ruff errors, so these scripts serve the same purpose but this one has basedpyright and ruff enabled
 """

based_build/generateAllDocstubs.sh

@@ -1,5 +1,5 @@
 for pythonVersion in 3.13 3.12 3.11 3.10 3.9 3.8; do
     ./pw uv venv --python $pythonVersion
     ./pw uv sync --only-group=docstubs --no-install-project
-    ./pw uv run npm run generate-docstubs
+    ./pw uv run --no-sync based_build/generate_docstubs.py
 done

based_build/generate_docstubs.py

@@ -1,24 +1,36 @@
 from __future__ import annotations
 
 from pathlib import Path
-from shutil import copytree
+from shutil import copytree, rmtree
 
 from docify import main as docify  # pyright:ignore[reportMissingTypeStubs]
 
 
-def main():
-    """adds docstrings to the stubs located in `../stubdocs` for any modules that are compiled,
+def main(*, overwrite: bool):
+    """
+    adds docstrings to the stubs located in `../stubdocs` for any modules that are compiled,
     because otherwise pyright would have no way to see the docstrings because there's no source
     code.
 
     note that it only generates stubs for modules and objects that exist on your current python
-    version and OS."""
+    version and OS.
+
+    :param overwrite:
+        whether to overwrite existing generated docstubs if they already exist. should be `True`
+        when running locally to avoid running with a potentially outdated version of typeshed, but
+        `False` in CI when generating them for all platforms because it needs to run multiple times
+        on the previously generated output
+    """
     stubs_path = Path("packages/pyright-internal/typeshed-fallback")
     stubs_with_docs_path = Path("docstubs")
-    if not stubs_with_docs_path.exists():
+    if overwrite:
+        if stubs_with_docs_path.exists():
+            rmtree(stubs_with_docs_path)
+        copytree(stubs_path, stubs_with_docs_path, dirs_exist_ok=False)
+    elif not stubs_with_docs_path.exists():
         copytree(stubs_path, stubs_with_docs_path, dirs_exist_ok=True)
     docify([str(stubs_with_docs_path / "stdlib"), "--if-needed", "--in-place"])
 
 
 if __name__ == "__main__":
-    main()
+    main(overwrite=False)

pdm_build.py

@@ -38,7 +38,8 @@ def pdm_build_update_files(self, context: Context, files: dict[str, Path]):
         npm_script_paths = cast(PackageJson, loads((npm_package_dir / package_json).read_text()))[
             "bin"
         ].values()
-        generate_docstubs()
+        if context.builder.config_settings.get("regenerate_docstubs") != "false":
+            generate_docstubs(overwrite=True)
 
         run_npm("ci")
         run_npm("run", "build:cli:dev")

pw

@@ -15,7 +15,7 @@ import sys
 from pathlib import Path
 from venv import EnvBuilder
 
-VERSION = "3.0.9"
+VERSION = "3.1.3"
 
 PYPROJECTX_INSTALL_DIR_ENV_VAR = "PYPROJECTX_INSTALL_DIR"
 PYPROJECTX_PACKAGE_ENV_VAR = "PYPROJECTX_PACKAGE"

pyproject.toml

@@ -163,7 +163,6 @@ enable = [
     "redefined-slots-in-subclass",
     "redundant-returns-doc",
     "redundant-yields-doc",
-    "shallow-copy-environ",
     "useless-param-doc",
     "useless-parent-delegation",
     "useless-type-doc",
@@ -249,9 +248,7 @@ ignore = [
     "D10",     # Missing docstring
     "D203",    # 1 blank line required before class docstring
     "D205",    # 1 blank line required between summary line and description
-    "D209",    # Multi-line docstring closing quotes should be on a separate line
     "D212",    # Multi-line docstring summary should start at the first line
-    "D213",    # Multi-line docstring summary should start at the second line
     "D400",    # First line should end with a period
     "D401",    # First line should be in imperative mood
     "D403",    # First word of the first line should be properly capitalized
@@ -273,8 +270,13 @@ ignore-overlong-task-comments = true
 [tool.ruff.lint.per-file-ignores]
 "*.pyi" = ["A001", "A002", "N"] # we don't control names in 3rd party modules
 "{tests,based_build}/**/*.py" = [
-    "S", # none of these security focused rules are relevant for tests/build scripts
+    "S",    # none of these security focused rules are relevant for tests/build scripts
+    "T201",
 ]
+"based_build/**/*.py" = [
+    "T201", # print
+]
+
 [tool.ruff.lint.isort]
 combine-as-imports = true
 required-imports = ["from __future__ import annotations"]

tests/__init__.py

@@ -1,2 +1,4 @@
-"""tests for python code. any tests for typescript code should go in
-`packages/pyright-internal/src/tests` instead"""
+"""
+tests for python code. any tests for typescript code should go in
+`packages/pyright-internal/src/tests` instead
+"""

tests/test_python_command.py

@@ -4,8 +4,10 @@
 
 
 def test_version():
-    """pretty useless test, this is mainly just making sure the python wrapper scripts aren't
-    busted"""
+    """
+    pretty useless test, this is mainly just making sure the python wrapper scripts aren't
+    busted
+    """
     result = run(["basedpyright", "--version"], check=True, capture_output=True)
     assert result.returncode == 0
     assert result.stdout.startswith(b"basedpyright ")