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

Question

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 of pip, 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?

---

Update: I posed this question as an issue on pip's Github page.

Answer 1

Disclaimer: I am not a contributing author on pip and these are speculations rather than insights from the authors or maintainers of pip.

One or more of the following may have led the author to make the options hidden:

1. Some options are really noops and exist for completeness and compatibility, but wouldn't be typically used by someone reading help. For instance, --use-wheel which is enabled by default.

2. Some options are transitional or deprecated and should not be used because they may be removed in a future version. For instance --use-mirrors, which is marked with the comment TODO: Remove after 6.0.

3. Some options may be experimental or may not work in all environment. This could be a problem for end users who expect the software to be cross-platform and the authors didn't go through the hassle of testing the environment and putting conditional statements - perhaps an unnecessary complexity for infrequently used specialized options. Perhaps --default-vcs is an example of that.

4. Another possibility is that the behaviour of a rarely-used option is non-standard or difficult to describe as it depends on external variables or the environment, in which case it may be easier to suppress help than to provide a confusing one.

5. When I was maintainer of grep, we had many undocumented options initially. These were options whose behaviour was non-standard (e.g., did not comply with POSIX) but where there for historic reasons and removing them could've broken critical system scripts around the world that may have been using them. I wouldn't know if any such options exist in pip, but wanted to mention this for completeness as a reason for why some options might be hidden.