Initial pyright config

.github/workflows/pyright.yml

@@ -0,0 +1,89 @@
+# Split workflow file to not interfere with skeleton
+name: pyright
+
+on:
+  merge_group:
+  push:
+    branches-ignore:
+    # temporary GH branches relating to merge queues (jaraco/skeleton#93)
+    - gh-readonly-queue/**
+    tags:
+    # required if branches-ignore is supplied (jaraco/skeleton#103)
+    - '**'
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: >-
+    ${{ github.workflow }}-
+    ${{ github.ref_type }}-
+    ${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: true
+
+env:
+  # pin pyright so a new version doesn't suddenly cause the CI to fail,
+  # until types-setuptools is removed from typeshed.
+  # For help with static-typing issues, or pyright update, ping @Avasam
+  PYRIGHT_VERSION: "latest"
+
+  # Environment variable to support color support (jaraco/skeleton#66)
+  FORCE_COLOR: 1
+
+  # Suppress noisy pip warnings
+  PIP_DISABLE_PIP_VERSION_CHECK: 'true'
+  PIP_NO_PYTHON_VERSION_WARNING: 'true'
+  PIP_NO_WARN_SCRIPT_LOCATION: 'true'
+
+jobs:
+  pyright:
+    strategy:
+      # https://blog.jaraco.com/efficient-use-of-ci-resources/
+      matrix:
+        python:
+          - "3.8"
+          - "3.12"
+        platform:
+          - ubuntu-latest
+          - macos-latest
+          - windows-latest
+        include:
+          - python: "3.9"
+            platform: ubuntu-latest
+          - python: "3.10"
+            platform: ubuntu-latest
+          - python: "3.11"
+            platform: ubuntu-latest
+          # Python 3.8, 3.9 are on macos-13 but not macos-latest (macos-14-arm64)
+          # https://github.com/actions/setup-python/issues/850
+          # https://github.com/actions/setup-python/issues/696#issuecomment-1637587760
+          - {python: "3.8", platform: "macos-13"}
+        exclude:
+          - {python: "3.8", platform: "macos-latest"}
+    runs-on: ${{ matrix.platform }}
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          allow-prereleases: true
+      - name: Install typed dependencies
+        run: python -m pip install -e .[core,type]
+      - name: Inform how to run locally
+        run: |
+          echo 'To run this test locally with npm pre-installed, run:'
+          echo '> npx -y pyright@${{ env.PYRIGHT_VERSION }} --threads'
+          echo 'You can also instead install "Pyright for Python" which will install npm for you:'
+          if [ '$PYRIGHT_VERSION' == 'latest' ]; then
+            echo '> pip install -U'
+          else
+            echo '> pip install pyright==${{ env.PYRIGHT_VERSION }}'
+          fi
+          echo 'pyright --threads'
+        shell: bash
+      - name: Run pyright
+        uses: jakebailey/pyright-action@v2
+        with:
+          version: ${{ env.PYRIGHT_VERSION }}
+          extra-args: --threads

pkg_resources/__init__.py

@@ -568,24 +568,30 @@
 class IMetadataProvider(Protocol):
     def has_metadata(self, name: str) -> bool:
         """Does the package's distribution contain the named metadata?"""
+        ...
 
     def get_metadata(self, name: str) -> str:
         """The named metadata resource as a string"""
+        ...
 
     def get_metadata_lines(self, name: str) -> Iterator[str]:
         """Yield named metadata resource as list of non-blank non-comment lines
 
         Leading and trailing whitespace is stripped from each line, and lines
         with ``#`` as the first non-blank character are omitted."""
+        ...
 
     def metadata_isdir(self, name: str) -> bool:
         """Is the named metadata a directory?  (like ``os.path.isdir()``)"""
+        ...
 
     def metadata_listdir(self, name: str) -> list[str]:
         """List of metadata names in the directory (like ``os.listdir()``)"""
+        ...
 
     def run_script(self, script_name: str, namespace: dict[str, Any]) -> None:
         """Execute the named script in the supplied namespace dictionary"""
+        ...
 
 
 class IResourceProvider(IMetadataProvider, Protocol):
@@ -597,29 +603,35 @@
         """Return a true filesystem path for `resource_name`
 
         `manager` must be a ``ResourceManager``"""
+        ...
 
     def get_resource_stream(
         self, manager: ResourceManager, resource_name: str
     ) -> _ResourceStream:
         """Return a readable file-like object for `resource_name`
 
         `manager` must be a ``ResourceManager``"""
+        ...
 
     def get_resource_string(
         self, manager: ResourceManager, resource_name: str
     ) -> bytes:
         """Return the contents of `resource_name` as :obj:`bytes`
 
         `manager` must be a ``ResourceManager``"""
+        ...
 
     def has_resource(self, resource_name: str) -> bool:
         """Does the package contain the named resource?"""
+        ...
 
     def resource_isdir(self, resource_name: str) -> bool:
         """Is the named resource a directory?  (like ``os.path.isdir()``)"""
+        ...
 
     def resource_listdir(self, resource_name: str) -> list[str]:
         """List of resource names in the directory (like ``os.listdir()``)"""
+        ...
 
 
 class WorkingSet:
@@ -1872,7 +1884,7 @@
         # of multiple eggs and use module_path instead of .archive.
         eggs = filter(_is_egg_path, _parents(self.module_path))
         egg = next(eggs, None)
         egg and self._set_egg(egg)
 
     def _set_egg(self, path: str):
         self.egg_name = os.path.basename(path)
@@ -1936,7 +1948,7 @@
 empty_provider = EmptyProvider()
 
 
 class ZipManifests(Dict[str, "MemoizedZipManifests.manifest_mod"]):
     """
     zip manifest builder
     """
@@ -2324,7 +2336,7 @@
     for entry in sorted(entries):
         fullpath = os.path.join(path_item, entry)
         factory = dist_factory(path_item, entry, only)
         yield from factory(fullpath)
 
 
 def dist_factory(path_item, entry, only):
@@ -2420,7 +2432,7 @@
 
 
 if hasattr(pkgutil, 'ImpImporter'):
     register_finder(pkgutil.ImpImporter, find_on_path)
 
 register_finder(importlib.machinery.FileFinder, find_on_path)
 
@@ -2466,7 +2478,7 @@
         # capture warnings due to #1111
         with warnings.catch_warnings():
             warnings.simplefilter("ignore")
             loader = importer.find_module(packageName)
     else:
         loader = spec.loader if spec else None
 

pkg_resources/tests/test_pkg_resources.py

@@ -70,7 +70,7 @@ def teardown_class(cls):
             finalizer()
 
     def test_resource_listdir(self):
-        import mod
+        import mod  # pyright: ignore[reportMissingImports] # Temporary package for test
 
         zp = pkg_resources.ZipProvider(mod)
 
@@ -84,7 +84,7 @@ def test_resource_listdir(self):
         assert zp.resource_listdir('nonexistent') == []
         assert zp.resource_listdir('nonexistent/') == []
 
-        import mod2
+        import mod2  # pyright: ignore[reportMissingImports] # Temporary package for test
 
         zp2 = pkg_resources.ZipProvider(mod2)
 
@@ -100,7 +100,7 @@ def test_resource_filename_rewrites_on_change(self):
         same size and modification time, it should not be overwritten on a
         subsequent call to get_resource_filename.
         """
-        import mod
+        import mod  # pyright: ignore[reportMissingImports] # Temporary package for test
 
         manager = pkg_resources.ResourceManager()
         zp = pkg_resources.ZipProvider(mod)

pkg_resources/tests/test_resources.py

@@ -817,11 +817,11 @@ def test_two_levels_deep(self, symlinked_tmpdir):
             (pkg1 / '__init__.py').write_text(self.ns_str, encoding='utf-8')
             (pkg2 / '__init__.py').write_text(self.ns_str, encoding='utf-8')
         with pytest.warns(DeprecationWarning, match="pkg_resources.declare_namespace"):
-            import pkg1
+            import pkg1  # pyright: ignore[reportMissingImports] # Temporary package for test
         assert "pkg1" in pkg_resources._namespace_packages
         # attempt to import pkg2 from site-pkgs2
         with pytest.warns(DeprecationWarning, match="pkg_resources.declare_namespace"):
-            import pkg1.pkg2
+            import pkg1.pkg2  # pyright: ignore[reportMissingImports] # Temporary package for test
         # check the _namespace_packages dict
         assert "pkg1.pkg2" in pkg_resources._namespace_packages
         assert pkg_resources._namespace_packages["pkg1"] == ["pkg1.pkg2"]
@@ -862,8 +862,8 @@ def test_path_order(self, symlinked_tmpdir):
             (subpkg / '__init__.py').write_text(vers_str % number, encoding='utf-8')
 
         with pytest.warns(DeprecationWarning, match="pkg_resources.declare_namespace"):
-            import nspkg
-            import nspkg.subpkg
+            import nspkg  # pyright: ignore[reportMissingImports] # Temporary package for test
+            import nspkg.subpkg  # pyright: ignore[reportMissingImports] # Temporary package for test
         expected = [str(site.realpath() / 'nspkg') for site in site_dirs]
         assert nspkg.__path__ == expected
         assert nspkg.subpkg.__version__ == 1

pyproject.toml

@@ -54,14 +54,6 @@ test = [
 	# for tools/finalize.py
 	'jaraco.develop >= 7.21; python_version >= "3.9" and sys_platform != "cygwin"',
 	"pytest-home >= 0.5",
-	# pin mypy version so a new version doesn't suddenly cause the CI to fail,
-	# until types-setuptools is removed from typeshed.
-	# For help with static-typing issues, or mypy update, ping @Avasam 
-	"mypy==1.11.*",
-	# No Python 3.11 dependencies require tomli, but needed for type-checking since we import it directly
-	"tomli",
-	# No Python 3.12 dependencies require importlib_metadata, but needed for type-checking since we import it directly
-	"importlib_metadata",
 	"pytest-subprocess",
 
 	# workaround for pypa/setuptools#4333
@@ -134,6 +126,14 @@ type = [
 	"pytest-mypy",
 
 	# local
+	# pin mypy so a new version doesn't suddenly cause the CI to fail,
+	# until types-setuptools is removed from typeshed.
+	# For help with static-typing issues, or mypy update, ping @Avasam
+	"mypy==1.11.*",
+	# Typing fixes in version newer than we require at runtime
+	"importlib_metadata>=7.0.2; python_version < '3.10'",
+	# Imported unconditionally in tools/finalize.py
+	'jaraco.develop >= 7.21; sys_platform != "cygwin"',
 ]
 
 

pyrightconfig.json

@@ -0,0 +1,32 @@
+{
+	"$schema": "https://raw.githubusercontent.com/microsoft/pyright/main/packages/vscode-pyright/schemas/pyrightconfig.schema.json",
+	"exclude": [
+		"build",
+		".tox",
+		".eggs",
+		"**/_vendor", // Vendored
+		"setuptools/_distutils", // Vendored
+		"setuptools/config/_validate_pyproject/**", // Auto-generated
+	],
+	// Our testing setup doesn't allow passing CLI arguments, so local devs have to set this manually.
+	// "pythonVersion": "3.8",
+	// For now we don't mind if mypy's `type: ignore` comments accidentally suppresses pyright issues
+	"enableTypeIgnoreComments": true,
+	"typeCheckingMode": "basic",
+	// Too many issues caused by dynamic patching, still worth fixing when we can
+	"reportAttributeAccessIssue": "warning",
+	// Fails on Python 3.12 due to missing distutils and on cygwin CI tests
+	"reportAssignmentType": "warning",
+	"reportMissingImports": "warning",
+	"reportOptionalCall": "warning",
+	// FIXME: A handful of reportOperatorIssue spread throughout the codebase
+	"reportOperatorIssue": "warning",
+	// Deferred initialization (initialize_options/finalize_options) causes many "potentially None" issues
+	// TODO: Fix with type-guards or by changing how it's initialized
+	"reportArgumentType": "warning", // A lot of these are caused by jaraco.path.build's spec argument not being a Mapping https://github.com/jaraco/jaraco.path/pull/3
+	"reportCallIssue": "warning",
+	"reportGeneralTypeIssues": "warning",
+	"reportOptionalIterable": "warning",
+	"reportOptionalMemberAccess": "warning",
+	"reportOptionalOperand": "warning",
+}

