Documented the misbehavior of Windows pipes in combination with Python.

jedi/_compatibility.py

@@ -438,6 +438,13 @@ if sys.version_info[:2] == (3, 3):
 _PICKLE_PROTOCOL = 2
 is_windows = sys.platform == 'win32'
 
+# The Windows shell on Python 2 consumes all control characters (below 32) and expand on
+# all Python versions \n to \r\n.
+# pickle starting from protocol version 1 uses binary data, which could not be escaped by
+# any normal unicode encoder. Therefore, the only bytes encoder which doesn't produce
+# control characters is binascii.hexlify.
+
+
 def pickle_load(file):
     if is_windows:
         try:
@@ -447,6 +454,8 @@ def pickle_load(file):
                 return pickle.loads(data, encoding='bytes')
             else:
                 return pickle.loads(data)
+        # Python on Windows don't throw EOF errors for pipes. So reraise them with
+        # the correct type, which is cought upwards.
         except OSError:
             raise EOFError()
     else:
@@ -455,6 +464,7 @@ def pickle_load(file):
         else:
             return pickle.load(file)
 
+
 def pickle_dump(data, file):
     if is_windows:
         try:
@@ -462,7 +472,11 @@ def pickle_dump(data, file):
             data = binascii.hexlify(data)
             file.write(data)
             file.write(b'\n')
+            # On Python 3.3 flush throws sometimes an error even if the two file writes
+            # should done it already before. This could be also computer / speed depending.
             file.flush()
+        # Python on Windows don't throw EPIPE errors for pipes. So reraise them with
+        # the correct type and error number.
         except OSError:
             raise IOError(errno.EPIPE)
     else: