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             return unicode(self.data)
  99         except UnicodeError, error: # catch ..Encode.. and ..Decode.. errors
 100             if isinstance(self.data, EnvironmentError):
 101                 return  u"[Errno %s] %s: '%s'" % (self.data.errno,
 102                     SafeString(self.data.strerror, self.encoding,
 103                             self.decoding_errors),
 104                     SafeString(self.data.filename, self.encoding,
 105                             self.decoding_errors))
 106             if isinstance(self.data, Exception):
 107                 args = [unicode(SafeString(arg, self.encoding,
 108                             decoding_errors=self.decoding_errors))
 109                         for arg in self.data.args]
 110                 return u', '.join(args)
 111             if isinstance(error, UnicodeDecodeError):
 112                 return unicode(self.data, self.encoding, self.decoding_errors)
 113             raise
 114
 115 class ErrorString(SafeString):
 116     """
 117     Safely report exception type and message.
 118     """
 119     def __str__(self):
 120         return '%s: %s' % (self.data.__class__.__name__,
 121                             super(ErrorString, self).__str__())
 122
 123     def __unicode__(self):
 124         return u'%s: %s' % (self.data.__class__.__name__,
 125                             super(ErrorString, self).__unicode__())
 126
 127
 128 class ErrorOutput(object):
 129     """
 130     Wrapper class for file-like error streams with
 131     failsave de- and encoding of `str`, `bytes`, `unicode` and
 132     `Exception` instances.
 133     """
 134
 135     def __init__(self, stream=None, encoding=None,
 136                  encoding_errors='backslashreplace',
 137                  decoding_errors='replace'):
 138         """
 139         :Parameters:
 140             - `stream`: a file-like object (which is written to),
 141                         a string (opended as a file),
 142                         `None` (bind to `sys.stderr`; default).
 143                         If evaluating to `False` (but not `None`),
 144                         write() requests are ignored.
 145             - `encoding`: `stream` text encoding. Guessed if None.
 146             - `encoding_errors`: how to treat encoding errors.
 147         """
 148         if stream is None:
 149             stream = sys.stderr
 150         elif not(stream):
 151             stream = False
 152         # if `stream` is a file name, open it
 153         elif isinstance(stream, str):
 154             stream = open(stream, 'w')
 155         elif isinstance(stream, unicode):
 156             stream = open(stream.encode(sys.getfilesystemencoding()), 'w')
 157
 158         self.stream = stream
 159         """Where warning output is sent."""
 160
 161         self.encoding = (encoding or getattr(stream, 'encoding', None) or
 162                          locale_encoding or 'ascii')
 163         """The output character encoding."""
 164
 165         self.encoding_errors = encoding_errors
 166         """Encoding error handler."""
 167
 168         self.decoding_errors = decoding_errors
 169         """Decoding error handler."""
 170
 171     def write(self, data):
 172         """
 173         Write `data` to self.stream. Ignore, if self.stream is False.
 174
 175         `data` can be a `string`, `unicode`, or `Exception` instance.
 176         """
 177         if self.stream is False:
 178             return
 179         if isinstance(data, Exception):
 180             data = unicode(SafeString(data, self.encoding,
 181                                   self.encoding_errors, self.decoding_errors))
 182         try:
 183             self.stream.write(data)
 184         except UnicodeEncodeError:
 185             self.stream.write(data.encode(self.encoding, self.encoding_errors))
 186         except TypeError: # in Python 3, stderr expects unicode
 187             self.stream.write(unicode(data, self.encoding, self.decoding_errors))
 188
 189     def close(self):
 190         """
 191         Close the error-output stream.
 192
 193         Ignored if the stream is` sys.stderr` or `sys.stdout` or has no
 194         close() method.
 195         """
 196         if self.stream in (sys.stdout, sys.stderr):
 197             return
 198         try:
 199             self.stream.close()
 200         except AttributeError:
 201             pass
 202