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_CUSTOM`` before installation and each time before use. For example ``export ESP_PYTHON_CUSTOM=/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_CUSTOM`` before installation and each time before use. For example ``export ESP_PYTHON_CUSTOM=/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_CUSTOM``，例如 ``export ESP_PYTHON_CUSTOM=/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_CUSTOM``，例如 ``export ESP_PYTHON_CUSTOM=/opt/bin/python3.13``。
 
 .. _get-started-get-esp-idf:
 

export.fish

@@ -16,7 +16,7 @@ if not test -f "$idf_path/tools/idf.py"
     exit 1
 end
 
-source "$idf_path"/tools/detect_python.fish
+source "$idf_path"/tools/detect_python.fish || return 1
 
 eval ("$ESP_PYTHON" "$idf_path"/tools/activate.py --export)
 set -e idf_path

export.sh

@@ -53,7 +53,7 @@ then
     return 1
 fi
 
-. "${idf_path}/tools/detect_python.sh"
+. "${idf_path}/tools/detect_python.sh" || return 1
 
 # Evaluate the ESP-IDF environment set up by the activate.py script.
 idf_exports=$("$ESP_PYTHON" "${idf_path}/tools/activate.py" --export --shell $shell_type)

install.fish

@@ -7,7 +7,7 @@ set -x IDF_PATH $basedir
 echo "INFO: Using IDF_PATH '$IDF_PATH' for installation."
 
 echo "Detecting the Python interpreter"
-source "$IDF_PATH"/tools/detect_python.fish
+source "$IDF_PATH"/tools/detect_python.fish || exit 1
 
 echo "Checking Python compatibility"
 "$ESP_PYTHON" "$IDF_PATH"/tools/python_version_checker.py

install.sh

@@ -10,7 +10,7 @@ export IDF_PATH
 echo "INFO: Using IDF_PATH '${IDF_PATH}' for installation."
 
 echo "Detecting the Python interpreter"
-. "${IDF_PATH}/tools/detect_python.sh"
+. "${IDF_PATH}/tools/detect_python.sh" || exit 1
 
 echo "Checking Python compatibility"
 "${ESP_PYTHON}" "${IDF_PATH}/tools/python_version_checker.py"

tools/detect_python.fish

@@ -2,24 +2,36 @@
 #
 # This is a port of detect_python.sh. More information are provided there.
 
+function detect_python
+
 set OLDEST_PYTHON_SUPPORTED_MAJOR 3
 set OLDEST_PYTHON_SUPPORTED_MINOR 10
 
-set -x ESP_PYTHON python
+if test -z "$ESP_PYTHON_CUSTOM"
+    set PYTHON_CANDIDATES python3 python python3.10 python3.11 python3.12 python3.13
+else
+    echo "Reading ESP_PYTHON_CUSTOM from environment: \"$ESP_PYTHON_CUSTOM\""
+    set PYTHON_CANDIDATES "$ESP_PYTHON_CUSTOM"
+end
 
-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 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 exit 1
+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 return 1
 
 $ESP_PYTHON --version
 echo "$ESP_PYTHON has been detected"
+set -x ESP_PYTHON "$ESP_PYTHON"
+
+end
+detect_python

tools/detect_python.sh

@@ -3,28 +3,48 @@
 # 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_CUSTOM 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
 
+detect_python () {
+
 OLDEST_PYTHON_SUPPORTED_MAJOR=3
 OLDEST_PYTHON_SUPPORTED_MINOR=10
 
-ESP_PYTHON=python
+PYTHON_CANDIDATES="python3
+python
+python3.10
+python3.11
+python3.12
+python3.13"
+
+if [ -n "$ESP_PYTHON_CUSTOM" ]; then
+    echo "Reading ESP_PYTHON_CUSTOM from environment: \"$ESP_PYTHON_CUSTOM\""
+    PYTHON_CANDIDATES="$ESP_PYTHON_CUSTOM"
+fi
 
-for p_cmd in python3 python python3.10 python3.11 python3.12 python3.13; do
-    $p_cmd --version >/dev/null 2>&1 || continue
+while IFS= read -r p_cmd; 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
+    ESP_PYTHON="$p_cmd"
     break
-done
+done << EOF
+$PYTHON_CANDIDATES
+EOF
 
-$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."
-    exit 1
-}
+unset PYTHON_CANDIDATES
+
+if [ -z "$ESP_PYTHON" ]; then
+    echo "Python ${OLDEST_PYTHON_SUPPORTED_MAJOR}.${OLDEST_PYTHON_SUPPORTED_MINOR}+ is not installed! Please see the documentation for how to install it." >&2
+    return 1
+fi
 echo "\"$ESP_PYTHON\" has been detected"
+export ESP_PYTHON
+
+}
+detect_python