feat(tools): allow to specify python binary by ESP_PYTHON_CUSTOM environment… (IDFGH-16803)

docs/en/api-guides/tools/idf-tools.rst

@@ -161,7 +161,7 @@ Shell-specific user-facing installation scripts are provided in the root directo
 * ``install.sh`` for Bash
 * ``install.fish`` for Fish
 
-Apart from downloading and installing the tools in ``IDF_TOOLS_PATH``, these scripts prepare a Python virtual environment, and install the required packages into that environment.
+Apart from downloading and installing the tools in ``IDF_TOOLS_PATH``, these scripts prepare a Python virtual environment, and install the required packages into that environment. If you want to specify a particular Python for ESP-IDF, you need to set environment variable ``ESP_PYTHON`` before installation and each time before use. For example ``export ESP_PYTHON=/opt/bin/python3.13``.
 
 These scripts accept optionally a comma-separated list of chip targets and ``--enable-*`` arguments for enabling features. These arguments are passed to the ``idf_tools.py`` script which stores them in ``idf-env.json``. Therefore, chip targets and features can be enabled incrementally.
 

docs/en/get-started/linux-macos-setup.rst

@@ -116,6 +116,8 @@ To install supported Python 3 on macOS:
 
     During installation, the install script will check for supported Python versions on your system and select the oldest version that meets the minimum requirement.
 
+If you want to specify a particular Python for ESP-IDF, you need to set environment variable ``ESP_PYTHON`` before installation and each time before use. For example ``export ESP_PYTHON=/opt/bin/python3.13``.
+
 .. _get-started-get-esp-idf:
 
 Step 2. Get ESP-IDF

docs/zh_CN/api-guides/tools/idf-tools.rst

@@ -161,7 +161,7 @@ ESP-IDF 的根目录中提供了针对不同 shell 的用户安装脚本，包
 * ``install.sh`` 适用于 Bash
 * ``install.fish`` 适用于 Fish
 
-这些脚本除了下载和安装 ``IDF_TOOLS_PATH`` 中的工具外，还会准备一个 Python 虚拟环境，并在此虚拟环境中安装所需软件包。
+这些脚本除了下载和安装 ``IDF_TOOLS_PATH`` 中的工具外，还会准备一个 Python 虚拟环境，并在此虚拟环境中安装所需软件包。如果要指定 ESP-IDF 使用特定的 Python ，则需要在安装之前及每次使用之前设置环境变量 ``ESP_PYTHON``，例如 ``export ESP_PYTHON=/opt/bin/python3.13``。
 
 为启用相应功能，这些脚本可以选择性地接受一组以逗号分隔的芯片目标列表及 ``--enable-*`` 参数，这类参数会传递给 ``idf_tools.py`` 脚本，并由该脚本将这类参数存储在 ``idf-env.json`` 中，从而逐步启用芯片目标及功能。
 

docs/zh_CN/get-started/linux-macos-setup.rst

@@ -115,6 +115,8 @@ Apple M1 用户
 .. note::
 
     安装过程中，安装脚本 (install.sh) 会检查系统中已安装的 Python 版本，并在所有符合最低要求的版本中，选择最早的版本使用。
+
+如果要指定 ESP-IDF 使用特定的 Python ，则需要在安装之前及每次使用之前设置环境变量 ``ESP_PYTHON``，例如 ``export ESP_PYTHON=/opt/bin/python3.13``。
 
 .. _get-started-get-esp-idf:
 

tools/detect_python.fish

@@ -5,20 +5,27 @@
 set OLDEST_PYTHON_SUPPORTED_MAJOR 3
 set OLDEST_PYTHON_SUPPORTED_MINOR 10
 
-set -x ESP_PYTHON python
+if test -z "$ESP_PYTHON"
+    set PYTHON_CANDIDATES python3 python python3.10 python3.11 python3.12 python3.13
+else
+    echo "Reading ESP_PYTHON from environment: \"$ESP_PYTHON\""
+    set PYTHON_CANDIDATES $ESP_PYTHON
+end
+set -e ESP_PYTHON  # Unset it. Will assign after candidate check
 
