Repository: miurahr/aqtinstall
Pull request #439 (2021-10-29 18:19:24)

Add suggestion to use `--extractor` on MemoryError
This is intended to address #436, but it probably does not fix it outright.

This adds a suggestion to the `OutOfMemory` error message that the user can try an alternate 7z extractor program with the `--external` flag, with a link to the documentation for that flag. This also adds some hints on where to acquire an external 7z extractor.

I am concerned that telling users where to obtain an external 7z extractor might be a little excessive. I think it's very unlikely that a developer using aqtinstall doesn't already have such tools installed. It is probably better to be neutral about which tool users should use, and not promote any one 7zip extractor tool. However, I would prefer to err on the side of being "too helpful" in the documentation than "not helpful enough". The documentation change is in a separate commit so that it can be easily reverted if necessary.


Patch:
diff --git a/aqt/installer.py b/aqt/installer.py
index 17d51bb..9beddca 100644
--- a/aqt/installer.py
+++ b/aqt/installer.py
@@ -850,14 +850,19 @@ def run_installer(archives: List[QtPackage], base_dir: str, sevenzip: Optional[s
         raise CliKeyboardInterrupt("Installer halted by keyboard interrupt.") from e
     except MemoryError as e:
         close_worker_pool_on_exception(e)
+        alt_extractor_msg = (
+            "Please try using the '--external' flag to specify an alternate 7z extraction tool "
+            "(see https://aqtinstall.readthedocs.io/en/latest/cli.html#cmdoption-list-tool-external)"
+        )
         if Settings.concurrency > 1:
             docs_url = "https://aqtinstall.readthedocs.io/en/stable/configuration.html#configuration"
             raise OutOfMemory(
                 "Out of memory when downloading and extracting archives in parallel.",
-                suggested_action=[f"Please reduce your 'concurrency' setting (see {docs_url})"],
+                suggested_action=[f"Please reduce your 'concurrency' setting (see {docs_url})", alt_extractor_msg],
             ) from e
         raise OutOfMemory(
-            "Out of memory when downloading and extracting archives.", suggested_action=["Please free up more memory."]
+            "Out of memory when downloading and extracting archives.",
+            suggested_action=["Please free up more memory.", alt_extractor_msg],
         )
     except Exception as e:
         close_worker_pool_on_exception(e)
diff --git a/docs/cli.rst b/docs/cli.rst
index 6c77707..b29db53 100644
--- a/docs/cli.rst
+++ b/docs/cli.rst
@@ -223,7 +223,15 @@ are described here:
 
     Specify external 7zip command path. By default, aqt uses py7zr_ for this task.
 
+    In the past, our users have had success using 7-zip_ on Windows, Linux and Mac.
+    You can install 7-zip on Windows with Choco_.
+    The Linux/Mac port of 7-zip is called ``p7zip``, and you can install it with brew_ on Mac,
+    or on Linux with your package manager.
+
 .. _py7zr: https://pypi.org/project/py7zr/
+.. _7-zip: https://www.7-zip.org/
+.. _Choco: https://community.chocolatey.org/packages/7zip/19.0
+.. _brew: https://formulae.brew.sh/formula/p7zip
 
 .. option:: --internal
 


Test patch:
diff --git a/tests/test_install.py b/tests/test_install.py
index 2a0b7bb..0fbe6c1 100644
--- a/tests/test_install.py
+++ b/tests/test_install.py
@@ -614,7 +614,9 @@ def test_install_nonexistent_archives(monkeypatch, capsys, cmd, xml_file: Option
             "Out of memory when downloading and extracting archives in parallel.\n"
             "==============================Suggested follow-up:==============================\n"
             "* Please reduce your 'concurrency' setting (see "
-            "https://aqtinstall.readthedocs.io/en/stable/configuration.html#configuration)",
+            "https://aqtinstall.readthedocs.io/en/stable/configuration.html#configuration)\n"
+            "* Please try using the '--external' flag to specify an alternate 7z extraction tool "
+            "(see https://aqtinstall.readthedocs.io/en/latest/cli.html#cmdoption-list-tool-external)",
             1,
         ),
         (
@@ -623,7 +625,9 @@ def test_install_nonexistent_archives(monkeypatch, capsys, cmd, xml_file: Option
             "Caught MemoryError, terminating installer workers\n"
             "Out of memory when downloading and extracting archives.\n"
             "==============================Suggested follow-up:==============================\n"
-            "* Please free up more memory.",
+            "* Please free up more memory.\n"
+            "* Please try using the '--external' flag to specify an alternate 7z extraction tool "
+            "(see https://aqtinstall.readthedocs.io/en/latest/cli.html#cmdoption-list-tool-external)",
             1,
         ),
     ),