1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
|
=======
Plugins
=======
If you want to extend Pygments without hacking the sources, but want to
use the lexer/formatter/style/filter lookup functions (`lexers.get_lexer_by_name`
et al.), you can use `setuptools`_ entrypoints to add new lexers, formatters
or styles as if they were in the Pygments core.
.. _setuptools: https://pypi.org/project/setuptools/
That means you can use your highlighter modules with the `pygmentize` script,
which relies on the mentioned functions.
Plugin discovery
================
At runtime, discovering plugins is preferentially done using Python's
standard library module `importlib.metadata`_, available in Python 3.8
and higher. In earlier Python versions, Pygments attempts to use the
`importlib_metadata`_ backport, if available. If not available, a
fallback is attempted on the older `pkg_resources`_ module. Finally, if
``pkg_resources`` is not available, no plugins will be loaded at
all. Note that ``pkg_resources`` is distributed with `setuptools`_, and
thus available on most Python environments. However, ``pkg_resources``
is considerably slower than ``importlib.metadata`` or its
``importlib_metadata`` backport. For this reason, if you run Pygments
under Python older than 3.8, it is recommended to install
``importlib-metadata``. Pygments defines a ``plugins`` packaging extra,
so you can ensure it is installed with best plugin support (i.e., that
``importlib-metadata`` is also installed in case you are running Python
earlier than 3.8) by specifying ``pygments[plugins]`` as the
requirement, for example, with ``pip``:
.. sourcecode:: shell
$ python -m pip install --user pygments[plugins]
.. _importlib.metadata: https://docs.python.org/3.10/library/importlib.metadata.html
.. _importlib_metadata: https://pypi.org/project/importlib-metadata
.. _pkg_resources: https://setuptools.pypa.io/en/latest/pkg_resources.html
Defining plugins through entrypoints
====================================
Here is a list of setuptools entrypoints that Pygments understands:
`pygments.lexers`
This entrypoint is used for adding new lexers to the Pygments core.
The name of the entrypoint values doesn't really matter, Pygments extracts
required metadata from the class definition:
.. sourcecode:: ini
[pygments.lexers]
yourlexer = yourmodule:YourLexer
Note that you have to define ``name``, ``aliases`` and ``filename``
attributes so that you can use the highlighter from the command line:
.. sourcecode:: python
class YourLexer(...):
name = 'Name Of Your Lexer'
aliases = ['alias']
filenames = ['*.ext']
`pygments.formatters`
You can use this entrypoint to add new formatters to Pygments. The
name of an entrypoint item is the name of the formatter. If you
prefix the name with a slash it's used as a filename pattern:
.. sourcecode:: ini
[pygments.formatters]
yourformatter = yourmodule:YourFormatter
/.ext = yourmodule:YourFormatter
`pygments.styles`
To add a new style you can use this entrypoint. The name of the entrypoint
is the name of the style:
.. sourcecode:: ini
[pygments.styles]
yourstyle = yourmodule:YourStyle
`pygments.filters`
Use this entrypoint to register a new filter. The name of the
entrypoint is the name of the filter:
.. sourcecode:: ini
[pygments.filters]
yourfilter = yourmodule:YourFilter
How To Use Entrypoints
======================
This documentation doesn't explain how to use those entrypoints because this is
covered in the `setuptools documentation`_. That page should cover everything
you need to write a plugin.
.. _setuptools documentation: https://setuptools.readthedocs.io/en/latest/
Extending The Core
==================
If you have written a Pygments plugin that is open source, please inform us
about that. There is a high chance that we'll add it to the Pygments
distribution.
|
