[PyPI examples] Manage Drake version consistently

[tyler-yankee]

When the PyPI (pip and poetry) examples were added in #358, there was not too much care taken for which version of Drake would be installed and used. This came to light with the recent release of Drake v1.38.0. The goal of this PR is to:

• be more clear about the minimum version of Drake supported by the examples in our documentation (which should be maintained going forward)
• for Poetry, maintain the pyproject.toml as a set of build instructions but not the poetry.lock file as a record of deployment, which makes managing dependencies across versions and platforms easier

---

This change is 

[tyler-yankee]

+@mwoehlke-kitware could you feature review this to make sure the versions and language make sense?

[mwoehlke-kitware]

Reviewed all commit messages.
Reviewable status: 5 unresolved discussions, LGTM missing from assignee mwoehlke-kitware, platform LGTM missing

---

drake_pip/README.md line 6 at r1 (raw file):

the Python package manager.

Currently, this example is supported using

(Note: I'm also not sure if it would be better to omit "using" as well.)

Also, "or later" after the link.

Suggestion:

Currently, this example supports using

---

drake_pip/requirements.txt line 1 at r1 (raw file):

# This example is currently supported using Drake 1.38.0.

(Note: I'm also not sure if it would be better to omit "using" as well.)

Suggestion:

# This example currently supports using Drake 1.38.0 or later.

---

drake_pip/requirements.txt line 3 at r1 (raw file):

# This example is currently supported using Drake 1.38.0.
# Feel free to add more packages for your own project below!
drake>=1.38.0

I guess we should try to keep this consistent with Poetry's ^1.38.0...

Suggestion:

drake~=1.38

---

drake_poetry/pyproject.toml line 11 at r1 (raw file):

readme = "README.md"

# This example is currently supported using Drake 1.38.0.

(Note: I'm also not sure if it would be better to omit "using" as well.)

Suggestion:

# This example currently supports using Drake 1.38.0 or later.

---

drake_poetry/README.md line 7 at r1 (raw file):

see [Basic usage](https://python-poetry.org/docs/basic-usage/).

Currently, this example is supported using

(Note: I'm also not sure if it would be better to omit "using" as well.)

Also, "or later" after the link.

Suggestion:

Currently, this example supports using

[jwnimmer-tri]

drake_pip/requirements.txt line 1 at r1 (raw file):

# This example is currently supported using Drake 1.38.0.

nit We shouldn't repeat ourselves by pasting the version number in the comment as well. That will defeat our ability to have dependabot auto-bump this file for us.

[mwoehlke-kitware]

drake_pip/requirements.txt line 1 at r1 (raw file):

Previously, jwnimmer-tri (Jeremy Nimmer) wrote…

nit We shouldn't repeat ourselves by pasting the version number in the comment as well. That will defeat our ability to have dependabot auto-bump this file for us.

👍

...but what do we do about it? Can we omit it entirely? Should we say something about how we only test against the latest release?

Also, I guess this applies to both README.mds as well?

[jwnimmer-tri]

Reviewable status: 6 unresolved discussions, LGTM missing from assignee mwoehlke-kitware, platform LGTM missing (waiting on @mwoehlke-kitware and @tyler-yankee)

---

drake_pip/requirements.txt line 1 at r1 (raw file):

Should we say something about how we only test against the latest release?

This repo is (primarily) a starter pack meant to be copied by users, not a CI suite. We don't need to tell explain to them which version(s) the starter pack is tested against. The only thing that matters is that when they copy this dir into a new repo run it, that it works.

..but what do we do about it?

I don't know. The comment seemed vacuous to me in the first place, so I don't know what it was trying to accomplish in the first place.

[tyler-yankee]

Reviewable status: 6 unresolved discussions, LGTM missing from assignee mwoehlke-kitware, platform LGTM missing (waiting on @jwnimmer-tri and @mwoehlke-kitware)

---

drake_pip/README.md line 6 at r1 (raw file):

Previously, mwoehlke-kitware (Matthew Woehlke) wrote…

(Note: I'm also not sure if it would be better to omit "using" as well.)

Also, "or later" after the link.

@jwnimmer-tri: Per the discussion below, is this comment in the README's worth it?

---

drake_pip/requirements.txt line 1 at r1 (raw file):

The comment seemed vacuous to me in the first place...

The comment was originally put there in #358 to go along the lines of DEE being a sort of "starter pack," telling users that this is where they would put other packages used by their own project (even though this may be obvious to even intermediate Python users). I can revert these changes so that the comment remains along those lines while also not getting in the way of dependabot.

Would we like to configure dependabot for this PR while we're at it?

---

drake_pip/requirements.txt line 3 at r1 (raw file):

Previously, mwoehlke-kitware (Matthew Woehlke) wrote…

I guess we should try to keep this consistent with Poetry's ^1.38.0...

Good catch, thanks.

[mwoehlke-kitware]

drake_pip/requirements.txt line 1 at r1 (raw file):

Previously, tyler-yankee (Tyler Yankee) wrote…

The comment seemed vacuous to me in the first place...

The comment was originally put there in #358 to go along the lines of DEE being a sort of "starter pack," telling users that this is where they would put other packages used by their own project (even though this may be obvious to even intermediate Python users). I can revert these changes so that the comment remains along those lines while also not getting in the way of dependabot.

Would we like to configure dependabot for this PR while we're at it?

What I meant was that the examples themselves might use newer features, or old versions of Drake might contain bugs. We do have CI to test that the example is not broken, but that testing only happens against recent drake.

Pending a better suggestion, my thought would be to change this comment to "Currently, this only includes a recent version of drake" (thus, retaining the intent of the original comment) and remove the README.md comments.

[tyler-yankee]

drake_pip/requirements.txt line 1 at r1 (raw file):

Previously, mwoehlke-kitware (Matthew Woehlke) wrote…

What I meant was that the examples themselves might use newer features, or old versions of Drake might contain bugs. We do have CI to test that the example is not broken, but that testing only happens against recent drake.

Pending a better suggestion, my thought would be to change this comment to "Currently, this only includes a recent version of drake" (thus, retaining the intent of the original comment) and remove the README.md comments.

I agree with this, thanks for the suggestion. I've made the changes.

[mwoehlke-kitware]

Reviewed 2 of 5 files at r2.
Reviewable status: 8 unresolved discussions, LGTM missing from assignee mwoehlke-kitware, platform LGTM missing (waiting on @jwnimmer-tri and @tyler-yankee)

---

drake_pip/requirements.txt line 3 at r2 (raw file):
This should drop the .0; The ~ decorator (pip) and ^ decorator (poetry ) aren't directly interchangeable. Note the examples and their stated equivalences to <=> combinations:

pip:

~= 2.2
>= 2.2, == 2.*

~= 2.2.0
>= 2.2.0, == 2.2.*

poetry:

^1.2.3
>=1.2.3, <2.0.0

The Poetry ^1.38.0 translates to >=1.38.0, <2, i.e. >=1.38.0, ==1.*. The closest ~ equivalent is therefore ~1.38, not ~1.38.0. (The latter two are very different!)

This might even warrant a comment to the effect "don't write x.y.z here, only x.y". If it helps, on the Poetry side, ^x.y.0 and ^x.y are roughly equivalent. (Although I'm not sure what happens when you ask for x.y.z and the package version is x.y with no z component...)

Suggestion:

~=1.38

---

drake_poetry/README.md line 23 at r2 (raw file):

    of Drake up to date. It will be created once the environment is set up,
    and it's encouraged to check in this file for your own project
    using Drake in order to manage its dependencies.

Suggestion:

    and it is encouraged to include this file in your own project's version
    control in order to manage your project's dependencies.

[tyler-yankee]

drake_pip/requirements.txt line 3 at r2 (raw file):

Previously, mwoehlke-kitware (Matthew Woehlke) wrote…

This should drop the .0; The ~ decorator (pip) and ^ decorator (poetry ) aren't directly interchangeable. Note the examples and their stated equivalences to <=> combinations:

pip:

~= 2.2
>= 2.2, == 2.*

~= 2.2.0
>= 2.2.0, == 2.2.*

poetry:

^1.2.3
>=1.2.3, <2.0.0

The Poetry ^1.38.0 translates to >=1.38.0, <2, i.e. >=1.38.0, ==1.*. The closest ~ equivalent is therefore ~1.38, not ~1.38.0. (The latter two are very different!)

This might even warrant a comment to the effect "don't write x.y.z here, only x.y". If it helps, on the Poetry side, ^x.y.0 and ^x.y are roughly equivalent. (Although I'm not sure what happens when you ask for x.y.z and the package version is x.y with no z component...)

Oh, thanks for pointing this out; initially just missed the detail in your suggestion, but I actually didn't realize that subtle difference so it was good to read up on.

[tyler-yankee]

While we're cleaning up the version of Drake in these examples, I figured I'd also make a cleanup pass to the GHA pointed out in #374 by factoring out '3.12' to an environment variable. When we eventually support Python 3.13, this will make that transition easier.

Reviewable status: 2 unresolved discussions, LGTM missing from assignee mwoehlke-kitware, platform LGTM missing (waiting on @mwoehlke-kitware)

[mwoehlke-kitware]

pending @jwnimmer-tri's approval of the documentation.

Reviewed 6 of 6 files at r3.
Reviewable status: 1 unresolved discussion, platform LGTM missing

---

drake_pip/requirements.txt line 1 at r1 (raw file):

Previously, tyler-yankee (Tyler Yankee) wrote…

I agree with this, thanks for the suggestion. I've made the changes.

Waiting on @jwnimmer-tri to confirm we're okay with the current state of comments.

[tyler-yankee]

Note that the CI error on drake_cmake_installed is due to #22703. Happy to re-run it once that fix has landed.

[jwnimmer-tri]

Reviewed 1 of 5 files at r1, 3 of 5 files at r2, 6 of 6 files at r3, all commit messages.
Reviewable status: complete! all discussions resolved, platform LGTM from [jwnimmer-tri] (waiting on @tyler-yankee)