From aa69ce868ab191b3032a68118d4069339db5eec7 Mon Sep 17 00:00:00 2001
From: Andy Kipp <anki-code@users.noreply.github.com>
Date: Wed, 22 May 2024 15:25:35 +0200
Subject: [PATCH] Now last executed CommandPipeline is available in
 ``__xonsh__.last`` (#5422)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

### Motivation

There is no way to access to the CommandPipeline of executed command in
uncaptured mode. This causes:
 * No chance to get return code in one universal way.
 * Barrier to trace and inspection.

### Before

```xsh
$(ls nofile)
# No way to access to the CommandPipeline of executed command.
```

### After
```xsh
$(ls nofile)
__xonsh__.last.rtn  # In interactive or not interactive.
# 2
```
```xsh
# Sugar sir:
last = type('LastCP', (object,), {'__getattr__':lambda self, name: getattr(__xonsh__.last, name) })()

ls nofile
last.rtn
# 2
```

JFYI #5342

## For community
⬇️ **Please click the 👍 reaction instead of leaving a `+1` or 👍
comment**

---------

Co-authored-by: a <1@1.1>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
---
 docs/bash_to_xsh.rst | 14 ++++++--------
 news/last_cp.rst     | 23 +++++++++++++++++++++++
 xonsh/built_ins.py   |  1 +
 xonsh/procs/specs.py |  7 ++++++-
 4 files changed, 36 insertions(+), 9 deletions(-)
 create mode 100644 news/last_cp.rst

diff --git a/docs/bash_to_xsh.rst b/docs/bash_to_xsh.rst
index f6aae62d6..d5834f723 100644
--- a/docs/bash_to_xsh.rst
+++ b/docs/bash_to_xsh.rst
@@ -101,10 +101,10 @@ line is ``#!/usr/bin/env xonsh``.
       - ``os.getpid()``
       - Get PID of the current shell.
     * - ``$?``
-      - ``_.rtn``
+      - ``__xonsh__.last.rtn`` anywhere or ``_.rtn`` in prompt mode
       - Returns the exit code, or status, of the previous command. The underscore ``_`` is working
         in the prompt mode. To get the exit code of the command in xonsh script
-        use captured subprocess ``!().rtn``.
+        use ``!().rtn`` for not interactive processes.
     * - ``!$``
       - ``__xonsh__.history[-1, -1]``
       - Get the last argument of the last command
@@ -116,17 +116,15 @@ line is ``#!/usr/bin/env xonsh``.
       - ``$ARGS``
       - List of all command line argument and parameter strings.
     * - ``while getopts``
-      - ``import argparse``
-      - Start from `argparse <https://docs.python.org/3/library/argparse.html>`_ library to describe
-        the command line arguments in your script. Next try
-        `xontrib-argcomplete <https://github.com/anki-code/xontrib-argcomplete>`_ to activate
-        tab completion for your script.
+      - Use `argparse <https://docs.python.org/3/library/argparse.html>`_ or `click <https://click.palletsprojects.com>`_.
+      - See also `awesome-cli-app <https://github.com/anki-code/xonsh-awesome-cli-app>`_ and
+        `xontrib-argcomplete <https://github.com/anki-code/xontrib-argcomplete>`_ .
     * - ``complete``
       - ``completer list``
       - As with many other shells, xonsh ships with the ability to complete partially-specified arguments
         upon hitting the “tab” key.
     * - OhMyBash or BashIt
-      - `Xontribs <https://xon.sh/xontribs.html>`_
+      - `awesome-xontribs <https://github.com/xonsh/awesome-xontribs>`_
       - Xontributions, or ``xontribs``, are a set of tools and conventions for extending the functionality
         of xonsh beyond what is provided by default.
     * - Display completions as list
diff --git a/news/last_cp.rst b/news/last_cp.rst
new file mode 100644
index 000000000..70c35d705
--- /dev/null
+++ b/news/last_cp.rst
@@ -0,0 +1,23 @@
+**Added:**
+
+* Now last executed CommandPipeline is available in ``__xonsh__.last``.
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>
diff --git a/xonsh/built_ins.py b/xonsh/built_ins.py
index d52a6ca6b..4ba75572d 100644
--- a/xonsh/built_ins.py
+++ b/xonsh/built_ins.py
@@ -566,6 +566,7 @@ class XonshSession:
         self._completers = None
         self.builtins = None
         self._initial_builtin_names = None
+        self.last = None  # Last executed CommandPipeline.
 
     @property
     def aliases(self):
diff --git a/xonsh/procs/specs.py b/xonsh/procs/specs.py
index c0d01d5d1..e63a3a237 100644
--- a/xonsh/procs/specs.py
+++ b/xonsh/procs/specs.py
@@ -966,7 +966,12 @@ def _run_command_pipeline(specs, cmds):
 
 def _run_specs(specs, cmds):
     cp = _run_command_pipeline(specs, cmds)
-    proc, captured, background = cp.proc, specs[-1].captured, cp.spec.background
+    XSH.last, proc, captured, background = (
+        cp,
+        cp.proc,
+        specs[-1].captured,
+        cp.spec.background,
+    )
 
     # For some reason, some programs are in a stopped state when the flow
     # reaches this point, hence a SIGCONT should be sent to `proc` to make