setuptools/__init__.py

@@ -12,6 +12,7 @@
 import re
 import sys
 from abc import abstractmethod
+from collections.abc import Mapping
 from typing import TYPE_CHECKING, TypeVar, overload
 
 sys.path.extend(((vendor_path := os.path.join(os.path.dirname(os.path.dirname(__file__)), 'setuptools', '_vendor')) not in sys.path) * [vendor_path])  # fmt: skip
@@ -59,7 +60,7 @@ class MinimalDistribution(distutils.core.Distribution):
         fetch_build_eggs interface.
         """
 
-        def __init__(self, attrs):
+        def __init__(self, attrs: Mapping[str, object]):
             _incl = 'dependency_links', 'setup_requires'
             filtered = {k: attrs[k] for k in set(_incl) & set(attrs)}
             super().__init__(filtered)

setuptools/_reqs.py

@@ -28,15 +28,13 @@ def parse_strings(strs: _StrOrIter) -> Iterator[str]:
     return text.join_continuation(map(text.drop_comment, text.yield_lines(strs)))
 
 
+# These overloads are only needed because of a mypy false-positive, pyright gets it right
+# https://github.com/python/mypy/issues/3737
 @overload
 def parse(strs: _StrOrIter) -> Iterator[Requirement]: ...
-
-
 @overload
 def parse(strs: _StrOrIter, parser: Callable[[str], _T]) -> Iterator[_T]: ...
-
-
-def parse(strs, parser=parse_req):
+def parse(strs: _StrOrIter, parser: Callable[[str], _T] = parse_req) -> Iterator[_T]:  # type: ignore[assignment]
     """
     Replacement for ``pkg_resources.parse_requirements`` that uses ``packaging``.
     """

setuptools/command/build.py

@@ -87,12 +87,15 @@ def finalize_options(self):
 
     def initialize_options(self):
         """(Required by the original :class:`setuptools.Command` interface)"""
+        ...
 
     def finalize_options(self):
         """(Required by the original :class:`setuptools.Command` interface)"""
+        ...
 
     def run(self):
         """(Required by the original :class:`setuptools.Command` interface)"""
+        ...
 
     def get_source_files(self) -> list[str]:
         """
