Restore progressbar iterator interface; add test

- add a test for iterating on a progressbar with next()
- implement `next()` in terms of `iter(ProgressBar)`, which is already
  well-defined
- add a note about slow operations with progressbar to narrative docs

One of the keys to this working is that `ProgressBar.generator` is
consuming an iterable and doesn't store any important state in local
variables, making it re-entry safe.

I wasn't sure how we can best hint in the public docs that simply
walking the bar and stopping one step short of finishing will result in
the progress bar "hanging" unfinished. Noting that we work well with
things like `time.sleep()` seems like a decent way of advertising
positively something which we support *and* guiding anyone going
off-book into proper usage.

closes #1125

1 files changed, 20 insertions, 0 deletions

diff --git a/tests/test_termui.py b/tests/test_termui.py
index 79fb7c6..845cb38 100644
--- a/tests/test_termui.py
+++ b/tests/test_termui.py
@@ -185,6 +185,26 @@ def test_progressbar_iter_outside_with_exceptions(runner):
         assert False, 'Expected an exception because of abort-related inputs.'
 
 
+def test_progressbar_is_iterator(runner, monkeypatch):
+    fake_clock = FakeClock()
+
+    @click.command()
+    def cli():
+        with click.progressbar(range(10), label='test') as progress:
+            while True:
+                try:
+                    next(progress)
+                    fake_clock.advance_time()
+                except StopIteration:
+                    break
+
+    monkeypatch.setattr(time, 'time', fake_clock.time)
+    monkeypatch.setattr(click._termui_impl, 'isatty', lambda _: True)
+
+    result = runner.invoke(cli, [])
+    assert result.exception is None
+
+
 def test_choices_list_in_prompt(runner, monkeypatch):
     @click.command()
     @click.option('-g', type=click.Choice(['none', 'day', 'week', 'month']),