feat: basic typing support

.pre-commit-config.yaml

@@ -34,8 +34,10 @@ repos:
   rev: 20.8b1
   hooks:
   - id: black
+    # By default, this ignores pyi files, though black supports them
+    types: [text]
     # Not all Python files are Blacked, yet
-    files: ^(setup.py|pybind11|tests/extra)
+    files: ^(setup.py|pybind11|tests/extra|tools).*\.pyi?$
 
 # Changes tabs to spaces
 - repo: https://github.com/Lucas-C/pre-commit-hooks
@@ -60,6 +62,15 @@ repos:
     types: [file]
     files: (\.cmake|CMakeLists.txt)(.in)?$
 
+# Check static types with mypy
+- repo: https://github.com/pre-commit/mirrors-mypy
+  rev: v0.790
+  hooks:
+  - id: mypy
+    # The default Python type ignores .pyi files, so let's rerun if detected
+    files: ^pybind11.*\.pyi?$
+    pass_filenames: false
+
 # Checks the manifest for missing files (native support)
 - repo: https://github.com/mgedmin/check-manifest
   rev: "0.43"

MANIFEST.in

@@ -1,4 +1,6 @@
 recursive-include pybind11/include/pybind11 *.h
 recursive-include pybind11 *.py
+recursive-include pybind11 py.typed
+recursive-include pybind11 *.pyi
 include pybind11/share/cmake/pybind11/*.cmake
 include LICENSE README.rst pyproject.toml setup.py setup.cfg

pybind11/__main__.py

@@ -9,6 +9,7 @@
 
 
 def print_includes():
+    # type: () -> None
     dirs = [
         sysconfig.get_path("include"),
         sysconfig.get_path("platinclude"),
@@ -18,13 +19,15 @@ def print_includes():
     # Make unique but preserve order
     unique_dirs = []
     for d in dirs:
-        if d not in unique_dirs:
+        if d and d not in unique_dirs:
             unique_dirs.append(d)
 
     print(" ".join("-I" + d for d in unique_dirs))
 
 
 def main():
+    # type: () -> None
+
     parser = argparse.ArgumentParser()
     parser.add_argument(
         "--includes",

pybind11/_version.pyi

@@ -0,0 +1,6 @@
+from typing import Union, Tuple
+
+def _to_int(s: str) -> Union[int, str]: ...
+
+__version__: str
+version_info: Tuple[Union[int, str], ...]

pybind11/commands.py

@@ -6,12 +6,14 @@
 
 
 def get_include(user=False):
+    # type: (bool) -> str
     installed_path = os.path.join(DIR, "include")
     source_path = os.path.join(os.path.dirname(DIR), "include")
     return installed_path if os.path.exists(installed_path) else source_path
 
 
 def get_cmake_dir():
+    # type: () -> str
     cmake_installed_path = os.path.join(DIR, "share", "cmake", "pybind11")
     if os.path.exists(cmake_installed_path):
         return cmake_installed_path

pybind11/setup_helpers.pyi

@@ -0,0 +1,47 @@
+from typing import Any, Iterator, Optional, Type, TypeVar, Union
+from types import TracebackType
+
+from distutils.command.build_ext import build_ext as _build_ext  # type: ignore
+from distutils.extension import Extension as _Extension
+import distutils.ccompiler
+import contextlib
+
+WIN: bool
+PY2: bool
+MACOS: bool
+STD_TMPL: str
+
+class Pybind11Extension(_Extension):
+    def _add_cflags(self, *flags: str) -> None: ...
+    def _add_lflags(self, *flags: str) -> None: ...
+    def __init__(
+        self, *args: Any, cxx_std: int = 0, language: str = "c++", **kwargs: Any
+    ) -> None: ...
+    @property
+    def cxx_std(self) -> int: ...
+    @cxx_std.setter
+    def cxx_std(self, level: int) -> None: ...
+
+@contextlib.contextmanager
+def tmp_chdir() -> Iterator[str]: ...
+def has_flag(compiler: distutils.ccompiler.CCompiler, flag: str) -> bool: ...
+def auto_cpp_level(compiler: distutils.ccompiler.CCompiler) -> Union[int, str]: ...
+
+class build_ext(_build_ext):  # type: ignore
+    def build_extensions(self) -> None: ...
+
+T = TypeVar("T", bound="ParallelCompile")
+
+class ParallelCompile:
+    def __init__(
+        self, envvar: Optional[str] = None, default: int = 0, max: int = 0
+    ): ...
+    def function(self) -> Any: ...
+    def install(self: T) -> T: ...
+    def __enter__(self: T) -> T: ...
+    def __exit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc_value: Optional[BaseException],
+        traceback: Optional[TracebackType],
+    ) -> None: ...

setup.cfg

@@ -64,3 +64,7 @@ ignore =
     N813
     # Black conflict
     W503, E203
+
+[mypy]
+files = pybind11
+strict = True

tests/extra_python_package/test_files.py

@@ -58,8 +58,11 @@
     "__init__.py",
     "__main__.py",
     "_version.py",
+    "_version.pyi",
     "commands.py",
+    "py.typed",
     "setup_helpers.py",
+    "setup_helpers.pyi",
 }
 
 headers = main_headers | detail_headers

tools/libsize.py

@@ -19,7 +19,7 @@
 
 libsize = os.path.getsize(lib)
 
-print("------", os.path.basename(lib), "file size:", libsize, end='')
+print("------", os.path.basename(lib), "file size:", libsize, end="")
 
 if os.path.exists(save):
     with open(save) as sf:
@@ -34,5 +34,5 @@
 else:
     print()
 
-with open(save, 'w') as sf:
+with open(save, "w") as sf:
     sf.write(str(libsize))

tools/setup_main.py.in

@@ -19,6 +19,7 @@ setup(
         "pybind11.share.cmake.pybind11",
     ],
     package_data={
+        "pybind11": ["py.typed", "*.pyi"],
         "pybind11.include.pybind11": ["*.h"],
         "pybind11.include.pybind11.detail": ["*.h"],
         "pybind11.share.cmake.pybind11": ["*.cmake"],