feat: add support for nodejs-wheel

Author: RobertCraigie

README.md

@@ -16,6 +16,15 @@ Use the package manager [pip](https://pip.pypa.io/en/stable/) to install pyright
 pip install pyright
 ```
 
+> [!TIP]
+> It's highly recommended to install `pyright` with the `nodejs` extra which uses [`nodejs-wheel`](https://pypi.org/project/nodejs-wheel-binaries/) to
+> download Node.js binaries as it is more reliable than the default [`nodeenv`](https://pypi.org/project/nodeenv/) solution.
+>
+> ```bash
+> pip install pyright[nodejs]
+> ```
+
+
 ## Usage
 
 Pyright can be invoked using two different methods

pyright/node.py

@@ -8,35 +8,26 @@
 import logging
 import platform
 import subprocess
-from typing import Any, Dict, Tuple, Union, Mapping, Optional, cast
+import importlib.util
+from typing import Any, Dict, Tuple, Union, Mapping, Optional, NamedTuple, cast
 from pathlib import Path
 from functools import lru_cache
+from typing_extensions import Literal, assert_never
 
 from . import errors
-from .types import Binary, Target, Strategy, check_target
+from .types import Target, check_target
 from .utils import env_to_bool, get_bin_dir, get_env_dir, maybe_decode
 
 log: logging.Logger = logging.getLogger(__name__)
 
 ENV_DIR: Path = get_env_dir()
 BINARIES_DIR: Path = get_bin_dir(env_dir=ENV_DIR)
 USE_GLOBAL_NODE = env_to_bool('PYRIGHT_PYTHON_GLOBAL_NODE', default=True)
+USE_NODEJS_WHEEL = env_to_bool('PYRIGHT_PYTHON_NODEJS_WHEEL', default=True)
 NODE_VERSION = os.environ.get('PYRIGHT_PYTHON_NODE_VERSION', default=None)
 VERSION_RE = re.compile(r'\d+\.\d+\.\d+')
 
 
-def _ensure_available(target: Target) -> Binary:
-    """Ensure the target node executable is available"""
-    path = None
-    if USE_GLOBAL_NODE:
-        path = _get_global_binary(target)
-
-    if path is not None:
-        return Binary(path=path, strategy=Strategy.GLOBAL)
-
-    return Binary(path=_ensure_node_env(target), strategy=Strategy.NODEENV)
-
-
 def _is_windows() -> bool:
     return platform.system().lower() == 'windows'
 
@@ -97,31 +88,83 @@ def _install_node_env() -> None:
     subprocess.run(args, check=True)
 
 
+class GlobalStrategy(NamedTuple):
+    type: Literal['global']
+    path: Path
+
+
+class NodeJSWheelStrategy(NamedTuple):
+    type: Literal['nodejs_wheel']
+
+
+class NodeenvStrategy(NamedTuple):
+    type: Literal['nodeenv']
+    path: Path
+
+
+Strategy = Union[GlobalStrategy, NodeJSWheelStrategy, NodeenvStrategy]
+
+
+def _resolve_strategy(target: Target) -> Strategy:
+    if USE_NODEJS_WHEEL:
+        if importlib.util.find_spec('nodejs_wheel') is not None:
+            log.debug('Using nodejs_wheel package for resolving binaries')
+            return NodeJSWheelStrategy(type='nodejs_wheel')
+
+    if USE_GLOBAL_NODE:
+        path = _get_global_binary(target)
+        if path is not None:
+            log.debug('Using global %s binary', target)
+            return GlobalStrategy(type='global', path=path)
+
+    log.debug('Installing binaries using nodeenv')
+    return NodeenvStrategy(type='nodeenv', path=_ensure_node_env(target))
+
+
 def run(
     target: Target, *args: str, **kwargs: Any
 ) -> Union['subprocess.CompletedProcess[bytes]', 'subprocess.CompletedProcess[str]']:
     check_target(target)
-    binary = _ensure_available(target)
-    env = kwargs.pop('env', None) or os.environ.copy()
 
-    if binary.strategy == Strategy.NODEENV:
+    strategy = _resolve_strategy(target)
+    if strategy.type == 'global':
+        node_args = [str(strategy.path), *args]
+        log.debug('Running global node command with args: %s', node_args)
+        return cast(
+            'subprocess.CompletedProcess[str] | subprocess.CompletedProcess[bytes]',
+            subprocess.run(node_args, **kwargs),
+        )
+    elif strategy.type == 'nodejs_wheel':
+        import nodejs_wheel
+
+        if target == 'node':
+            return cast(
+                'subprocess.CompletedProcess[str] | subprocess.CompletedProcess[bytes]',
+                nodejs_wheel.node(args, return_completed_process=True, **kwargs),
+            )
+        elif target == 'npm':
+            return cast(
+                'subprocess.CompletedProcess[str] | subprocess.CompletedProcess[bytes]',
+                nodejs_wheel.npm(args, return_completed_process=True, **kwargs),
+            )
+        else:
+            assert_never(target)
+    elif strategy.type == 'nodeenv':
+        env = kwargs.pop('env', None) or os.environ.copy()
         env.update(get_env_variables())
 
         # If we're using `nodeenv` to resolve the node binary then we also need
         # to ensure that `node` is in the PATH so that any install scripts that
         # assume it is present will work.
-        env.update(PATH=_update_path_env(env=env, target_bin=binary.path.parent))
-        node_args = [str(binary.path), *args]
-    elif binary.strategy == Strategy.GLOBAL:
-        node_args = [str(binary.path), *args]
+        env.update(PATH=_update_path_env(env=env, target_bin=strategy.path.parent))
+        node_args = [str(strategy.path), *args]
+        log.debug('Running nodeenv command with args: %s', node_args)
+        return cast(
+            'subprocess.CompletedProcess[str] | subprocess.CompletedProcess[bytes]',
+            subprocess.run(node_args, **kwargs),
+        )
     else:
-        raise RuntimeError(f'Unknown strategy: {binary.strategy}')
-
-    log.debug('Running node command with args: %s', node_args)
-    return cast(
-        'subprocess.CompletedProcess[str] | subprocess.CompletedProcess[bytes]',
-        subprocess.run(node_args, env=env, **kwargs),
-    )
+        assert_never(strategy)
 
 
 def version(target: Target) -> Tuple[int, ...]:

pyright/types.py

@@ -1,24 +1,14 @@
+from __future__ import annotations
+
 import sys
-from enum import Enum
-from typing import Any, NamedTuple
-from pathlib import Path
+from typing import Any
 
 if sys.version_info >= (3, 8):
     from typing import Literal
 else:
     from typing_extensions import Literal
 
 
-class Strategy(int, Enum):
-    GLOBAL = 0
-    NODEENV = 1
-
-
-class Binary(NamedTuple):
-    path: Path
-    strategy: Strategy
-
-
 # we have to define twice to support runtime type checking
 # on python < 3.7 as typing.get_args is not available
 Target = Literal['node', 'npm']

requirements.txt

@@ -1,2 +1,2 @@
 nodeenv>=1.6.0
-typing-extensions>=3.7; python_version < '3.8'
+typing-extensions>=4.1

setup.py

@@ -26,7 +26,8 @@
 extras = {
     'dev': [
         'twine>=3.4.1',
-    ]
+    ],
+    'nodejs': ['nodejs-wheel-binaries'],
 }
 
 setup(

tests/conftest.py

@@ -3,8 +3,7 @@
 from pathlib import Path
 
 import pytest
-
-from pyright import node
+import nodejs_wheel
 
 
 @pytest.fixture(name='tmp_path')
@@ -20,9 +19,10 @@ def tmp_path_fixture(tmp_path: Path) -> Iterator[Path]:
 
 @pytest.fixture(name='node', scope='session')
 def node_fixture() -> str:
-    return str(
-        node._ensure_available('node').path  # pyright: ignore[reportPrivateUsage]
-    )
+    if os.name == 'nt':
+        return str(Path(nodejs_wheel.__file__).parent / 'node.exe')
+
+    return str(Path(nodejs_wheel.__file__).parent / 'bin' / 'node')
 
 
 @pytest.fixture(autouse=True)

tests/test_node.py

@@ -77,6 +77,7 @@ def test_run_env_argument(tmp_path: Path) -> None:
 
 @mock.patch('pyright.node.NODE_VERSION', '13.1.0')
 @mock.patch('pyright.node.USE_GLOBAL_NODE', False)
+@mock.patch('pyright.node.USE_NODEJS_WHEEL', False)
 def test_node_version_env() -> None:
     """Ensure the custom version is respected."""
     proc = pyright.node.run(