From a483e55e3f9109ab638949eadc5d3751bb48f1b6 Mon Sep 17 00:00:00 2001
From: Casper da Costa-Luis <casper.dcl@physics.org>
Date: Sun, 31 Jan 2016 20:29:05 +0100
Subject: [PATCH] Update documentation, per-file refresh

---
 README.rst    | 39 +++++++++++++++++++++++++++++++++++++++
 tqdm/_tqdm.py |  3 ++-
 2 files changed, 41 insertions(+), 1 deletion(-)

diff --git a/README.rst b/README.rst
index 4e7429a0..6bfd7438 100644
--- a/README.rst
+++ b/README.rst
@@ -315,6 +315,21 @@ Returns
           Cleanup and (if leave=False) close the progressbar.
           """
 
+      def clear(self):
+          """
+          Clear current bar display
+          """
+
+      def refresh(self):
+          """
+          Force refresh the display of this bar
+          """
+
+      def write(cls, s, file=sys.stdout, end="\n"):
+          """
+          Print a message via tqdm (without overlap with bars)
+          """
+
     def trange(*args, **kwargs):
         """
         A shortcut for tqdm(xrange(*args), **kwargs).
@@ -449,6 +464,30 @@ For manual control over positioning (e.g. for multi-threaded use),
 you may specify `position=n` where `n=0` for the outermost bar,
 `n=1` for the next, and so on.
 
+Writing messages
+~~~~~~~~~~~~~~~~~~~~
+Since ``tqdm`` uses a simple printing mechanism to display progress bars,
+you should not write any message in the terminal using ``print()``.
+
+To write messages in the terminal without any collision with ``tqdm`` bar
+display, a ``.write()`` method is provided:
+
+.. code:: python
+
+    from tqdm import tqdm, trange
+    from time import sleep
+
+    bar = trange(10)
+    for i in bar:
+        # Print using tqdm class method .write()
+        sleep(0.1)
+        if not (i % 3):
+            tqdm.write("Done task %i" % i)
+        # Can also use bar.write()
+
+By default, this will print to standard output ``sys.stdout``. but you can
+specify any file-like object using the ``file`` argument. For example, this
+can be used to redirect the messages writing to a log file or class.
 
 How to make a good progress bar
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/tqdm/_tqdm.py b/tqdm/_tqdm.py
index 7ed7449e..9709d296 100644
--- a/tqdm/_tqdm.py
+++ b/tqdm/_tqdm.py
@@ -292,7 +292,8 @@ class tqdm(object):
         """
         # Clear all bars
         for inst in cls._instances:
-            inst.clear()
+            if inst.fp == file:
+                inst.clear()
         # Write the message
         file.write(s)
         file.write(end)