lethe.format – Support for formatted text

This module implements a base class for text formatting and manages extensions providing specific markup formats.

Multiple formats are supported and identified by content types. Extensions should use the same content type names as in MIME.

Why not choose the simple solution of supporting only one markup format? Markdown is the obvious choice for it, while the author uses reStructuredText for this manual and some other works. Complex works need HTML or LaTeX. Each wiki has its own incompatible markup. Other users have documents with different markup languages, while they could use Lethe to handle drafts for their works and copy them to other systems. For these reasons, we need support for multiple formats and a general infrastructure handling them.

Todo

implement and mention linking: its design is another reason for format complexity

class lethe.format.Format(text)

Base class for text formatters.

To format a text, get a subclass constructor from get_format (or FormatRegistry.get_format). Construct an instance with the text containing markup in the text argument and use methods like to_html to format the text.

Subclasses should implement the to_html and verify methods. If the format has direct support for plain text output (e.g. with different text than via HTML), to_text should be implemented too. The default implementations should be ok for plain text represented as preformatted text in HTML.

Subclasses must override the content_type attribute and should override name and template.

content_type = None

Content type that this instance handles. Must be replaced in subclasses.

name = None

Name that identifies the format for humans. Use content_type if this is None.

Return the input with replaced links. Implementations of to_html should use this method.

Parameters:html – a string with HTML text.
Returns:a markupsafe.Markup instance with the input text with link targets replaced by the link processor

Run process_uri on each link target in the text as returned by to_html.

Use this function to make site-internal links point to URLs used by your frontend for Lethe.

Parameters:process_uri – a function that accepts a single string argument and returns a URI to use instead of the argument, or None to not change the URIs
template = None

Template name for HTML fragment documenting the format. None for undocumented formats.

text = None

The unformatted text. Don’t change it. (This is an instance attribute, not a class attribute.)

to_html()

Return a markupsafe.Markup instance containing the text in HTML markup.

to_text()

Return a plain text approximation of the text as a Unicode string.

The base implementation extracts text from the HTML representation of the document.

verify()

Verify markup syntax.

Returns:a list of syntax errors found (as human-readable strings) or an empty list if the markup is correct
class lethe.format.FormatRegistry

Keep content type to Format implementation mapping.

add_default_formats()

Register all formats declared in modules of the lethe.ext.format package.

add_format(format_class)

Register the specified Format subclass.

Raises TypeError:
 if format_class doesn’t have a string in the Format.content_type attribute
content_types()

Return a sequence of pairs of content type and human-readable name.

get_format(content_type)

Return a Format subclass handling the specified content_type.

Raises KeyError:
 when there is no format handling the content_type
lethe.format.get_format = <bound method FormatRegistry.get_format of <lethe.format.FormatRegistry object at 0x4526e50>>

FormatRegistry.get_format for the default registry providing all lethe.ext.format extensions.

lethe.format.content_types = <bound method FormatRegistry.content_types of <lethe.format.FormatRegistry object at 0x4526e50>>

FormatRegistry.content_types for the default registry providing all lethe.ext.format extensions.

Supported formats

lethe.ext.format.markdown: text/x-markdown
Markdown, parsed via the Python-Markdown package
lethe.ext.format.plain: text/plain
preformatted text, put in the <pre> HTML element

Table Of Contents

Previous topic

lethe.index – Relational data index

Next topic

lethe.node_import – Import nodes from other sources

This Page