docutils/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 (which is written to),
 144                         a string (opended as a file),
 145                         `None` (bind to `sys.stderr`; default).
 146                         If evaluating to `False` (but not `None`),
 147                         write() requests are ignored.
 148             - `encoding`: `stream` text encoding. Guessed if None.
 149             - `encoding_errors`: how to treat encoding errors.
 150         """
 151         if stream is None:
 152             stream = sys.stderr
 153         elif not(stream):
 154             stream = False
 155         # if `stream` is a file name, open it
 156         elif isinstance(stream, str):
 157             stream = open(stream, 'w')
 158         elif isinstance(stream, unicode):
 159             stream = open(stream.encode(sys.getfilesystemencoding()), 'w')
 160
 161         self.stream = stream
 162         """Where warning output is sent."""
 163
 164         self.encoding = (encoding or getattr(stream, 'encoding', None) or
 165                          locale_encoding or 'ascii')
 166         """The output character encoding."""
 167
 168         self.encoding_errors = encoding_errors
 169         """Encoding error handler."""
 170
 171         self.decoding_errors = decoding_errors
 172         """Decoding error handler."""
 173
 174     def write(self, data):
 175         """
 176         Write `data` to self.stream. Ignore, if self.stream is False.
 177
 178         `data` can be a `string`, `unicode`, or `Exception` instance.
 179         """
 180         if self.stream is False:
 181             return
 182         if isinstance(data, Exception):
 183             data = unicode(SafeString(data, self.encoding,
 184                                   self.encoding_errors, self.decoding_errors))
 185         try:
 186             self.stream.write(data)
 187         except UnicodeEncodeError:
 188             self.stream.write(data.encode(self.encoding, self.encoding_errors))
 189         except TypeError: # in Python 3, stderr expects unicode
 190             if self.stream in (sys.stderr, sys.stdout):
 191                 self.stream.buffer.write(data) # write bytes to raw stream
 192             else:
 193                 self.stream.write(unicode(data, self.encoding,
 194                                           self.decoding_errors))
 195
 196     def close(self):
 197         """
 198         Close the error-output stream.
 199
 200         Ignored if the stream is` sys.stderr` or `sys.stdout` or has no
 201         close() method.
 202         """
 203         if self.stream in (sys.stdout, sys.stderr):
 204             return
 205         try:
 206             self.stream.close()
 207         except AttributeError:
 208             pass