GH-49831: [Python] Withhold py.typed from the wheel until stubs are complete

ci/scripts/python_wheel_macos_build.sh

@@ -147,7 +147,8 @@ popd
 
 echo "=== (${PYTHON_VERSION}) Building wheel ==="
 export PYARROW_BUNDLE_ARROW_CPP=ON
-export PYARROW_REQUIRE_STUB_DOCSTRINGS=ON
+# TODO(GH-49831): Re-enable when pyarrow-stubs are shipped in wheels again.
+# export PYARROW_REQUIRE_STUB_DOCSTRINGS=ON
 export PYARROW_WITH_ACERO=${ARROW_ACERO}
 export PYARROW_WITH_AZURE=${ARROW_AZURE}
 export PYARROW_WITH_DATASET=${ARROW_DATASET}

ci/scripts/python_wheel_validate_contents.py

@@ -22,6 +22,11 @@
 import zipfile
 
 
+# TODO(GH-48970): Set to True and remove the temporary absence checks below when
+# pyarrow-stubs are complete and should be shipped in wheels again.
+_STUBS_SHIPPED_IN_WHEEL = False
+
+
 def _count_docstrings(source):
     """Count docstrings in module, function, and class bodies."""
     tree = ast.parse(source)
@@ -54,6 +59,24 @@ def validate_wheel(path):
                 info.filename.split("/")[-1] == filename for info in wheel_zip.filelist
             ), f"{filename} is missing from the wheel."
 
+        if not _STUBS_SHIPPED_IN_WHEEL:
+            assert not any(
+                info.filename == "pyarrow/py.typed" for info in wheel_zip.filelist
+            ), "pyarrow/py.typed must not be present in the wheel."
+
+            wheel_stub_files = sorted(
+                info.filename
+                for info in wheel_zip.filelist
+                if (info.filename.startswith("pyarrow/")
+                    and info.filename.endswith(".pyi"))
+            )
+            assert not wheel_stub_files, (
+                "pyarrow .pyi files must not be present in the wheel: "
+                f"{wheel_stub_files}"
+            )
+            print(f"The wheel: {wheels[0]} seems valid.")
+            return
+
         assert any(
             info.filename == "pyarrow/py.typed" for info in wheel_zip.filelist
         ), "pyarrow/py.typed is missing from the wheel."

ci/scripts/python_wheel_windows_build.bat

@@ -116,7 +116,8 @@ popd
 
 echo "=== (%PYTHON%) Building wheel ==="
 set PYARROW_BUNDLE_ARROW_CPP=ON
-set PYARROW_REQUIRE_STUB_DOCSTRINGS=ON
+rem TODO(GH-49831): Re-enable when pyarrow-stubs are shipped in wheels again.
+rem set PYARROW_REQUIRE_STUB_DOCSTRINGS=ON
 set PYARROW_WITH_ACERO=%ARROW_ACERO%
 set PYARROW_WITH_AZURE=%ARROW_AZURE%
 set PYARROW_WITH_DATASET=%ARROW_DATASET%

ci/scripts/python_wheel_xlinux_build.sh

@@ -157,7 +157,8 @@ check_arrow_visibility
 
 echo "=== (${PYTHON_VERSION}) Building wheel ==="
 export PYARROW_BUNDLE_ARROW_CPP=ON
-export PYARROW_REQUIRE_STUB_DOCSTRINGS=ON
+# TODO(GH-49831): Re-enable when pyarrow-stubs are shipped in wheels again.
+# export PYARROW_REQUIRE_STUB_DOCSTRINGS=ON
 export PYARROW_WITH_ACERO=${ARROW_ACERO}
 export PYARROW_WITH_AZURE=${ARROW_AZURE}
 export PYARROW_WITH_DATASET=${ARROW_DATASET}

python/CMakeLists.txt

@@ -1041,32 +1041,40 @@ endif()
 #
 # Type stubs with docstring injection
 #
