Ticket #3332: mimeview_refactoring-r3507.diff

trac/attachment.py

@@ -26 +26 @@
 from trac.config import BoolOption, IntOption
 from trac.core import *
 from trac.env import IEnvironmentSetupParticipant
-from trac.mimeview import *
+from trac.mimeview.api import Mimeview, MimeType, FileMimeContent
 from trac.util import get_reporter_id, create_unique_file
 from trac.util.datefmt import format_datetime, pretty_timedelta
 from trac.util.markup import Markup, html
@@ -124 +124 @@
     def parent_href(self, req):
         return req.href(self.parent_type, self.parent_id)
 
-    def _get_title(self):
+    def _get_title(self): # TODO: should extend to other `parent_type`s
         return '%s%s: %s' % (self.parent_type == 'ticket' and '#' or '',
                              self.parent_id, self.filename)
     title = property(_get_title)
@@ -227 +227 @@
 
     select = classmethod(select)
 
-    def open(self):
+    def open(self): # deprecate?
         self.env.log.debug('Trying to open attachment at %s', self.path)
         try:
             fd = open(self.path, 'rb')
@@ -505 +505 @@
                                  'author': get_reporter_id(req)}
 
     def _render_view(self, req, attachment):
+        # FIXME: perm_map should extend to other `parent_type`s
         perm_map = {'ticket': 'TICKET_VIEW', 'wiki': 'WIKI_VIEW'}
         req.perm.assert_permission(perm_map[attachment.parent_type])
 
@@ -522 +523 @@
         if req.perm.has_permission(perm_map[attachment.parent_type]):
             req.hdf['attachment.can_delete'] = 1
 
-        fd = attachment.open()
-        try:
-            mimeview = Mimeview(self.env)
+        format = req.args.get('format')
+        raw_href = attachment.href(req, format='raw')
 
-            # MIME type detection
-            str_data = fd.read(1000)
-            fd.seek(0)
-            
-            binary = is_binary(str_data)
-            mime_type = mimeview.get_mimetype(attachment.filename, str_data)
+        mimecontent = FileMimeContent(self.env, attachment.path, raw_href,
+                                      'Attachment')
+        can_render_as_txt = self.render_unsafe_content and \
+                             not mimecontent.is_binary
 
-            # Eventually send the file directly
-            format = req.args.get('format')
-            if format in ('raw', 'txt'):
-                if not self.render_unsafe_content and not binary:
-                    # Force browser to download HTML/SVG/etc pages that may
-                    # contain malicious code enabling XSS attacks
-                    req.send_header('Content-Disposition', 'attachment;' +
-                                    'filename=' + attachment.filename)
-                if not mime_type or (self.render_unsafe_content and \
-                                     not binary and format == 'txt'):
-                    mime_type = 'text/plain'
-                if 'charset=' not in mime_type:
-                    charset = mimeview.get_charset(str_data, mime_type)
-                    mime_type = mime_type + '; charset=' + charset
-                req.send_file(attachment.path, mime_type)
+        # Eventually send the file directly
+        if format in ('raw', 'txt'):
+            if not self.render_unsafe_content and not mimecontent.is_binary:
+                # Force browser to download HTML/SVG/etc pages that may
+                # contain malicious code enabling XSS attacks
+                req.send_header('Content-Disposition',
+                                'attachment;filename=%s' % attachment.filename)
+            if not mimecontent.type.is_known or \
+                   (format == 'txt' and can_render_as_txt):
+                # Force the content to be displayed as text
+                type = MimeType('text/plain', mimecontent.encoding)
+            else:
+                type = mimecontent.type
+            req.send_file(attachment.path, type.mimetype_charset)
 
-            # add ''Plain Text'' alternate link if needed
-            if self.render_unsafe_content and not binary and \
-               mime_type and not mime_type.startswith('text/plain'):
-                plaintext_href = attachment.href(req, format='txt')
-                add_link(req, 'alternate', plaintext_href, 'Plain Text',
-                         mime_type)
+        mimetype = mimecontent.type.mimetype
 
-            # add ''Original Format'' alternate link (always)
-            raw_href = attachment.href(req, format='raw')
-            add_link(req, 'alternate', raw_href, 'Original Format', mime_type)
+        # add ''Plain Text'' alternate link if needed
+        if can_render_as_txt and mimecontent.type.is_known and \
+               mimetype != 'text/plain':
+            add_link(req, 'alternate', attachment.href(req, format='txt'),
+                     'Plain Text', 'text/plain')
 
