Handle BrokenPipeError gracefully.

Author: cjerdonek

news/4170.bugfix

@@ -0,0 +1 @@
+Handle a broken stdout pipe more gracefully (e.g. when running ``pip list | head``).

src/pip/_internal/cli/base_command.py

@@ -1,11 +1,12 @@
 """Base Command class, and related routines"""
-from __future__ import absolute_import
+from __future__ import absolute_import, print_function
 
 import logging
 import logging.config
 import optparse
 import os
 import sys
+import traceback
 
 from pip._internal.cli import cmdoptions
 from pip._internal.cli.parser import (
@@ -27,7 +28,7 @@
 )
 from pip._internal.req.req_file import parse_requirements
 from pip._internal.utils.deprecation import deprecated
-from pip._internal.utils.logging import setup_logging
+from pip._internal.utils.logging import BrokenStdoutLoggingError, setup_logging
 from pip._internal.utils.misc import (
     get_prog, normalize_path, redact_password_from_url,
 )
@@ -191,6 +192,14 @@ def main(self, args):
             logger.critical('ERROR: %s', exc)
             logger.debug('Exception information:', exc_info=True)
 
+            return ERROR
+        except BrokenStdoutLoggingError:
+            # Bypass our logger and write any remaining messages to stderr
+            # because stdout no longer works.
+            print('ERROR: Pipe to stdout was broken', file=sys.stderr)
+            if logger.getEffectiveLevel() <= logging.DEBUG:
+                traceback.print_exc(file=sys.stderr)
+
             return ERROR
         except KeyboardInterrupt:
             logger.critical('Operation cancelled by user')

src/pip/_internal/utils/logging.py

@@ -1,9 +1,13 @@
 from __future__ import absolute_import
 
 import contextlib
+import errno
 import logging
 import logging.handlers
 import os
+import sys
+
+from pip._vendor.six import PY2
 
 from pip._internal.utils.compat import WINDOWS
 from pip._internal.utils.misc import ensure_dir
@@ -33,6 +37,23 @@ class BrokenStdoutLoggingError(Exception):
     pass
 
 
+if PY2:
+    # BrokenPipeError does not exist in Python 2.
+    def _is_broken_pipe_error(exc_class, exc):
+        """
+        Return whether an exception is a broken pipe error.
+
+        Args:
+          exc_class: an exception class.
+          exc: an exception instance.
+        """
+        return (exc_class is IOError and exc.errno == errno.EPIPE)
+
+else:
+    def _is_broken_pipe_error(exc_class, exc):
+        return (exc_class is BrokenPipeError)  # noqa: F821
+
+
 @contextlib.contextmanager
 def indent_log(num=2):
     """
@@ -103,6 +124,16 @@ def __init__(self, stream=None, no_color=None):
         if WINDOWS and colorama:
             self.stream = colorama.AnsiToWin32(self.stream)
 
+    def _using_stdout(self):
+        """
+        Return whether the handler is using sys.stdout.
+        """
+        if WINDOWS and colorama:
+            # Then self.stream is an AnsiToWin32 object.
+            return self.stream.wrapped is sys.stdout
+
+        return self.stream is sys.stdout
+
     def should_color(self):
         # Don't colorize things if we do not have colorama or if told not to
         if not colorama or self._no_color:
@@ -135,6 +166,19 @@ def format(self, record):
 
         return msg
 
+    # The logging module says handleError() can be customized.
+    def handleError(self, record):
+        exc_class, exc = sys.exc_info()[:2]
+        # If a broken pipe occurred while calling write() or flush() on the
+        # stdout stream in logging's Handler.emit(), then raise our special
+        # exception so we can handle it in main() instead of logging the
+        # broken pipe error and continuing.
+        if (exc_class and self._using_stdout() and
+                _is_broken_pipe_error(exc_class, exc)):
+            raise BrokenStdoutLoggingError()
+
+        return super(ColorizedStreamHandler, self).handleError(record)
+
 
 class BetterRotatingFileHandler(logging.handlers.RotatingFileHandler):