fix(ux): better error report when no links found

Author: abn

src/poetry/installation/chooser.py

@@ -50,7 +50,16 @@ def choose_for(self, package: Package) -> Link:
         Return the url of the selected archive for a given package.
         """
         links = []
+
+        # these are used only for providing insightful errors to the user
+        unsupported_wheels = set()
+        links_seen = 0
+        wheels_skipped = 0
+        sdists_skipped = 0
+
         for link in self._get_links(package):
+            links_seen += 1
+
             if link.is_wheel:
                 if not self._no_binary_policy.allows(package.name):
                     logger.debug(
@@ -59,6 +68,7 @@ def choose_for(self, package: Package) -> Link:
                         link.filename,
                         package.name,
                     )
+                    wheels_skipped += 1
                     continue
 
                 if not Wheel(link.filename).is_supported_by_environment(self._env):
@@ -67,6 +77,7 @@ def choose_for(self, package: Package) -> Link:
                         " environment",
                         link.filename,
                     )
+                    unsupported_wheels.add(link.filename)
                     continue
 
             if link.ext in {".egg", ".exe", ".msi", ".rpm", ".srpm"}:
@@ -80,12 +91,67 @@ def choose_for(self, package: Package) -> Link:
                     link.filename,
                     package.name,
                 )
+                sdists_skipped += 1
                 continue
 
             links.append(link)
 
         if not links:
-            raise RuntimeError(f"Unable to find installation candidates for {package}")
+            messages = []
+            info = (
+                f"This is likely not a Poetry issue.\n\n"
+                f"  - {links_seen} candidates were identified for the package\n"
+            )
+
+            if wheels_skipped > 0:
+                info += f"  - {wheels_skipped} wheels were skipped due to your <c1>installer.no-binary</> policy\n"
+
+            if sdists_skipped > 0:
+                info += f"  - {sdists_skipped} source distributions were skipped due to your <c1>installer.only-binary</> policy\n"
+
+            if unsupported_wheels:
+                info += (
+                    f"  - {len(unsupported_wheels)} wheels were skipped as your project's environment does not support "
+                    f"the identified abi tags\n"
+                )
+
+            messages.append(ConsoleMessage(info))
+
+            if unsupported_wheels:
+                messages += [
+                    ConsoleMessage(
+                        "The following wheels were skipped as the current project environment does not support them "
+                        "due to abi compatibility issues.",
+                        debug=True,
+                    ),
+                    ConsoleMessage("\n".join(unsupported_wheels), debug=True)
+                    .indent("  - ")
+                    .wrap("warning"),
+                    ConsoleMessage(
+                        "If you would like to see the supported tags in your project environment, you can execute "
+                        "the following command:\n\n"
+                        "    <c1>python -c 'from packaging.tags import sys_tags; print(\"\\n\".join(set(str(t) for t in sys_tags())))'</>\n\n"
+                        "<warning>The above expects you to have <c1>packaging</> package installed in the environment.",
+                        debug=True,
+                    ),
+                ]
+
+            messages.append(
+                ConsoleMessage(
+                    f"Make sure the lockfile is up-to-date. You can try one of the following;\n\n"
+                    f"    1. <b>Regenerate lockfile: </><fg=yellow>poetry lock --no-cache --regenerate</>\n"
+                    f"    2. <b>Update package     : </><fg=yellow>poetry update --no-cache {package.name}</>\n\n"
+                    f"If neither works, please check your source to verify {package.name} has released distributions "
+                    f"that are compatible with your current environment."
+                )
+                .make_section("Solutions")
+                .wrap("info")
+            )
+
+            raise PoetryRuntimeError(
+                reason=f"Unable to find installation candidates for {package}",
+                messages=messages,
+            )
 
         # Get the best link
         chosen = max(links, key=lambda link: self._sort_key(package, link))