+# TODO(GH-49831): Temporarily do not install pyarrow-stubs into wheels.
+# The stubs are incomplete, and some type checkers consume .pyi files even
+# without the py.typed marker. Re-enable this when the stubs are complete.
+if(PYARROW_REQUIRE_STUB_DOCSTRINGS)
+  message(FATAL_ERROR "PYARROW_REQUIRE_STUB_DOCSTRINGS cannot be used while "
+                      "pyarrow-stubs are omitted from wheels (GH-49831).")
+endif()
+#
 # Stubs live in pyarrow-stubs/pyarrow/ during development but are installed
 # alongside the package so type checkers can find them (PEP 561).
-set(PYARROW_STUBS_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/pyarrow-stubs/pyarrow")
-if(EXISTS "${PYARROW_STUBS_SOURCE_DIR}")
-  install(DIRECTORY "${PYARROW_STUBS_SOURCE_DIR}/"
-          DESTINATION "."
-          FILES_MATCHING
-          PATTERN "*.pyi")
-
-  if(PYARROW_REQUIRE_STUB_DOCSTRINGS)
-    install(CODE "
-      execute_process(
-        COMMAND \"${Python3_EXECUTABLE}\"
-                \"${CMAKE_CURRENT_SOURCE_DIR}/scripts/update_stub_docstrings.py\"
-                \"${CMAKE_INSTALL_PREFIX}\"
-                \"${CMAKE_CURRENT_SOURCE_DIR}\"
-        RESULT_VARIABLE _pyarrow_stub_docstrings_result
-      )
-      if(NOT _pyarrow_stub_docstrings_result EQUAL 0)
-        message(FATAL_ERROR \"Stub docstring injection failed (exit code: \${_pyarrow_stub_docstrings_result})\")
-      endif()
-    ")
-  endif()
-else()
-  if(PYARROW_REQUIRE_STUB_DOCSTRINGS)
-    message(FATAL_ERROR "PyArrow stub source directory not found at ${PYARROW_STUBS_SOURCE_DIR}; "
-                        "cannot build wheel without .pyi files.")
-  endif()
-endif()
+# set(PYARROW_STUBS_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/pyarrow-stubs/pyarrow")
+# if(EXISTS "${PYARROW_STUBS_SOURCE_DIR}")
+#   install(DIRECTORY "${PYARROW_STUBS_SOURCE_DIR}/"
+#           DESTINATION "."
+#           FILES_MATCHING
+#           PATTERN "*.pyi")
+#
+#   if(PYARROW_REQUIRE_STUB_DOCSTRINGS)
+#     install(CODE "
+#       execute_process(
+#         COMMAND \"${Python3_EXECUTABLE}\"
+#                 \"${CMAKE_CURRENT_SOURCE_DIR}/scripts/update_stub_docstrings.py\"
+#                 \"${CMAKE_INSTALL_PREFIX}\"
+#                 \"${CMAKE_CURRENT_SOURCE_DIR}\"
+#         RESULT_VARIABLE _pyarrow_stub_docstrings_result
+#       )
+#       if(NOT _pyarrow_stub_docstrings_result EQUAL 0)
+#         message(FATAL_ERROR \"Stub docstring injection failed (exit code: \${_pyarrow_stub_docstrings_result})\")
+#       endif()
+#     ")
+#   endif()
+# else()
+#   if(PYARROW_REQUIRE_STUB_DOCSTRINGS)
+#     message(FATAL_ERROR "PyArrow stub source directory not found at ${PYARROW_STUBS_SOURCE_DIR}; "
+#                         "cannot build wheel without .pyi files.")
+#   endif()
+# endif()

python/pyproject.toml

@@ -88,6 +88,12 @@ metadata.version.provider = "scikit_build_core.metadata.setuptools_scm"
 sdist.include = ["pyarrow/_generated_version.py", "cmake_modules/", "pyarrow-stubs/"]
 wheel.packages = ["pyarrow"]
 wheel.install-dir = "pyarrow"
+# TODO(GH-48970): Remove this when stubfiles are complete
+# Withhold the PEP 561 marker until the type stubs are complete. The .pyi files
+# are also temporarily omitted from wheels, so type checkers don't rely on the
+# incomplete stubs and break downstream users (GH-49831). py.typed is kept
+# in-tree for CI type-checking.
+wheel.exclude = ["pyarrow/py.typed"]
 
 [tool.scikit-build.cmake.define]
 PYARROW_BUNDLE_ARROW_CPP = {env = "PYARROW_BUNDLE_ARROW_CPP", default = "OFF"}