GitLocker: The Coding Marketplace

Description:

comprehemd 1.0.0

🤔 CompreheMD
CompreheMD is a Python package for parsing Markdown documents.

Installation
MarkdownParser class

Parsing a stream
Parsing chunks

Blocks classes

Block
CodeBlock
EmptyBlock
HeadingBlock

Project

Contributing
Licence
Author
Acknowledgements

Installation
CompreheMD requires Python 3.8 or later.
Install CompreheMD via pip:
pip install comprehemd

MarkdownParser class
Parsing a stream
The Markdown document parsed in this example is example.md.
To read an entire text stream, call read(). The method yields blocks until the stream ends.
from comprehemd import MarkdownParser

with open("docs/example.md", "r") as fp:
for block in MarkdownParser().read(fp):
print(block)

HeadingBlock (1): An Example Document
EmptyBlock
HeadingBlock (2): Introduction
EmptyBlock
Block: This is just a short example document.
EmptyBlock
HeadingBlock (2): Block examples
EmptyBlock
Block: Here's some backtick-fenced code:
EmptyBlock
CodeBlock (python): print("Hello, world!")
EmptyBlock
Block: Here's some tilde-fenced code:
EmptyBlock
CodeBlock (python): print("Hello, galaxy!")
EmptyBlock
Block: Here's some indented code:
EmptyBlock
CodeBlock (<None>): print("Hello, multiverse!")
EmptyBlock
Block: That's your lot!

Parsing chunks
The parser can be fed ad-hoc chunks of Markdown. The feed() method yields all the blocks that the chunk completed.
After feeding the final chunk, you must call close() to flush and yield any buffered blocks.
from comprehemd import CodeBlock, HeadingBlock, MarkdownParser

def tease(chunk: str) -> None:
escaped = chunk.replace("\n", "\\n")
for block in parser.feed(chunk):
print(f'After "{escaped}", the parser yielded:')
print(block)
print()
else:
print(f'After "{escaped}", the parser did not yield.')
print()

parser = MarkdownParser()

tease("# Feeding exam")
tease("ple\n\nThis de")
tease("monstrates chu")
tease("nked feeding.")

for block in parser.close():
print("After closing, the parser yielded:")
print(block)
print()

After "# Feeding exam", the parser did not yield.

After "ple\n\nThis de", the parser yielded:
HeadingBlock (1): Feeding example

After "ple\n\nThis de", the parser yielded:
EmptyBlock

After "ple\n\nThis de", the parser did not yield.

After "monstrates chu", the parser did not yield.

After "nked feeding.", the parser did not yield.

After closing, the parser yielded:
Block: This demonstrates chunked feeding.

Blocks classes
Block
The Block class is the base of all blocks.

source returns the original Markdown source for the block.
text returns the meaningful text representation of the block.

CodeBlock
The CodeBlock class represents a code block.

language returns the language hint if one was specified.
The block can be rendered back to Markdown by calling render().

EmptyBlock
EmptyBlock represents an empty line.
HeadingBlock
The HeadingBlock class represents a heading.

level returns the heading's level (i.e. 1 for the top-most heading, down to 6 for the lowest).

Project
Contributing
To contribute a bug report, enhancement or feature request, please raise an issue at github.com/cariad/comprehemd/issues.
If you want to contribute a code change, please raise an issue first so we can chat about the direction you want to take.
Licence
CompreheMD is released at github.com/cariad/comprehemd under the MIT Licence.
See LICENSE for more information.
Author
Hello! 👋 I'm Cariad Eccleston and I'm a freelance DevOps and backend engineer. My contact details are available on my personal wiki at cariad.earth.
Please consider supporting my open source projects by sponsoring me on GitHub.
Acknowledgements

Epic ❤️ to John Gruber for developing the original Markdown specification.
This documentation was pressed by Edition.