Add "python setup.py --version" replacement command

[jeanas]

https://discuss.python.org/t/replacement-for-setup-py-version

---

📚 Documentation preview 📚: https://python-packaging-user-guide--1415.org.readthedocs.build/en/1415/

[sinoroc]

I am not convinced we need to add this.

I believe it was essential to write about install, develop, sdist, and bdist_wheel because using those can actually be damaging (they do produce out of date results), and also there is a clear obvious replacement. The replacement commands are even build backend agnostic and based on standards, so this was a no-brainer (from my point of view).

With things like --name, and --version (and also test and so on) this is not as straightforward in my opinion. As far as I know there is no real "damage" that can occur when using those. And also there is no "standard" replacement.

Maybe we could list those (--name --version test and so on) in a separate table further down below in a less prominent place where we can expand a bit more on the use cases.

[jeanas]

I don't want to argue on whether it is “essential”, but does it hurt?

The setuptools maintainers have been quite clear that all usage of setup.py is deprecated. From what I understand of pypa/setuptools#4047 (comment) (CC @abravalheri), setuptools does not want to maintain python setup.py --version anymore (nor any other CLI invocation of setup.py) so it is in "minimal bug fixes as long as it doesn't stand in the way" mode. In other words, while it still works now, it could stop doing so in the more or less near future.

And, yes, there is no standardized general replacement. However, it's easy and obvious to grep pyproject.toml or a __version__ attribute when the version is specified in either of these. So, I'd expect that for a good proportion of people searching documentation on how to replace python setup.py --version, python -m setuptools_scm is the right answer.

[sinoroc]

I thought merely having setuptools-scm installed had side effects, but looking at the documentation it seems like it doesn't. It has to be listed in build dependencies and there has to be a setuptools-scm table in pyproject.toml for it to be enabled. Is that right? If yes, then I might be more likely to agree with this suggestion.

[jeanas]

setuptools-scm will be autodetected and used by setuptools when installed (like all setuptools plugins, which are discovered through entry points), but it will not change your build if you have not configured it in pyproject.toml.

[sinoroc]

I am thinking this should be a "suggestion" rather than a recommendation.

I am thinking maybe we could add a whole new subsection of suggestions (soft recommendations), something along the lines of:

What commands should be used instead?

[...]

What about other commands?

setup.py --version => a possible replacement (among others) is to rely on setuptools-scm: python -m setuptools-scm
setup.py test => the recommendation is to use a dedicated test runner, for example pytest
setup.py check and setup.py upload => a possible replacement is to use twine: python -m twine check and python -m twine upload

What about custom commands?

[...]

What do you think? Would that work for you?

This is more or less what is at the bottom of Paul's article: https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html#summary

I do not want the guide to be seen as recommending specific tools unless they are the absolute obvious choice (such as build). Maybe twine could be one of those, I guess it is recommended in some other places in this guide. But for setuptools-scm (and pytest) I am a bit more reluctant, first there are other alternatives, and second the whole question about version strings is its own (hotly debated) topic.

[jeanas]

Well. I didn't write “a replacement for python setup.py --version is python -m setuptools_scm“. I wrote (the table equivalent) of “if you are using setuptools-scm, then a replacement for python setup.py --version is python -m setuptools_scm”. For me, this doesn't imply any sort of recommendation in the slightest, but maybe I'm thinking too much like the CS/math student I am, for whom “if it's raining, then I don't exist” is a perfectly true sentence as long as the weather's sunny?

[sinoroc]

this doesn't imply any sort of recommendation

Yes but this table is for "hard" recommendations, as the header of the right-hand column says: "Recommendation". That is why I suggest moving this to another location outside of this recommendation table.

[jeanas]

Sorry, going to close this; I started updating it but trying to organize the thing well was starting to take me more time than I had to spend on this.

[sinoroc]

Sorry for being picky about this. But this motivated me to open my own pull request on this. So effort is not lost. :)

#1418