Spaces:
Sleeping
Sleeping
| # 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) | |