search

pyOpenSci / python-package-guide

scientific Python package recommendations & guidance curated by pyOpenSci
https://www.pyopensci.org/python-package-guide/
Other
72 stars 43 forks source link

Version specification in main text of `tutorials/pyproject-toml.md` #191

Closed sneakers-the-rat closed 3 months ago

sneakers-the-rat commented 4 months ago

Currently version specifiers are just in an admonition, and the examples all use dependency specifiers without versions. I think it's important to model version specification in the tutorials, since they probably won't see many real packages with wide open version specifiers in the wild, and they are the things that are the most troublesome/require the most maintenance over time/will be the source of the most bugs if left without version spec.

Currently

Screenshot 2024-03-01 at 2 59 37 PM Screenshot 2024-03-01 at 2 59 47 PM

This PR

After the unchanged start of the section...

Screenshot 2024-03-01 at 2 51 10 PM Screenshot 2024-03-01 at 2 51 19 PM

So now the "pin dependencies with caution" is just about pinning and narrow version constraints, and it also has a specific example for poetry, and the main text has a discussion about version specification.

I also changed the dependencies array throughout to match.

Something that newbies will also experience (i mean i am currently dealing with a problem like this) some cryptic messages about version incompatibility from requires-python saying they need to add an upper bound. I added a quick note there saying that lower bounds are just one way to specify it, but that you can use the more general version spec syntax there.

IDK why gh's syntax highlighter is showing everything as red...

willingc commented 3 months ago

@lwasser @sneakers-the-rat How would you like to reboot this PR? I'm happy to add and commit the suggestions which will likely fix the merge conflict.

sneakers-the-rat commented 3 months ago

oop sorry accidentally marked as read. i can fix merge conflict and accept suggestions!

lwasser commented 3 months ago

ok i'll put this PR in my task list for tomorrow / monday to re-review. thank you all for this. @sneakers-the-rat another great addition to our guide here. thank you!