Merge 000903cc79 into a15dd75d98

docs/html/cli/pip_install.rst

@@ -45,8 +45,8 @@ When looking at the items to be installed, pip checks what type of item
 each is, in the following order:
 
 1. Project or archive URL.
-2. Local directory (which must contain a ``setup.py``, or pip will report
-   an error).
+2. Local directory (which must contain a ``pyproject.toml`` or ``setup.py``,
+   otherwise pip will report an error).
 3. Local file (a sdist or wheel format archive, following the naming
    conventions for those formats).
 4. A requirement, as specified in :pep:`440`.

news/11577.bugfix.rst

@@ -0,0 +1 @@
+Improve error message when using non-local file URIs

news/12417.doc.rst

@@ -0,0 +1 @@
+Fix outdated pip install argument description in documentation.

src/pip/_internal/utils/urls.py

@@ -1,5 +1,7 @@
 import os
+import re
 import string
+import sys
 import urllib.parse
 import urllib.request
 from typing import Optional
@@ -40,8 +42,15 @@ def url_to_path(url: str) -> str:
         # If we have a UNC path, prepend UNC share notation.
         netloc = "\\\\" + netloc
     else:
+        # do not include traceback as the error message should be self-explaining
+        sys.tracebacklimit = 0
+        # suggest using 'file:/' to the user:
+        suggestion = re.sub("(^file:)(/)+", "file:/", url)
+
         raise ValueError(
-            f"non-local file URIs are not supported on this platform: {url!r}"
+            f"{url!r} points to the domain '{netloc}'. "
+            f"Non-local file URIs are not supported on this platform. "
+            f"Did you mean to use '{suggestion}'?"
         )
 
     path = urllib.request.url2pathname(netloc + path)