From e2b22a84c35c808e0c12fba24fa5c8799420cfe6 Mon Sep 17 00:00:00 2001
From: Roman Yurchak <rth.yurchak@gmail.com>
Date: Tue, 17 May 2022 20:07:36 +0200
Subject: [PATCH] Add FAQ when micropip fails to find a pure python wheel
 (#2558)

Closes #2557:
Users keep reporting issues about micropip not finding a pure python wheel
e.g. latest in pyscript/pyscript#297 so it appears the the current message is
not explicit enough.

We should explain in more detail,
* what is happening and why
* what the user can do about it and possibly point them to the issue tracker.
---
 docs/usage/faq.md                           | 24 +++++++++++++++++++++
 packages/micropip/src/micropip/_micropip.py | 17 ++++++++++-----
 2 files changed, 36 insertions(+), 5 deletions(-)

diff --git a/docs/usage/faq.md b/docs/usage/faq.md
index f3b9e257e..9b0e5a8cc 100644
--- a/docs/usage/faq.md
+++ b/docs/usage/faq.md
@@ -337,3 +337,27 @@ functools.reduce = reduce(...)
 <...OMITTED LINES>
 You are now leaving help and returning to the Python interpreter.
 ```
+
+## Micropip can't find a pure Python wheel
+
+When installing a Python package from PyPI, micropip will produce an error if
+it cannot find a pure Python wheel. To determine if a package has a pure
+Python wheel manually, you can open its PyPi page (for instance
+https://pypi.org/project/snowballstemmer/) and go to the "Download files" tab.
+If this tab doesn't contain a file `*py3-none-any.whl` then the pure Python
+wheel is missing.
+
+This can happen for two reasons,
+
+1. either the package is pure Python (you can check language composition for a
+   package on Github), and its maintainers didn't upload a wheel.
+   In this case, you can report this issue to the package issue tracker. As a
+   temporary solution, you can also [build the
+   wheel](https://packaging.python.org/en/latest/tutorials/packaging-projects/#generating-distribution-archives)
+   yourself, upload it to some temporary location and install it with micropip
+   from the corresponding URL.
+2. or the package has binary extensions (e.g. C, Fortran or Rust), in which
+   case it needs to be packaged in Pyodide. Please open [an
+   issue](https://github.com/pyodide/pyodide/issues) after checking than an
+   issue for this opackage doesn't exist already. Then follow
+   {ref}`new-packages`.
diff --git a/packages/micropip/src/micropip/_micropip.py b/packages/micropip/src/micropip/_micropip.py
index ee9642e47..e460fb62d 100644
--- a/packages/micropip/src/micropip/_micropip.py
+++ b/packages/micropip/src/micropip/_micropip.py
@@ -95,7 +95,7 @@ class WheelInfo:
                 raise e
             else:
                 raise ValueError(
-                    f"Couldn't fetch wheel from '{self.url}'."
+                    f"Can't fetch wheel from '{self.url}'."
                     "One common reason for this is when the server blocks "
                     "Cross-Origin Resource Sharing (CORS)."
                     "Check if the server is sending the correct 'Access-Control-Allow-Origin' header."
@@ -149,9 +149,13 @@ class WheelInfo:
         setattr(loadedPackages, name, url)
 
 
+FAQ_URLS = {
+    "cant_find_wheel": "https://pyodide.org/en/stable/usage/faq.html#micropip-can-t-find-a-pure-python-wheel"
+}
+
+
 def find_wheel(metadata: dict[str, Any], req: Requirement) -> WheelInfo:
     """Parse metadata to find the latest version of pure python wheel.
-
     Parameters
     ----------
     metadata : ``Dict[str, Any]``
@@ -180,8 +184,10 @@ def find_wheel(metadata: dict[str, Any], req: Requirement) -> WheelInfo:
                 return wheel
 
     raise ValueError(
-        f"Couldn't find a pure Python 3 wheel for '{req}'. "
-        "You can use `micropip.install(..., keep_going=True)` to get a list of all packages with missing wheels."
+        f"Can't find a pure Python 3 wheel for '{req}'.\n"
+        f"See: {FAQ_URLS['cant_find_wheel']}\n"
+        "You can use `micropip.install(..., keep_going=True)`"
+        "to get a list of all packages with missing wheels."
     )
 
 
@@ -398,7 +404,8 @@ async def install(
     if transaction.failed:
         failed_requirements = ", ".join([f"'{req}'" for req in transaction.failed])
         raise ValueError(
-            f"Couldn't find a pure Python 3 wheel for: {failed_requirements}"
+            f"Can't find a pure Python 3 wheel for: {failed_requirements}\n"
+            f"See: {FAQ_URLS['cant_find_wheel']}\n"
         )
 
     wheel_promises = []