Clarify warning for incompletely removed distributions

[2ykwang]

Fixes #11849.

add a distinct warning for ~ -prefixed leftovers, marking them as incompletely removed and safe to delete.

the check uses the metadata directory name instead of the distribution name, since pkg_resources (default on 3.10) turns the leading ~ into -. Open to a different approach.

output:

[sepehr-rs]

Hi @2ykwang, thanks for the contribution!
Just a heads-up that pip is a volunteer project, so it may take some time before a maintainer gets to review this.
Appreciate the PR!

[2ykwang]

Thanks @sepehr-rs appreciate it. no rush!

[sepehr-rs]

Thank you for your contribution!
I tested this locally and the new warning message is more user-friendly. The tests look good too.
I do have one comment on the leftover_name logic that's worth addressing for future releases. Besides that, LGTM from me!
Let me know if you have any questions.

[ichard26]

Sorry for taking a while to review this. My overall concern is that I'm not too sure what happens when an incompletely removed distribution is left. I'm fairly certain it's safe to remove in 95% of situations, but I don't know where it could go wrong.

I'll take a closer look when I can when I have more time to dig into the uninstall code.

[pfmoore]

Maybe we should just qualify the message a little?

'~'-prefixed leftover directories are the result of a previous incomplete installation, and can be deleted.

By explaining the cause, and deliberately omitting the word "safe", we still indicate what the user should do, but with the implication that "if you want to be cautious, you should work out why the previous installation failed".

[2ykwang]

@pfmoore 's suggestion sounds like a good compromise to me, since it avoids stating categorically that the directories are safe to delete.
I also think the message could be more helpful if it explained what happens when those directories are deleted.

[ichard26]

+1 to @pfmoore's suggestion. It'd still be nice to understand when ~ prefixed directories are left though (with the rewording, it's not essential to accepting this PR, but I'm more comfortable when I have the larger picture).

[2ykwang]

before updating the wording. I'll also look into this a bit more