add generic on_pre_spec_run and on_post_spec_run (#5232)

* add generic on_pre_spec_run and on_post_spec_run

* black

* edit docs/events.rst

* news

* Update on_pre_spec_run-on_post_spec_run.rst

---------

Co-authored-by: Andy Kipp <anki-code@users.noreply.github.com>

docs/events.rst

@@ -14,6 +14,21 @@ are ignored otherwise. Here are their specifications.
 
 -------
 
+``on_pre_spec_run(spec: SubprocSpec) -> None``
+.........................................................
+This event fires whenever any command has its ``SubprocSpec.run()``
+method called.  This is fired prior to the run call executing anything
+at all. This receives the ``SubprocSpec`` object as ``spec`` that triggered
+the event, allowing the handler to modify the spec if needed.  For example,
+if we wanted to intercept all specs, we could write:
+
+.. code-block:: python
+
+    @events.on_pre_spec_run
+    def print_when_ls(spec=None, **kwargs):
+        print("Running a command")
+
+
 ``on_pre_spec_run_<cmd-name>(spec: SubprocSpec) -> None``
 .........................................................
 This event fires whenever a command with a give name (``<cmd-name>``)
@@ -30,6 +45,26 @@ intercept an ``ls`` spec, we could write:
         print("Look at me list stuff!")
 
 
+``on_post_spec_run(spec: SubprocSpec) -> None``
+..........................................................
+This event fires whenever any command has its ``SubprocSpec.run()``
+method called.  This is fired after to the run call has executed
+everything except returning. This recieves the ``SubprocSpec`` object as
+``spec`` that triggered the event, allowing the handler to modify the spec
+if needed. Note that because of the way process pipelines and specs work
+in xonsh, the command will have started running, but won't necessarily have
+completed. This is because ``SubprocSpec.run()`` does not block.
+For example, if we wanted to get any spec after a command has started running,
+we could write:
+
+.. code-block:: python
+
+    @events.on_post_spec_run
+    def print_while_ls(spec=None, **kwargs):
+        print("A command is running")
+
+
+
 ``on_post_spec_run_<cmd-name>(spec: SubprocSpec) -> None``
 ..........................................................
 This event fires whenever a command with a give name (``<cmd-name>``)
@@ -48,5 +83,3 @@ we could write:
     @events.on_post_spec_run_ls
     def print_while_ls(spec=None, **kwargs):
         print("Mom! I'm listing!")
-
-

news/on_pre_spec_run-on_post_spec_run.rst

@@ -0,0 +1,24 @@
+**Added:**
+
+* Added ``on_pre_spec_run`` event.
+* Added ``on_post_spec_run`` event.
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

xonsh/procs/specs.py

@@ -548,6 +548,9 @@ class SubprocSpec:
         if events.exists(event_name):
             event = getattr(events, event_name)
             event.fire(spec=self)
+        if events.exists("on_pre_spec_run"):
+            event = events.on_pre_spec_run
+            event.fire(spec=self)
 
     def _post_run_event_fire(self, name, proc):
         events = XSH.builtins.events
@@ -555,6 +558,9 @@ class SubprocSpec:
         if events.exists(event_name):
             event = getattr(events, event_name)
             event.fire(spec=self, proc=proc)
+        if events.exists("on_post_spec_run"):
+            event = events.on_post_spec_run
+            event.fire(spec=self)
 
     #
     # Building methods