`trac.mimeview.api` – Trac content transformation APIs¶

Interfaces¶

class trac.mimeview.api.IHTMLPreviewRenderer¶

Bases: trac.core.Interface

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.

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¶

Bases: trac.core.Interface

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

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¶

Bases: trac.core.Interface

An extension point interface for generic MIME based content conversion.

Note

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

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¶

Bases: trac.core.Component

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.

max_preview_size¶: Maximum file size for HTML preview.

treat_as_binary¶: Comma-separated list of MIME types that should be treated as binary data.

get_supported_conversions(mimetype)¶

Return a list of target MIME types as instances of the namedtuple MimeConversion. Output is ordered from best to worst quality.

The MimeConversion namedtuple has fields: key, name, extension, in_mimetype, out_mimetype, quality, converter.

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_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_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)¶

Prepares a rendered preview of the given content.

Note: content will usually be an object with a read method.

send_converted(req, in_type, content, selector, filename='file')¶

Helper method for converting content and sending it directly.

selector can be either a key or a MIME Type.

class trac.mimeview.api.ImageRenderer¶

Bases: trac.core.Component

Inline image display.

This component doesn’t need the content at all.

class trac.mimeview.api.LineNumberAnnotator¶

Bases: trac.core.Component

Text annotator that adds a column with line numbers.

class trac.mimeview.api.PlainTextRenderer¶

Bases: trac.core.Component

HTML preview renderer for plain text, and fallback for any kind of text for which no more specific renderer is available.

class trac.mimeview.api.WikiTextRenderer¶

Bases: trac.core.Component

HTML renderer for files containing Trac’s own Wiki formatting markup.

Helper classes¶

class trac.mimeview.api.RenderingContext(resource, href=None, perm=None)¶

Bases: object

A rendering context specifies ‘’how’’ the content should be rendered.

It holds together all the needed contextual information that will be needed by individual renderer components.

To that end, a context keeps track of the Href instance (.href) which should be used as a base for building URLs.

It also provides a PermissionCache (.perm) which can be used to restrict the output so that only the authorized information is shown.

A rendering context may also be associated to some Trac resource which will be used as the implicit reference when rendering relative links or for retrieving relative content and can be used to retrieve related metadata.

Rendering contexts can be nested, and a new context can be created from an existing context using the call syntax. The previous context can be retrieved using the .parent attribute.

For example, when rendering a wiki text of a wiki page, the context will be associated to a resource identifying that wiki page.

If that wiki text contains a [[TicketQuery]] wiki macro, the macro will set up nested contexts for each matching ticket that will be used for rendering the ticket descriptions.

Since:	version 1.0

Directly create a RenderingContext.

Parameters:	resource (`Resource`) – the associated resource href – an `Href` object suitable for creating URLs perm – a `PermissionCache` object used for restricting the generated output to “authorized” information only.

The actual perm attribute of the rendering context will be bound to the given resource so that fine-grained permission checks will apply to that.

parent = None¶: The parent context, if any

child(resource=None, id=False, version=False, parent=False)¶

Create a nested rendering context.

self will be the parent for the new nested context.

Parameters:	resource – either a `Resource` object or the realm string for a resource specification to be associated to the new context. If `None`, the resource will be the same as the resource of the parent context. id – the identifier part of the resource specification version – the version of the resource specification
Returns:	the new context object
Return type:	`RenderingContext`

>>> context = RenderingContext('wiki', 'WikiStart')
>>> ticket1 = Resource('ticket', 1)
>>> context.child('ticket', 1).resource == ticket1
True
>>> context.child(ticket1).resource is ticket1
True
>>> context.child(ticket1)().resource is ticket1
True

set_hints(**keyvalues)¶

Set rendering hints for this rendering context.

>>> ctx = RenderingContext('timeline')
>>> ctx.set_hints(wiki_flavor='oneliner', shorten_lines=True)
>>> t_ctx = ctx('ticket', 1)
>>> t_ctx.set_hints(wiki_flavor='html', preserve_newlines=True)
>>> (t_ctx.get_hint('wiki_flavor'), t_ctx.get_hint('shorten_lines'),              t_ctx.get_hint('preserve_newlines'))
('html', True, True)
>>> (ctx.get_hint('wiki_flavor'), ctx.get_hint('shorten_lines'),              ctx.get_hint('preserve_newlines'))
('oneliner', True, None)

get_hint(hint, default=None)¶

