GH-49452: [Python] Reintroduce docstring injection for stubfiles

[rok]

Rationale for this change

Warning: should not be merged before #49259.
See #49452 and #48618

What changes are included in this PR?

Adds a wheel build time script to populate stubfiles with runtime docstrings.

Are these changes tested?

Not yet.

Are there any user-facing changes?

Users will get docstrings.

• GitHub Issue: [Python] Reintroduce docstring injection for stubfiles #49452

[github-actions]

⚠️ GitHub issue #49452has been automatically assigned in GitHub to PR creator.

[rok]

@raulcd this is ready for review

[raulcd]

@github-actions crossbow submit wheel*-cp313-*

[github-actions]

Revision: f885111

Submitted crossbow builds: ursacomputing/crossbow @ actions-c1678cd8dd

Task	Status
wheel-macos-monterey-cp313-cp313-amd64
wheel-macos-monterey-cp313-cp313-arm64
wheel-macos-monterey-cp313-cp313t-amd64
wheel-macos-monterey-cp313-cp313t-arm64
wheel-manylinux-2-28-cp313-cp313-amd64
wheel-manylinux-2-28-cp313-cp313-arm64
wheel-manylinux-2-28-cp313-cp313t-amd64
wheel-manylinux-2-28-cp313-cp313t-arm64
wheel-musllinux-1-2-cp313-cp313-amd64
wheel-musllinux-1-2-cp313-cp313-arm64
wheel-musllinux-1-2-cp313-cp313t-amd64
wheel-musllinux-1-2-cp313-cp313t-arm64
wheel-windows-cp313-cp313-amd64
wheel-windows-cp313-cp313t-amd64

[raulcd]

@rok the new check on the ci/scripts/python_wheel_validate_contents.py doesn't seem to work :(

[rok]

@github-actions crossbow submit wheel*-cp313-*

[github-actions]

Revision: 10509c4

Submitted crossbow builds: ursacomputing/crossbow @ actions-f3f679ce77

Task	Status
wheel-macos-monterey-cp313-cp313-amd64
wheel-macos-monterey-cp313-cp313-arm64
wheel-macos-monterey-cp313-cp313t-amd64
wheel-macos-monterey-cp313-cp313t-arm64
wheel-manylinux-2-28-cp313-cp313-amd64
wheel-manylinux-2-28-cp313-cp313-arm64
wheel-manylinux-2-28-cp313-cp313t-amd64
wheel-manylinux-2-28-cp313-cp313t-arm64
wheel-musllinux-1-2-cp313-cp313-amd64
wheel-musllinux-1-2-cp313-cp313-arm64
wheel-musllinux-1-2-cp313-cp313t-amd64
wheel-musllinux-1-2-cp313-cp313t-arm64
wheel-windows-cp313-cp313-amd64
wheel-windows-cp313-cp313t-amd64

[rok]

Thanks for the review @raulcd, I've pushed some changes, can you check if this now makes sense?

[rok]

@kou could you do a pass here too? Especially feedback on CMake changes would be valuable :).

[kou]

+1

[raulcd]

Thanks @rok this looks simpler now, thanks for the improvements. I have a nit about a possibly unnecessary warning appearing everywhere.

[raulcd]

This will happen for everything not only for wheels, I am wondering whether we want this warning at all we already have the checks for the wheels and we are setting PYARROW_REQUIRE_STUB_DOCSTRINGS on those. The validation of the wheel will fail if files are not present and this warning will appear every time we build locally now. Probably we can just remove the else case here?

Suggested change

	message(WARNING "PyArrow stub source directory not found at ${PYARROW_STUBS_SOURCE_DIR}; "
	"wheel will be built without .pyi files.")
	message(WARNING "PyArrow stub source directory not found at ${PYARROW_STUBS_SOURCE_DIR}; "
	"PyArrow will be built without .pyi files.")

[rok]

Good point! I removed the else clause now, so we don't get too much noise.

[rok]

Thanks for reviews @raulcd@kou! Will merge when CI passes.

[conbench-apache-arrow]

After merging your PR, Conbench analyzed the 3 benchmarking runs that have been run so far on merge-commit 0a2a0c7.

There were no benchmark performance regressions. 🎉

The full Conbench report has more details. It also includes information about 37 possible false positives for unstable benchmarks that are known to sometimes produce them.