all2md.utils.escape

Format-specific text escaping utilities.

This module provides escape functions for various markup formats to ensure special characters are properly handled in rendered output.

all2md.utils.escape.escape_asciidoc(text: str) → str

Escape special AsciiDoc characters in text content.

AsciiDoc has many special characters that need escaping when they appear in regular text content to prevent unintended formatting.

Parameters:: text (str) – Text to escape
Returns:: Escaped text safe for AsciiDoc
Return type:: str

Examples

>>> escape_asciidoc("Text with [brackets] and *stars*")
'Text with \\[brackets\\] and \\*stars\\*'

all2md.utils.escape.escape_asciidoc_attribute(text: str) → str

Escape text for use in AsciiDoc attribute values.

Attribute values have additional escaping requirements beyond regular text content.

Parameters:: text (str) – Text to escape for attribute value
Returns:: Escaped text safe for AsciiDoc attributes
Return type:: str

Examples

>>> escape_asciidoc_attribute('Title: A "Special" Document')
'Title: A \\"Special\\" Document'

all2md.utils.escape.escape_rst(text: str) → str

Escape special reStructuredText characters.

RST uses backslash escaping for its special characters.

Parameters:: text (str) – Text to escape
Returns:: Escaped text safe for RST
Return type:: str

Examples

>>> escape_rst("Text with *emphasis* and `code`")
'Text with \\*emphasis\\* and \\`code\\`'

all2md.utils.escape.escape_markdown_context_aware(text: str, context: str = 'text') → str

Escape markdown with context awareness.

Different contexts require different escaping strategies.

Parameters:

text (str) – Text to escape
context ({'text', 'table', 'link', 'image_alt'}, default = 'text') – Context where text will be used

Returns:

Escaped text

Return type:

str

Examples

>>> escape_markdown_context_aware("Text with [brackets]", "text")
'Text with \\[brackets\\]'
>>> escape_markdown_context_aware("Cell | with | pipes", "table")
'Cell \\| with \\| pipes'

all2md.utils.escape.escape_inline_code(code: str, delimiter: str = '`') → tuple[str, str]

Escape inline code and determine appropriate delimiter.

Handles cases where code contains the delimiter character by using a longer delimiter sequence or different delimiter.

Parameters:

code (str) – Code content to escape
delimiter (str, default = '`') – Preferred delimiter character

Returns:

(escaped_code, delimiter_to_use)

Return type:

tuple[str, str]

Examples

>>> escape_inline_code("simple code", "`")
('simple code', '`')
>>> escape_inline_code("code with ` backtick", "`")
('code with ` backtick', '``')

all2md.utils.escape.escape_mediawiki(text: str) → str

Escape special MediaWiki characters (minimal/experimental implementation).

WARNING: This is a minimal implementation. MediaWiki markup has complex escaping rules, and this function currently performs no actual escaping.

MediaWiki is generally lenient with special characters in plain text contexts. The main characters that can cause formatting issues are: - ‘’ (two apostrophes) for italic - ‘’’ (three apostrophes) for bold - [[ and ]] for links - {{ and }} for templates

However, in most plain text contexts (like within <code> tags or table cells), MediaWiki handles these gracefully without explicit escaping.

Parameters:: text (str) – Text to escape
Returns:: Text (currently unchanged - passes through as-is)
Return type:: str

Examples

>>> escape_mediawiki("Text with ''quotes''")
"Text with ''quotes''"
>>> escape_mediawiki("Normal text")
'Normal text'

Notes

This function is marked as experimental because: - MediaWiki’s escaping rules are context-dependent - Most text renders correctly without escaping in the contexts where this is used - Full escaping would require <nowiki> tags, which may not be appropriate in all contexts

If you need robust MediaWiki escaping, consider using <nowiki> tags explicitly or HTML entities for special characters.

all2md.utils.escape.escape_dokuwiki(text: str, context: str = 'text') → str

Escape special DokuWiki characters in text content.

DokuWiki uses several special character sequences for formatting. This function escapes them to prevent unintended formatting.

Parameters:

text (str) – Text to escape
context ({'text', 'table', 'link', 'code'}, default = 'text') – Context where text will be used. Different contexts have different escaping requirements: - ‘text’: Regular paragraph text (escape all special sequences) - ‘table’: Table cell content (escape | and ^ additionally) - ‘link’: Link text or URL (escape brackets) - ‘code’: Code context (minimal escaping, preserve literal characters)

Returns:

Escaped text safe for DokuWiki rendering

Return type:

str

Examples

Escape formatting characters:

>>> escape_dokuwiki("Text with **bold** and //italic//")
'Text with \\*\\*bold\\*\\* and \\/\\/italic\\/\\/'

Table context:

>>> escape_dokuwiki("Cell | with | pipes", context="table")
'Cell \\| with \\| pipes'

Code context (minimal escaping):

>>> escape_dokuwiki("code_example()", context="code")
'code_example()'

Notes

DokuWiki special sequences that need escaping: - ** for bold - // for italic - __ for underline - ‘’ for monospace (two single quotes) - [[ and ]] for links - {{ and }} for images - \\ for line breaks (four backslashes in source become two in display) - | and ^ for tables - \ at end of line for forced line break

In DokuWiki, backslash is used as the escape character. To display a literal special character, prefix it with backslash.

all2md.utils.escape.escape_html_entities(text: str) → str

Escape HTML special characters to entities.

Used when embedding text in HTML contexts. This function uses Python’s built-in html.escape() for standard HTML5 entity encoding.

Parameters:: text (str) – Text to escape
Returns:: Text with HTML entities
Return type:: str

Examples

>>> escape_html_entities("<script>alert('XSS')</script>")
'&lt;script&gt;alert(&#x27;XSS&#x27;)&lt;/script&gt;'

Notes

This function escapes the following characters: - & -> & - < -> < - > -> > - “ -> " - ‘ -> ' (HTML5 standard)