diff options
Diffstat (limited to 'doc/docs/plugins.rst')
| -rw-r--r-- | doc/docs/plugins.rst | 39 |
1 files changed, 34 insertions, 5 deletions
diff --git a/doc/docs/plugins.rst b/doc/docs/plugins.rst index 1008013a..67388607 100644 --- a/doc/docs/plugins.rst +++ b/doc/docs/plugins.rst @@ -1,6 +1,6 @@ -================ -Register Plugins -================ +======= +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` @@ -13,8 +13,37 @@ That means you can use your highlighter modules with the `pygmentize` script, which relies on the mentioned functions. -Entrypoints -=========== +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: |