Warn users about shadowed entrypoint scripts on installation

[chrahunt]

As mentioned by @pradyunsg in #7209 (comment).

What's the problem this feature will solve?

When installing a package using --user with entrypoints/scripts that shadow another executable, there can be problems if that executable is on PATH before the new executable. This is especially true for Python scripts when something changes about the actual function that gets imported (like moving pip._internal:main to pip._internal.main:main).

This is one of the causes behind #5599.

Describe the solution you'd like

On installation of a package, identify the executables that were created for scripts/entrypoints. For each executable, determine if it is the executable that would be found given a normal invocation of the name (or basename, for scripts that end with something in PATHEXT). If not, then trace a warning to the user like

The package {package name} installed the script {script name} to {location}, but we found another script with the same name at {location} which is ahead of it on your PATH. If you want to execute the new script then invoke it directory or update your PATH.

Alternative Solutions

• Do nothing

Additional context

• ImportError in system pip wrappers after an upgrade #5599
• 19.3 doesn't work after upgrading from 19.2.3 #7209

[pfmoore]

determine if it is the executable that would be found given a normal invocation of the name

Just to note, such a check can only ever be approximate. Cases like shell aliases, or shells hashing commands, would defeat this check. I'm not saying that we couldn't do such a check, just that we need to be cautious about how we report the result. (We could even get false positives - a shell function could mean that the user does pick up the new wrapper, even though our check identified an issue). We had a similar debate a while ago (#6414) because not all shells expand ~ the same way in PATH.

[chrahunt]

Agreed. All of these kinds of warnings are only meant to cover the 90% case, to help reduce bad user experience (and our support workload).

We're tracking reporting possible shell path hashing issues in #6863. I think there will be overlaps with the situations matched with this heuristic, and in those cases printing both should be okay, IMO.

[pfmoore]

Sounds good to me.

[pradyunsg]

Thanks for filing this @chrahunt!