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).
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
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.
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 an XHTML preview of the raw content in a RenderingContext.
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.
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
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.
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.
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.
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 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.
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)
Generic HTML renderer for data, typically source code.
List of components that implement IHTMLPreviewAnnotator
Return a MIME type to (mode,quality) mapping for given option
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).
List of components that implement IContentConverter
Charset to be used when in doubt.
Generator that returns all available annotation types.
Infer the character encoding from the content or the mimetype.
content is either a str or an unicode object.
| Deprecated: | since 0.10, use max_preview_size attribute directly. |
|---|
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.
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.
Check if a file must be considered as binary.
Maximum file size for HTML preview. (‘’since 0.9’‘)
Prepares a rendered preview of the given content.
Note: content will usually be an object with a read method.
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.
List of components that implement IHTMLPreviewRenderer
Helper method for converting content and sending it directly.
selector can be either a key or a MIME Type.
Displayed tab width in file preview. (‘’since 0.9’‘)
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().
Convert an encoded content to utf-8.
| Deprecated: | since 0.10, you should use unicode strings only. |
|---|
Comma-separated list of MIME types that should be treated as binary data. (‘’since 0.11.5’‘)
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: |
|
|---|
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.
Create a nested rendering context.
self will be the parent for the new nested context.
| Parameters: |
|
|---|---|
| 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
| Deprecated: | since 1.0, use web_context instead. Will be removed |
|---|
in release 1.3.1.
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
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 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)
| Deprecated: | since 1.0, use RenderingContext instead. Context is kept for compatibility and will be removed release 1.3.1. |
|---|
Directly create a RenderingContext.
| Parameters: |
|
|---|
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.
Guess the most probable MIME type of a file with the given name.
| Parameters: |
|---|
Return the mimetype part of a content type.
Detect binary content by checking the first thousand bytes for zeroes.
Detect different unicode charsets by looking for BOMs (Byte Order Mark).
Operate obviously only on str objects.
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 !'