docutils/error_reporting.py

   1 #!/usr/bin/env python
   2 # -*- coding: utf8 -*-
   3
   4 # :Id: $Id$
   5 # :Copyright: © 2011 Günter Milde.
   6 # :License: Released under the terms of the `2-Clause BSD license`_, in short:
   7 #
   8 #    Copying and distribution of this file, with or without modification,
   9 #    are permitted in any medium without royalty provided the copyright
  10 #    notice and this notice are preserved.
  11 #    This file is offered as-is, without any warranty.
  12 #
  13 # .. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause
  14
  15 """
  16 Error reporting should be safe from encoding/decoding errors.
  17 However, implicit conversions of strings and exceptions like
  18
  19 >>> u'%s world: %s' % ('H\xe4llo', Exception(u'H\xe4llo')
  20
  21 fail in some Python versions:
  22
  23 * In Python <= 2.6, ``unicode(<exception instance>)`` uses
  24   `__str__` and fails with non-ASCII chars in`unicode` arguments.
  25   (work around http://bugs.python.org/issue2517):
  26
  27 * In Python 2, unicode(<exception instance>) fails, with non-ASCII
  28   chars in arguments. (Use case: in some locales, the errstr
  29   argument of IOError contains non-ASCII chars.)
  30
  31 * In Python 2, str(<exception instance>) fails, with non-ASCII chars
  32   in `unicode` arguments.
  33
  34 The `SafeString`, `ErrorString` and `ErrorOutput` classes handle
  35 common exceptions.
  36 """
  37
  38 import sys, codecs
  39
  40 # Guess the locale's encoding.
  41 # If no valid guess can be made, locale_encoding is set to `None`:
  42 try:
  43     import locale # module missing in Jython
  44 except ImportError:
  45     locale_encoding = None
  46 else:
  47     locale_encoding = locale.getlocale()[1] or locale.getdefaultlocale()[1]
  48     # locale.getpreferredencoding([do_setlocale=True|False])
  49     # has side-effects | might return a wrong guess.
  50     # (cf. Update 1 in http://stackoverflow.com/questions/4082645/using-python-2-xs-locale-module-to-format-numbers-and-currency)
  51     try:
  52         codecs.lookup(locale_encoding or '') # None -> ''
  53     except LookupError:
  54         locale_encoding = None
  55
  56
  57
  58 class SafeString(object):
  59     """
  60     A wrapper providing robust conversion to `str` and `unicode`.
  61     """
  62
  63     def __init__(self, data, encoding=None, encoding_errors='backslashreplace',
  64                  decoding_errors='replace'):
  65         self.data = data
  66         self.encoding = (encoding or getattr(data, 'encoding', None) or
  67                          locale_encoding or 'ascii')
  68         self.encoding_errors = encoding_errors
  69         self.decoding_errors = decoding_errors
  70
  71
  72     def __str__(self):
  73         try:
  74             return str(self.data)
  75         except UnicodeEncodeError, err:
  76             if isinstance(self.data, Exception):
  77                 args = [str(SafeString(arg, self.encoding,
  78                                         self.encoding_errors))
  79                         for arg in self.data.args]
  80                 return ', '.join(args)
  81             if isinstance(self.data, unicode):
  82                 return self.data.encode(self.encoding, self.encoding_errors)
  83             raise
  84
  85     def __unicode__(self):
  86         """
  87         Return unicode representation of `self.data`.
  88
  89         Try ``unicode(self.data)``, catch `UnicodeError` and
  90
  91         * if `self.data` is an Exception instance, work around
  92           http://bugs.python.org/issue2517 with an emulation of
  93           Exception.__unicode__,
  94
  95         * else decode with `self.encoding` and `self.decoding_errors`.
  96         """
  97         try:
  98             u = unicode(self.data)
  99             if isinstance(self.data, EnvironmentError):
 100                 u = u.replace(": u'", ": '") # normalize filename quoting
 101             return u
 102         except UnicodeError, error: # catch ..Encode.. and ..Decode.. errors
 103             if isinstance(self.data, EnvironmentError):
 104                 return  u"[Errno %s] %s: '%s'" % (self.data.errno,
 105                     SafeString(self.data.strerror, self.encoding,
 106                                self.decoding_errors),
 107                     SafeString(self.data.filename, self.encoding,
 108                                self.decoding_errors))
 109             if isinstance(self.data, Exception):
 110                 args = [unicode(SafeString(arg, self.encoding,
 111                             decoding_errors=self.decoding_errors))
 112                         for arg in self.data.args]
 113                 return u', '.join(args)
 114             if isinstance(error, UnicodeDecodeError):
 115                 return unicode(self.data, self.encoding, self.decoding_errors)
 116             raise
 117
 118 class ErrorString(SafeString):
 119     """
 120     Safely report exception type and message.
 121     """
 122     def __str__(self):
 123         return '%s: %s' % (self.data.__class__.__name__,
 124                             super(ErrorString, self).__str__())
 125
 126     def __unicode__(self):
 127         return u'%s: %s' % (self.data.__class__.__name__,
 128                             super(ErrorString, self).__unicode__())
 129
 130
 131 class ErrorOutput(object):
 132     """
 133     Wrapper class for file-like error streams with
 134     failsave de- and encoding of `str`, `bytes`, `unicode` and
 135     `Exception` instances.
 136     """
 137
 138     def __init__(self, stream=None, encoding=None,
 139                  encoding_errors='backslashreplace',
 140                  decoding_errors='replace'):
 141         """
 142         :Parameters:
 143             - `stream`: a file-like object,
 144                         a string (path to a file),
 145                         `None` (write to `sys.stderr`, default), or
 146                         evaluating to `False` (write() requests are ignored).
 147             - `encoding`: `stream` text encoding. Guessed if None.
 148             - `encoding_errors`: how to treat encoding errors.
 149         """
 150         if stream is None:
 151             stream = sys.stderr
 152         elif not(stream):
 153             stream = False
 154         # if `stream` is a file name, open it
 155         elif isinstance(stream, str):
 156             stream = open(stream, 'w')
 157         elif isinstance(stream, unicode):
 158             stream = open(stream.encode(sys.getfilesystemencoding()), 'w')
 159
 160         self.stream = stream
 161         """Where warning output is sent."""
 162
 163         self.encoding = (encoding or getattr(stream, 'encoding', None) or
 164                          locale_encoding or 'ascii')
 165         """The output character encoding."""
 166
 167         self.encoding_errors = encoding_errors
 168         """Encoding error handler."""
 169
 170         self.decoding_errors = decoding_errors
 171         """Decoding error handler."""
 172
 173     def write(self, data):
 174         """
 175         Write `data` to self.stream. Ignore, if self.stream is False.
 176
 177         `data` can be a `string`, `unicode`, or `Exception` instance.
 178         """
 179         if self.stream is False:
 180             return
 181         if isinstance(data, Exception):
 182             data = unicode(SafeString(data, self.encoding,
 183                                   self.encoding_errors, self.decoding_errors))
 184         try:
 185             self.stream.write(data)
 186         except UnicodeEncodeError:
 187             self.stream.write(data.encode(self.encoding, self.encoding_errors))
 188         except TypeError: # in Python 3, stderr expects unicode
 189             if self.stream in (sys.stderr, sys.stdout):
 190                 self.stream.buffer.write(data) # write bytes to raw stream
 191             else:
 192                 self.stream.write(unicode(data, self.encoding,
 193                                           self.decoding_errors))
 194
 195     def close(self):
 196         """
 197         Close the error-output stream.
 198
 199         Ignored if the stream is` sys.stderr` or `sys.stdout` or has no
 200         close() method.
 201         """
 202         if self.stream in (sys.stdout, sys.stderr):
 203             return
 204         try:
 205             self.stream.close()
 206         except AttributeError:
 207             pass