tessl/pypi-python-creole
A pure Python markup converter supporting creole2html, html2creole, html2ReSt, and html2textile conversions
—
rest-tools.mddocs/
ReStructuredText Tools
Clean HTML generation from ReStructuredText markup with minimal formatting output. These tools are designed for documentation systems, web publishing, and PyPI package descriptions that require clean, semantic HTML without extra div elements or CSS classes.
Capabilities
Clean HTML Generation
Convert ReStructuredText to clean HTML output without extra formatting elements.
def rest2html(content: str, enable_exit_status: bool = None, **kwargs) -> strParameters:
content: ReStructuredText markup to convertenable_exit_status: Enable docutils exit status reporting**kwargs: Additional docutils settings overrides
Returns: Clean HTML string
Usage Examples:
from creole.rest_tools.clean_writer import rest2html
# Basic conversion
html = rest2html("This is **bold** text")
# Returns: '<p>This is <strong>bold</strong> text</p>\n'
# Convert bullet list
rest_content = """
- First item
- Second item
- Third item
"""
html = rest2html(rest_content)
# Returns: '<ul>\n<li>First item</li>\n<li>Second item</li>\n<li>Third item</li>\n</ul>\n'
# Convert with link
html = rest2html("A link to `Example <http://example.com>`_ site")
# Returns: '<p>A link to <a href="http://example.com">Example</a> site</p>\n'
# Convert headings
rest_content = """
Main Title
==========
Subtitle
--------
Content here.
"""
html = rest2html(rest_content)
# Returns clean HTML with h1, h2 tags and paragraphPyPI-Compatible ReStructuredText Processing
Process ReStructuredText with PyPI-compatible restrictions for package descriptions.
def pypi_rest2html(source: str, output_encoding: str = 'unicode') -> strParameters:
source: ReStructuredText source textoutput_encoding: Output encoding (default: 'unicode')
Returns: HTML string compatible with PyPI rendering
Usage Examples:
from creole.rest_tools.pypi_rest2html import pypi_rest2html
# Convert for PyPI compatibility
readme_rst = """
My Package
==========
This package does amazing things.
Features
--------
* Feature one
* Feature two
* Feature three
"""
html = pypi_rest2html(readme_rst)
# Returns HTML that matches PyPI's rendering rulesWriter Classes
Clean HTML Writer
Custom docutils writer that produces minimal HTML output.
class CleanHTMLWriter:
def __init__(self): ...
def write(self, document, destination): ...
class CleanHTMLTranslator:
def __init__(self, document): ...
def visit_document(self, node): ...
def depart_document(self, node): ...Usage Examples:
from creole.rest_tools.clean_writer import CleanHTMLWriter
from docutils.core import publish_parts
# Use custom writer directly
writer = CleanHTMLWriter()
parts = publish_parts(
source="**bold text**",
writer=writer,
settings_overrides={
"input_encoding": "unicode",
"doctitle_xform": False,
}
)
html = parts["html_body"]Configuration Options
The rest2html function accepts docutils configuration through keyword arguments:
# Disable file insertion for security
html = rest2html(content, file_insertion_enabled=False)
# Disable raw HTML for security
html = rest2html(content, raw_enabled=False)
# Custom settings
html = rest2html(content,
doctitle_xform=False,
initial_header_level=2,
report_level=2)Security Considerations
By default, rest2html disables potentially dangerous docutils features:
file_insertion_enabled=False: Prevents file inclusion directivesraw_enabled=False: Prevents raw HTML/LaTeX inclusion
These settings make it safe to process untrusted ReStructuredText content.
Error Handling
The function validates input as Unicode strings and will raise AssertionError for non-string input. Docutils parsing errors are handled according to the enable_exit_status parameter:
None(default): Suppress docutils exit statusTrue: Allow docutils to exit on severe errorsFalse: Convert errors to exceptions
For testing and validation, you can enable strict error reporting:
try:
html = rest2html(malformed_rst, enable_exit_status=True)
except SystemExit as e:
print(f"ReStructuredText error: exit code {e.code}")Install with Tessl CLI
npx tessl i tessl/pypi-python-creole