[ci] [python-package] replace 'python setup.py' with a shell script

[jameslamb]

Contributes to #5061.

This PR proposes replacing all existing direct invocations of python setup.py with a shell script, build-python-package.sh.

What will the use experience be like?

For people using pip install or conda install, this PR does not change anything.

Anyone currently building / installing the Python package from sources here on GitHub using commands like the following:

cd python-package
python setup.py {command} [OPTIONS]

Would now instead run

sh ./build-python.sh {command} [OPTIONS]

Why a shell script?

Most Python build tools (e.g. wheel, build, pip wheel, scikit-build, hatchling, etc.) assume a directory structure with all source files at or below the level of where the tool is called from. This repo contains more than just a Python package, and so it can't be directly used that way.

This project currently solves that problem via Python code in a setup.py file which reaches up into the parent directory and copying files at build time.

LightGBM/python-package/setup.py

Lines 61 to 68 in f74875e

	if not IS_SOURCE_FLAG_PATH.is_file():
	copy_files_helper('include')
	copy_files_helper('src')
	for submodule in (CURRENT_DIR.parent / 'external_libs').iterdir():
	submodule_stem = submodule.stem
	if submodule_stem == 'compute' and not use_gpu:
	continue
	copy_files_helper(Path('external_libs') / submodule_stem)

As described #5061, the Python packaging community is moving away from supporting such setup.py invocations.

I'm proposing that we use an sh-compatible shell script to create an isolated source directory prior to invoking any Python build tools for the following reasons:

• that approach has been working well for the R package for 2+ years (since [R-package] Create portable configuration with 'configure' scripts #2960)
• sh is highly portable
• allows maximum flexibility to change the strategy for how the package is built in the future without affecting users
  • e.g., enables work in a followup PR to switch from setup.py to something like scikit-build-core (which I'm working on in [python-package] [ci] switch to PEP 517 / 518 builds (remove setup.py) (fixes #5061) #5759) or hatchling (like XGBoost is trying in Replace setup.py with pyproject.toml dmlc/xgboost#9021)
  • really important, I think, given how quickly the Python packaging tools are evolving

How I tested this

In addition to all off the checks run in CI, I did the following:

• ran many combinations of the commands and options for this new script locally on my Mac
• checked the sdist and wheel contents using pydistcheck, to confirm that they have the same contents as those built on main, and are the same size
  • reference: [ci] [python-package] check distributions with pydistcheck #5838

[jameslamb]

This was originally put in to work around the following error using mingw32-make.exe + CMake:

CMake Error at C:/Program Files (x86)/CMake/share/cmake-3.16/Modules/CMakeMinGWFindMake.cmake:12 (message):
  sh.exe was found in your PATH, here:
  C:/Program Files/Git/usr/bin/sh.exe
  For MinGW make to work correctly sh.exe must NOT be in your path.
  Run cmake from a shell that does not have sh.exe in your PATH.
  If you want to use a UNIX shell, then use MSYS Makefiles.
Call Stack (most recent call first):
  CMakeLists.txt:39 (project)

If we're going to encourage the use of a shell script to build a development version of the package, that's a problem.

Thankfully, I found that passing a flag through to CMake that says "don't worry, I'm confident having sh.exe on PATH won't be a problem" (as suggested in this Stack Overflow post) works for LightGBM's Python build!

[jameslamb]

All of this copying-files-around stuff is unnecessary now the setup.py will only be invoked from the root of a directory containing all of the C/C++ source files + CMake scripts in the expected places.

[jameslamb]

see the successful Appveyor MinGW build for evidence that this works: https://ci.appveyor.com/project/guolinke/lightgbm/builds/46835500/job/a4uo45pxxl8gwwti

[jameslamb]

this pattern allows both of these invocations to work corrrectly:

sh ./build-python.sh bdist_wheel --boost-include-dir /usr/local/src/Boost/include
sh ./build-python.sh bdist_wheel --boost-include-dir=/usr/local/src/Boost/include

as suggested here: https://unix.stackexchange.com/a/580258/550004

[jameslamb]

Alright I'm excited to say that this is ready for review!

If other maintainers agree with this proposal, it'll be a big step towards finally resolving #5061, and I think it'll make the next PR proposing the use of scikit-build-core a bit easier to review.

Since this is a significant breaking change, I'd ideally like approvals from all 3 of @shiyu1994 @guolinke and @jmoralez whenever you have time. Thank you for considering it!

[jameslamb]

@guolinke could you look through this and let me know what you think?

I know that removing the ability to run python setup.py {command} will be disruptive for some users but I think that that's going to be forced on us eventually by the Python packaging tools like setuptools and wheel, based on all the documentation in #5061, and that switching to a shell script means we'll never have to break "build the Python package from git sources" this way again.

[guolinke]

Sorry for missing this PR, will check it today

[jameslamb]

Thanks for the help everyone! This is a painful but I think necessary step towards keeping lightgbm up to date with changes in Python packaging practices.

And I hope this'll also be a step towards unlocking some other features that newer build systems offer, like cross-compilation for platforms we don't currently publish wheels for.

I strongly suspect that this one is going to be found from search engines, so after merging I'm going to lock discussion on this PR.

If you are reading this comment right now and want to say or ask something about this change, please comment on #5061 or open a new issue.