update documentation, tidy

Makefile

@@ -89,7 +89,7 @@ tqdm/tqdm.1: .tqdm.1.md
     cat "$<" - |\
     pandoc -o "$@" -s -t man
 
-README.rst:
+README.rst: .readme.rst tqdm/_tqdm.py tqdm/_main.py
 	@python mkdocs.py
 
 distclean:

README.rst

@@ -301,7 +301,7 @@ Parameters
 * file  : ``io.TextIOWrapper`` or ``io.StringIO``, optional  
     Specifies where to output the progress messages
     (default: sys.stderr). Uses ``file.write(str)`` and ``file.flush()``
-    methods.
+    methods.  For encoding, see ``write_bytes``.
 * ncols  : int, optional  
     The width of the entire output message. If specified,
     dynamically resizes the progressbar to stay within this bound.
@@ -369,6 +369,10 @@ Parameters
     Calls ``set_postfix(**postfix)`` if possible (dict).
 * unit_divisor  : float, optional  
     [default: 1000], ignored unless ``unit_scale`` is True.
+* write_bytes  : bool, optional  
+    If (default: None) and ``file`` is unspecified,
+    bytes will be written in Python 2. If ``True`` will also write
+    bytes. In all other cases will default to unicode.
 
 Extra CLI Options
 ~~~~~~~~~~~~~~~~~

tqdm/_tqdm.py

@@ -733,10 +733,7 @@ def __init__(self, iterable=None, desc=None, total=None, leave=True,
         file  : `io.TextIOWrapper` or `io.StringIO`, optional
             Specifies where to output the progress messages
             (default: sys.stderr). Uses `file.write(str)` and `file.flush()`
-            methods.  Bytes will be written if running in Python 2 and this
-            parameter is not specified, otherwise unicode will be written to
-            the file.  This behavior can be overridden by passing `True` or
-            `False` to `write_bytes`.
+            methods.  For encoding, see `write_bytes`.
         ncols  : int, optional
             The width of the entire output message. If specified,
             dynamically resizes the progressbar to stay within this bound.
@@ -804,11 +801,10 @@ def __init__(self, iterable=None, desc=None, total=None, leave=True,
             Calls `set_postfix(**postfix)` if possible (dict).
         unit_divisor  : float, optional
             [default: 1000], ignored unless `unit_scale` is True.
-        write_bytes  : bool or None, optional
-            Not passing or passing None will result in default behavior as
-            described by the `file` attribute.  Passing `True` will force
-            bytes to be written while passing `False` will force unicode to
-            be written.
+        write_bytes  : bool, optional
+            If (default: None) and `file` is unspecified,
+            bytes will be written in Python 2. If `True` will also write
+            bytes. In all other cases will default to unicode.
         gui  : bool, optional
             WARNING: internal parameter - do not use.
             Use tqdm_gui(...) instead. If set, will attempt to use
@@ -818,23 +814,17 @@ def __init__(self, iterable=None, desc=None, total=None, leave=True,
         -------
         out  : decorated iterator.
         """
-
         if write_bytes is None:
-            write_bytes = (file is None) and (sys.version_info < (3,))
+            write_bytes = file is None and sys.version_info < (3,)
 
         if file is None:
             file = sys.stderr
 
         if write_bytes:
-            # Despite coercing unicode into bytes, the std streams in
-            # in Python 2 should have bytes written to them.  This is
-            # particularly important when a test framework or such
-            # substitutes a file-like for stdout or stderr that expects bytes
-            # and does not coerce unicode.
-
-            encoding = getattr(file, 'encoding', 'utf-8')
-
-            file = SimpleTextIOWrapper(file, encoding=encoding)
+            # Despite coercing unicode into bytes, py2 sys.std* streams
+            # should have bytes written to them.
+            file = SimpleTextIOWrapper(
+                file, encoding=getattr(file, 'encoding', 'utf-8'))
 
         if disable is None and hasattr(file, "isatty") and not file.isatty():
             disable = True

tqdm/_utils.py

@@ -143,22 +143,20 @@ def __ge__(self, other):
 
 
 class SimpleTextIOWrapper(object):
-    """Change only `.write()` of the wrapped object by encoding the passed
+    """
+    Change only `.write()` of the wrapped object by encoding the passed
     value and passing the result to the wrapped object's `.write()` method.
     """
-
     # pylint: disable=too-few-public-methods
-
     def __init__(self, wrapped, encoding):
         object.__setattr__(self, '_wrapped', wrapped)
         object.__setattr__(self, 'encoding', encoding)
 
     def write(self, s):
-        """Encode `s` and pass the result to the wrapped object's `.write()`
-        method.
         """
-        b = s.encode(getattr(self, 'encoding'))
-        return getattr(self, '_wrapped').write(b)
+        Encode `s` and pass to the wrapped object's `.write()` method.
+        """
+        return getattr(self, '_wrapped').write(s.encode(getattr(self, 'encoding')))
 
     def __getattr__(self, name):
         return getattr(self._wrapped, name)

tqdm/tests/tests_tqdm.py

@@ -343,7 +343,6 @@ class WriteTypeChecker(BytesIO):
     """File-like to assert the expected type is written"""
     def __init__(self, expected_type):
         super(WriteTypeChecker, self).__init__()
-
         self.expected_type = expected_type
 
     def write(self, s):
@@ -366,18 +365,15 @@ def test_native_string_io_for_default_file():
 @with_setup(pretest, posttest)
 def test_unicode_string_io_for_specified_file():
     """Unicode strings written to specified files"""
-    f = WriteTypeChecker(expected_type=type(u''))
-
-    for _ in tqdm(range(3), file=f):
+    for _ in tqdm(range(3), file=WriteTypeChecker(expected_type=type(u''))):
         pass
 
 
 @with_setup(pretest, posttest)
 def test_byte_string_io_for_specified_file_with_forced_bytes():
     """Byte strings written to specified files when forced"""
-    f = WriteTypeChecker(expected_type=type(b''))
-
-    for _ in tqdm(range(3), file=f, write_bytes=True):
+    for _ in tqdm(range(3), file=WriteTypeChecker(expected_type=type(b'')),
+                  write_bytes=True):
         pass