348 lines
13 KiB
Python
348 lines
13 KiB
Python
|
# CodeHilite Extension for Python-Markdown
|
||
|
|
# ========================================
|
||
|
|
|
||
|
|
# Adds code/syntax highlighting to standard Python-Markdown code blocks.
|
||
|
|
|
||
|
|
# See https://Python-Markdown.github.io/extensions/code_hilite
|
||
|
|
# for documentation.
|
||
|
|
|
||
|
|
# Original code Copyright 2006-2008 [Waylan Limberg](http://achinghead.com/).
|
||
|
|
|
||
|
|
# All changes Copyright 2008-2014 The Python Markdown Project
|
||
|
|
|
||
|
|
# License: [BSD](https://opensource.org/licenses/bsd-license.php)
|
||
|
|
|
||
|
|
"""
|
||
|
|
Adds code/syntax highlighting to standard Python-Markdown code blocks.
|
||
|
|
|
||
|
|
See the [documentation](https://Python-Markdown.github.io/extensions/code_hilite)
|
||
|
|
for details.
|
||
|
|
"""
|
||
|
|
|
||
|
|
from __future__ import annotations
|
||
|
|
|
||
|
|
from . import Extension
|
||
|
|
from ..treeprocessors import Treeprocessor
|
||
|
|
from ..util import parseBoolValue
|
||
|
|
from typing import TYPE_CHECKING, Callable, Any
|
||
|
|
|
||
|
|
if TYPE_CHECKING: # pragma: no cover
|
||
|
|
import xml.etree.ElementTree as etree
|
||
|
|
|
||
|
|
try: # pragma: no cover
|
||
|
|
from pygments import highlight
|
||
|
|
from pygments.lexers import get_lexer_by_name, guess_lexer
|
||
|
|
from pygments.formatters import get_formatter_by_name
|
||
|
|
from pygments.util import ClassNotFound
|
||
|
|
pygments = True
|
||
|
|
except ImportError: # pragma: no cover
|
||
|
|
pygments = False
|
||
|
|
|
||
|
|
|
||
|
|
def parse_hl_lines(expr: str) -> list[int]:
|
||
|
|
"""Support our syntax for emphasizing certain lines of code.
|
||
|
|
|
||
|
|
`expr` should be like '1 2' to emphasize lines 1 and 2 of a code block.
|
||
|
|
Returns a list of integers, the line numbers to emphasize.
|
||
|
|
"""
|
||
|
|
if not expr:
|
||
|
|
return []
|
||
|
|
|
||
|
|
try:
|
||
|
|
return list(map(int, expr.split()))
|
||
|
|
except ValueError: # pragma: no cover
|
||
|
|
return []
|
||
|
|
|
||
|
|
|
||
|
|
# ------------------ The Main CodeHilite Class ----------------------
|
||
|
|
class CodeHilite:
|
||
|
|
"""
|
||
|
|
Determine language of source code, and pass it on to the Pygments highlighter.
|
||
|
|
|
||
|
|
Usage:
|
||
|
|
|
||
|
|
```python
|
||
|
|
code = CodeHilite(src=some_code, lang='python')
|
||
|
|
html = code.hilite()
|
||
|
|
```
|
||
|
|
|
||
|
|
Arguments:
|
||
|
|
src: Source string or any object with a `.readline` attribute.
|
||
|
|
|
||
|
|
Keyword arguments:
|
||
|
|
lang (str): String name of Pygments lexer to use for highlighting. Default: `None`.
|
||
|
|
guess_lang (bool): Auto-detect which lexer to use.
|
||
|
|
Ignored if `lang` is set to a valid value. Default: `True`.
|
||
|
|
use_pygments (bool): Pass code to Pygments for code highlighting. If `False`, the code is
|
||
|
|
instead wrapped for highlighting by a JavaScript library. Default: `True`.
|
||
|
|
pygments_formatter (str): The name of a Pygments formatter or a formatter class used for
|
||
|
|
highlighting the code blocks. Default: `html`.
|
||
|
|
linenums (bool): An alias to Pygments `linenos` formatter option. Default: `None`.
|
||
|
|
css_class (str): An alias to Pygments `cssclass` formatter option. Default: 'codehilite'.
|
||
|
|
lang_prefix (str): Prefix prepended to the language. Default: "language-".
|
||
|
|
|
||
|
|
Other Options:
|
||
|
|
|
||
|
|
Any other options are accepted and passed on to the lexer and formatter. Therefore,
|
||
|
|
valid options include any options which are accepted by the `html` formatter or
|
||
|
|
whichever lexer the code's language uses. Note that most lexers do not have any
|
||
|
|
options. However, a few have very useful options, such as PHP's `startinline` option.
|
||
|
|
Any invalid options are ignored without error.
|
||
|
|
|
||
|
|
* **Formatter options**: <https://pygments.org/docs/formatters/#HtmlFormatter>
|
||
|
|
* **Lexer Options**: <https://pygments.org/docs/lexers/>
|
||
|
|
|
||
|
|
Additionally, when Pygments is enabled, the code's language is passed to the
|
||
|
|
formatter as an extra option `lang_str`, whose value being `{lang_prefix}{lang}`.
|
||
|
|
This option has no effect to the Pygments' builtin formatters.
|
||
|
|
|
||
|
|
Advanced Usage:
|
||
|
|
|
||
|
|
```python
|
||
|
|
code = CodeHilite(
|
||
|
|
src = some_code,
|
||
|
|
lang = 'php',
|
||
|
|
startinline = True, # Lexer option. Snippet does not start with `<?php`.
|
||
|
|
linenostart = 42, # Formatter option. Snippet starts on line 42.
|
||
|
|
hl_lines = [45, 49, 50], # Formatter option. Highlight lines 45, 49, and 50.
|
||
|
|
linenos = 'inline' # Formatter option. Avoid alignment problems.
|
||
|
|
)
|
||
|
|
html = code.hilite()
|
||
|
|
```
|
||
|
|
|
||
|
|
"""
|
||
|
|
|
||
|
|
def __init__(self, src: str, **options):
|
||
|
|
self.src = src
|
||
|
|
self.lang: str | None = options.pop('lang', None)
|
||
|
|
self.guess_lang: bool = options.pop('guess_lang', True)
|
||
|
|
self.use_pygments: bool = options.pop('use_pygments', True)
|
||
|
|
self.lang_prefix: str = options.pop('lang_prefix', 'language-')
|
||
|
|
self.pygments_formatter: str | Callable = options.pop('pygments_formatter', 'html')
|
||
|
|
|
||
|
|
if 'linenos' not in options:
|
||
|
|
options['linenos'] = options.pop('linenums', None)
|
||
|
|
if 'cssclass' not in options:
|
||
|
|
options['cssclass'] = options.pop('css_class', 'codehilite')
|
||
|
|
if 'wrapcode' not in options:
|
||
|
|
# Override Pygments default
|
||
|
|
options['wrapcode'] = True
|
||
|
|
# Disallow use of `full` option
|
||
|
|
options['full'] = False
|
||
|
|
|
||
|
|
self.options = options
|
||
|
|
|
||
|
|
def hilite(self, shebang: bool = True) -> str:
|
||
|
|
"""
|
||
|
|
Pass code to the [Pygments](https://pygments.org/) highlighter with
|
||
|
|
optional line numbers. The output should then be styled with CSS to
|
||
|
|
your liking. No styles are applied by default - only styling hooks
|
||
|
|
(i.e.: `<span class="k">`).
|
||
|
|
|
||
|
|
returns : A string of html.
|
||
|
|
|
||
|
|
"""
|
||
|
|
|
||
|
|
self.src = self.src.strip('\n')
|
||
|
|
|
||
|
|
if self.lang is None and shebang:
|
||
|
|
self._parseHeader()
|
||
|
|
|
||
|
|
if pygments and self.use_pygments:
|
||
|
|
try:
|
||
|
|
lexer = get_lexer_by_name(self.lang, **self.options)
|
||
|
|
except ValueError:
|
||
|
|
try:
|
||
|
|
if self.guess_lang:
|
||
|
|
lexer = guess_lexer(self.src, **self.options)
|
||
|
|
else:
|
||
|
|
lexer = get_lexer_by_name('text', **self.options)
|
||
|
|
except ValueError: # pragma: no cover
|
||
|
|
lexer = get_lexer_by_name('text', **self.options)
|
||
|
|
if not self.lang:
|
||
|
|
# Use the guessed lexer's language instead
|
||
|
|
self.lang = lexer.aliases[0]
|
||
|
|
lang_str = f'{self.lang_prefix}{self.lang}'
|
||
|
|
if isinstance(self.pygments_formatter, str):
|
||
|
|
try:
|
||
|
|
formatter = get_formatter_by_name(self.pygments_formatter, **self.options)
|
||
|
|
except ClassNotFound:
|
||
|
|
formatter = get_formatter_by_name('html', **self.options)
|
||
|
|
else:
|
||
|
|
formatter = self.pygments_formatter(lang_str=lang_str, **self.options)
|
||
|
|
return highlight(self.src, lexer, formatter)
|
||
|
|
else:
|
||
|
|
# just escape and build markup usable by JavaScript highlighting libraries
|
||
|
|
txt = self.src.replace('&', '&')
|
||
|
|
txt = txt.replace('<', '<')
|
||
|
|
txt = txt.replace('>', '>')
|
||
|
|
txt = txt.replace('"', '"')
|
||
|
|
classes = []
|
||
|
|
if self.lang:
|
||
|
|
classes.append('{}{}'.format(self.lang_prefix, self.lang))
|
||
|
|
if self.options['linenos']:
|
||
|
|
classes.append('linenums')
|
||
|
|
class_str = ''
|
||
|
|
if classes:
|
||
|
|
class_str = ' class="{}"'.format(' '.join(classes))
|
||
|
|
return '<pre class="{}"><code{}>{}\n</code></pre>\n'.format(
|
||
|
|
self.options['cssclass'],
|
||
|
|
class_str,
|
||
|
|
txt
|
||
|
|
)
|
||
|
|
|
||
|
|
def _parseHeader(self) -> None:
|
||
|
|
"""
|
||
|
|
Determines language of a code block from shebang line and whether the
|
||
|
|
said line should be removed or left in place. If the shebang line
|
||
|
|
contains a path (even a single /) then it is assumed to be a real
|
||
|
|
shebang line and left alone. However, if no path is given
|
||
|
|
(e.i.: `#!python` or `:::python`) then it is assumed to be a mock shebang
|
||
|
|
for language identification of a code fragment and removed from the
|
||
|
|
code block prior to processing for code highlighting. When a mock
|
||
|
|
shebang (e.i: `#!python`) is found, line numbering is turned on. When
|
||
|
|
colons are found in place of a shebang (e.i.: `:::python`), line
|
||
|
|
numbering is left in the current state - off by default.
|
||
|
|
|
||
|
|
Also parses optional list of highlight lines, like:
|
||
|
|
|
||
|
|
:::python hl_lines="1 3"
|
||
|
|
"""
|
||
|
|
|
||
|
|
import re
|
||
|
|
|
||
|
|
# split text into lines
|
||
|
|
lines = self.src.split("\n")
|
||
|
|
# pull first line to examine
|
||
|
|
fl = lines.pop(0)
|
||
|
|
|
||
|
|
c = re.compile(r'''
|
||
|
|
(?:(?:^::+)|(?P<shebang>^[#]!)) # Shebang or 2 or more colons
|
||
|
|
(?P<path>(?:/\w+)*[/ ])? # Zero or 1 path
|
||
|
|
(?P<lang>[\w#.+-]*) # The language
|
||
|
|
\s* # Arbitrary whitespace
|
||
|
|
# Optional highlight lines, single- or double-quote-delimited
|
||
|
|
(hl_lines=(?P<quot>"|')(?P<hl_lines>.*?)(?P=quot))?
|
||
|
|
''', re.VERBOSE)
|
||
|
|
# search first line for shebang
|
||
|
|
m = c.search(fl)
|
||
|
|
if m:
|
||
|
|
# we have a match
|
||
|
|
try:
|
||
|
|
self.lang = m.group('lang').lower()
|
||
|
|
except IndexError: # pragma: no cover
|
||
|
|
self.lang = None
|
||
|
|
if m.group('path'):
|
||
|
|
# path exists - restore first line
|
||
|
|
lines.insert(0, fl)
|
||
|
|
if self.options['linenos'] is None and m.group('shebang'):
|
||
|
|
# Overridable and Shebang exists - use line numbers
|
||
|
|
self.options['linenos'] = True
|
||
|
|
|
||
|
|
self.options['hl_lines'] = parse_hl_lines(m.group('hl_lines'))
|
||
|
|
else:
|
||
|
|
# No match
|
||
|
|
lines.insert(0, fl)
|
||
|
|
|
||
|
|
self.src = "\n".join(lines).strip("\n")
|
||
|
|
|
||
|
|
|
||
|
|
# ------------------ The Markdown Extension -------------------------------
|
||
|
|
|
||
|
|
|
||
|
|
class HiliteTreeprocessor(Treeprocessor):
|
||
|
|
""" Highlight source code in code blocks. """
|
||
|
|
|
||
|
|
config: dict[str, Any]
|
||
|
|
|
||
|
|
def code_unescape(self, text: str) -> str:
|
||
|
|
"""Unescape code."""
|
||
|
|
text = text.replace("<", "<")
|
||
|
|
text = text.replace(">", ">")
|
||
|
|
# Escaped '&' should be replaced at the end to avoid
|
||
|
|
# conflicting with < and >.
|
||
|
|
text = text.replace("&", "&")
|
||
|
|
return text
|
||
|
|
|
||
|
|
def run(self, root: etree.Element) -> None:
|
||
|
|
""" Find code blocks and store in `htmlStash`. """
|
||
|
|
blocks = root.iter('pre')
|
||
|
|
for block in blocks:
|
||
|
|
if len(block) == 1 and block[0].tag == 'code':
|
||
|
|
local_config = self.config.copy()
|
||
|
|
text = block[0].text
|
||
|
|
if text is None:
|
||
|
|
continue
|
||
|
|
code = CodeHilite(
|
||
|
|
self.code_unescape(text),
|
||
|
|
tab_length=self.md.tab_length,
|
||
|
|
style=local_config.pop('pygments_style', 'default'),
|
||
|
|
**local_config
|
||
|
|
)
|
||
|
|
placeholder = self.md.htmlStash.store(code.hilite())
|
||
|
|
# Clear code block in `etree` instance
|
||
|
|
block.clear()
|
||
|
|
# Change to `p` element which will later
|
||
|
|
# be removed when inserting raw html
|
||
|
|
block.tag = 'p'
|
||
|
|
block.text = placeholder
|
||
|
|
|
||
|
|
|
||
|
|
class CodeHiliteExtension(Extension):
|
||
|
|
""" Add source code highlighting to markdown code blocks. """
|
||
|
|
|
||
|
|
def __init__(self, **kwargs):
|
||
|
|
# define default configs
|
||
|
|
self.config = {
|
||
|
|
'linenums': [
|
||
|
|
None, "Use lines numbers. True|table|inline=yes, False=no, None=auto. Default: `None`."
|
||
|
|
],
|
||
|
|
'guess_lang': [
|
||
|
|
True, "Automatic language detection - Default: `True`."
|
||
|
|
],
|
||
|
|
'css_class': [
|
||
|
|
"codehilite", "Set class name for wrapper <div> - Default: `codehilite`."
|
||
|
|
],
|
||
|
|
'pygments_style': [
|
||
|
|
'default', 'Pygments HTML Formatter Style (Colorscheme). Default: `default`.'
|
||
|
|
],
|
||
|
|
'noclasses': [
|
||
|
|
False, 'Use inline styles instead of CSS classes - Default `False`.'
|
||
|
|
],
|
||
|
|
'use_pygments': [
|
||
|
|
True, 'Highlight code blocks with pygments. Disable if using a JavaScript library. Default: `True`.'
|
||
|
|
],
|
||
|
|
'lang_prefix': [
|
||
|
|
'language-', 'Prefix prepended to the language when `use_pygments` is false. Default: `language-`.'
|
||
|
|
],
|
||
|
|
'pygments_formatter': [
|
||
|
|
'html', 'Use a specific formatter for Pygments highlighting. Default: `html`.'
|
||
|
|
],
|
||
|
|
}
|
||
|
|
""" Default configuration options. """
|
||
|
|
|
||
|
|
for key, value in kwargs.items():
|
||
|
|
if key in self.config:
|
||
|
|
self.setConfig(key, value)
|
||
|
|
else:
|
||
|
|
# manually set unknown keywords.
|
||
|
|
if isinstance(value, str):
|
||
|
|
try:
|
||
|
|
# Attempt to parse `str` as a boolean value
|
||
|
|
value = parseBoolValue(value, preserve_none=True)
|
||
|
|
except ValueError:
|
||
|
|
pass # Assume it's not a boolean value. Use as-is.
|
||
|
|
self.config[key] = [value, '']
|
||
|
|
|
||
|
|
def extendMarkdown(self, md):
|
||
|
|
""" Add `HilitePostprocessor` to Markdown instance. """
|
||
|
|
hiliter = HiliteTreeprocessor(md)
|
||
|
|
hiliter.config = self.getConfigs()
|
||
|
|
md.treeprocessors.register(hiliter, 'hilite', 30)
|
||
|
|
|
||
|
|
md.registerExtension(self)
|
||
|
|
|
||
|
|
|
||
|
|
def makeExtension(**kwargs): # pragma: no cover
|
||
|
|
return CodeHiliteExtension(**kwargs)
|