Returncode enhancements (#4798)

Co-authored-by: Gil Forsyth <gforsyth@users.noreply.github.com>

docs/tutorial.rst

@@ -1554,6 +1554,8 @@ By default, the following variables are available for use:
   * ``localtime``: The current, local time as given by ``time.localtime()``.
     This is formatted with the time format string found in ``time_format``.
   * ``time_format``: A time format string, defaulting to ``"%H:%M:%S"``.
+  * ``last_return_code``: The return code of the last issued command. 
+  * ``last_return_code_if_nonzero``: The return code of the last issued command if it is non-zero, otherwise ``None``. This is useful for only printing the code in case of errors.
 
 .. note:: See the section below on ``PROMPT_FIELDS`` for more information on changing.
 

news/feat_returncode_enhancements.rst

@@ -0,0 +1,24 @@
+**Added:**
+
+* Added a special '$LAST_RETURN_CODE' environment variable to access the return code of the last issued command. (Only set during interactive use).
+* New prompt-customization fields: 'last_return_code_if_nonzero', 'last_return_code'.
+
+**Changed:**
+
+* The default prompt (on unix-systems) now includes a red [<errorcode>] field in case a command failed.
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

xonsh/base_shell.py

@@ -430,6 +430,7 @@ class BaseShell:
         """
         hist = XSH.history  # pylint: disable=no-member
         info["rtn"] = hist.last_cmd_rtn if hist is not None else None
+        XSH.env["LAST_RETURN_CODE"] = info["rtn"] or 0
         tee_out = tee_out or None
         last_out = hist.last_cmd_out if hist is not None else None
         if last_out is None and tee_out is None:

xonsh/environ.py

@@ -920,6 +920,11 @@ class GeneralSetting(Xettings):
         "should cause an end to execution. This is less useful at a terminal. "
         "The error that is raised is a ``subprocess.CalledProcessError``.",
     )
+    LAST_RETURN_CODE = Var.with_default(
+        0,
+        "Integer return code of the last command. Only updated during interactive use, i.e. not during execution of scripts.",
+    )
+
     SHLVL = Var(
         is_valid_shlvl,
         to_shlvl,

xonsh/prompt/base.py

@@ -158,6 +158,7 @@ def default_prompt():
             "{env_name}"
             "{BOLD_GREEN}{user}@{hostname}{BOLD_BLUE} "
             "{cwd}{branch_color}{curr_branch: {}}{RESET} "
+            "{RED}{last_return_code_if_nonzero:[{BOLD_INTENSE_RED}{}{RED}] }{RESET}"
             "{BOLD_BLUE}{prompt_end}{RESET} "
         )
     return dp
@@ -355,6 +356,9 @@ class PromptFields(tp.MutableMapping[str, "FieldType"]):
                 vte_new_tab_cwd=vte_new_tab_cwd,
                 time_format="%H:%M:%S",
                 localtime=_localtime,
+                last_return_code=lambda: XSH.env.get("LAST_RETURN_CODE", 0),
+                last_return_code_if_nonzero=lambda: XSH.env.get("LAST_RETURN_CODE", 0)
+                or None,
             )
         )
         for val in self.get_fields(gitstatus):