Parser

Some helpers around docutils parser to easily parse reStructuredText markup with some options.

Note

This module try to load the pygment directive if available, so you don’t need to load it from your code if you want to use Pygment to highlight code blocks.

class rstview.parser.RstBasicRenderer(*args, **kwargs)[source]

Bases: object

Basic interface around docutils to parse and render reStructuredText markup.

This follows the legacy behaviors of docutils parser, that means:

  • Parser errors and warnings are inserted inside the rendered source;
  • Errors and warnings are pushed to the standard output;

Example

1
2
3
4
>>> from rstview.parser import RstBasicRenderer
>>> renderer = RstBasicRenderer()
>>> renderer.parse("Lorem **ipsum** salace")
<p>Lorem <strong>ipsum</strong> salace</p>
get_options(name, initial_header_level=None, silent=False)[source]

Load the given configuration and possibly update parameters with given keyword arguments.

Parameters:

name (string) – Configuration name from registered configurations.

Keyword Arguments:
 
  • initial_header (int) – To modify option initial_header_level.
  • silent (string) – If True, will push the parser reporter level to the lowest verbosiy so errors and warnings are ignored. Default value is the same as settings.RSTVIEW_PARSER_SILENT.
Returns:

Options to give to Docutils parser.

Return type:

dict

get_writer_option()[source]

Get the writer option for parser config depending it’s html4 or html5.

Returns:A dict containing the right writer option name and value.
Return type:dict
parse(source, setting_key='default', body_only=True, **kwargs)[source]

Parse reStructuredText source with given options.

Parameters:
  • source (string) – reStructuredText source to parse.
  • **kwargs – Arbitrary keyword arguments to give as options to RstBasicRenderer.get_options().
Keyword Arguments:
 
  • setting_key (string) – Configuration name from registered configurations.
  • body_only (string) – If True, parser will only return the rendered content else it will return the full dict from Docutils parser. This dict contains many datas about parsing. Default is True.
Returns:

Depending from body_only, it will be a rendered content as a string or a dict containing datas about parsing (rendered content, styles, messages, title, etc..).

Return type:

string or dict

class rstview.parser.RstExtendedRenderer(*args, **kwargs)[source]

Bases: rstview.parser.RstBasicRenderer

Extended interface for next generation usage.

This promotes some extended behaviors:

  • Parser can be used to validate markup out of rendered document;
  • Nothing is printed out on standard output;

docutils parser is a bit touchy to use programatically, so we need to apply some monkey patchs before and after parsing.

Example

1
2
3
4
5
6
7
8
>>> from rstview.parser import RstExtendedRenderer
>>> renderer = RstExtendedRenderer()
>>> renderer.parse("Lorem **ipsum** salace")
<p>Lorem <strong>ipsum</strong> salace</p>
>>> rendered.is_valid()
True
>>> rendered.get_messages()
[]
format_parsing_error(error)[source]

Format error message datas to a message line.

Parameters:error (tuple) – Message error returned by reporter contain four elements: line number, error code and message.
Returns:Formatted message.
Return type:string
get_messages()[source]

Get a list of formatted messages

Returns:A list of messages.
is_valid()[source]

Only to be used after parsing

Returns:True if no errors, else False
Return type:bool
parse(*args, **kwargs)[source]

Proceed to parsing for validation

We apply monkey patchs on two docutils methods, parse source then unmonkey.

Everytime validation is processed, messages are reseted so it should be safe enough to use the RstExtendedRenderer instance for many documents.

Once done you can access raw error messages datas from instance attribute messages or use RstExtendedRenderer.get_messages to have formatted message lines.

Returns:Depending from body_only, it will be a rendered content as a string or a dict containing datas about parsing (rendered content, styles, messages, title, etc..).
Return type:string or dict
rstview.parser.build_output(source, output_filepath, **kwargs)[source]

Very basic shortcut helper to build a file from rendered reStructuredText source.

Parameters:
  • source (string) – reStructuredText source to parse and render.
  • output_filepath (string) – File path where to write rendered source.
  • **kwargs – Arbitrary keyword arguments to give as options to rstview.parser.SourceParser.