Renamed progress_bar context manager to ProgressBar + other doc improvements.

26 files changed, 71 insertions, 66 deletions

diff --git a/docs/pages/dialogs.rst b/docs/pages/dialogs.rst
index f338e321..4fca12c9 100644
--- a/docs/pages/dialogs.rst
+++ b/docs/pages/dialogs.rst
@@ -10,12 +10,12 @@ the Whiptail program, but in pure Python.
 Message box
 -----------
 
-Use the :func:`~prompt_toolkit.shortcuts.dialogs.message_dialog` function to
-display a simple message box. For instance:
+Use the :func:`~prompt_toolkit.shortcuts.message_dialog` function to display a
+simple message box. For instance:
 
 .. code:: python
 
-    from prompt_toolkit.shortcuts.dialogs import message_dialog
+    from prompt_toolkit.shortcuts import message_dialog
 
     message_dialog(
         title='Example dialog window',
@@ -27,12 +27,12 @@ display a simple message box. For instance:
 Input box
 ---------
 
-The :func:`~prompt_toolkit.shortcuts.dialogs.input_dialog` function can display
-an input box. It will return the user input as a string.
+The :func:`~prompt_toolkit.shortcuts.input_dialog` function can display an
+input box. It will return the user input as a string.
 
 .. code:: python
 
-    from prompt_toolkit.shortcuts.dialogs import input_dialog
+    from prompt_toolkit.shortcuts import input_dialog
 
     text = input_dialog(
         title='Input dialog example',
@@ -42,20 +42,19 @@ an input box. It will return the user input as a string.
 
 
 The ``password=True`` option can be passed to the
-:func:`~prompt_toolkit.shortcuts.dialogs.input_dialog` function to turn this
-into a password input box.
+:func:`~prompt_toolkit.shortcuts.input_dialog` function to turn this into a
+password input box.
 
 
 Yes/No confirmation dialog
 --------------------------
 
-The :func:`~prompt_toolkit.shortcuts.dialogs.yes_no_dialog` function displays a
-yes/no confirmation dialog. It will return a boolean according to the
-selection.
+The :func:`~prompt_toolkit.shortcuts.yes_no_dialog` function displays a yes/no
+confirmation dialog. It will return a boolean according to the selection.
 
 .. code:: python
 
-    from prompt_toolkit.shortcuts.dialogs import yes_no_dialog
+    from prompt_toolkit.shortcuts import yes_no_dialog
 
     result = yes_no_dialog(
         title='Yes/No dialog example',
@@ -67,13 +66,13 @@ selection.
 Button dialog
 --------------------------
 
-The :func:`~prompt_toolkit.shortcuts.dialogs.button_dialog` function displays a
-dialog with choices offered as buttons. Buttons are indicated as a list of
-tuples, each providing the label (first) and return value if clicked (second).
+The :func:`~prompt_toolkit.shortcuts.button_dialog` function displays a dialog
+with choices offered as buttons. Buttons are indicated as a list of tuples,
+each providing the label (first) and return value if clicked (second).
 
 .. code:: python
 
-    from prompt_toolkit.shortcuts.dialogs import button_dialog
+    from prompt_toolkit.shortcuts import button_dialog
 
     result = button_dialog(
         title='Button dialog example',
@@ -99,7 +98,7 @@ dialogs to override the default style. Also, text can be styled by passing an
 .. code:: python
 
     from prompt_toolkit.formatted_text import HTML
-    from prompt_toolkit.shortcuts.dialogs import message_dialog
+    from prompt_toolkit.shortcuts import message_dialog
     from prompt_toolkit.styles import Style
 
     example_style = Style.from_dict({
diff --git a/docs/pages/reference.rst b/docs/pages/reference.rst
index 948d9c3b..a71f4602 100644
--- a/docs/pages/reference.rst
+++ b/docs/pages/reference.rst
@@ -88,13 +88,12 @@ Shortcuts
 ---------
 
 .. automodule:: prompt_toolkit.shortcuts
-    :members: prompt, PromptSession, clear, clear_title, print_formatted_text,
-        set_title
+    :members: prompt, PromptSession, confirm, CompleteStyle,
+        create_confirm_session, clear, clear_title, print_formatted_text,
+        set_title, ProgressBar, input_dialog, message_dialog, progress_dialog,
+        radiolist_dialog, yes_no_dialog, button_dialog
 
-.. automodule:: prompt_toolkit.shortcuts.dialogs
-    :members:
-
-.. automodule:: prompt_toolkit.shortcuts.progress_bar
+.. automodule:: prompt_toolkit.shortcuts.progress_bar.formatters
     :members:
 
 
diff --git a/examples/dialogs/button_dialog.py b/examples/dialogs/button_dialog.py
index d20ab269..ee4988f4 100755
--- a/examples/dialogs/button_dialog.py
+++ b/examples/dialogs/button_dialog.py
@@ -3,7 +3,7 @@
 Example of button dialog window.
 """
 from __future__ import unicode_literals
-from prompt_toolkit.shortcuts.dialogs import button_dialog
+from prompt_toolkit.shortcuts import button_dialog
 
 
 def main():
diff --git a/examples/dialogs/input_dialog.py b/examples/dialogs/input_dialog.py
index 9cb9f2f5..2a5dc688 100755
--- a/examples/dialogs/input_dialog.py
+++ b/examples/dialogs/input_dialog.py
@@ -3,7 +3,7 @@
 Example of an input box dialog.
 """
 from __future__ import unicode_literals
-from prompt_toolkit.shortcuts.dialogs import input_dialog
+from prompt_toolkit.shortcuts import input_dialog
 
 
 def main():
diff --git a/examples/dialogs/messagebox.py b/examples/dialogs/messagebox.py
index 22418fe0..70576550 100755
--- a/examples/dialogs/messagebox.py
+++ b/examples/dialogs/messagebox.py
@@ -3,7 +3,7 @@
 Example of a message box window.
 """
 from __future__ import unicode_literals
-from prompt_toolkit.shortcuts.dialogs import message_dialog
+from prompt_toolkit.shortcuts import message_dialog
 
 
 def main():
diff --git a/examples/dialogs/password_dialog.py b/examples/dialogs/password_dialog.py
index 2f69eefd..62eddd4b 100755
--- a/examples/dialogs/password_dialog.py
+++ b/examples/dialogs/password_dialog.py
@@ -3,7 +3,7 @@
 Example of an password input dialog.
 """
 from __future__ import unicode_literals
-from prompt_toolkit.shortcuts.dialogs import input_dialog
+from prompt_toolkit.shortcuts import input_dialog
 
 
 def main():
diff --git a/examples/dialogs/progress_dialog.py b/examples/dialogs/progress_dialog.py
index 6affc779..fa0761bf 100755
--- a/examples/dialogs/progress_dialog.py
+++ b/examples/dialogs/progress_dialog.py
@@ -3,7 +3,7 @@
 Example of a progress bar dialog.
 """
 from __future__ import unicode_literals
-from prompt_toolkit.shortcuts.dialogs import progress_dialog
+from prompt_toolkit.shortcuts import progress_dialog
 import time
 import os
 
diff --git a/examples/dialogs/radio_dialog.py b/examples/dialogs/radio_dialog.py
index 6929c76f..7f5993c2 100755
--- a/examples/dialogs/radio_dialog.py
+++ b/examples/dialogs/radio_dialog.py
@@ -4,7 +4,7 @@ Example of a radio list box dialog.
 """
 from __future__ import unicode_literals
 from prompt_toolkit.formatted_text import HTML
-from prompt_toolkit.shortcuts.dialogs import radiolist_dialog
+from prompt_toolkit.shortcuts import radiolist_dialog
 
 
 def main():
diff --git a/examples/dialogs/styled_messagebox.py b/examples/dialogs/styled_messagebox.py
index 0f8ba038..a3d0eca7 100755
--- a/examples/dialogs/styled_messagebox.py
+++ b/examples/dialogs/styled_messagebox.py
@@ -9,7 +9,7 @@ text.
 """
 from __future__ import unicode_literals
 from prompt_toolkit.formatted_text import HTML
-from prompt_toolkit.shortcuts.dialogs import message_dialog
+from prompt_toolkit.shortcuts import message_dialog
 from prompt_toolkit.styles import Style
 
 
diff --git a/examples/dialogs/yes_no_dialog.py b/examples/dialogs/yes_no_dialog.py
index 47f241df..f27a5623 100755
--- a/examples/dialogs/yes_no_dialog.py
+++ b/examples/dialogs/yes_no_dialog.py
@@ -3,7 +3,7 @@
 Example of confirmation (yes/no) dialog window.
 """
 from __future__ import unicode_literals
-from prompt_toolkit.shortcuts.dialogs import yes_no_dialog
+from prompt_toolkit.shortcuts import yes_no_dialog
 
 
 def main():
diff --git a/examples/progress-bar/a-lot-of-parallel-tasks.py b/examples/progress-bar/a-lot-of-parallel-tasks.py
index d63b9231..e7f72cb6 100755
--- a/examples/progress-bar/a-lot-of-parallel-tasks.py
+++ b/examples/progress-bar/a-lot-of-parallel-tasks.py
@@ -3,7 +3,7 @@
 More complex demonstration of what's possible with the progress bar.
 """
 from __future__ import unicode_literals
-from prompt_toolkit.shortcuts.progress_bar import progress_bar
+from prompt_toolkit.shortcuts import ProgressBar
 from prompt_toolkit import HTML
 import random
 import threading
@@ -11,7 +11,7 @@ import time
 
 
 def main():
-    with progress_bar(
+    with ProgressBar(
             title=HTML('<b>Example of many parallel tasks.</b>'),
             bottom_toolbar=HTML('<b>[Control-L]</b> clear  <b>[Control-C]</b> abort')) as pb:
 
diff --git a/examples/progress-bar/custom-key-bindings.py b/examples/progress-bar/custom-key-bindings.py
index e5c18a95..cfedcdae 100755
--- a/examples/progress-bar/custom-key-bindings.py
+++ b/examples/progress-bar/custom-key-bindings.py
@@ -7,7 +7,7 @@ from __future__ import unicode_literals
 from prompt_toolkit import HTML
 from prompt_toolkit.key_binding import KeyBindings
 from prompt_toolkit.patch_stdout import patch_stdout
-from prompt_toolkit.shortcuts.progress_bar import progress_bar
+from prompt_toolkit.shortcuts import ProgressBar
 
 import time
 import os
@@ -31,7 +31,7 @@ def main():
     # Use `patch_stdout`, to make sure that prints go above the
     # application.
     with patch_stdout():
-        with progress_bar(key_bindings=kb, bottom_toolbar=bottom_toolbar) as pb:
+        with ProgressBar(key_bindings=kb, bottom_toolbar=bottom_toolbar) as pb:
             for i in pb(range(800)):
                 time.sleep(.01)
 
diff --git a/examples/progress-bar/many-parallel-tasks.py b/examples/progress-bar/many-parallel-tasks.py
index d0206bd1..ca276816 100755
--- a/examples/progress-bar/many-parallel-tasks.py
+++ b/examples/progress-bar/many-parallel-tasks.py
@@ -3,14 +3,14 @@
 More complex demonstration of what's possible with the progress bar.
 """
 from __future__ import unicode_literals
-from prompt_toolkit.shortcuts.progress_bar import progress_bar
+from prompt_toolkit.shortcuts import ProgressBar
 from prompt_toolkit import HTML
 import time
 import threading
 
 
 def main():
-    with progress_bar(
+    with ProgressBar(
             title=HTML('<b>Example of many parallel tasks.</b>'),
             bottom_toolbar=HTML('<b>[Control-L]</b> clear  <b>[Control-C]</b> abort')) as pb:
 
diff --git a/examples/progress-bar/nested-progress-bars.py b/examples/progress-bar/nested-progress-bars.py
index e3b4331f..86855b90 100755
--- a/examples/progress-bar/nested-progress-bars.py
+++ b/examples/progress-bar/nested-progress-bars.py
@@ -3,13 +3,13 @@
 Example of nested progress bars.
 """
 from __future__ import unicode_literals
-from prompt_toolkit.shortcuts.progress_bar import progress_bar
+from prompt_toolkit.shortcuts import ProgressBar
 from prompt_toolkit import HTML
 import time
 
 
 def main():
-    with progress_bar(
+    with ProgressBar(
             title=HTML('<b fg="#aa00ff">Nested progress bars</b>'),
             bottom_toolbar=HTML(' <b>[Control-L]</b> clear  <b>[Control-C]</b> abort')) as pb:
 
diff --git a/examples/progress-bar/scrolling-task-name.py b/examples/progress-bar/scrolling-task-name.py
index 79ca182c..0c7350ae 100755
--- a/examples/progress-bar/scrolling-task-name.py
+++ b/examples/progress-bar/scrolling-task-name.py
@@ -4,12 +4,12 @@ A very simple progress bar where the name of the task scrolls, because it's too
 iterator.
 """
 from __future__ import unicode_literals
-from prompt_toolkit.shortcuts.progress_bar import progress_bar
+from prompt_toolkit.shortcuts import ProgressBar
 import time
 
 
 def main():
-    with progress_bar(title='Scrolling task name (make sure the window is not too big).') as pb:
+    with ProgressBar(title='Scrolling task name (make sure the window is not too big).') as pb:
         for i in pb(range(800), label='This is a very very very long task that requires horizontal scrolling ...'):
             time.sleep(.01)
 
diff --git a/examples/progress-bar/simple-progress-bar.py b/examples/progress-bar/simple-progress-bar.py
index b9aec721..74e8531d 100755
--- a/examples/progress-bar/simple-progress-bar.py
+++ b/examples/progress-bar/simple-progress-bar.py
@@ -4,12 +4,12 @@ A very simple progress bar which keep track of the progress as we consume an
 iterator.
 """
 from __future__ import unicode_literals
-from prompt_toolkit.shortcuts.progress_bar import progress_bar
+from prompt_toolkit.shortcuts import ProgressBar
 import time
 
 
 def main():
-    with progress_bar() as pb:
+    with ProgressBar() as pb:
         for i in pb(range(800)):
             time.sleep(.01)
 
diff --git a/examples/progress-bar/styled-1.py b/examples/progress-bar/styled-1.py
index de14e352..cc39b4ae 100755
--- a/examples/progress-bar/styled-1.py
+++ b/examples/progress-bar/styled-1.py
@@ -4,7 +4,7 @@ A very simple progress bar which keep track of the progress as we consume an
 iterator.
 """
 from __future__ import unicode_literals
-from prompt_toolkit.shortcuts.progress_bar import progress_bar
+from prompt_toolkit.shortcuts import ProgressBar
 from prompt_toolkit.styles import Style
 import time
 
@@ -23,7 +23,7 @@ style = Style.from_dict({
 
 
 def main():
-    with progress_bar(style=style, title='Progress bar example with custom styling.') as pb:
+    with ProgressBar(style=style, title='Progress bar example with custom styling.') as pb:
         for i in pb(range(1600), label='Downloading...'):
             time.sleep(.01)
 
diff --git a/examples/progress-bar/styled-2.py b/examples/progress-bar/styled-2.py
index bf4994d1..4bc7e5bf 100755
--- a/examples/progress-bar/styled-2.py
+++ b/examples/progress-bar/styled-2.py
@@ -4,10 +4,10 @@ A very simple progress bar which keep track of the progress as we consume an
 iterator.
 """
 from __future__ import unicode_literals
-from prompt_toolkit.shortcuts.progress_bar import progress_bar
-from prompt_toolkit.styles import Style
-from prompt_toolkit.shortcuts.progress_bar import formatters
 from prompt_toolkit.formatted_text import HTML
+from prompt_toolkit.shortcuts import ProgressBar
+from prompt_toolkit.shortcuts.progress_bar import formatters
+from prompt_toolkit.styles import Style
 import time
 
 
@@ -35,7 +35,9 @@ def main():
         formatters.Text(' left: '),
         formatters.TimeLeft(),
     ]
-    with progress_bar(title='Progress bar example with custom formatter.', formatters=custom_formatters, style=style) as pb:
+    with ProgressBar(title='Progress bar example with custom formatter.',
+                     formatters=custom_formatters, style=style) as pb:
+
         for i in pb(range(20), label='Downloading...'):
             time.sleep(1)
 
diff --git a/examples/progress-bar/styled-apt-get-install.py b/examples/progress-bar/styled-apt-get-install.py
index 44ae9391..e1591fe3 100755
--- a/examples/progress-bar/styled-apt-get-install.py
+++ b/examples/progress-bar/styled-apt-get-install.py
@@ -3,7 +3,7 @@
 Styled just like an apt-get installation.
 """
 from __future__ import unicode_literals
-from prompt_toolkit.shortcuts.progress_bar import progress_bar
+from prompt_toolkit.shortcuts import ProgressBar
 from prompt_toolkit.styles import Style
 from prompt_toolkit.shortcuts.progress_bar import formatters
 import time
@@ -25,7 +25,7 @@ def main():
         formatters.Text('  '),
     ]
 
-    with progress_bar(style=style, formatters=custom_formatters) as pb:
+    with ProgressBar(style=style, formatters=custom_formatters) as pb:
         for i in pb(range(1600), label='Installing'):
             time.sleep(.01)
 
diff --git a/examples/progress-bar/styled-rainbow.py b/examples/progress-bar/styled-rainbow.py
index d1e5bc62..6555443c 100755
--- a/examples/progress-bar/styled-rainbow.py
+++ b/examples/progress-bar/styled-rainbow.py
@@ -4,13 +4,14 @@ A simple progress bar, visualised with rainbow colors (for fun).
 """
 from __future__ import unicode_literals
 from prompt_toolkit.output import ColorDepth
-from prompt_toolkit.shortcuts.progress_bar import progress_bar, formatters
+from prompt_toolkit.shortcuts import ProgressBar
+from prompt_toolkit.shortcuts.progress_bar import formatters
 from prompt_toolkit.shortcuts.prompt import confirm
 import time
 
 
 def main():
-    true_color = confirm('Yes true colors? ')
+    true_color = confirm('Yes true colors? (y/n) ')
 
     custom_formatters = [
         formatters.Label(),
@@ -25,7 +26,7 @@ def main():
     else:
         color_depth = ColorDepth.DEPTH_8_BIT
 
-    with progress_bar(formatters=custom_formatters, color_depth=color_depth) as pb:
+    with ProgressBar(formatters=custom_formatters, color_depth=color_depth) as pb:
         for i in pb(range(20), label='Downloading...'):
             time.sleep(1)
 
diff --git a/examples/progress-bar/styled-tqdm-1.py b/examples/progress-bar/styled-tqdm-1.py
index cd250580..b1cebdf8 100755
--- a/examples/progress-bar/styled-tqdm-1.py
+++ b/examples/progress-bar/styled-tqdm-1.py
@@ -5,7 +5,7 @@ Styled similar to tqdm, another progress bar implementation in Python.
 See: https://github.com/noamraph/tqdm
 """
 from __future__ import unicode_literals
-from prompt_toolkit.shortcuts.progress_bar import progress_bar
+from prompt_toolkit.shortcuts import ProgressBar
 from prompt_toolkit.styles import Style
 from prompt_toolkit.shortcuts.progress_bar import formatters
 import time
@@ -33,7 +33,7 @@ def main():
         formatters.Text('  '),
     ]
 
-    with progress_bar(style=style, formatters=custom_formatters) as pb:
+    with ProgressBar(style=style, formatters=custom_formatters) as pb:
         for i in pb(range(1600), label='Installing'):
             time.sleep(.01)
 
diff --git a/examples/progress-bar/styled-tqdm-2.py b/examples/progress-bar/styled-tqdm-2.py
index d9e38447..8a958cf3 100755
--- a/examples/progress-bar/styled-tqdm-2.py
+++ b/examples/progress-bar/styled-tqdm-2.py
@@ -5,7 +5,7 @@ Styled similar to tqdm, another progress bar implementation in Python.
 See: https://github.com/noamraph/tqdm
 """
 from __future__ import unicode_literals
-from prompt_toolkit.shortcuts.progress_bar import progress_bar
+from prompt_toolkit.shortcuts import ProgressBar
 from prompt_toolkit.styles import Style
 from prompt_toolkit.shortcuts.progress_bar import formatters
 import time
@@ -31,7 +31,7 @@ def main():
         formatters.Text('it/s]'),
     ]
 
-    with progress_bar(style=style, formatters=custom_formatters) as pb:
+    with ProgressBar(style=style, formatters=custom_formatters) as pb:
         for i in pb(range(1600), label='Installing'):
             time.sleep(.01)
 
diff --git a/examples/progress-bar/unknown-length.py b/examples/progress-bar/unknown-length.py
index 42dacb02..f0abdcf1 100755
--- a/examples/progress-bar/unknown-length.py
+++ b/examples/progress-bar/unknown-length.py
@@ -4,7 +4,7 @@ A very simple progress bar which keep track of the progress as we consume an
 iterator.
 """
 from __future__ import unicode_literals
-from prompt_toolkit.shortcuts.progress_bar import progress_bar
+from prompt_toolkit.shortcuts import ProgressBar
 import time
 
 
@@ -18,7 +18,7 @@ def data():
 
 
 def main():
-    with progress_bar() as pb:
+    with ProgressBar() as pb:
         for i in pb(data()):
             time.sleep(.1)
 
diff --git a/prompt_toolkit/shortcuts/__init__.py b/prompt_toolkit/shortcuts/__init__.py
index 0e47ff74..0235db82 100644
--- a/prompt_toolkit/shortcuts/__init__.py
+++ b/prompt_toolkit/shortcuts/__init__.py
@@ -2,6 +2,7 @@ from __future__ import unicode_literals
 from .dialogs import yes_no_dialog, button_dialog, input_dialog, message_dialog, radiolist_dialog, progress_dialog
 from .prompt import PromptSession, prompt, confirm, create_confirm_session, CompleteStyle
 from .utils import print_formatted_text, clear, set_title, clear_title
+from .progress_bar import ProgressBar
 
 
 __all__ = [
@@ -20,6 +21,9 @@ __all__ = [
     'create_confirm_session',
     'CompleteStyle',
 
+    # Progress bars.
+    'ProgressBar',
+
     # Utils.
     'clear',
     'clear_title',
diff --git a/prompt_toolkit/shortcuts/progress_bar/__init__.py b/prompt_toolkit/shortcuts/progress_bar/__init__.py
index 3a1bbab3..c3e32488 100644
--- a/prompt_toolkit/shortcuts/progress_bar/__init__.py
+++ b/prompt_toolkit/shortcuts/progress_bar/__init__.py
@@ -1,9 +1,9 @@
 from __future__ import unicode_literals
-from .base import progress_bar
+from .base import ProgressBar
 from .formatters import Formatter, Text, Label, Percentage, Bar, Progress, TimeElapsed, TimeLeft, IterationsPerSecond, SpinningWheel, Rainbow
 
 __all__ = [
-    'progress_bar',
+    'ProgressBar',
 
     # Formatters.
     'Formatter',
diff --git a/prompt_toolkit/shortcuts/progress_bar/base.py b/prompt_toolkit/shortcuts/progress_bar/base.py
index 8e35c30d..33df18a6 100644
--- a/prompt_toolkit/shortcuts/progress_bar/base.py
+++ b/prompt_toolkit/shortcuts/progress_bar/base.py
@@ -3,7 +3,7 @@ Progress bar implementation on top of prompt_toolkit.
 
 ::
 
-    with progress_bar(...) as pb:
+    with ProgressBar(...) as pb:
         for item in pb(data):
             ...
 """
@@ -35,7 +35,7 @@ import sys
 from .formatters import create_default_formatters, Formatter
 
 __all__ = [
-    'progress_bar',
+    'ProgressBar',
 ]
 
 
@@ -58,13 +58,13 @@ def create_key_bindings():
     return kb
 
 
-class progress_bar(object):
+class ProgressBar(object):
     """
     Progress bar context manager.
 
     Usage ::
 
-        with progress_bar(...) as pb:
+        with ProgressBar(...) as pb:
             for item in pb(data):
                 ...