为何安装后Pygments无法识别自定义Lexer？

一、遗漏的关键步骤及修复方法 #

1. 修正pyproject.toml的entry points配置格式 #

你当前的pyproject.toml采用了setup.cfg的配置格式，在pyproject.toml规范中，需要将Pygments lexer注册到project.entry-points分组下，正确配置如下：

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

[project]
name = "my-lexer"
version = "0.0.1"
dependencies = ["Pygments"]

[project.entry-points."pygments.lexers"]
dummy = "pkg.mylexer:MyLexer"

2. 验证包结构与Lexer实现 #

• 确保pkg是合法的Python包：目录下建议保留__init__.py（Python 3.3+可省略，但兼容性推荐添加），且pkg/mylexer.py中MyLexer正确继承自pygments.lexers.RegexLexer或pygments.lexers.Lexer，并实现了核心的tokens属性（或get_tokens_unprocessed方法）。
• 示例Lexer结构参考：

from pygments.lexer import RegexLexer
from pygments.token import *

class MyLexer(RegexLexer):
    name = 'Dummy'
    aliases = ['dummy']
    filenames = ['*.dummy']

    tokens = {
        'root': [
            (r'#.*', Comment.Single),
            (r'\d+', Number),
            (r'[a-zA-Z_]\w*', Name),
            (r'\s+', Text),
        ]
    }

3. 重新构建并强制安装 #

修改配置后，执行以下命令重新构建安装，确保覆盖旧的无效安装：

python -m build --clean
pip install --force-reinstall dist/*.tar.gz

二、Pygments插件发现机制 #

• 触发时机：每次执行pygmentize命令（如-L、-l）或在代码中调用pygments.lexers.get_lexer_by_name()等查找方法时，都会触发插件发现流程。
• 发现流程：
  1. Pygments通过Python的importlib.metadata.entry_points()（旧版本使用pkg_resources.iter_entry_points()）扫描所有已安装包的entry points。
  2. 筛选出注册到pygments.lexers分组下的所有入口点，加载对应的Lexer类。
  3. 验证加载的类是否符合Pygments Lexer的接口规范，最终将合法的Lexer加入可用列表。

三、追踪插件发现过程的方法 #

• 检查entry points是否注册成功：运行以下命令查看已注册的Pygments lexers，确认你的dummy条目存在：

python -c "import importlib.metadata; print([ep.name for ep in importlib.metadata.entry_points().get('pygments.lexers', [])])"

• 查看安装后的entry points文件：找到你的包在site-packages中的.dist-info目录，查看entry_points.txt文件，确认包含如下内容：

[pygments.lexers]
dummy = pkg.mylexer:MyLexer

• 跟踪代码执行流程：使用Python的trace工具追踪pygmentize的执行，查看是否扫描到你的插件：

python -m trace -t $(which pygmentize) -L

• 断点调试：在Python代码中对pygments.lexers._iter_lexers函数设置断点，观察扫描到的entry points列表，定位是否有加载失败的情况。

内容的提问来源于stack exchange，提问作者biosbob