@@ -104,6 +107,7 @@ def get_source_files(self) -> list[str]:
         with all the files necessary to build the distribution.
         All files should be strings relative to the project root directory.
         """
+        ...
 
     def get_outputs(self) -> list[str]:
         """
@@ -117,6 +121,7 @@ def get_outputs(self) -> list[str]:
            in ``get_output_mapping()`` plus files that are generated during the build
            and don't correspond to any source file already present in the project.
         """
+        ...
 
     def get_output_mapping(self) -> dict[str, str]:
         """
@@ -127,3 +132,4 @@ def get_output_mapping(self) -> dict[str, str]:
         Destination files should be strings in the form of
         ``"{build_lib}/destination/file/path"``.
         """
+        ...

setuptools/command/build_clib.py

@@ -5,7 +5,9 @@
 from distutils.errors import DistutilsSetupError
 
 try:
-    from distutils._modified import newer_pairwise_group
+    from distutils._modified import (  # pyright: ignore[reportMissingImports]
+        newer_pairwise_group,
+    )
 except ImportError:
     # fallback for SETUPTOOLS_USE_DISTUTILS=stdlib
     from .._distutils._modified import newer_pairwise_group

setuptools/command/build_ext.py

@@ -156,20 +156,18 @@ def _get_output_mapping(self) -> Iterator[tuple[str, str]]:
                 yield (output_cache, inplace_cache)
 
     def get_ext_filename(self, fullname):
-        so_ext = os.getenv('SETUPTOOLS_EXT_SUFFIX')
+        so_ext = os.getenv('SETUPTOOLS_EXT_SUFFIX', '')
         if so_ext:
             filename = os.path.join(*fullname.split('.')) + so_ext
         else:
             filename = _build_ext.get_ext_filename(self, fullname)
-            so_ext = get_config_var('EXT_SUFFIX')
+            so_ext = str(get_config_var('EXT_SUFFIX'))
 
         if fullname in self.ext_map:
             ext = self.ext_map[fullname]
-            use_abi3 = ext.py_limited_api and get_abi3_suffix()
-            if use_abi3:
-                filename = filename[: -len(so_ext)]
-                so_ext = get_abi3_suffix()
-                filename = filename + so_ext
+            abi3_suffix = get_abi3_suffix()
+            if ext.py_limited_api and abi3_suffix:  # Use abi3
+                filename = filename[: -len(so_ext)] + abi3_suffix
             if isinstance(ext, Library):
                 fn, ext = os.path.splitext(filename)
                 return self.shlib_compiler.library_filename(fn, libtype)