From b54cc10216c18e00befabfb848c02aeba3e06fa2 Mon Sep 17 00:00:00 2001 From: Casper da Costa-Luis Date: Tue, 5 Feb 2019 00:47:13 +0000 Subject: [PATCH] update documentation, tidy --- Makefile | 2 +- README.rst | 6 +++++- tqdm/_tqdm.py | 30 ++++++++++-------------------- tqdm/_utils.py | 12 +++++------- tqdm/tests/tests_tqdm.py | 10 +++------- 5 files changed, 24 insertions(+), 36 deletions(-) diff --git a/Makefile b/Makefile index f6cce1d26..034310cf8 100644 --- a/Makefile +++ b/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: diff --git a/README.rst b/README.rst index e6b6afe83..f84343834 100644 --- a/README.rst +++ b/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 ~~~~~~~~~~~~~~~~~ diff --git a/tqdm/_tqdm.py b/tqdm/_tqdm.py index 117d47fc5..945f909b7 100755 --- a/tqdm/_tqdm.py +++ b/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 diff --git a/tqdm/_utils.py b/tqdm/_utils.py index 591ac3895..4e9f536c8 100644 --- a/tqdm/_utils.py +++ b/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) diff --git a/tqdm/tests/tests_tqdm.py b/tqdm/tests/tests_tqdm.py index 61c4ea5f8..1a642e435 100644 --- a/tqdm/tests/tests_tqdm.py +++ b/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