Add examples for pip and poetry

.github/workflows/ci.yml

@@ -23,6 +23,10 @@ jobs:
     uses: ./.github/workflows/bazel_download.yml
   cmake_installed_apt:
     uses: ./.github/workflows/cmake_installed_apt.yml
+  pip:
+    uses: ./.github/workflows/pip.yml
+  poetry:
+    uses: ./.github/workflows/poetry.yml
   file_sync:
     name: file sync
     runs-on: ubuntu-latest

.github/workflows/pip.yml

@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: MIT-0
+
+---
+name: ci
+on:
+  workflow_call:
+
+jobs:
+  macos_sonoma_arm_pip:
+    name: macos sonoma 14 arm
+    runs-on: macos-14
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+      # See issue https://github.com/actions/setup-python/issues/577.  There is
+      # some kind of environment conflict between the symlinks found in the
+      # GitHub Actions runner and `brew upgrade python` where `brew` detects and
+      # refuses to overwrite symlinks.  The cause for our runs is not clear,
+      # we do not use that action, but if that issue is closed this section
+      # can be removed.
+      - name: sanitize GHA / brew python environment
+        run: |
+          # Remove the symlinks that cause issues.
+          find /usr/local/bin -lname '*/Library/Frameworks/Python.framework/*' -delete
+          sudo rm -rf /Library/Frameworks/Python.framework/
+      - name: python setup
+        id: macos_python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - 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
+    runs-on: ubuntu-latest
+    container: ubuntu:jammy
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+      - name: pip setup
+        working-directory: drake_pip
+        run: .github/ubuntu_setup
+        shell: bash
+      - name: pip build and test
+        working-directory: drake_pip
+        run: .github/ci_build_test
+        env:
+          PYTHON_VERSION: '3.10'
+        shell: bash

.github/workflows/poetry.yml

@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: MIT-0
+
+---
+name: ci
+on:
+  workflow_call:
+
+jobs:
+  macos_sonoma_arm_poetry:
+    name: macos sonoma 14 arm
+    runs-on: macos-14
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+      # See issue https://github.com/actions/setup-python/issues/577.  There is
+      # some kind of environment conflict between the symlinks found in the
+      # GitHub Actions runner and `brew upgrade python` where `brew` detects and
+      # refuses to overwrite symlinks.  The cause for our runs is not clear,
+      # we do not use that action, but if that issue is closed this section
+      # can be removed.
+      - name: sanitize GHA / brew python environment
+        run: |
+          # Remove the symlinks that cause issues.
+          find /usr/local/bin -lname '*/Library/Frameworks/Python.framework/*' -delete
+          sudo rm -rf /Library/Frameworks/Python.framework/
+      - name: python setup
+        id: macos_python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: poetry setup
+        working-directory: drake_poetry
+        run: setup/install_prereqs
+        shell: zsh -efuo pipefail {0}
+      - name: poetry build and test
+        working-directory: drake_poetry
+        run: .github/ci_build_test
+        env:
+          PYTHON_VERSION: '3.12'
+        shell: zsh -efuo pipefail {0}
+  ubuntu_jammy_poetry:
+    name: ubuntu 22.04 jammy
+    runs-on: ubuntu-latest
+    container: ubuntu:jammy
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+      # This should be kept in one step because updating of the PATH variable
+      # after installing poetry does not persist between steps on GHA.
+      - name: poetry setup, build, and test
+        working-directory: drake_poetry
+        run: |
+          .github/ubuntu_setup
+          source $HOME/.profile # update PATH
+          .github/ci_build_test
+        env:
+          PYTHON_VERSION: '3.10'
+        shell: bash

README.md

@@ -8,6 +8,8 @@ own project:
 * [`drake_cmake_external`](./drake_cmake_external)
 * [`drake_cmake_installed`](./drake_cmake_installed)
 * [`drake_cmake_installed_apt`](./drake_cmake_installed_apt)
+* [`drake_pip`](./drake_pip)
+* [`drake_poetry`](./drake_poetry)
 
 ## Continuous Integration
 
