Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Why are useful command line options in pip undocumented and explicitly hidden? #2429

Open
musically-ut opened this issue Feb 18, 2015 · 11 comments
Open

Comments

@musically-ut
Copy link

@musically-ut musically-ut commented Feb 18, 2015

I use export PIP_REQUIRE_VIRTUALENV=true; in my .bashrc to ensure that I do not accidentally pollute my global env while installing packages for the various projects I work on.

I vaguely remembered that this was the same as adding a --require-virtualenv to the command line while invoking pip.

However, I was unable to find any documentation for this anywhere except in the source code, where help for the feature is explicitly suppressed (using SUPRESS_HELP)! There are 11 such options for which the help has also been explicitly disabled (e.g. --no-input).

I look through the history of the file, but did not find any mention of why the feature was hidden in the commit messages.

Is this an experimental feature which should not be relied upon? Should I not use (nor encourage others to use) these features or is there a different way of using these features? Could someone please shine some light on this conundrum?


This is a question which I had previously posted on StackOverflow hoping that there was an explanation along the lines that these options were only to be used if pip was invoked from other dependency management software.

However, that doesn't seem to be case, or at least it isn't common knowledge.

@remram44
Copy link
Contributor

@remram44 remram44 commented Mar 31, 2015

+1, it's hard to defend hiding recognized command-line flags, but useful ones it's just stupid. SUPPRESS_HELP is meant for internal or otherwise-documented options, not to filter what you feel people should read about elsewhere.

Relevant code: cmdoptions.py

@keitherskine
Copy link

@keitherskine keitherskine commented Dec 30, 2015

At the very least, please give guidance about whether these command options are still valid or are deprecated. Not documenting them at all just leaves them in limbo, and causes confusion for the users.

@justinmayer
Copy link

@justinmayer justinmayer commented Apr 15, 2017

I fully agree that these extremely useful options should be documented. They were documented previously at the following, now-defunct location: http://www.pip-installer.org/en/latest/other-tools.html#using-pip-with-virtualenv

@chrahunt
Copy link
Member

@chrahunt chrahunt commented Sep 1, 2019

To be specific, in the current version of pip these are the hidden options:

Name Location Note
--require-virtualenv link added in 301dc31, no explanation
--no-input link added in 4d33521, no explanation
--skip-requirements-regex link added in 5aa4be, no explanation - deprecated in #7297
--no-use-pep517 link this was done in #5743 here probably just to remove any redundancy with --use-pep517
--always-unzip link Commented with "Deprecated, remove later", looks like it is a no-op
install --no-user link #5116 indicates it needed more thought before exposing
@deveshks
Copy link
Contributor

@deveshks deveshks commented May 13, 2020

There is now #8182 to test --no-input and officially document and unhide it.

@pradyunsg
Copy link
Member

@pradyunsg pradyunsg commented May 13, 2020

At the very least, please give guidance about whether these command options are still valid or are deprecated.

Any pip functionality that is not documented in any form (in the CLI --help, or in docs/) is not supported. Documenting them would move the to being supported and following pip's deprecation policy.

I'm not opposed to supporting --no-input or --require-virtualenv. Both of these would likely need to be documented in the docs, in addition to surfacing them in --help.

@gutsytechster
Copy link
Contributor

@gutsytechster gutsytechster commented May 15, 2020

I would like to create the PR to document the --require-virtualenv. :)

@deveshks
Copy link
Contributor

@deveshks deveshks commented May 16, 2020

I'm not opposed to supporting --no-input or --require-virtualenv. Both of these would likely need to be documented in the docs, in addition to surfacing them in --help.

Correct me if I am wrong, but removing SUPPRESS_HELP from the cmdoptions should automatically document for e.g. --no-input under pip's General Options , as well as showing them in --help

Is there any other place in the docs we need to add these options manually?

@pradyunsg
Copy link
Member

@pradyunsg pradyunsg commented May 16, 2020

Is there any other place in the docs we need to add these options manually?

For --no-input, I don't think we need anything else.

For --require-virtualenv, I think we should add a section to the User Guide, describing the behavior of it and what the intended use case is.

@deveshks
Copy link
Contributor

@deveshks deveshks commented Jun 11, 2020

I have created issue #8408 to get rid of --always-unzip from pip source. If this is something we are looking to do, I can go ahead and create a PR for it.

@deveshks
Copy link
Contributor

@deveshks deveshks commented Jun 19, 2020

I have created issue #8408 to get rid of --always-unzip from pip source. If this is something we are looking to do, I can go ahead and create a PR for it.

#8470 is created for this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
8 participants
You can’t perform that action at this time.