tessl/pypi-python-creole
A pure Python markup converter supporting creole2html, html2creole, html2ReSt, and html2textile conversions
—
core-conversions.mddocs/
Core Conversion Functions
The primary markup conversion functions that handle transformation between Creole, HTML, ReStructuredText, and Textile formats. These functions provide the main interface for python-creole and handle the most common conversion scenarios with sensible defaults.
Capabilities
Creole to HTML Conversion
Convert Creole markup to HTML with support for macros, custom block rules, and different line break modes.
def creole2html(markup_string: str, debug: bool = False,
parser_kwargs: dict = None, emitter_kwargs: dict = None,
block_rules: tuple = None, blog_line_breaks: bool = True,
macros: dict = None, verbose: int = None, stderr = None,
strict: bool = False) -> strParameters:
markup_string: Creole markup text to convertdebug: Enable debug output for parser and emitterparser_kwargs: Additional parser configuration (deprecated)emitter_kwargs: Additional emitter configuration (deprecated)block_rules: Custom block-level parsing rulesblog_line_breaks: Use blog-style line breaks (True) vs wiki-style (False)macros: Dictionary of macro functions for extending markupverbose: Verbosity level for outputstderr: Error output streamstrict: Enable strict Creole 1.0 compliance mode
Returns: HTML string
Usage Examples:
from creole import creole2html
# Basic conversion
html = creole2html("This is **bold** text")
# Returns: '<p>This is <strong>bold</strong> text</p>'
# With macros
macros = {'code': lambda ext, text: f'<pre><code class="{ext}">{text}</code></pre>'}
html = creole2html('<<code ext="python">>\nprint("hello")\n<</code>>', macros=macros)
# With custom image sizing (non-standard extension)
html = creole2html('{{image.jpg|Alt text|90x120}}')
# Returns: '<p><img src="image.jpg" title="Alt text" alt="Alt text" width="90" height="120" /></p>'
# Strict mode (standard Creole only)
html = creole2html('{{image.jpg|Alt text|90x120}}', strict=True)
# Returns: '<p><img src="image.jpg" title="Alt text|90x120" alt="Alt text|90x120" /></p>'HTML to Creole Conversion
Convert HTML markup back to Creole format with configurable handling of unknown tags and strict compliance options.
def html2creole(html_string: str, debug: bool = False,
parser_kwargs: dict = None, emitter_kwargs: dict = None,
unknown_emit = None, strict: bool = False) -> strParameters:
html_string: HTML markup to convertdebug: Enable debug outputparser_kwargs: Additional parser configuration (deprecated)emitter_kwargs: Additional emitter configuration (deprecated)unknown_emit: Handler function for unknown HTML tagsstrict: Enable strict Creole output mode
Returns: Creole markup string
Usage Examples:
from creole import html2creole
from creole.shared.unknown_tags import transparent_unknown_nodes
# Basic conversion
creole = html2creole('<p>This is <strong>bold</strong> text</p>')
# Returns: 'This is **bold** text'
# Handle unknown tags transparently
creole = html2creole('<p>Text with <unknown>content</unknown></p>',
unknown_emit=transparent_unknown_nodes)
# Returns: 'Text with content'
# Convert complex HTML structures
html = '''
<h1>Heading</h1>
<ul>
<li>Item 1</li>
<li>Item 2</li>
</ul>
<p>Paragraph with <a href="http://example.com">link</a></p>
'''
creole = html2creole(html)
# Returns: '= Heading =\n\n* Item 1\n* Item 2\n\nParagraph with [[http://example.com|link]]'HTML to ReStructuredText Conversion
Convert HTML to ReStructuredText markup for documentation systems and Sphinx integration.
def html2rest(html_string: str, debug: bool = False,
parser_kwargs: dict = None, emitter_kwargs: dict = None,
unknown_emit = None) -> strParameters:
html_string: HTML markup to convertdebug: Enable debug outputparser_kwargs: Additional parser configuration (deprecated)emitter_kwargs: Additional emitter configuration (deprecated)unknown_emit: Handler function for unknown HTML tags
Returns: ReStructuredText markup string
Usage Examples:
from creole import html2rest
# Basic conversion
rest = html2rest('<p>This is <strong>bold</strong> and <em>italic</em> text</p>')
# Returns: 'This is **bold** and *italic* text'
# Convert headings and lists
html = '''
<h1>Main Title</h1>
<h2>Subtitle</h2>
<ul>
<li>First item</li>
<li>Second item</li>
</ul>
<p>Link to <a href="https://example.com">example</a></p>
'''
rest = html2rest(html)
# Returns ReStructuredText with proper heading underlines and reference linksHTML to Textile Conversion
Convert HTML to Textile markup format.
def html2textile(html_string: str, debug: bool = False,
parser_kwargs: dict = None, emitter_kwargs: dict = None,
unknown_emit = None) -> strParameters:
html_string: HTML markup to convertdebug: Enable debug outputparser_kwargs: Additional parser configuration (deprecated)emitter_kwargs: Additional emitter configuration (deprecated)unknown_emit: Handler function for unknown HTML tags
Returns: Textile markup string
Usage Examples:
from creole import html2textile
# Basic conversion
textile = html2textile('<p>This is <strong>bold</strong> and <i>italic</i> text</p>')
# Returns: 'This is *bold* and __italic__ text'
# Convert links and formatting
html = '<p>Visit <a href="http://example.com">example site</a> for more <em>information</em></p>'
textile = html2textile(html)
# Returns: 'Visit "example site":http://example.com for more __information__'HTML Document Tree Parsing
Low-level function to parse HTML into document tree structure for advanced processing.
def parse_html(html_string: str, debug: bool = False) -> DocNodeParameters:
html_string: HTML markup to parsedebug: Enable debug output
Returns: Document tree root node
Usage Examples:
from creole import parse_html
# Parse HTML into document tree
html = '<p>Hello <strong>world</strong></p>'
doc_tree = parse_html(html)
# Access document structure
if debug:
doc_tree.debug() # Print tree structureError Handling
All conversion functions accept Unicode strings and will raise AssertionError if non-Unicode input is provided. For HTML parsing errors or malformed markup, the functions attempt graceful degradation rather than raising exceptions.
Unknown HTML tags are handled according to the unknown_emit parameter:
None(default): Remove unknown tags, keep contentraise_unknown_node: Raise exception on unknown tagstransparent_unknown_nodes: Pass through content onlyescape_unknown_nodes: Escape the tags as text- Custom function: Provide your own handling logic
Install with Tessl CLI
npx tessl i tessl/pypi-python-creole