-            self.log.debug("Rendering preview of file %s with mime-type %s"
-                           % (attachment.filename, mime_type))
+        # add ''Original Format'' alternate link (always)
+        add_link(req, 'alternate', raw_href, 'Original Format', mimetype)
 
-            req.hdf['attachment'] = mimeview.preview_to_hdf(
-                req, fd, os.fstat(fd.fileno()).st_size, mime_type,
-                attachment.filename, raw_href, annotations=['lineno'])
-        finally:
-            fd.close()
+        self.log.debug("Rendering preview of file %s with mime-type %s" % \
+                       (attachment.filename, mimetype))
 
+        req.hdf['attachment'] = Mimeview(self.env).preview_to_hdf(
+            req, mimecontent, annotations=['lineno'])
+
     def _render_list(self, req, p_type, p_id):
         self._parent_to_hdf(req, p_type, p_id)
         req.hdf['attachment'] = {

trac/mimeview/rst.py

@@ -28 +28 @@
 import re
 
 from trac.core import *
-from trac.mimeview.api import IHTMLPreviewRenderer, content_to_unicode
+from trac.mimeview.api import IHTMLPreviewRenderer
 from trac.web.href import Href
 from trac.wiki.formatter import WikiProcessor
 from trac.wiki import WikiSystem
@@ -223 +223 @@
 
         _inliner = rst.states.Inliner()
         _parser = rst.Parser(inliner=_inliner)
-        content = content_to_unicode(self.env, content, mimetype)
+        content = unicode(content)
         content = content.encode('utf-8')
         html = publish_string(content, writer_name='html', parser=_parser,
                               settings_overrides={'halt_level': 6})

trac/mimeview/api.py

@@ -19 +19 @@
 #         Christian Boos <cboos@neuf.fr>
 
 """
-The `trac.mimeview` module centralize the intelligence related to
-file metadata, principally concerning the `type` (MIME type) of the content
-and, if relevant, concerning the text encoding (charset) used by the content.
+The `trac.mimeview` module centralizes the intelligence related to file
+metadata, principally concerning the `type` (MIME type) and the text
+encoding (charset) used by the content, if the latter one is relevant.
 
 There are primarily two approaches for getting the MIME type of a given file:
  * taking advantage of existing conventions for the file name
  * examining the file content and applying various heuristics
 
-The module also knows how to convert the file content from one type
-to another type.
+The module also knows about conversions from one data type to another type,
+like conversions to text/html (this is no more a special case).
 
-In some cases, only the `url` pointing to the file's content is actually
-needed, that's why we avoid to read the file's content when it's not needed.
-
-The actual `content` to be converted might be a `unicode` object,
-but it can also be the raw byte string (`str`) object, or simply
-an object that can be `read()`.
+In order to keep the API simple, we deal with a few classes,
+each encapsulating a part of the knowledge related to content.
+ * the `MimeType`, for storing the mime type string, the charset,
+   but also eventually the name and the commonly used file extension
+   for that type
+ * the `MimeContent` and `FileMimeContent`, which provide a flexible
+   API for handling string and file content, respectively.
+   Those classes inherit from the abstract `MimeContentBase`, which
+   can be used to make new wrapper classes for any kind of content.
+ * the `Conversion` class, which is use to specify conversion from
+   one `MimeType` to another
 """
 
+import os
 import re
 from StringIO import StringIO
 
 from trac.config import IntOption, ListOption, Option
 from trac.core import *
 from trac.util import sorted
-from trac.util.text import to_utf8, to_unicode
+from trac.util.text import to_utf8, to_unicode, IDENTITY_CHARSET
 from trac.util.markup import escape, Markup, Fragment, html
 
 
-__all__ = ['get_mimetype', 'is_binary', 'detect_unicode', 'Mimeview',
-           'content_to_unicode']
+__all__ = ['get_mimetype', 'is_binary', 'detect_unicode',
+           'Mimeview', 'MimeType', 'Conversion',
+           'MimeContentBase', 'MimeContent', 'FileMimeContent',
+           'TEXT_PLAIN', 'TEXT_HTML', 'APPLICATION_OCTET_STREAM']
 
 
 # Some common MIME types and their associated keywords and/or file extensions
 
+APPLICATION_OCTET_STREAM_STR = 'application/octet-stream'
+
 KNOWN_MIME_TYPES = {
     'application/pdf':        ['pdf'],
     'application/postscript': ['ps'],
@@ -114 +124 @@
     for e in exts:
         MIME_MAP[e] = t
 
-# Simple builtin autodetection from the content using a regexp
-MODE_RE = re.compile(
-    r"#!(?:[/\w.-_]+/)?(\w+)|"               # look for shebang
-    r"-\*-\s*(?:mode:\s*)?([\w+-]+)\s*-\*-|" # look for Emacs' -*- mode -*-
-    r"vim:.*?syntax=(\w+)"                   # look for VIM's syntax=<n>
-    )
 
-def get_mimetype(filename, content=None, mime_map=MIME_MAP):
-    """Guess the most probable MIME type of a file with the given name.
+# -- a few functions for dealing with MIME types / binary / text content
+#    in a simple way (get_mimetype, is_binary, detect_unicode)
 
+def get_mimetype_from_filename(filename, mime_map=MIME_MAP):
+    """Guess the most probable MIME type of file with the given `filename`.
+
     `filename` is either a filename (the lookup will then use the suffix)
     or some arbitrary keyword.
-    
-    `content` is either a `str` or an `unicode` string.
+    `mime_map` maps keywords to MIME types.
+
+    Return the MIME type as a string, or `None` if not detected.
     """
     suffix = filename.split('.')[-1]
     if suffix in mime_map:
@@ -141 +149 @@
             mimetype = mimetypes.guess_type(filename)[0]
         except:
             pass
-        if not mimetype and content:
-            match = re.search(MODE_RE, content[:1000])
-            if match:
-                mode = match.group(1) or match.group(3) or \
-                    match.group(2).lower()
-                if mode in mime_map:
-                    # 3) mimetype from the content, using the `MODE_RE`
-                    return mime_map[mode]
-            else:
-                if is_binary(content):
-                    # 4) mimetype from the content, using`is_binary`
-                    return 'application/octet-stream'
         return mimetype
 
+# Simple builtin autodetection from the content using a regexp
+MODE_RE = re.compile(
+    r"#!(?:[/\w.-_]+/)?(\w+)|"               # look for shebang
+    r"-\*-\s*(?:mode:\s*)?([\w+-]+)\s*-\*-|" # look for Emacs' -*- mode -*-
+    r"vim:.*?syntax=(\w+)"                   # look for VIM's syntax=<n>
+    )
+
+def get_mimetype_from_content(content):
+    """Guess the most probable MIME type of file with the given `filename`.
+
+    `content` is either a `str` or an `unicode` string 
+
+    Return the MIME type as a string, or `None` if not detected.
+    """
+    match = re.search(MODE_RE, content[:1000])
+    if match:
+        mode = match.group(1) or match.group(3) or \
+            match.group(2).lower()
+        if mode in mime_map:
+            # 3) mimetype from the content, using the `MODE_RE`
+            return mime_map[mode]
+    else:
+        if is_binary(content):
+            # 4) mimetype from the content, using `is_binary`
+            return APPLICATION_OCTET_STREAM_STR
+
+def get_mimetype(filename, content=None, mime_map=MIME_MAP):
+    """Auto-detect MIME type either from the `filename` or from the `content`.
+    """
+    mimetype = get_mimetype_from_filename(filename, mime_map)
+    if not mimetype and content:
+        mimetype = get_mimetype_from_content(content)
+    return mimetype
+
 def is_binary(data):
     """Detect binary content by checking the first thousand bytes for zeroes.
 
@@ -165 +195 @@
     return '\0' in data[:1000]
 
 def detect_unicode(data):
-    """Detect different unicode charsets by looking for BOMs (Byte Order Marks).
+    """Detect different unicode charsets by looking for Byte Order Marks.
 
     Operate obviously only on `str` objects.
     """
@@ -178 +208 @@
     else:
         return None
 
-def content_to_unicode(env, content, mimetype):
-    """Retrieve an `unicode` object from a `content` to be previewed"""
-    mimeview = Mimeview(env)
-    if hasattr(content, 'read'):
-        content = content.read(mimeview.max_preview_size)
-    return mimeview.to_unicode(content, mimetype)
 
+# -- Classes for mimetype, content and conversion
 
+class MimeType(object):
+    """Representation of a MIME-Type.
+
+    If the MIME type correspond to text content, the object can also
+    store a `charset` information.
+
+    A MIME type has a `name` and has an `extension`
+    that can be used for storing the converted data in a file.
+
+    All the properties of this class are read-only.
+    """
+    
+    def __init__(self, mimetype, charset=None, name=None, extension=None):
+        """The `mimetype` string can eventually embed the `charset`."""
+        self._mimetype = mimetype
+        # determine charset
+        self._charset = charset
+        if not self._charset and self._mimetype:
+            sep_idx = mimetype.find(';')
+            if sep_idx >= 0:
+                self._mimetype = mimetype[:sep_idx].strip()
+                charset_idx = mimetype.find('charset=', sep_idx)
+                if charset_idx >= 0:
+                    self._charset = mimetype[charset_idx+8:].strip()
+        self._extension = extension
+        self._name = name
+
+    def __repr__(self):
+        return self.mimetype_charset
+
+    def _get_extension(self):
+        if not self._extension:
+            self._extension = KNOWN_MIME_TYPES.get(self.mimetype)
+            if not self._extension:
+                detail = self.mimetype.split('/', 1)[1]
+                if detail.startswith('x-'):
+                    self._extension = detail[2:]
+        return self._extension
+
+    def _get_mimetype_charset(self):
+        """Combine the MIME type and charset information in a single string.
+        """
+        if self._mimetype and self._charset:
+            return '%s; charset=%s' % (self.mimetype, self.charset)
+        else:
+            return self.mimetype
+
+    is_known = property(lambda x: x._mimetype is not None)
+    mimetype = property(lambda x: x._mimetype or APPLICATION_OCTET_STREAM_STR,
+                        doc="MIME Type string (without charset information)")
+    charset = property(lambda x: x._charset,
+                       doc="Eventual charset information")
+    name = property(lambda x: x._name or x._extension)
+    extension = property(_get_extension)
+    mimetype_charset = property(_get_mimetype_charset)
+
+    def match(self, other, regexp=False):
+        """Compare MIME type string only.
+
+        If `regexp` is set, `self.mimetype` is used as a regexp.
+        """
+        if not isinstance(other, MimeType):
+            return False
+        if regexp:
+            return re.match(self.mimetype, other.mimetype)
+        else:
+            return self.mimetype == other.mimetype
+
+
+TEXT_PLAIN = MimeType('text/plain', 'utf-8', 'Plain Text', 'txt')
+TEXT_HTML = MimeType('text/html', 'utf-8', 'HTML', 'html')
+APPLICATION_OCTET_STREAM = MimeType(APPLICATION_OCTET_STREAM_STR,
+                                    IDENTITY_CHARSET,
+                                    'Undefined (binary)', 'bin') 
+
+
+class MimeContentBase(object):
+    """An abstract MIME content, with an associated MimeType.
+
+    Such an object has means to auto-detect both the MIME Type and
+    the `encoding` of its content.
+
+    That `encoding` is more reliable than the `type.charset` information.
+    There are additional consistency checks that are performed, and it
+    can be `None` if the content is an `unicode` object.
+
+    The content itself can be accessed in various ways: through
+    the iterator protocol, the len() and unicode() operators...
+    """
+
+    def __init__(self, env, mimetype=None, filename=None, url=None):
+        """
+        `mimetype` can be specified as a `MimeType` object,
+        or as string, which will then be a hint about the content.
+
+        If the mimetype is not specified or equal to
+        "application/octet-stream", then it will be auto-detected when needed.
+
+        In case auto-detection fails, APPLICATION_OCTET_STREAM will be the
+        corresponding MIME type.
+
+        The `filename` is simply a suggested basename for that content.
+
+        The `url` is a link for retrieving the raw content directly
+        from the server. This can be useful for converters that can
+        provide links to objects, instead of having to expand the
+        content inline.
+        """
+        self.env = env
+        if isinstance(mimetype, basestring):
+            mimetype = MimeType(mimetype)
+        self._type = mimetype
+        self._filename = filename
+        self._url = url
+        self._binary = None
+        self._encoding = False
+
+    def __repr__(self):
+        return '<%s %s "%s">' % (self.__class__.__name__, self._type,
+                                 self._filename or self._url)
+
+    def __unicode__(self):
+        """Return the `unicode` object corresponding to the content."""
+        return to_unicode(self.content, self.encoding)
+        # Note: this does the right thing if the content is already `unicode`
+
+
+    def _is_binary(self):
+        """An heuristic to guess whether the content is binary data or not.
+
+        This will trigger the retrieval of an `excerpt` of the content.
+        """
+        if self._binary is None:
+            mimetype = self.type.mimetype
+            self._binary = is_binary(self.excerpt) or \
+                           (self.type.is_known and 
+                            mimetype == APPLICATION_OCTET_STREAM_STR) or \
+                            mimetype in Mimeview(self.env).treat_as_binary
+        return self._binary
+
+    def _get_type(self):
+        """Get or determine the MimeType corresponding to this content.
+
+        An `excerpt` of the content will be examined if needed.
+        """
+        if self._type is None: # not set
+            mimetype = None
+            if self.filename:
+                mimemap = Mimeview(self.env).mimemap
+                mimetype = get_mimetype_from_filename(self.filename, mimemap)
+            if not mimetype:
+                mimetype = get_mimetype_from_content(self.excerpt)
+            if not mimetype:
+                pass # TODO 0.11: go through IMimeTypeDetectors
+            self._type = MimeType(mimetype)
+        return self._type
+
+    def _set_type(self, type):
+        """Simply replace the existing `type` by the given `MimeType` object.
+
+        If `None` is given, this will force auto-detection the next time
+        `type` will be accessed.
+
+        Can be used for in-place conversion (e.g. ''any'' to text/plain).
+        """
+        self._type = type
+
+    def _get_encoding(self):
+        """Get or determine the current encoding of that `content`.
+
+        The encoding will be determined using this order:
+         * from the charset information present in the mimetype information
+         * auto-detection of the charset from the `content`
+         * if nothing else worked, use the configured `default_charset`
+
+        If the `content` happens to be a genuine `unicode` object, then
+        this returns `None`.
+        If the `content` is binary, then the encoding will be the identity
+        charset (ISO Latin 1).
+        """
+        if self._encoding is False:
+            charset = self.type.charset
+            if charset:
+                self._encoding = charset
+            elif isinstance(self.excerpt, str):
+                utf_encoding = detect_unicode(self.excerpt)
+                if utf_encoding is not None:
+                    self._encoding = utf_encoding
+                elif self.is_binary:
+                    self._encoding = IDENTITY_CHARSET
+            elif isinstance(self.excerpt, unicode):
+                self._encoding = None
+            if self._encoding is False:
+                pass # TODO 0.11: go through ICharsetDetectors here
+            if self._encoding is False:
+                self._encoding = Mimeview(self.env).default_charset
+        return self._encoding
+    
+    def _get_content(self):
+        """Retrieve all the content.
+
+        Default implementation based on iterator. If the iterator itself
+        is implemented based on the content... reimplement this one!
+        """
+        return "".join(self.__iter__())
+
+    def read(self): # TODO: remove in 0.11
+        return self.content # (compatibility with IHTMLPreviewRenderer)
+
+    # Methods that need to be reimplemented by subclasses:
+
+    def __iter__(self):
+        """Iterate on chunks of raw content."""
+        raise NotImplementedError
+
+    def __len__(self):
+        """Length of the raw content, in bytes."""
+        raise NotImplementedError
+
+    def _get_excerpt(self, len=1000):
+        """Extracts the first `len` characters from the content."""
+        raise NotImplementedError
+            
+    type = property(fget=lambda x: x._get_type(),
+                    fset=lambda x, y: x._set_type(y))
+    is_binary = property(lambda x: x._is_binary())
+    encoding = property(lambda x: x._get_encoding())
+    excerpt = property(lambda x: x._get_excerpt())
+    content = property(lambda x: x._get_content())
+    filename = property(lambda x: x._filename)
+    url = property(lambda x: x._url)
+
+
+class MimeContent(MimeContentBase):
+    """MIME-typed content wrapper for a basestring."""
+
+    def __init__(self, env, content, mimetype, filename='file', url=None):
+        MimeContentBase.__init__(self, env, mimetype, filename, url)
+        self._content = content
+
+    # Reimplemented methods
+
+    def _get_content(self):
+        """Retrieve the wrapped content.
+
+        Note: therefore this *might* be an `unicode` object.
+        Remember that in this case, `encoding` will be `None`.
+        """
+        return self._content
+
+    def __iter__(self):
+        """Iterate on chunks of content.
+
+        If the content `is_binary` property is `False`, those chunks will
+        be lines, with the line endings kept.
+        """
+        if self.is_binary:
+            buf = StringIO(self.content)
+            chunk = buf.read(1000)
+            while chunk:
+                yield chunk
+                chunk = buf.read(1000)
+        else:
+            for line in self.content.splitlines(True):
+                yield line
+
+    def __len__(self):
+        """Length of the content, in characters."""
+        return len(self.content)
+
+    def _get_excerpt(self, len=1000):
+        """Extracts the first `len` characters from the content."""
+        return self._content[:len]
+
+
+class FileMimeContent(MimeContentBase):
+    """MIME-typed content wrapper for a file."""
+
+    def __init__(self, env, path, url=None, kind='File', mimetype=None):
+        self._fd = None
+        self._path = path
+        self._kind = kind
+        self._excerpt = None
+        MimeContentBase.__init__(self, env, mimetype, os.path.basename(path),
+                                 url)
+    def __del__(self):
+        if self._fd:
+            self._fd.close()
+
+    def _ensure_open(self):
+        if not self._fd:
+            try:
+                self._fd = open(self._path)
+            except IOError:
+                raise TracError('%s "%s" not found' % (self._kind,
+                                                       self._filename))
+    # Reimplemented methods
+    
+    def __iter__(self):
+        """Iterate on chunks of raw content."""
+        chunk = self.excerpt
+        while chunk:
+            yield chunk
+            chunk = self._fd.read(1000)
+
+    def __len__(self):
+        """Length of the raw content, in bytes."""
+        if self._fd:
+            stat = os.fstat(self._fd.fileno())
+        else:
+            stat = os.stat(self._path)
+        return stat.st_size
+
+    def _get_excerpt(self, len=1000):
+        """Extracts the `len` first bytes from the content."""
+        if self._excerpt is None:
+            self._ensure_open()
+            self._excerpt = self._fd.read(1000)
+        return self._excerpt
+
+        
+class NoConversion(TracError):
+    def __init__(self, msg, from_, to):
+        self.msg = msg
+        self.from_ = from_
+        self.to = to
+
+    def message(self):
+        return '%s, from %s to %s' % \
+               (self.msg, self.from_.mimetype, self.to.mimetype)
+
+class Conversion(object):
+    """A specification for performing a data conversion.
+
+    Each conversion is identified by a `key` and targets an output `mimetype`.
+
+    A conversion also specifies a `quality` ranking, which is a number
+    in the range 0 to 9, where 0 means no support and 9 means "perfect"
+    support (try to keep 9 available for user defined conversions,
+    though nothing will prevent them from using 10 or 100...)
+
+    Finally, `expand_tabs` indicates whether a tab expansion should precede
+    the conversion attempt.
+
+    e.g. Conversion(key='latex', quality=8, mimetype=MimeType('text/x-tex'))
+    """
+
+    def __init__(self, key, quality=1, mimetype=TEXT_HTML, expand_tabs=False):
+        self.key = key
+        self.quality = quality
+        self.mimetype = mimetype
+        self.expand_tabs = expand_tabs
+
+    def __repr__(self):
+        return '<Conversion "%s" to %s>' % (self.key, self.mimetype) 
+
+
+# -- Deprecated (TODO: remove in 0.11)
+
 class IHTMLPreviewRenderer(Interface):
     """Extension point interface for components that add HTML renderers of
     specific content types to the `Mimeview` component.
 
-    (Deprecated)
+    Deprecated in 0.10. Implement `IContentConverter` instead.
     """
 
     # implementing classes should set this property to True if they
@@ -198 +582 @@
     expand_tabs = False
 
     def get_quality_ratio(mimetype):
-        """Return the level of support this renderer provides for the `content`
-        of the specified MIME type. The return value must be a number between
-        0 and 9, where 0 means no support and 9 means "perfect" support.
-        """
+        """Return the level of support this renderer provides"""
 
     def render(req, mimetype, content, filename=None, url=None):
-        """Render an XHTML preview of the raw `content`.
+        """Render an XHTML preview of the raw `content`."""
 
-        The `content` might be:
-         * a `str` object
-         * an `unicode` stri