Retrieve a rendering hint from this context or an ancestor context.

>>> ctx = RenderingContext('timeline')
>>> ctx.set_hints(wiki_flavor='oneliner')
>>> t_ctx = ctx('ticket', 1)
>>> t_ctx.get_hint('wiki_flavor')
'oneliner'
>>> t_ctx.get_hint('preserve_newlines', True)
True

has_hint(hint)¶

Test whether a rendering hint is defined in this context or in some ancestor context.

>>> ctx = RenderingContext('timeline')
>>> ctx.set_hints(wiki_flavor='oneliner')
>>> t_ctx = ctx('ticket', 1)
>>> t_ctx.has_hint('wiki_flavor')
True
>>> t_ctx.has_hint('preserve_newlines')
False

class trac.mimeview.api.Content(input, max_size)¶

Bases: object

A lazy file-like object that only reads input if necessary.

Functions¶

trac.mimeview.api.get_mimetype(filename, content=None, mime_map=MIME_MAP)¶

Guess the most probable MIME type of a file with the given name.

Parameters:	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.

trac.mimeview.api.ct_mimetype(content_type)¶: Return the mimetype part of a content type.

trac.mimeview.api.is_binary(data)¶

Detect binary content by checking the first thousand bytes for zeroes.

Operate on either str or unicode strings.

trac.mimeview.api.detect_unicode(data)¶

Detect different unicode charsets by looking for BOMs (Byte Order Mark).

Operate obviously only on str objects.

trac.mimeview.api.content_to_unicode(env, content, mimetype)¶

Retrieve an unicode object from a content to be previewed.

In case the raw content had an unicode BOM, we remove it.

>>> from trac.test import EnvironmentStub
>>> env = EnvironmentStub()
>>> content_to_unicode(env, u"\ufeffNo BOM! h\u00e9 !", '')
u'No BOM! h\xe9 !'
>>> content_to_unicode(env, "﻿No BOM! hé !", '')
u'No BOM! h\xe9 !'

Sub-modules¶

class trac.mimeview.patch.PatchRenderer¶

Bases: trac.core.Component

HTML renderer for patches in unified diff format.

This uses the same layout as in the wiki diff view or the changeset view.

class trac.mimeview.pygments.PygmentsRenderer¶

Bases: trac.core.Component

HTML renderer for syntax highlighting based on Pygments.

pygments_lexer_options¶

Configure Pygments [%(url)s lexer] options.

For example, to set the [%(url)s#lexers-for-php-and-related-languages PhpLexer] options startinline and funcnamehighlighting: {{{#!ini [pygments-lexer] php.startinline = True php.funcnamehighlighting = True }}}

The lexer name is derived from the class name, with Lexer stripped from the end. The lexer //short names// can also be used in place of the lexer name.

default_style¶: The default style to use for Pygments syntax highlighting.

pygments_modes¶

List of additional MIME types known by Pygments.

For each, a tuple mimetype:mode:quality has to be specified, where mimetype is the MIME type, mode is the corresponding Pygments mode to be used for the conversion and quality is the quality ratio associated to this conversion. That can also be used to override the default quality ratio used by the Pygments render.

trac.mimeview.rst.trac_directive(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)¶

Inserts a reference node into the document for a given TracLink, based on the content of the arguments.

Usage:

.. trac:: target [text]

target may be any TracLink, provided it doesn’t embed a space character (e.g. wiki:”…” notation won’t work).

[text] is optional. If not given, target is used as the reference text.

trac.mimeview.rst.code_block_directive(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)¶

Create a code-block directive for docutils.

Usage: .. code-block:: language

If the language can be syntax highlighted it will be.

class trac.mimeview.rst.ReStructuredTextRenderer¶

Bases: trac.core.Component

HTML renderer for plain text in reStructuredText format.

Trac support for Textile See also: https://github.com/textile/python-textile

class trac.mimeview.txtl.TextileRenderer¶

Bases: trac.core.Component

Renders plain text in Textile format as HTML.

Table of Contents

Previous topic

Next topic

This Page

`trac.mimeview.api` – Trac content transformation APIs¶

Interfaces¶

Components¶

Helper classes¶

Functions¶

Sub-modules¶

trac.mimeview.api – Trac content transformation APIs¶

Interfaces¶

Components¶

Helper classes¶

Functions¶

Sub-modules¶

`trac.mimeview.api` – Trac content transformation APIs¶