@@ -23,9 +25,12 @@ Scripts are provided for various CI instances in `scripts/continuous_integration
 | `drake_cmake_external` | - | o |
 | `drake_cmake_installed` | o | - |
 | `drake_cmake_installed_apt` | o | - |
+| `drake_pip` | o | - |
+| `drake_poetry` | o | - |
 || ![GitHub Actions](https://img.shields.io/github/actions/workflow/status/RobotLocomotion/drake-external-examples/ci.yml?branch=main) | [![Jenkins](https://img.shields.io/jenkins/build.svg?jobUrl=https://drake-jenkins.csail.mit.edu/job/RobotLocomotion/job/drake-external-examples/job/main)](https://drake-jenkins.csail.mit.edu/job/RobotLocomotion/job/drake-external-examples/) |
 
 
 Note, the GitHub Actions jobs only build and test `drake_bazel_download`,
-`drake_cmake_installed`, and `drake_cmake_installed_apt` since these are the
-exemplary cases for lightweight, open-source builds on public CI servers.
+`drake_cmake_installed`, `drake_cmake_installed_apt`, `drake_pip`, and
+`drake_poetry`, since these are the exemplary cases for lightweight, 
+open-source builds on public CI servers.

drake_pip/.clang-format

@@ -0,0 +1,22 @@
+# -*- mode: yaml -*-
+# vi: set ft=yaml :
+# SPDX-License-Identifier: MIT-0
+
+---
+BasedOnStyle: Google
+---
+Language: Cpp
+DerivePointerAlignment: false
+PointerAlignment: Left
+
+IncludeCategories:
+  - Regex:    '^[<"](aio|arpa/inet|assert|complex|cpio|ctype|curses|dirent|dlfcn|errno|fcntl|fenv|float|fmtmsg|fnmatch|ftw|glob|grp|iconv|inttypes|iso646|langinfo|libgen|limits|locale|math|monetary|mqueue|ndbm|netdb|net/if|netinet/in|netinet/tcp|nl_types|poll|pthread|pwd|regex|sched|search|semaphore|setjmp|signal|spawn|stdalign|stdarg|stdatomic|stdbool|stddef|stdint|stdio|stdlib|stdnoreturn|string|strings|stropts|sys/ipc|syslog|sys/mman|sys/msg|sys/resource|sys/select|sys/sem|sys/shm|sys/socket|sys/stat|sys/statvfs|sys/time|sys/times|sys/types|sys/uio|sys/un|sys/utsname|sys/wait|tar|term|termios|tgmath|threads|time|trace|uchar|ulimit|uncntrl|unistd|utime|utmpx|wchar|wctype|wordexp)\.h[">]$'
+    Priority: 10
+  - Regex:    '^[<"](algorithm|array|atomic|bitset|cassert|ccomplex|cctype|cerrno|cfenv|cfloat|chrono|cinttypes|ciso646|climits|clocale|cmath|codecvt|complex|condition_variable|csetjmp|csignal|cstdalign|cstdarg|cstdbool|cstddef|cstdint|cstdio|cstdlib|cstring|ctgmath|ctime|cuchar|cwchar|cwctype|deque|exception|forward_list|fstream|functional|future|initializer_list|iomanip|ios|iosfwd|iostream|istream|iterator|limits|list|locale|map|memory|mutex|new|numeric|ostream|queue|random|ratio|regex|scoped_allocator|set|shared_mutex|sstream|stack|stdexcept|streambuf|string|strstream|system_error|thread|tuple|type_traits|typeindex|typeinfo|unordered_map|unordered_set|utility|valarray|vector)[">]$'
+    Priority: 20
+  - Regex:    '^<'
+    Priority: 30
+  - Regex:    '^"(drake|drake_external_examples)'
+    Priority: 50
+  - Regex:    '^"'
+    Priority: 40

drake_pip/.github/ci_build_test

@@ -0,0 +1,17 @@
+#!/bin/bash
+# SPDX-License-Identifier: MIT-0
+
+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__)'
+
+python3 src/particle_test.py
+
+deactivate
+rm -rf env src/__pycache__

drake_pip/.github/ubuntu_setup

@@ -0,0 +1,11 @@
+#!/bin/bash
+# SPDX-License-Identifier: MIT-0
+
+set -euxo pipefail
+
+echo 'APT::Acquire::Retries "4";' > /etc/apt/apt.conf.d/80-acquire-retries
+echo 'APT::Get::Assume-Yes "true";' > /etc/apt/apt.conf.d/90-get-assume-yes
+
+export DEBIAN_FRONTEND='noninteractive'
+
+setup/install_prereqs

drake_pip/.github/workflows/ci.yml

@@ -0,0 +1,64 @@
+# SPDX-License-Identifier: MIT-0
+
+---
+name: ci
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  schedule:
+    - cron: '0 12 * * *'
+concurrency:
+  # Cancel previous CI runs when additional commits are added to a pull request.
+  # This will not cancel CI runs associated with `schedule` or `push`.
+  group: ${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+jobs:
+  macos_sonoma_arm_pip:
+    name: macos sonoma 14 arm
+    runs-on: macos-14
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+      # See issue https://github.com/actions/setup-python/issues/577.  There is
+      # some kind of environment conflict between the symlinks found in the
+      # GitHub Actions runner and `brew upgrade python` where `brew` detects and
+      # refuses to overwrite symlinks.  The cause for our runs is not clear,
+      # we do not use that action, but if that issue is closed this section
+      # can be removed.
+      - name: sanitize GHA / brew python environment
+        run: |
+          # Remove the symlinks that cause issues.
+          find /usr/local/bin -lname '*/Library/Frameworks/Python.framework/*' -delete
+          sudo rm -rf /Library/Frameworks/Python.framework/
+      - name: python setup
+        id: macos_python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - 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
+    runs-on: ubuntu-latest
+    container: ubuntu:jammy
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+      - name: pip setup
+        working-directory: drake_pip
+        run: .github/ubuntu_setup
+        shell: bash
+      - name: pip build and test
+        working-directory: drake_pip
+        run: .github/ci_build_test
+        env:
+          PYTHON_VERSION: '3.10'
+        shell: bash

drake_pip/CPPLINT.cfg

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: MIT-0
+
+set noparent
+
+filter=-build/c++11
+filter=-build/header_guard
+filter=-build/include_subdir

drake_pip/LICENSE

@@ -0,0 +1,16 @@
+Copyright (c) 2017-2023 by the drake-external-examples developers.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

drake_pip/README.md

@@ -0,0 +1,55 @@
+# Python Project with Drake Installed from Pip
+
+This installs Drake using [`pip`](https://pypi.org/project/pip/),
+the Python package manager.
+
+## Instructions
+
+First, install the required Ubuntu packages (this step is not needed on Mac):
+
+```
+setup/install_prereqs
+```
+
+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:
+
+```
+python3 -m venv env
+source env/bin/activate
+```
+
+*Note:* Depending on the system and which version of Python is installed,
+it may be beneficial (or necessary) to instantiate the virtual environment
+with a specific command. For example, call `python3.10` on Ubuntu 22.04.
+Refer to [Source Installation](https://drake.mit.edu/from_source.html)
+for the version of Python currently supported by Drake on each
+operating system.
+
+Then install Drake for Python in the virtual environment:
+
+```
+pip install drake
+```
+
+Call the following to ensure `pydrake` can be imported:
+
+```
+python3 -c 'import pydrake.all; print(pydrake.__file__)'
+```
+
+That's all that is needed to use Drake from Python.
+See [Installation via Pip](https://drake.mit.edu/pip.html#stable-releases)
+for more information on installation.
+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
+
+To run the particle example tests in this directory, navigate to `src` and call the test file to execute the unit tests:
+
+```
+cd src
+python3 particle_test.py
+```