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 assettings.RSTVIEW_PARSER_SILENT
.
Returns: Options to give to Docutils parser.
Return type: dict
- initial_header (int) – To modify option
-
get_writer_option
()[source]¶ Get the writer option for parser config depending it’s
html4
orhtml5
.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 isTrue
.
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
-
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 useRstExtendedRenderer.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
.