rst-fast-parse 0.0.12

A fast parser for reStructuredText

rst_fast_parse

A fast parser for reStructuredText.

This parser is NOT (at least for now) intended to be a full replacement for the docutils/sphinx rST parser. The initial goal is to parse the "outline" of a reStructuredText document, without knowing any information about the roles / directives that are available, into a structure that can be used for things like Language Servers, to provide quick information (as opposed to having to wait for a full sphinx build).

Features:

• Fault tolerant parsing, designed to never raise an exception
• Concrete syntax tokens with full source mapping
• Diagnostics for common issues
• Functional design, with separate functions for each block element
• Fully typed with "strict" mypy settings

Incremental parsing and formatting is also planned.

Usage

To parse a string, use the parse_string function.

from rst_fast_parse import parse_string

elements, diagnostics = parse_string("""
Hello
-----
world!
""")
assert elements.debug_repr() == """\
<title_underline> 1-2
<paragraph> 3-3
"""

Diagnostics are returned for any issues found during parsing.

from rst_fast_parse import parse_string

elements, diagnostics = parse_string("""
- list
no blank line
""")
assert elements.debug_repr() == """\
<bullet_list> 1-1
  <list_item> 1-1
    <paragraph> 1-1
<paragraph> 2-2
"""
assert [d.as_dict() for d in diagnostics] == [{
    'code': 'block.blank_line',
    'message': 'Blank line expected after Bullet list',
    'line_start': 1,
}]

Design decisions

The parse does not automatically nest sections, based on title underline styles, like docutils. This allows for incremental parsing, as well as a simpler design.