Use pybind11-stubgen to create typestubs for extensions

.github/workflows/cmake.yml

@@ -31,8 +31,21 @@ jobs:
             libbz2-dev \
             ninja-build \
             software-properties-common
+      - name: Install Python 3.12 with the latest version of uv.
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: '3.12'
       - uses: actions/checkout@v4
+      - name: Create venv and install build dependencies
+        run: |
+          uv venv --isolated
+          source .venv/bin/activate
+          uv pip install scikit-build-core~=0.10 numpy pybind11-stubgen pybind11~=2.2 setuptools-scm~=9.2.2
       - name: Check CMake configure
-        run: cmake -B build -G Ninja
+        run: |
+          source .venv/bin/activate
+          cmake -B build -G Ninja
       - name: CMake build
-        run: cmake --build build
+        run: |
+          source .venv/bin/activate
+          cmake --build build

CMakeLists.txt

@@ -69,6 +69,8 @@ message(STATUS "HACKDIR set to: ${HACKDIR}")
 set(VARDIR ${HACKDIR})
 set(INSTDIR ${HACKDIR})
 
+# Use FindPython in PyBind11 to find Python.
+set(PYBIND11_FINDPYTHON NEW)
 # pybind11 via FetchContent
 include(FetchContent)
 FetchContent_Declare(
@@ -77,6 +79,7 @@ FetchContent_Declare(
   GIT_TAG v3.0.1
   EXCLUDE_FROM_ALL)
 FetchContent_MakeAvailable(pybind11)
+message(STATUS "Python_EXECUTABLE is set to: ${Python_EXECUTABLE}")
 
 # de-boost-ified version of boost.context via FetchContent
 FetchContent_Declare(
@@ -222,15 +225,47 @@ set_target_properties(_pyconverter PROPERTIES CXX_STANDARD 14)
 target_include_directories(
   _pyconverter PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/third_party/converter)
 
+set(STUB_DIR ${CMAKE_CURRENT_BINARY_DIR}/stubs)
+set_directory_properties(PROPERTIES ADDITIONAL_CLEAN_FILES "${STUB_DIR}")
+add_custom_command(
+  OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/stubs/nle/_pyconverter.pyi
+  COMMAND ${Python_EXECUTABLE} -m pybind11_stubgen _pyconverter --output-dir
+          ${STUB_DIR}
+  WORKING_DIRECTORY $<TARGET_FILE_DIR:_pyconverter>
+  DEPENDS _pyconverter
+  COMMENT "Generating type stubs ..."
+  VERBATIM)
+
+add_custom_command(
+  OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/stubs/nle/_pynethack/__init__.pyi
+  COMMAND ${Python_EXECUTABLE} -m pybind11_stubgen _pynethack --output-dir
+          ${STUB_DIR} --ignore-unresolved-names game_end_types
+  WORKING_DIRECTORY $<TARGET_FILE_DIR:_pynethack>
+  DEPENDS _pynethack
+  COMMENT "Generating type stubs ..."
+  VERBATIM)
+
+add_custom_target(
+  my_module_stubs ALL
+  DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/stubs/nle/_pynethack/__init__.pyi
+          ${CMAKE_CURRENT_BINARY_DIR}/stubs/nle/_pyconverter.pyi)
+
 set(TILE_FILES "win/share/monsters.txt" "win/share/objects.txt"
                "win/share/other.txt")
 
 install(FILES ${TILE_FILES} DESTINATION ${INSTDIR}/tiles)
+
 # Only install if we are building as part of a Python project.
 if(DEFINED SKBUILD_PROJECT_VERSION)
   install(
     TARGETS _pynethack _pyconverter nethack
     RUNTIME DESTINATION ${PYTHON_PACKAGE_NAME}
     LIBRARY DESTINATION ${PYTHON_PACKAGE_NAME}
     ARCHIVE DESTINATION ${PYTHON_PACKAGE_NAME})
+
+  install(
+    DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/stubs/"
+    DESTINATION ${PYTHON_PACKAGE_NAME}
+    FILES_MATCHING
+    PATTERN "*.pyi")
 endif()

pyproject.toml

@@ -28,9 +28,16 @@ file = "LICENSE"
 [project.urls]
 Homepage = "https://github.com/NetHack-LE/nle"
 
+
 [build-system]
 # Lock build-deps as uv does not yet support locking of build deps: astral-sh/uv#5190
-requires = ["scikit-build-core~=0.10", "pybind11~=2.2", "setuptools-scm~=9.2.2"]
+requires = [
+  "scikit-build-core~=0.10",
+  "numpy",
+  "pybind11-stubgen",
+  "pybind11~=2.2",
+  "setuptools-scm~=9.2.2",
+]
 build-backend = "scikit_build_core.build"
 
 [tool.scikit-build]