Improved first-run experience (#190)

Improves message for global directory.
Adds check for whether the latest Python is installed, separate from any. (Fixes #187)
Use default_platform to select best online runtime. (Fixes #186)

Author: zooba

src/manage/commands.py

@@ -262,6 +262,7 @@ def execute(self):
         "check_long_paths": (config_bool, None, "env"),
         "check_py_on_path": (config_bool, None, "env"),
         "check_any_install": (config_bool, None, "env"),
+        "check_latest_install": (config_bool, None, "env"),
         "check_global_dir": (config_bool, None, "env"),
     },
 
@@ -698,16 +699,22 @@ class ListCommand(BaseCommand):
     one = False
     unmanaged = True
     source = None
+    fallback_source = None
     default_source = False
     keep_log = False
 
+    # Not settable from the CLI/config, but used internally
+    formatter_callable = None
+    fallback_source_only = False
+
     def execute(self):
         from .list_command import execute
         self.show_welcome()
         if self.default_source:
             LOGGER.debug("Loading 'install' command to get source")
             inst_cmd = COMMANDS["install"](["install"], self.root)
             self.source = inst_cmd.source
+            self.fallback_source = inst_cmd.fallback_source
         if self.source and "://" not in str(self.source):
             try:
                 self.source = Path(self.source).absolute().as_uri()
@@ -981,7 +988,8 @@ class FirstRun(BaseCommand):
     check_app_alias = True
     check_long_paths = True
     check_py_on_path = True
-    check_any_install = True
+    check_any_install = False
+    check_latest_install = True
     check_global_dir = True
 
     def execute(self):

src/manage/firstrun.py

@@ -248,6 +248,51 @@ def check_any_install(cmd):
     return True
 
 
+def _list_available_fallback_runtimes(cmd):
+    from .commands import find_command
+
+    candidates = []
+    try:
+        list_cmd = find_command(["list", "--online", "-1", "default"], cmd.root)
+        list_cmd.formatter_callable = lambda cmd, installs: candidates.extend(installs)
+        list_cmd.fallback_source_only = True
+        list_cmd.execute()
+        if not candidates:
+            list_cmd.fallback_source_only = False
+            list_cmd.execute()
+    except Exception:
+        LOGGER.debug("Check skipped: Failed to find 'list' command.", exc_info=True)
+        return []
+    except SystemExit:
+        LOGGER.debug("Check skipped: Failed to execute 'list' command.")
+        return []
+
+    return candidates
+
+
+def check_latest_install(cmd):
+    LOGGER.debug("Checking if any default runtime is installed")
+
+    available = _list_available_fallback_runtimes(cmd)
+    if not available:
+        return "skip"
+
+    installs = cmd.get_installs(include_unmanaged=True, set_default=False)
+    if not installs:
+        LOGGER.debug("Check failed: no installs found")
+        return False
+
+    present = {i.get("tag") for i in installs}
+    available = set(j for i in available for j in i.get("install-for", []))
+    LOGGER.debug("Already installed: %s", sorted(present))
+    LOGGER.debug("Available: %s", sorted(available))
+    if available & present:
+        LOGGER.debug("Check passed: installs found")
+        return True
+    LOGGER.debug("Check failed: no equivalent 'default' runtime installed")
+    return False
+
+
 def do_install(cmd):
     from .commands import find_command
     try:
@@ -360,16 +405,19 @@ def first_run(cmd):
             welcome()
             line_break()
             shown_any = True
-            LOGGER.print("!Y!The directory for versioned Python commands is not "
+            LOGGER.print("!Y!The global shortcuts directory is not "
                          "configured.!W!", level=logging.WARN)
-            LOGGER.print("\nThis will prevent commands like !B!python3.14.exe!W! "
-                         "working, but will not affect the !B!python!W! or "
-                         "!B!py!W! commands (for example, !B!py -V:3.14!W!).",
+            LOGGER.print("\nConfiguring this enables commands like "
+                         "!B!python3.14.exe!W! to run from your terminal, "
+                         "but is not needed for the !B!python!W! or !B!py!W! "
+                         "commands (for example, !B!py -V:3.14!W!).",
+                         wrap=True)
+            LOGGER.print("\nWe can add the directory (!B!%s!W!) to PATH now, "
+                         "but you will need to restart your terminal to use "
+                         "it. The entry will be removed if you run !B!py "
+                         "uninstall --purge!W!, or else you can remove it "
+                         "manually when uninstalling Python.\n", cmd.global_dir,
                          wrap=True)
-            LOGGER.print("\nWe can add the directory to PATH now, but you will "
-                         "need to restart your terminal to see the change, and "
-                         "must manually edit environment variables to later "
-                         "remove the entry.\n", wrap=True)
             if (
                 not cmd.confirm or
                 not cmd.ask_ny("Add commands directory to your PATH now?")
@@ -399,6 +447,22 @@ def first_run(cmd):
         elif cmd.explicit:
             LOGGER.info("Checked for any Python installs")
 
+    if cmd.check_latest_install:
+        if not check_latest_install(cmd):
+            welcome()
+            line_break()
+            shown_any = True
+            LOGGER.print("!Y!You do not have the latest Python runtime.!W!",
+                         level=logging.WARN)
+            LOGGER.print("\nInstall the current latest version of CPython? If "
+                         "not, you can use '!B!py install default!W!' later to "
+                         "install.\n", wrap=True)
+            LOGGER.info("")
+            if not cmd.confirm or cmd.ask_yn("Install CPython now?"):
+                do_install(cmd)
+        elif cmd.explicit:
+            LOGGER.info("Checked for the latest available Python install")
+
     if shown_any or cmd.explicit:
         line_break()
         LOGGER.print("!G!Configuration checks completed.!W!", level=logging.WARN)

src/manage/list_command.py

@@ -1,5 +1,4 @@
 import json
-import sys
 
 from . import logging
 from .exceptions import ArgumentError
@@ -285,36 +284,67 @@ def _get_installs_from_index(indexes, filters):
 def execute(cmd):
     LOGGER.debug("BEGIN list_command.execute: %r", cmd.args)
 
-    try:
-        LOGGER.debug("Get formatter %s", cmd.format)
-        formatter = FORMATTERS[cmd.format]
-    except LookupError:
-        formatters = FORMATTERS.keys() - {"legacy", "legacy-paths"}
-        expect = ", ".join(sorted(formatters))
-        raise ArgumentError(f"'{cmd.format}' is not a valid format; expected one of: {expect}") from None
+    if cmd.formatter_callable:
+        formatter = cmd.formatter_callable
+    else:
+        try:
+            LOGGER.debug("Get formatter %s", cmd.format)
+            formatter = FORMATTERS[cmd.format]
+        except LookupError:
+            formatters = FORMATTERS.keys() - {"legacy", "legacy-paths"}
+            expect = ", ".join(sorted(formatters))
+            raise ArgumentError(f"'{cmd.format}' is not a valid format; expected one of: {expect}") from None
 
     from .tagutils import tag_or_range, install_matches_any
     tags = []
+    plat = None
     for arg in cmd.args:
         if arg.casefold() == "default".casefold():
             LOGGER.debug("Replacing 'default' with '%s'", cmd.default_tag)
             tags.append(tag_or_range(cmd.default_tag))
         else:
             try:
                 tags.append(tag_or_range(arg))
+                try:
+                    if not plat:
+                        plat = tags[-1].platform
+                except AttributeError:
+                    pass
             except ValueError as ex:
                 LOGGER.warn("%s", ex)
+    plat = plat or cmd.default_platform
 
     if cmd.source:
         from .indexutils import Index
         from .urlutils import IndexDownloader
-        try:
-            installs = _get_installs_from_index(
-                IndexDownloader(cmd.source, Index),
-                tags,
-            )
-        except OSError as ex:
-            raise SystemExit(1) from ex
+        installs = []
+        first_exc = None
+        for source in [
+            None if cmd.fallback_source_only else cmd.source,
+            cmd.fallback_source,
+        ]:
+            if source:
+                try:
+                    installs = _get_installs_from_index(
+                        IndexDownloader(source, Index),
+                        tags,
+                    )
+                    break
+                except OSError as ex:
+                    if first_exc is None:
+                        first_exc = ex
+        if first_exc:
+            raise SystemExit(1) from first_exc
+        if cmd.one:
+            # Pick the first non-prerelease that'll install for our platform
+            best = [i for i in installs
+                    if any(t.endswith(plat) for t in i.get("install-for", []))]
+            for i in best:
+                if not i["sort-version"].is_prerelease:
+                    installs = [i]
+                    break
+            else:
+                installs = best[:1] or installs
     elif cmd.install_dir:
         try:
             installs = cmd.get_installs(include_unmanaged=cmd.unmanaged)

src/manage/uninstall_command.py

@@ -18,7 +18,6 @@ def _iterdir(p, only_files=False):
 
 
 def _do_purge_global_dir(global_dir, warn_msg, *, hive=None, subkey="Environment"):
-    import os
     import winreg
 
     if hive is None:

src/manage/verutils.py

@@ -13,15 +13,19 @@ class Version:
     }
 
     _TEXT_UNMAP = {v: k for k, v in TEXT_MAP.items()}
+    _LEVELS = None
 
     # Versions with more fields than this will be truncated.
     MAX_FIELDS = 8
 
     def __init__(self, s):
         import re
-        levels = "|".join(re.escape(k) for k in self.TEXT_MAP if k)
+        if isinstance(s, Version):
+            s = s.s
+        if not Version._LEVELS:
+            Version._LEVELS = "|".join(re.escape(k) for k in self.TEXT_MAP if k)
         m = re.match(
-            r"^(?P<numbers>\d+(\.\d+)*)([\.\-]?(?P<level>" + levels + r")[\.]?(?P<serial>\d*))?$",
+            r"^(?P<numbers>\d+(\.\d+)*)([\.\-]?(?P<level>" + Version._LEVELS + r")[\.]?(?P<serial>\d*))?$",
             s,
             re.I,
         )

tests/conftest.py

@@ -149,6 +149,7 @@ def localserver():
 
 class FakeConfig:
     def __init__(self, global_dir, installs=[]):
+        self.root = global_dir.parent if global_dir else None
         self.global_dir = global_dir
         self.confirm = False
         self.installs = list(installs)

tests/test_firstrun.py

@@ -99,6 +99,27 @@ def test_check_any_install(fake_config):
     assert firstrun.check_any_install(fake_config) == True
 
 
+def test_check_latest_install(fake_config, monkeypatch):
+    fake_config.default_tag = "1"
+    fake_config.default_platform = "-64"
+    assert firstrun.check_latest_install(fake_config) == False
+
+    fake_config.installs.append({"tag": "1.0-64"})
+    assert firstrun.check_latest_install(fake_config) == False
+
+    def _fallbacks(cmd):
+        return [{"install-for": ["1.0-64"]}]
+
+    monkeypatch.setattr(firstrun, "_list_available_fallback_runtimes", _fallbacks)
+    assert firstrun.check_latest_install(fake_config) == True
+
+    def _fallbacks(cmd):
+        return [{"install-for": ["1.0-32"]}]
+
+    monkeypatch.setattr(firstrun, "_list_available_fallback_runtimes", _fallbacks)
+    assert firstrun.check_latest_install(fake_config) == False
+
+
 def test_welcome(assert_log):
     welcome = firstrun._Welcome()
     assert_log(assert_log.end_of_log())

tests/test_list.py

@@ -31,7 +31,9 @@ def __init__(self):
         self.captured = []
         self.source = None
         self.install_dir = "<none>"
+        self.default_platform = "-64"
         self.format = "test"
+        self.formatter_callable = None
         self.one = False
         self.unmanaged = True
         list_command.FORMATTERS["test"] = lambda c, i: self.captured.extend(i)