fix: use system Python with --target for Windows embeddable builds

The embeddable Python distribution lacks development headers (Python.h)
required to compile native extensions. When using the embeddable Python's
pip directly, packages with native code fail to build with:

  fatal error C1083: Cannot open include file: 'Python.h'

This fix uses the system Python (which has headers) to compile packages,
while directing the output to the embeddable Python's site-packages
directory using pip's --target flag.

Changes:
- build-windows-executable-app.yaml: Use system Python with --target,
  remove unnecessary pip installation in embeddable Python
- test-win-exe-w-embed-py.yaml: Add setup-python action, use system
  Python with --target, remove pip installation step
- docs/win_exe_with_embed_py.md: Add prerequisites section explaining
  the need for system Python, update install command to use --target

https://claude.ai/code/session_0152zcfBS5dWLtM12ubuYrKC

Author: claude

.github/workflows/build-windows-executable-app.yaml

@@ -235,18 +235,15 @@ jobs:
         cp $PYTHON_DIR/DLLs/tcl86t.dll $EMBED_DIR/
         cp $PYTHON_DIR/DLLs/tk86t.dll $EMBED_DIR/
 
-    - name: Install pip
-      run: |
-        curl -O https://bootstrap.pypa.io/get-pip.py
-        ./python-${{ env.PYTHON_VERSION }}/python get-pip.py --no-warn-script-location
-        rm get-pip.py
-
     - name: Uncomment 'import site' in python311._pth file
       run: |
         sed -i 's/#import site/import site/' python-${{ env.PYTHON_VERSION }}/python311._pth
 
     - name: Install Required Packages
-      run: .\python-${{ env.PYTHON_VERSION }}\python -m pip install --force-reinstall -r requirements.txt --no-warn-script-location
+      # Use system Python (which has development headers) to compile packages,
+      # installing into the embeddable Python's site-packages directory.
+      # The embeddable Python lacks Python.h headers needed for native extensions.
+      run: python -m pip install -r requirements.txt --target python-${{ env.PYTHON_VERSION }}/Lib/site-packages --upgrade --no-warn-script-location
 
     - name: Set to offline deployment
       run: |

.github/workflows/test-win-exe-w-embed-py.yaml

@@ -17,29 +17,31 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
 
+      - name: Set up Python (regular distribution)
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }} # Use the same version as the embeddable version
+
       - name: Download python embeddable version
         run: |
           mkdir python-${{ env.PYTHON_VERSION }}
           curl -O https://www.python.org/ftp/python/${{ env.PYTHON_VERSION }}/python-${{ env.PYTHON_VERSION }}-embed-amd64.zip
           unzip python-${{ env.PYTHON_VERSION }}-embed-amd64.zip -d python-${{ env.PYTHON_VERSION }}
           rm python-${{ env.PYTHON_VERSION }}-embed-amd64.zip
 
-      - name: Install pip
-        run: |
-          curl -O https://bootstrap.pypa.io/get-pip.py
-          ./python-${{ env.PYTHON_VERSION }}/python get-pip.py --no-warn-script-location
-          rm get-pip.py
-          
       - name: Uncomment 'import site' in python311._pth file
         run: |
           sed -i 's/#import site/import site/' python-${{ env.PYTHON_VERSION }}/python311._pth
-          
+
       - name: Print content of python311._pth file
         run: |
           cat python-${{ env.PYTHON_VERSION }}/python311._pth
 
       - name: Install Required Packages
-        run: .\python-${{ env.PYTHON_VERSION }}\python -m pip install -r requirements.txt --no-warn-script-location
+        # Use system Python (which has development headers) to compile packages,
+        # installing into the embeddable Python's site-packages directory.
+        # The embeddable Python lacks Python.h headers needed for native extensions.
+        run: python -m pip install -r requirements.txt --target python-${{ env.PYTHON_VERSION }}/Lib/site-packages --upgrade --no-warn-script-location
 
       - name: Create .bat file
         run: |

docs/win_exe_with_embed_py.md

@@ -3,6 +3,12 @@
 To create an executable for Streamlit app on Windows, we'll use an embeddable version of Python.</br>
 Here's a step-by-step guide:
 
+### Prerequisites
+
+You need a **system Python installation** (the regular Python installer from python.org) of the same version as the embeddable Python you'll download. This is required because the embeddable Python lacks development headers (`Python.h`) needed to compile native extensions.
+
+Install Python 3.11.9 from https://www.python.org/downloads/ if you don't have it already.
+
 ### Download and Extract Python Embeddable Version
 
 1. Download a suitable Python embeddable version. For example, let's download Python 3.11.9:
@@ -22,24 +28,6 @@ Here's a step-by-step guide:
    rm python-3.11.9-embed-amd64.zip
    ```
 
-### Install pip
-
-1. Download `get-pip.py`:
-
-   ```bash
-   # use curl command or manually download
-   curl -O https://bootstrap.pypa.io/get-pip.py
-   ```
-
-2. Install pip:
-
-   ```bash
-   ./python-3.11.9/python get-pip.py --no-warn-script-location
-
-   # no need anymore get-pip.py
-   rm get-pip.py
-   ```
-
 ### Configure Python Environment
 
 1. Uncomment 'import site' in the `._pth` file:
@@ -55,12 +43,20 @@ Here's a step-by-step guide:
 
 ### Install Required Packages
 
-Install all required packages from `requirements.txt`:
+Install all required packages from `requirements.txt` using the **system Python** with `--target` to install into the embeddable Python's site-packages:
 
 ```bash
-./python-3.11.9/python -m pip install -r requirements.txt --no-warn-script-location
+# Use system Python (which has development headers) to compile packages,
+# installing into the embeddable Python's site-packages directory.
+# The embeddable Python lacks Python.h headers needed for native extensions.
+python -m pip install -r requirements.txt --target python-3.11.9/Lib/site-packages --upgrade --no-warn-script-location
 ```
 
+> **Important**: Do NOT use `./python-3.11.9/python -m pip install ...` directly. The embeddable Python lacks the development headers required to compile native extensions (e.g., `Python.h`), which will cause builds to fail with errors like:
+> ```
+> fatal error C1083: Cannot open include file: 'Python.h': No such file or directory
+> ```
+
 ### Test and create `run_app.bat` file
 
 1. Test by running app