setuptools setup.py commands are unintuitive and undiscoverable (--help-commands should replace --help)

[Thomas Jollans]

On 27/04/18 06:06, jimbo1qaz wrote:
> Frequently I have encountered projects packaged using setuptools, with a
> setup.py. To find out how to install it, I usually turned to Stack Overflow
> (https://stackoverflow.com/a/1472014) which doesn't explain what options
> exist or do.
> 
> Surprisingly, neither "setup.py" nor "setup.py --help" doesn't provide a
> list of options either, instead telling you how to show various metadata
> options which are not useful to end users of the software project, trying
> to build/install it.
> 
> Instead, to show a list of useful actions a user can perform, you need to
> use "setup.py --help-commands", which I only discovered several years after
> starting to use Python. Why isn't this command enabled by default (called
> without arguments, or with --help).
> 
> https://imgur.com/a/HF4Iw6D
> 

Sure, setuptools has a lot of weird historical quirks, but the help
message? That looks fine to me. It *starts* by telling you about
setup.py install and setup.py build. The only command most users will
ever need is listed clearly in the *third* line of the --help message.
How do you get any more discoverable than that?

There are other specialised commands, but those are mostly useful for
maintainers and some sysadmins. (and --help-commands is referenced in
the *first* line of the --help message)

Most of the time, you should just be installing things with pip anyway.
Most packages are on the PyPI, and even where they're not, pip can
install directly from source tarballs and git repositories.

-- Thomas