-for p_cmd in python3 python python3.10 python3.11 python3.12 python3.13;
+for p_cmd in $PYTHON_CANDIDATES
     $p_cmd --version >/dev/null 2>&1; or continue
     echo "Checking \"$p_cmd\" ..."
 
     $p_cmd -c "import sys; exit(1) if sys.version_info.major < int(\"$OLDEST_PYTHON_SUPPORTED_MAJOR\") else exit(0);"; or continue
     $p_cmd -c "import sys; exit(1) if sys.version_info.minor < int(\"$OLDEST_PYTHON_SUPPORTED_MINOR\") else exit(0);"; or continue
 
-    set ESP_PYTHON $p_cmd
+    set -x ESP_PYTHON $p_cmd
     break
 end
+set -e PYTHON_CANDIDATES
 
-test -n "$ESP_PYTHON"; or echo "Python $OLDEST_PYTHON_SUPPORTED_MAJOR.$OLDEST_PYTHON_SUPPORTED_MINOR+ is not installed! Please see the documentation for how to install it."
+test -n "$ESP_PYTHON"; or echo "Python $OLDEST_PYTHON_SUPPORTED_MAJOR.$OLDEST_PYTHON_SUPPORTED_MINOR+ is not installed! Please see the documentation for how to install it." >&2
 test -n "$ESP_PYTHON"; or exit 1
 
 $ESP_PYTHON --version

tools/detect_python.sh

@@ -3,28 +3,36 @@
 # This is a helper script for detecting Python executables in the PATH. It is intended to be used for determining
 # which Python should be used with idf_tools.py for installing tools and exporting environment variables.
 #
-# 1. The script is looking for python version same or greater than minimal required version on path
+# 1. If environment variable ESP_PYTHON already set, script uses that python binary, otherwise, looks for python version same or greater than minimal required version on path
 # 2. If required version of python is found it is assigned to environmental variable `ESP_PYTHON`
 # 3. If required version of python is not found, script will fail
 
 OLDEST_PYTHON_SUPPORTED_MAJOR=3
 OLDEST_PYTHON_SUPPORTED_MINOR=10
 
-ESP_PYTHON=python
 
-for p_cmd in python3 python python3.10 python3.11 python3.12 python3.13; do
-    $p_cmd --version >/dev/null 2>&1 || continue
+if [[ -z "$ESP_PYTHON" ]]; then
+    PYTHON_CANDIDATES=(python3 python python3.10 python3.11 python3.12 python3.13)
+else
+    echo "Reading ESP_PYTHON from environment: \"$ESP_PYTHON\""
+    PYTHON_CANDIDATES=("$ESP_PYTHON")
+fi
+ESP_PYTHON=  # Unset it. Will assign after candidate check
+
+for p_cmd in "${PYTHON_CANDIDATES[@]}"; do
+    "$p_cmd" --version >/dev/null 2>&1 || continue
     echo "Checking \"$p_cmd\" ..."
 
-    $p_cmd -c "import sys; exit(1) if sys.version_info.major < int(\"$OLDEST_PYTHON_SUPPORTED_MAJOR\") else exit(0);" || continue
-    $p_cmd -c "import sys; exit(1) if sys.version_info.minor < int(\"$OLDEST_PYTHON_SUPPORTED_MINOR\") else exit(0);" || continue
+    "$p_cmd" -c "import sys; exit(1) if sys.version_info.major < int(\"$OLDEST_PYTHON_SUPPORTED_MAJOR\") else exit(0);" || continue
+    "$p_cmd" -c "import sys; exit(1) if sys.version_info.minor < int(\"$OLDEST_PYTHON_SUPPORTED_MINOR\") else exit(0);" || continue
 
-    ESP_PYTHON=$p_cmd
+    export ESP_PYTHON="$p_cmd"
     break
 done
+unset PYTHON_CANDIDATES
 
-$ESP_PYTHON --version 2>/dev/null || {
-    echo "Python ${OLDEST_PYTHON_SUPPORTED_MAJOR}.${OLDEST_PYTHON_SUPPORTED_MINOR}+ is not installed! Please see the documentation for how to install it."
+[[ -n "$ESP_PYTHON" ]] &&  "$ESP_PYTHON" --version 2>/dev/null || {
+    echo "Python ${OLDEST_PYTHON_SUPPORTED_MAJOR}.${OLDEST_PYTHON_SUPPORTED_MINOR}+ is not installed! Please see the documentation for how to install it." >&2
     exit 1
 }
 echo "\"$ESP_PYTHON\" has been detected"