Added click.pause

5 files changed, 53 insertions, 2 deletions

diff --git a/CHANGES b/CHANGES
index 27b2a19..93ff603 100644
--- a/CHANGES
+++ b/CHANGES
@@ -36,6 +36,9 @@ Version 2.0
 - errors now go to stderr as intended.
 - fixed various issues with more exotic parameter formats like DOS/Windows
   style arguments.
+- added :func:`pause` which works similar to the windows ``pause`` cmd
+  built in but becomes an automatic noop if the application is not run
+  through a terminal.
 
 Version 1.1
 -----------
diff --git a/click/__init__.py b/click/__init__.py
index 8527fd4..4f3ca19 100644
--- a/click/__init__.py
+++ b/click/__init__.py
@@ -33,7 +33,8 @@ from .utils import echo, get_binary_stream, get_text_stream, \
 
 # Terminal functions
 from .termui import prompt, confirm, get_terminal_size, echo_via_pager, \
-     progressbar, clear, style, unstyle, secho, edit, launch, getchar
+     progressbar, clear, style, unstyle, secho, edit, launch, getchar, \
+     pause
 
 # Exceptions
 from .exceptions import ClickException, UsageError, BadParameter, \
@@ -67,7 +68,7 @@ __all__ = [
     # Terminal functions
     'prompt', 'confirm', 'get_terminal_size', 'echo_via_pager',
     'progressbar', 'clear', 'style', 'unstyle', 'secho', 'edit', 'launch',
-    'getchar',
+    'getchar', 'pause',
 
     # Exceptions
     'ClickException', 'UsageError', 'BadParameter', 'FileError',
diff --git a/click/termui.py b/click/termui.py
index a299a59..527fe61 100644
--- a/click/termui.py
+++ b/click/termui.py
@@ -461,3 +461,27 @@ def getchar(echo=False):
     if f is None:
         from ._termui_impl import getchar as f
     return f(echo)
+
+
+def pause(info='Press any key to continue ...'):
+    """This command stops execution and waits for the user to press any
+    key to continue.  This is similar to the Windows batch "pause"
+    command.  If the program is not run through a terminal this command
+    will do nothing instead.
+
+    .. versionadded:: 2.0
+
+    :param info: the info string to print before pausing.
+    """
+    if not isatty(sys.stdin) or not isatty(sys.stdout):
+        return
+    try:
+        if info:
+            echo(info, nl=False)
+        try:
+            getchar()
+        except (KeyboardInterrupt, EOFError):
+            pass
+    finally:
+        if info:
+            echo()
diff --git a/docs/api.rst b/docs/api.rst
index 5aa4f89..307348c 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -58,6 +58,8 @@ Utilities
 
 .. autofunction:: getchar
 
+.. autofunction:: pause
+
 .. autofunction:: get_terminal_size
 
 .. autofunction:: get_binary_stream
diff --git a/docs/utils.rst b/docs/utils.rst
index 099066f..4692b2e 100644
--- a/docs/utils.rst
+++ b/docs/utils.rst
@@ -149,6 +149,27 @@ too easy to forget about that and to create scripts that cannot be
 properly exited.
 
 
+Waiting for Key Press
+---------------------
+
+.. versionadded:: 2.0
+
+Sometimes it's useful to pause until the user presses any key on the
+keyboard.  This is especially useful on windows where ``cmd.exe`` by
+default will close the window at the end of the command execution instead
+of waiting.
+
+In click this can be accomplished by the :func:`pause` function.  This
+function will print a quick message to the terminal (which can be
+customized) and wait for the user to press a key.  In addition to that
+it will also become a noop if the script is not run interactively.
+
+Example::
+
+    import click
+    click.pause()
+
+
 Launching Editors
 -----------------