run: re-enable --help option

[immerrr]

This PR re-enables --help option for pipenv run command.

The issue

There are a few issues related to this problem:

• pipenv run should support -h and --help #1405
• pipenv run --help thows excption #2127
• pipenv run --help crashes #2843

As you see, it is a reoccurring confusion that pipenv run command does not support --help. It was disabled in #940 and there was no particular motivation referenced. I believe it deserves to be enabled back.

It is brought up by different members the core team that this is working "as intended" because pipenv forwards everything through to the subcommand, but it is not entirely true, e.g. pipenv run for example accepts all virtualenv creation parameters:

$ pipenv run --python=3 which python
Creating a virtualenv for this project...
Pipfile: /home/immerrr/Pipfile
Using /home/immerrr/src/pyenv/versions/3.7.0/bin/python3.7m (3.7.0) to create virtualenv...
⠙ Creating virtual environment...Using base prefix '/home/immerrr/src/pyenv/versions/3.7.0'
New python executable in /mnt/extraspace/virtualenvs/immerrr-8YhW2Khy/bin/python3.7m
Not overwriting existing python script /mnt/extraspace/virtualenvs/immerrr-8YhW2Khy/bin/python (you must use /mnt/extraspace/virtualenvs/immerrr-8YhW2Khy/bin/python3.7m)
Installing setuptools, pip, wheel...
done.
Running virtualenv with interpreter /home/immerrr/src/pyenv/versions/3.7.0/bin/python3.7m

✔ Successfully created virtual environment! 
Virtualenv location: /mnt/extraspace/virtualenvs/immerrr-8YhW2Khy
Creating a Pipfile for this project...
/mnt/extraspace/virtualenvs/immerrr-8YhW2Khy/bin/python

Or even --verbose:

$ pipenv run --verbose which python
/mnt/extraspace/virtualenvs/immerrr-8YhW2Khy/bin/python

The general convention that makes sense to me is that pipenv options end with the first cmdline argument that does not start with a dash. It is also reaffirmed that pipenv run is supposed to receive options in the usage generated by click:

$ pipenv run
Usage: pipenv run [OPTIONS] COMMAND [ARGS]...

And if you really need to run a command that starts with a dash, you have a -- separator convention that has you covered:

$ pipenv run -- --verbose which python
Error: the command --verbose could not be found within PATH or Pipfile's [scripts].

Hence I don't think it makes much sense to keep --help disabled maintaining the discrepancy between run and the rest of pipenv commands.

The fix

This PR re-enables --help option for pipenv run command.

The checklist

• Associated issue
• A news fragment in the news/ directory to describe this fix with the extension .bugfix, .feature, .behavior, .doc. .vendor. or .trivial (this will appear in the release changelog). Use semantic line breaks and name the file after the issue number or the PR #.

[techalchemy]

I’m fairly confident this was removed for a reason, you’ll have to check the commit history or the PR that changed it to verify

[techalchemy]

Ah I see you referenced a few issues. The topics at hand would have been whether to pass allow_interspersed_arguments to subcommands, specifically to pipenv run we disable this because (and I am 100% certain we have fielded issues on this directly) users often want to pass arguments to the thing they are invoking with pipenv run.

If we set the parser to parse pipenv arguments, it becomes impossible to pass the --help argument to anything invoked via pipenv run, for instance. Since there just isn’t much to know about pipenv run, the tradeoff is relatively minor. Changes to this behavior will break backwards compatibility— I haven’t reviewed this PR yet but if that’s what it does it most likely will be closed

Edit: ok so I reviewed it. Maybe it’s fine? Mobile editor says you modified the shell command though, not sure if that’s accurate...

[immerrr]

@techalchemy

re: allow_interspersed_arguments: yes, it makes sense to disable interspersed args for run, you want as little magic as possible when forwarding command line arguments.

If we set the parser to parse pipenv arguments <...>

It is not a matter of "if we enable this", it already happens, the parser parses pipenv parameters, e.g. --python or --verbose, as I have shown in the OP.

it becomes impossible to pass the --help argument to anything invoked via pipenv run, for instance

It will not become impossible. Firstly, because by default pipenv options end with the first non-dash argument, which is usually the name of the command:

$ pipenv run echo echo receives --help even without the -- separator
echo receives --help even without the -- separator

Secondly, because you can force to interpret something that looks like an option as a command with the -- separator:

immerrr@mmrcomp:~/tmp$ pipenv run --help
Usage: pipenv run [OPTIONS] COMMAND [ARGS]...

  Spawns a command installed into the virtualenv.

Options:
  --python TEXT       Specify which version of Python virtualenv should use.
  --three / --two     Use Python 3/2 when creating virtualenv.
  --clear             Clears caches (pipenv, pip, and pip-tools).  [env var:
                      PIPENV_CLEAR]
  -v, --verbose       Verbose mode.
  --pypi-mirror TEXT  Specify a PyPI mirror.
  -h, --help          Show this message and exit.
immerrr@mmrcomp:~/tmp$ pipenv run -- --help
Error: the command --help could not be found within PATH or Pipfile's [scripts].

So the only backward incompatibility that would be seen by the users is if they actually had a command called --help, which should be very rare and can be easily forced to be interpreted as a command by the -- separator convention.

[techalchemy]

awesome, thanks for the clarification then. This is probably good to go and will be merged shortly!

[boustrophedon]

Thanks for working on this @immerrr !