Improve SSL error message to instruct the user what to do

[uranusjr]

What's the problem this feature will solve?
I’ve seen quite a few issues on the tracker on the same error message:

WARNING: pip is configured with locations that require TLS/SSL,
however the ssl module in Python is not available.

They all have the same root cause: The ssl built-in module is not available, and pip cannot access HTTPS URLs without it. The warning is however not easy to understand for less experienced users, and they tend to report this as an issue (pypa/virtualenv#1139, #8171, #8472 to list a few. It is, however, a system configuration problem that pip cannot fix.

Describe the solution you'd like
Revise the error message to clearly say

1. This is not a pip bug.
2. Propose the solution to the most likely causes
   a. If the user is using a self-compiled Python, it needs to be recompiled.
   b. If the user is using pyenv, the system is missing build dependencies. This wiki page lists instructions on common platforms.
   c. If the Python is installed by Anaconda or a package manager (e.g. Homebrew), this is likely a runtime configuration issue.
3. Point to a documentation page that discusses the issue in detail, and provide more generic solutions if none of the specific instructions fit the user’s scenario.
4. Instruct the user to ask for help on pypa/packaging-problems.

Alternative Solutions
Do nothing, and continue marking the issues as duplicates. They are not that common, so the overhead isn’t that bad. Maybe it’s possible to have a bot responding to them as well.

Additional context
Some popular destinations if you search the issue description on the Internet. They list quite a few popular causes to this that can be helpful:

• StackOverflow (has diagnoses for Anaconda on Windows, Homebrew on macOS, and generic compiled-from-source scenarios)
• AskUbuntu (i.e. similar to the SO one, but Ubuntu-specific)
• Unix/Linux (describing a compiled-from-source scenario)

[pfmoore]

Maybe also suggest downloading all needed packages by other means and using a local wheelhouse via --find-links? Or is this too much detail? (It's hard to cover dependencies like this, so we risk getting people confused by the fact that they downloaded what they thought they needed and they still got errors...)

Note that checking for the SSL module and failing early isn't really an option as pip install local_file doesn't need it, and we need that to still work. (Adding this note because my initial thought was exactly "hey, let's check and fail early" 🙂)

[uranusjr]

Note that checking for the SSL module and failing early isn't really an option as pip install local_file doesn't need it, and we need that to still work.

I went through exactly this before filing this 😆

The --find-links suggestion is probably too niche to be included in the error message, but IMO it’d fit well in documentation. Maybe there really should be a dedicated section on “common pip patterns” that discusses various strategies and techniques, like how --find-links can be used to maintain an in-house package repository, and how pip wheel can help building it in cases, especially when it might be unnecessary or even undesired to compile the Python with SSL in some edge cases (e.g. in a Docker container?) But that’s likely a big enough issue to tackle as a (say) GSoc or even funded project, so I’d say let’s not include that (for now) to keep things simple.

[pfmoore]

Agreed. It's borederline related to the existing funded UX work (the suggested message here is very similar to where we've ended up with the ResolutionImpossible error for the new resolver) so maybe an "error messages style guide" would be reasonable to look at from that work?

[uranusjr]

The current UX work is an important source of inspiration to the suggestion 😆

[uranusjr]

Adding #8487 to the list of confused users.