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.
See also trac.mimeview.api.IHTMLPreviewRenderer extension point
-
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, withkeywords
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
(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.
-
render
(context, mimetype, content, filename=None, url=None)¶ Render an XHTML preview of the raw
content
in aRenderingContext
.- The
content
might be:
It is assumed that the content will correspond to the given
mimetype
.Besides the
content
value, the same content may eventually be available through thefilename
orurl
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.
- The
-
-
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.
See also trac.mimeview.api.IHTMLPreviewAnnotator extension point
-
annotate_row
(context, 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 andline
is the line’s actual content.data
is whatever additional data theget_annotation_data
method decided to provide.
-
get_annotation_data
(context)¶ 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.
-
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. Thelabel
element is used as column heading for the table, whiledescription
is used as a display name to let the user toggle the appearance of the annotation type.
-
-
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)
See also trac.mimeview.api.IContentConverter extension point
-
convert_content
(req, 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 iteratesstr
instances.
-
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)
-
Components¶
-
class
trac.mimeview.api.
Mimeview
¶ Bases:
trac.core.Component
Generic HTML renderer for data, typically source code.
-
annotators
¶ List of components that implement
IHTMLPreviewAnnotator
-
configured_modes_mapping
(renderer)¶ Return a MIME type to
(mode,quality)
mapping for givenoption
-
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).
-
converters
¶ List of components that implement
IContentConverter
-
default_charset
¶ Charset to be used when in doubt.
-
get_annotation_types
()¶ Generator that returns all available annotation types.
-
get_charset
(content='', mimetype=None)¶ Infer the character encoding from the
content
or themimetype
.content
is either astr
or anunicode
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
- from the charset information present in the
-
get_mimetype
(filename, content=None)¶ Infer the MIME type from the
filename
or thecontent
.content
is either astr
or anunicode
object.Return the detected MIME type, augmented by the charset information (i.e. “<mimetype>; charset=...”), or
None
if detection failed.
-
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.
-
is_binary
(mimetype=None, filename=None, content=None)¶ Check if a file must be considered as binary.
-
max_preview_size
¶ Maximum file size for HTML preview.
-
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 aread
method.
-
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 anIHTMLPreviewRenderer.render
‘scontent
argument.The specified
mimetype
will be used to select the most appropriateIHTMLPreviewRenderer
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 thedisable_warnings
hint is set toTrue
.
-
renderers
¶ List of components that implement
IHTMLPreviewRenderer
-
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.
-
tab_width
¶ Displayed tab width in file preview.
-
to_unicode
(content, mimetype=None, charset=None)¶ Convert
content
(an encodedstr
object) to anunicode
object.This calls
trac.util.to_unicode
with thecharset
provided, or the one obtained byMimeview.get_charset()
.
-
treat_as_binary
¶ Comma-separated list of MIME types that should be treated as binary data.
-
-
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 givenresource
so that fine-grained permission checks will apply to that.-
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. IfNone
, 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: >>> 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
- resource – either a
-
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
-
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)
- resource (
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:
-
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.
-
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 acontent
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.
-
default_style
¶ The default style to use for Pygments syntax highlighting.
-
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
andfuncnamehighlighting
: {{{#!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.
-
pygments_modes
¶ List of additional MIME types known by Pygments.
For each, a tuple
mimetype:mode:quality
has to be specified, wheremimetype
is the MIME type,mode
is the corresponding Pygments mode to be used for the conversion andquality
is the quality ratio associated to this conversion. That can also be used to override the default quality ratio used by the Pygments render.
-
-
class
trac.mimeview.rst.
ReStructuredTextRenderer
¶ Bases:
trac.core.Component
HTML renderer for plain text in reStructuredText format.
-
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.
-
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 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.