pygments.formatters plugin working together with a template
Project description
Pygments HTML Template -- pygments.formatter plugin
You can write a template for pygments HtmlFormatter with this package.
Template Example
<Pygmentshtmltemplate> <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(1)-->
<h1>${title}</h1> <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(2)-->
<ol class="${cssclass}"> <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(3)-->
<Line> <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(4)-->
<li _="${highlighted}" id="line-${lineno}" class="hll"><Tokens/></li> <!-- - - - - - - - - - - -(5)-->
<li id="line-${lineno}"><Tokens/></li> <!-- - - - - - - - - - - - - - - - - - - - - - - - - - -(6)-->
</Line>
<Tokens> <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -(7)-->
<code class="${token_class} init"><Token type="Name.Function" fullmatch="__init__"/></code> <!--(8)-->
<code class="${token_class}" title="${token_type}"><Token/></code> <!-- - - - - - - - - - - - -(9)-->
</Tokens>
</ol> <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - (10)-->
<p>${filename}</p> <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - (11)-->
</Pygmentshtmltemplate>
- (1): Must have a root node
Pygmentshtmltemplate
- The
.parsers.parse
function uses parserxml.sax.make_parser()
in the Python standard library. So the template must be able to read by the the SAX parser. You should not parse untrusted data.
- The
- (2), (3), (10), (11): Wrapping html parts
<Line>
(4) and<Tokens>
(7) block represent line formats and each token format in each code line.- In (2),
${title}
representstitle
option which is set to the formatter class. And that is replaced with its value.
- (5), (6): Select a line wrapper
- Each of
<Line>
(4) children represents a line format. Html elements can have options value for testing. If all values non-nil, then that line will be rendered.highlight
andlineno
are not the formatter class options, but implicitly generated fromlinenostart
andhl_lines
option.False
,None
, and empty Sequence are failed, but0
(zero) is success.- Properties which name starts with
_
are only used for testing, but they are not rendered. - The formatter tries the tests in textual order. The last line of the
<Line>
block should be always successful.
- Each of
- (8), (9): Select a token wrapper
- Html properties are the same as line’s.
token_class
andtoken_type
are not the formatter options.token_class
is generated byformatter._get_css_classes(ttype: pygments.token._TokenType)
.token_type
is generated by'.'.join(ttype: pygments.token._TokenType)
<Token>
(8) element can havetype
,match
, andfullmatch
properties for testing.- When Pygments gives the formatter a ‘tokentype’ and a ‘tokenvalue’, the formatter will test follows:
pygments.token.is_token_subtype(tokentype, pytments.token.string_to_tokentype(${type}))
re.fullmatch(${fullmatch}, tokenvalue)
orre.match(${match}, tokenvalue)
- When Pygments gives the formatter a ‘tokentype’ and a ‘tokenvalue’, the formatter will test follows:
- When all tests are failed, a ‘tokenvalue’ is rendered as it is.
- Html properties are the same as line’s.
Install
% pip install pygmentshtmltemplate
You can confirm pygments.formatters plugins:
>>> import importlib
>>> importlib.metadata.entry_points().select(group='pygments.formatters')
[EntryPoint(name='pygmentshtmltemplate', value='pygmentshtmltemplate:FormatterWithTemplate', group='pygments.formatters')]
Usage
FormatterWithTemplate
is the subclass of pygments.formatters.HtmlFormatter
. FormatterWithTemplate.name
is FormatterWithTemplate
, and FormatterWithTemplate.aliases
is ['fmtr_tmpl']
Formatter options
The options filename
, cssclass
, linenostart
, hl_lines
, classprefix
, and title
are in common spec with the HtmlFormatter
. Other options of the HtmlFormatter
are suppressed by the FormatterWithTemplate
. Almost other options may get alternatives by wrapping parts of a template.
There is the original option template
which is set to the path of a template file. If the template
isn’t set, the default template (the following code) is used.
<Pygmentshtmltemplate>
<ol class="${cssclass}">
<Line>
<li _="${highlighted}" class="hll"><Tokens/></li>
<li><Tokens/></li>
</Line>
<Tokens>
<code class="${token_class}"><Token/></code>
</Tokens>
</ol>
</Pygmentshtmltemplate>
Command line
The command line interface is provided by the Pygments. For example:
$ pygmentize -f fmtr_tmpl -O template=template.xml -o output.html want_to_highlight.py
$ pygmentize -f fmtr_tmpl -S default -a .highlight
In reStructuredText
You can use this formatter in the reStructuredText with docutils.
First, register the reST directive pygmentshtmltemplate.docutis.PygHtmlTmplRstDirective
. The target source code can be provided at that directive content block. Or using :file:
option, you can provide the source file.
from docutils.core import publish_string
from docutils.writers import html4css1
from docutils.parsers.rst import directives
from pygmentshtmltemplate.docutils import PygHtmlTmplRstDirective
directives.register_directive('fmtr-tmpl', PygHtmlTmplRstDirective)
ReST = f'''\
PygHtmlTmplRstDirective test
============================
pygmentize a file
.. fmtr-tmpl:: python :file: {__file__}
pygmentize a content block
.. fmtr-tmpl:: python
:hl_lines: 1
"""highlight this line"""
def hello(foo):
print(f'hello, {{foo}}!')
'''
if __name__ == '__main__':
formatted = publish_string(ReST, writer=html4css1.Writer())
with open(output, 'wb') as out:
out.write(formatted)
Future considered
- Template for the
full
option - Now, the
formatter.get_style_defs()
method corresponds to the only default template.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for pygmentshtmltemplate-0.1.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | cfce8d2d279432924ee8dc60536828f469d45afa5475af5d5280f53b058ef132 |
|
MD5 | 98f1002ebec66d71d24f650c66da14e7 |
|
BLAKE2b-256 | 7480f31dd85e00c01726a0e0aef8c603287870d33ef03a6082e42e9582369db1 |
Hashes for pygmentshtmltemplate-0.1.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5eb214b883c6b1f3582a7c9044f117d23502b9919d589b4a27f1733c981551c6 |
|
MD5 | 72d2c122646f8b949e1b50297c3c010b |
|
BLAKE2b-256 | d4c292c466ebe6a72d56fb6445aef04056fff772b2b6adec129171e6542d9361 |