tessl/pypi-mistune

A sane and fast Markdown parser with useful plugins and renderers

—

Pending

Overview

Eval results

Files

Core Parsing

Name: tessl/pypi-mistune
Author: tessl

Main parsing functionality that forms the foundation of mistune's Markdown processing. Provides factory functions for creating parsers, the main Markdown class for custom parsing workflows, and a pre-configured HTML parser for common use cases.

Capabilities

Factory Functions

Functions for creating configured Markdown parser instances with specific renderers, plugins, and options.

def create_markdown(
    escape: bool = True,
    hard_wrap: bool = False,
    renderer: Optional[RendererRef] = "html", 
    plugins: Optional[Iterable[PluginRef]] = None
) -> Markdown:
    """
    Create a Markdown instance based on the given condition.
    
    Parameters:
    - escape: Boolean. If using html renderer, escape html.
    - hard_wrap: Boolean. Break every new line into <br>.
    - renderer: renderer instance, default is HTMLRenderer. Can be "html", "ast", or BaseRenderer instance.
    - plugins: List of plugins to use.
    
    Returns:
    Configured Markdown instance for reuse.
    """

Usage example:

import mistune

# Create parser with custom configuration
md = mistune.create_markdown(
    escape=False,
    hard_wrap=True,
    renderer='html',
    plugins=['table', 'footnotes', 'strikethrough']
)

# Reuse the parser instance
html1 = md('# Heading 1')
html2 = md('**Bold text**')

Convenience Function

High-level function for one-off parsing with caching for performance optimization.

def markdown(
    text: str,
    escape: bool = True,
    renderer: Optional[RendererRef] = "html",
    plugins: Optional[Iterable[Any]] = None
) -> Union[str, List[Dict[str, Any]]]:
    """
    Parse markdown text with caching for performance.
    
    Parameters:
    - text: Markdown text to parse
    - escape: Boolean. If using html renderer, escape html.
    - renderer: renderer instance, default is HTMLRenderer. Can be "html", "ast", or BaseRenderer instance.
    - plugins: List of plugins to use.
    
    Returns:
    Parsed result as string (HTML/RST) or list of tokens (AST).
    """

Usage example:

import mistune

# Simple HTML parsing
html = mistune.markdown('# Hello **World**')
# Output: '<h1>Hello <strong>World</strong></h1>\n'

# Parse to AST
ast = mistune.markdown('**bold**', renderer='ast')
# Output: [{'type': 'paragraph', 'children': [{'type': 'strong', 'children': [{'type': 'text', 'raw': 'bold'}]}]}]

# With plugins
html = mistune.markdown('~~strikethrough~~', plugins=['strikethrough'])

Pre-configured Parser

Ready-to-use HTML parser instance with common plugins enabled for immediate use.

html: Markdown
# Pre-configured Markdown instance with HTMLRenderer and plugins: 
# ["strikethrough", "footnotes", "table", "speedup"]

Usage example:

import mistune

# Use pre-configured parser directly
result = mistune.html('''
# Table Example

| Name | Age |
|------|-----|
| John | 25  |
| Jane | 30  |

Text with ~~strikethrough~~.
''')

Markdown Class

Main parser class that orchestrates the parsing process, coordinating block parsing, inline parsing, rendering, and plugin execution.

class Markdown:
    """
    Markdown instance to convert Markdown text into HTML or other formats.
    
    Attributes:
    - renderer: Optional[BaseRenderer] - Output renderer
    - block: BlockParser - Block-level parser  
    - inline: InlineParser - Inline-level parser
    - before_parse_hooks: List[Callable] - Hooks executed before parsing
    - before_render_hooks: List[Callable] - Hooks executed before rendering  
    - after_render_hooks: List[Callable] - Hooks executed after rendering
    """
    
    def __init__(
        self,
        renderer: Optional[BaseRenderer] = None,
        block: Optional[BlockParser] = None, 
        inline: Optional[InlineParser] = None,
        plugins: Optional[Iterable[Plugin]] = None
    ):
        """
        Initialize Markdown parser.
        
        Parameters:
        - renderer: A renderer to convert parsed tokens
        - block: Block level syntax parser
        - inline: Inline level syntax parser  
        - plugins: Mistune plugins to use
        """
    
    def __call__(self, text: str) -> Union[str, List[Dict[str, Any]]]:
        """
        Parse Markdown text and return rendered output.
        
        Parameters:
        - text: Markdown text to parse
        
        Returns:
        Rendered output (string for renderers, token list for AST)
        """
    
    def parse(self, text: str) -> Tuple[Union[str, List[Dict[str, Any]]], BlockState]:
        """
        Parse Markdown text and return both output and state.
        
        Parameters:
        - text: Markdown text to parse
        
        Returns:
        Tuple of (rendered_output, final_block_state)
        """
    
    def read(self, filepath: str, encoding: str = "utf-8", state: Optional[BlockState] = None) -> Tuple[Union[str, List[Dict[str, Any]]], BlockState]:
        """
        Read and parse Markdown file.
        
        Parameters:
        - filepath: Path to Markdown file to read
        - encoding: File encoding (default: utf-8)
        - state: Optional BlockState to use
        
        Returns:
        Tuple of (rendered_output, final_block_state)
        """
    
    def use(self, plugin: Plugin) -> None:
        """
        Use a plugin to extend parser functionality.
        
        Parameters:
        - plugin: Plugin to add to this parser
        """

Usage example:

from mistune import Markdown, HTMLRenderer, BlockParser, InlineParser

# Create custom parser instance
renderer = HTMLRenderer(escape=False)
block = BlockParser()
inline = InlineParser(hard_wrap=True)

md = Markdown(renderer=renderer, block=block, inline=inline)

# Parse text
result = md('# Hello\n\nThis is **bold**.')

# Parse with state access  
output, state = md.parse('# Heading\n\nParagraph text.')
print(f"Tokens: {state.tokens}")
print(f"Environment: {state.env}")

Hook System

The Markdown class provides a hook system for extending functionality at different stages of processing:

# Hook types available on Markdown instances
before_parse_hooks: List[Callable[[Markdown, BlockState], None]]
before_render_hooks: List[Callable[[Markdown, BlockState], Any]]  
after_render_hooks: List[Callable[[Markdown, Union[str, List[Dict]], BlockState], Union[str, List[Dict]]]]

Usage example:

def custom_hook(md, state):
    print(f"Processing {len(state.tokens)} tokens")

md = mistune.create_markdown()
md.before_render_hooks.append(custom_hook)
result = md('# Example text')

Install with Tessl CLI