add docs and changelog for #830

davidism · davidism · commit 3496086aed43 · 2018-09-22T18:12:48.000-07:00
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -87,6 +87,8 @@ Unreleased
 -   Raw strings added so correct escaping occurs. (`#807`_)
 -   Fix 16k character limit of ``click.echo`` on Windows. (`#816`_,
     `#819`_)
+-   Overcome 64k character limit when writing to binary stream on
+    Windows 7. (`#825`_, `#830`_)
 -   Add bool conversion for "t" and "f". (`#842`_)
 -   ``NoSuchOption`` errors take ``ctx`` so that ``--help`` hint gets
     printed in error output. (`#860`_)
@@ -212,6 +214,8 @@ Unreleased
 .. _#819: https://github.com/pallets/click/pull/819
 .. _#821: https://github.com/pallets/click/issues/821
 .. _#822: https://github.com/pallets/click/issues/822
+.. _#825: https://github.com/pallets/click/issues/825
+.. _#830: https://github.com/pallets/click/pull/830
 .. _#842: https://github.com/pallets/click/pull/842
 .. _#860: https://github.com/pallets/click/issues/860
 .. _#862: https://github.com/pallets/click/issues/862
diff --git a/docs/wincmd.rst b/docs/wincmd.rst
@@ -59,14 +59,21 @@ This hackery is used on both Python 2 and Python 3 as neither version of
 Python has native support for cmd.exe with unicode characters.  There are
 some limitations you need to be aware of:
 
-*   this unicode support is limited to ``click.echo``, ``click.prompt`` as
+*   This unicode support is limited to ``click.echo``, ``click.prompt`` as
     well as ``click.get_text_stream``.
-*   depending on if unicode values or byte strings are passed the control
+*   Depending on if unicode values or byte strings are passed the control
     flow goes completely different places internally which can have some
     odd artifacts if data partially ends up being buffered.  Click
     attempts to protect against that by manually always flushing but if
     you are mixing and matching different string types to ``stdout`` or
     ``stderr`` you will need to manually flush.
+*   The raw output stream is set to binary mode, which is a global
+    operation on Windows, so ``print`` calls will be affected. Prefer
+    ``click.echo`` over ``print``.
+*   On Windows 7 and below, there is a limitation where at most 64k
+    characters can be written in one call in binary mode. In this
+    situation, ``sys.stdout`` and ``sys.stderr`` are replaced with
+    wrappers that work around the limitation.
 
 Another important thing to note is that the Windows console's default
 fonts do not support a lot of characters which means that you are mostly
