refactor pip example to use requirements.txt and install Drake from s…

…cript

.github/workflows/pip.yml

@@ -27,11 +27,13 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: '3.12'
+      - name: venv setup and install
+        working-directory: drake_pip
+        run: setup/setup_env 3.12
+        shell: zsh -eufo pipefail {0}
       - name: pip build and test
         working-directory: drake_pip
         run: .github/ci_build_test
-        env:
-          PYTHON_VERSION: '3.12'
         shell: zsh -efuo pipefail {0}
   ubuntu_jammy_pip:
     name: ubuntu 22.04 jammy
@@ -47,6 +49,4 @@ jobs:
       - name: pip build and test
         working-directory: drake_pip
         run: .github/ci_build_test
-        env:
-          PYTHON_VERSION: '3'
         shell: bash

drake_pip/.github/ci_build_test

@@ -3,13 +3,7 @@
 
 set -euxo pipefail
 
-"python$PYTHON_VERSION" --version
-"python$PYTHON_VERSION" -m venv env
-
 source env/bin/activate
-pip install drake
-
-python3 -c 'import pydrake.all; print(pydrake.__file__)'
 
 cd src
 python3 particle_test.py

drake_pip/.github/workflows/ci.yml

@@ -38,11 +38,13 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: '3.12'
+      - name: venv setup and install
+        working-directory: drake_pip
+        run: setup/setup_env 3.12
+        shell: zsh -eufo pipefail {0}
       - name: pip build and test
         working-directory: drake_pip
         run: .github/ci_build_test
-        env:
-          PYTHON_VERSION: '3.12'
         shell: zsh -efuo pipefail {0}
   ubuntu_jammy_pip:
     name: ubuntu 22.04 jammy
@@ -58,6 +60,4 @@ jobs:
       - name: pip build and test
         working-directory: drake_pip
         run: .github/ci_build_test
-        env:
-          PYTHON_VERSION: '3'
         shell: bash

drake_pip/README.md

@@ -3,36 +3,67 @@
 This installs Drake using [`pip`](https://pypi.org/project/pip/),
 the Python package manager.
 
-## Instructions
+# Instructions
 
-First, install the required Ubuntu packages:
+Follow the setup instructions for [Ubuntu](#ubuntu-setup)
+or [Mac OS](#mac-setup), and read the [General Overview](#general-overview)
+for additional background information.
 
-```
+## Ubuntu Setup
+
+If on Ubuntu, first install the required packages:
+
+```bash
 setup/install_prereqs
 ```
 
-For Mac users, simply ensure the correct version of Python
+This script will also run `setup/setup_env`, which creates the virtual environment for this project and installs Drake.
+
+To start programming, simply activate the environment by calling:
+
+```bash
+source env/bin/activate
+```
+
+## Mac Setup
+
+If on Mac OS X, simply ensure the correct version of Python
 is installed from Homebrew by referring to the
 [Supported Configurations](https://drake.mit.edu/installation.html#supported-configurations).
 
-Create a [virtual environment](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment)
-named `env` and activate it:
+Then, run the following script to create the virtual environment for this project and install Drake:
 
+```bash
+setup/setup_env
 ```
-python3 -m venv env
+
+*Note*: If you have multiple versions of Python installed,
+you can specify the correct version as an optional argument
+to the script. For example, `setup/setup_env 3.12`.
+
+To start programming, simply activate the environment by calling:
+
+```bash
 source env/bin/activate
 ```
 
-Then install Drake for Python in the virtual environment:
+## General Overview
 
-```
-pip install drake
-```
+The `setup_env` script takes care of the virtual environment
+and Drake installation, but read below for a quick overview of the steps.
 
-Call the following to ensure `pydrake` can be imported:
+Create a [virtual environment](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment)
+named `env` and activate it:
 
+```bash
+python3 -m venv env
+source env/bin/activate
 ```
-python3 -c 'import pydrake.all; print(pydrake.__file__)'
+
+Then install Drake in the virtual environment using the provided `requirements.txt` file:
+
+```bash
+pip3 install -r requirements.txt
 ```
 
 That's all that is needed to use Drake from Python.
@@ -42,12 +73,12 @@ For more information on what's available for Drake in Python,
 see [Using Drake from Python](https://drake.mit.edu/python_bindings.html)
 and the Python API [pydrake](https://drake.mit.edu/pydrake/index.html).
 
-## Examples
+# Examples
 
 To run the particle example tests in this directory,
 navigate to `src` and call the test file to execute the unit tests:
 
-```
+```bash
 cd src
 python3 particle_test.py
 ```

drake_pip/requirements.txt

@@ -0,0 +1,3 @@
+# Currently, this only includes the most recent version of drake.
+# Feel free to add more packages for your own project!
+drake

drake_pip/setup/install_prereqs

@@ -21,3 +21,5 @@ ${maybe_sudo} apt-get install --no-install-recommends $(cat <<EOF
   python3-venv
 EOF
 )
+
+setup/setup_env

drake_pip/setup/setup_env

@@ -0,0 +1,10 @@
+#!/bin/bash
+# SPDX-License-Identifier: MIT-0
+
+set -euxo pipefail
+
+PYTHON_VERSION=${1:-'3'}
+echo "Creating virtual environment with python${PYTHON_VERSION}"
+
+"python${PYTHON_VERSION}" -m venv env
+"env/bin/pip$PYTHON_VERSION" install -r requirements.txt