Made async stuff public

Author: kmvanbrunt

cmd2/cmd2.py

@@ -530,7 +530,7 @@ def __init__(self, completekey: str='tab', stdin=None, stdout=None, persistent_h
         # This lock should be acquired before doing any asynchronous changes to the terminal to
         # ensure the updates to the terminal don't interfere with the input being typed. It can be
         # acquired any time there is a readline prompt on screen.
-        self._terminal_lock = threading.RLock()
+        self.terminal_lock = threading.RLock()
 
     # -----  Methods related to presenting output to the user -----
 
@@ -2085,10 +2085,10 @@ def pseudo_raw_input(self, prompt: str) -> str:
         if self.use_rawinput:
             try:
                 if sys.stdin.isatty():
-                    # Wrap in try since _terminal_lock may not be locked when this function is called from unit tests
+                    # Wrap in try since terminal_lock may not be locked when this function is called from unit tests
                     try:
                         # A prompt is about to be drawn. Allow asynchronous changes to the terminal.
-                        self._terminal_lock.release()
+                        self.terminal_lock.release()
                     except RuntimeError:
                         pass
 
@@ -2104,7 +2104,7 @@ def pseudo_raw_input(self, prompt: str) -> str:
             finally:
                 if sys.stdin.isatty():
                     # The prompt is gone. Do not allow asynchronous changes to the terminal.
-                    self._terminal_lock.acquire()
+                    self.terminal_lock.acquire()
         else:
             if self.stdin.isatty():
                 # on a tty, print the prompt first, then read the line
@@ -3237,25 +3237,25 @@ def _clear_input_lines_str(self) -> str:
 
         return terminal_str
 
-    def _async_alert(self, alert_msg: str, new_prompt: Optional[str] = None) -> None:
+    def async_alert(self, alert_msg: str, new_prompt: Optional[str] = None) -> None:
         """
         Used to display an important message to the user while they are at the prompt in between commands.
         To the user it appears as if an alert message is printed above the prompt and their current input
         text and cursor location is left alone.
 
-        IMPORTANT: Do not call this unless you have acquired self._terminal_lock
+        IMPORTANT: Do not call this unless you have acquired self.terminal_lock
                    first, which ensures a prompt is onscreen
 
         :param alert_msg: the message to display to the user
         :param new_prompt: if you also want to change the prompt that is displayed, then include it here
                            see async_update_prompt() docstring for guidance on updating a prompt
-        :raises RuntimeError if called while another thread holds _terminal_lock
+        :raises RuntimeError if called while another thread holds terminal_lock
         """
         if not (vt100_support and self.use_rawinput):
             return
 
-        # Sanity check that can't fail if self._terminal_lock was acquired before calling this function
-        if self._terminal_lock.acquire(blocking=False):
+        # Sanity check that can't fail if self.terminal_lock was acquired before calling this function
+        if self.terminal_lock.acquire(blocking=False):
 
             # Generate a string to clear the prompt and input lines and replace with the alert
             terminal_str = self._clear_input_lines_str()
@@ -3275,30 +3275,30 @@ def _async_alert(self, alert_msg: str, new_prompt: Optional[str] = None) -> None
             # Redraw the prompt and input lines
             rl_force_redisplay()
 
-            self._terminal_lock.release()
+            self.terminal_lock.release()
 
         else:
-            raise RuntimeError("another thread holds _terminal_lock")
+            raise RuntimeError("another thread holds terminal_lock")
 
-    def _async_update_prompt(self, new_prompt: str) -> None:
+    def async_update_prompt(self, new_prompt: str) -> None:
         """
         Updates the prompt while the user is still typing at it. This is good for alerting the user to system
         changes dynamically in between commands. For instance you could alter the color of the prompt to indicate
         a system status or increase a counter to report an event. If you do alter the actual text of the prompt,
         it is best to keep the prompt the same width as what's on screen. Otherwise the user's input text will
         be shifted and the update will not be seamless.
 
-        IMPORTANT: Do not call this unless you have acquired self._terminal_lock
+        IMPORTANT: Do not call this unless you have acquired self.terminal_lock
                    first, which ensures a prompt is onscreen
 
         :param new_prompt: what to change the prompt to
-        :raises RuntimeError if called while another thread holds _terminal_lock
+        :raises RuntimeError if called while another thread holds terminal_lock
         """
         if not (vt100_support and self.use_rawinput):
             return
 
-        # Sanity check that can't fail if self._terminal_lock was acquired before calling this function
-        if self._terminal_lock.acquire(blocking=False):
+        # Sanity check that can't fail if self.terminal_lock was acquired before calling this function
+        if self.terminal_lock.acquire(blocking=False):
 
             # Generate a string to clear the prompt and input lines
             terminal_str = self._clear_input_lines_str()
@@ -3316,10 +3316,10 @@ def _async_update_prompt(self, new_prompt: str) -> None:
             # Redraw the prompt and input lines
             rl_force_redisplay()
 
-            self._terminal_lock.release()
+            self.terminal_lock.release()
 
         else:
-            raise RuntimeError("another thread holds _terminal_lock")
+            raise RuntimeError("another thread holds terminal_lock")
 
     @staticmethod
     def set_window_title(title: str) -> None:
@@ -3368,7 +3368,7 @@ def cmdloop(self, intro: Optional[str]=None) -> None:
         signal.signal(signal.SIGINT, self.sigint_handler)
 
         # Grab terminal lock before the prompt has been drawn by readline
-        self._terminal_lock.acquire()
+        self.terminal_lock.acquire()
 
         # Always run the preloop first
         for func in self._preloop_hooks:
@@ -3397,7 +3397,7 @@ def cmdloop(self, intro: Optional[str]=None) -> None:
 
         # Release terminal lock now that postloop code should have stopped any terminal updater threads
         # This will also zero the lock count in case cmdloop() is called again
-        self._terminal_lock.release()
+        self.terminal_lock.release()
 
         # Restore the original signal handler
         signal.signal(signal.SIGINT, original_sigint_handler)

docs/unfreefeatures.rst

@@ -198,12 +198,12 @@ the command line. This means the feedback is provided to the user when they are
 the prompt. To use this functionality, the application must be running in any terminal that supports
 VT100 control characters and readline. Linux, Mac, and Windows 10 and greater all support these.
 
-_async_alert()
+async_alert()
     Used to display an important message to the user while they are at the prompt in between commands.
     To the user it appears as if an alert message is printed above the prompt and their current input
     text and cursor location is left alone.
 
-_async_update_prompt()
+async_update_prompt()
     Updates the prompt while the user is still typing at it. This is good for alerting the user to system
     changes dynamically in between commands. For instance you could alter the color of the prompt to indicate
     a system status or increase a counter to report an event.

examples/async_printing.py

@@ -45,7 +45,7 @@ def __init__(self, *args, **kwargs) -> None:
 
     def _preloop_hook(self) -> None:
         """ Start the alerter thread """
-        # This runs after cmdloop() acquires self._terminal_lock, which will be locked until the prompt appears.
+        # This runs after cmdloop() acquires self.terminal_lock, which will be locked until the prompt appears.
         # Therefore this is the best place to start the alerter thread since there is no risk of it alerting
         # before the prompt is displayed. You can also start it via a command if its not something that should
         # be running during the entire application. See do_start_alerts().
@@ -57,7 +57,7 @@ def _preloop_hook(self) -> None:
     def _postloop_hook(self) -> None:
         """ Stops the alerter thread """
 
-        # After this function returns, cmdloop() releases self._terminal_lock which could make the alerter
+        # After this function returns, cmdloop() releases self.terminal_lock which could make the alerter
         # thread think the prompt is on screen. Therefore this is the best place to stop the alerter thread.
         # You can also stop it via a command. See do_stop_alerts().
         self._stop_thread = True
@@ -166,9 +166,9 @@ def _alerter_thread_func(self) -> None:
         self._next_alert_time = 0
 
         while not self._stop_thread:
-            # Always acquire _terminal_lock before printing alerts or updating the prompt
+            # Always acquire terminal_lock before printing alerts or updating the prompt
             # To keep the app responsive, do not block on this call
-            if self._terminal_lock.acquire(blocking=False):
+            if self.terminal_lock.acquire(blocking=False):
 
                 # Get any alerts that need to be printed
                 alert_str = self._generate_alert_str()
@@ -178,15 +178,15 @@ def _alerter_thread_func(self) -> None:
 
                 # Check if we have alerts to print
                 if alert_str:
-                    # new_prompt is an optional parameter to _async_alert()
-                    self._async_alert(alert_str, new_prompt)
+                    # new_prompt is an optional parameter to async_alert()
+                    self.async_alert(alert_str, new_prompt)
 
                 # No alerts needed to be printed, check if the prompt changed
                 elif new_prompt != self.prompt:
-                    self._async_update_prompt(new_prompt)
+                    self.async_update_prompt(new_prompt)
 
                 # Don't forget to release the lock
-                self._terminal_lock.release()
+                self.terminal_lock.release()
 
             time.sleep(0.5)