A fast parser for reStructuredText
Project description
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 style='-'> 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,
}]
Available diagnostic codes:
block.blank_line
: Warns on missing blank lines between syntax blocks.block.title_line
: Warns on issues with title under/over lines.block.title_disallowed
: Warns on unexpected titles in a context where they are not allowed.block.paragraph_indentation
: Warns on unexpected indentation of a paragraph line.block.literal_no_content
: Warns on literal blocks with no content.block.target_malformed
: Warns on malformed hyperlink targets.block.substitution_malformed
: Warns on malformed substitution definition.block.table_malformed
: Warns on malformed tables.block.inconsistent_title_level
: Warns on inconsistent title levels, e.g. a level 1 title style followed by a level 3 style.
Command line usage
There is also a simple CLI for linting reStructuredText stdin/files:
echo "- a\n1. b" | python -m rst_fast_parse.cli.lint --print-ast -
<bullet_list> 0-0
<list_item> 0-0
<paragraph> 0-0
<enum_list> 1-1
<list_item> 1-1
<paragraph> 1-1
<stdin>:0: Blank line expected after Bullet list [block.blank_line]
Found 1 error.
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.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distribution
Hashes for rst_fast_parse-0.0.14-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4a9728d138f4144b1d9182ee1e189acf3be889f387a103690a4868a4c0614051 |
|
MD5 | 7344b51e51c523008e0ba1d8db6d8691 |
|
BLAKE2b-256 | 9d15a8da0994bb2afceaa6582f509e7474c09955bd72c8ec3ffe627a20a2c3b8 |