Merge bitcoin/bitcoin#31421: cmake: Improve compatibility with Python version managers

dead908 cmake: Improve compatibility with Python version managers (Hennadii Stepanov)

Pull request description:

  This PR resolves the issue [highlighted](bitcoin/bitcoin#31411 (comment)) in bitcoin/bitcoin#31411:
  > Here's another case where CMake just picks some other Python...

  The fix leverages two [hints](https://cmake.org/cmake/help/latest/module/FindPython3.html#hints) for the CMake `FindPython3` module:
  1. `Python3_FIND_FRAMEWORK` is set to `LAST`. This ensures that Unix-style package components are preferred over frameworks on macOS. As a side effect, the `FindPython3` module reports a shim or symlink (e.g., from `pyenv`) rather than the underlying framework's binary.  The module's output aligns with the result of the `which` command.
  2. `Python3_FIND_UNVERSIONED_NAMES` is set to `FIRST`. This supports scenarios where tools like `pyenv`—which use shims—have multiple Python versions installed.

  Here are examples of output on my macOS 15.1.1 (Intel) with installed Homebrew's [Python 3.13.0](https://formulae.brew.sh/formula/[email protected]):
  - without any Python version manager:
  ```
  % which -a python3
  /usr/local/bin/python3
  /usr/bin/python3
  % cmake -B build
  <snip>
  -- Found Python3: /usr/local/bin/python3 (found suitable version "3.13.0", minimum required is "3.10") found components: Interpreter
  <snip>
  ```
  - using `pyenv`:
  ```
  % pyenv versions
    system
  * 3.10.14 (set by /Users/hebasto/dev/bitcoin/.python-version)
    3.12.8
    3.13.1
  % which -a python3
  /Users/hebasto/.pyenv/shims/python3
  /usr/local/bin/python3
  /usr/bin/python3
  % cmake -B build
  <snip>
  -- Found Python3: /Users/hebasto/.pyenv/shims/python3 (found suitable version "3.10.14", minimum required is "3.10") found components: Interpreter
  <snip>
  ```

  Both variables, `Python3_FIND_FRAMEWORK` and `Python3_FIND_UNVERSIONED_NAMES`, can still be overridden by the user via the command line if needed.

ACKs for top commit:
  theuni:
    No opinion on the python selection changes themselves, but code-review ACK dead908
  willcl-ark:
    ACK dead908

Tree-SHA512: 69f8541223e5b6c35c892b4ba2a2dcfc24b41a10cf20accc75d3008b16434db8a9240c99c886c3a4566ba24269c5b0e0d856357891811f0a77b39f4afbee3634

Author: fanquake

CMakeLists.txt

@@ -560,6 +560,13 @@ if(WERROR)
   unset(werror_flag)
 endif()
 
+# Prefer Unix-style package components over frameworks on macOS.
+# This improves compatibility with Python version managers.
+set(Python3_FIND_FRAMEWORK LAST CACHE STRING "")
+# Search for generic names before more specialized ones. This
+# improves compatibility with Python version managers that use shims.
+set(Python3_FIND_UNVERSIONED_NAMES FIRST CACHE STRING "")
+mark_as_advanced(Python3_FIND_FRAMEWORK Python3_FIND_UNVERSIONED_NAMES)
 find_package(Python3 3.10 COMPONENTS Interpreter)
 if(Python3_EXECUTABLE)
   set(PYTHON_COMMAND ${Python3_EXECUTABLE})