trac.mimeview.api – Trac content transformation APIs

File metadata management

The trac.mimeview package centralizes 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.

There are primarily two approaches for getting the MIME type of a given file, either taking advantage of existing conventions for the file name, or examining the file content and applying various heuristics.

The module also knows how to convert the file content from one type to another type.

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().

Note

(for plugin developers)

The Mimeview API is quite complex and many things there are currently a bit difficult to work with (e.g. what an actual content might be, see the last paragraph of this description).

So this area is mainly in a ‘’work in progress’’ state, which will be improved along the lines described in #3332.

In particular, if you are interested in writing IContentConverter and IHTMLPreviewRenderer components, note that those interfaces will be merged into a new style IContentConverter. Feel free to contribute remarks and suggestions for improvements to the corresponding ticket (#3332 as well).

Interfaces

class trac.mimeview.api.IHTMLPreviewRenderer

Extension point interface for components that add HTML renderers of specific content types to the Mimeview component.

Note

This interface will be merged with IContentConverter, as conversion to text/html will simply be a particular content conversion.

Note however that the IHTMLPreviewRenderer will still be supported for a while through an adapter, whereas the IContentConverter interface itself will be changed.

So if all you want to do is convert to HTML and don’t feel like following the API changes, you should rather implement this interface for the time being.

See also trac.mimeview.api.IHTMLPreviewRenderer extension point

expand_tabs = False

implementing classes should set this property to True if they support text content where Trac should expand tabs into spaces

returns_source = False

indicate whether the output of this renderer is source code that can be decorated with annotations

get_extra_mimetypes()

Augment the Mimeview system with new mimetypes associations.

This is an optional method. Not implementing the method or returning nothing is fine, the component will still be asked via get_quality_ratio if it supports a known mimetype. But implementing it can be useful when the component knows about additional mimetypes which may augment the list of already mimetype to keywords associations.

Generate (mimetype, keywords) pairs for each additional mimetype, with keywords being a list of keywords or extensions that can be used as aliases for the mimetype (typically file suffixes or Wiki processor keys).

New in version 1.0.

get_quality_ratio()

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.

render(mimetype, content, filename=None, url=None)

Render an XHTML preview of the raw content in a RenderingContext.

The content might be:

• a str object
• an unicode string
• any object with a read method, returning one of the above

It is assumed that the content will correspond to the given mimetype.

Besides the content value, the same content may eventually be available through the filename or url parameters. This is useful for renderers that embed objects, using <object> or <img> instead of including the content inline.

Can return the generated XHTML text as a single string or as an iterable that yields strings. In the latter case, the list will be considered to correspond to lines of text in the original content.

class trac.mimeview.api.IHTMLPreviewAnnotator

Extension point interface for components that can annotate an XHTML representation of file contents with additional information.

See also trac.mimeview.api.IHTMLPreviewAnnotator extension point

get_annotation_type()

Return a (type, label, description) tuple that defines the type of annotation and provides human readable names. The type element should be unique to the annotator. The label element is used as column heading for the table, while description is used as a display name to let the user toggle the appearance of the annotation type.

get_annotation_data()

Return some metadata to be used by the annotate_row method below.

This will be called only once, before lines are processed. If this raises an error, that annotator won’t be used.

annotate_row(row, number, line, data)

Return the XHTML markup for the table cell that contains the annotation data.

context is the context corresponding to the content being annotated, row is the tr Element being built, number is the line number being processed and line is the line’s actual content. data is whatever additional data the get_annotation_data method decided to provide.

class trac.mimeview.api.IContentConverter

An extension point interface for generic MIME based content conversion.

Note

This api will likely change in the future (see #3332)

See also trac.mimeview.api.IContentConverter extension point

get_supported_conversions()

Return an iterable of tuples in the form (key, name, extension, in_mimetype, out_mimetype, quality) representing the MIME conversions supported and the quality ratio of the conversion in the range 0 to 9, where 0 means no support and 9 means “perfect” support. eg. (‘latex’, ‘LaTeX’, ‘tex’, ‘text/x-trac-wiki’, ‘text/plain’, 8)

convert_content(mimetype, content, key)

Convert the given content from mimetype to the output MIME type represented by key. Returns a tuple in the form (content, output_mime_type) or None if conversion is not possible.

content must be a str instance or an iterable instance which iterates str instances.

Components

class trac.mimeview.api.Mimeview

Generic HTML renderer for data, typically source code.

renderers

List of components that implement IHTMLPreviewRenderer

annotators

List of components that implement IHTMLPreviewAnnotator

converters

List of components that implement IContentConverter

default_charset

Charset to be used when in doubt.

tab_width

Displayed tab width in file preview. (‘’since 0.9’’)

max_preview_size

Maximum file size for HTML preview. (‘’since 0.9’’)

treat_as_binary

Comma-separated list of MIME types that should be treated as binary data. (‘’since 0.11.5’’)

get_supported_conversions(mimetype)

Return a list of target MIME types in same form as IContentConverter.get_supported_conversions(), but with the converter component appended. Output is ordered from best to worst quality.

convert_content(req, mimetype, content, key, filename=None, url=None, iterable=False)

Convert the given content to the target MIME type represented by key, which can be either a MIME type or a key. Returns a tuple of (content, output_mime_type, extension).

get_annotation_types()

Generator that returns all available annotation types.

render(context, mimetype, content, filename=None, url=None, annotations=None, force_source=False)

Render an XHTML preview of the given content.

content is the same as an IHTMLPreviewRenderer.render’s content argument.

The specified mimetype will be used to select the most appropriate IHTMLPreviewRenderer implementation available for this MIME type. If not given, the MIME type will be infered from the filename or the content.

Return a string containing the XHTML text.

When rendering with an IHTMLPreviewRenderer fails, a warning is added to the request associated with the context (if any), unless the disable_warnings hint is set to True.

get_max_preview_size()

Deprecated:since 0.10, use max_preview_size attribute directly.

get_charset(content='', mimetype=None)

Infer the character encoding from the content or the mimetype.

content is either a str or an unicode object.

The charset will be determined using this order:

• from the charset information present in the mimetype argument
• auto-detection of the charset from the content
• the configured default_charset

get_mimetype(filename, content=None)

Infer the MIME type from the filename or the content.

content is either a str or an unicode object.

Return the detected MIME type, augmented by the charset information (i.e. “<mimetype>; charset=…”), or None if detection failed.

is_binary(mimetype=None, filename=None, content=None)

Check if a file must be considered as binary.

to_utf8(content, mimetype=None)

Convert an encoded content to utf-8.

Deprecated:since 0.10, you should use unicode strings only.

to_unicode(content, mimetype=None, charset=None)

Convert content (an encoded str object) to an unicode object.

This calls trac.util.to_unicode with the charset provided, or the one obtained by Mimeview.get_charset().

configured_modes_mapping(renderer)

Return a MIME type to (mode,quality) mapping for given option

preview_data(context, content, length, mimetype, filename, url=None, annotations=None, force_source=False)