This package adds support for easily adding parsing hooks to Python, using a special comment at or near the top of a file.
After this package has been installed, it is activated by placing the following at the top of any module you wish to use an alternate parser for:
# -*- parsing: <parsing-module> -*-Note that this will not work for code executed directly from the command
line (e.g. python3 foo.py), but will work if you execute the code as
a module (e.g. python3 -m foo).
When a parsing hook module is found, that module is imported, and the
parse_module() function in that module is invoked. The expected return
of the parse_module() function is an AST tree.
The parse_module() function MUST accept at least a file object and
filename string as arguments, and MUST also accept arbitrary keyword
arguments after those two arguments.
Known existing parsing hooks include:
- parsinghook.dumpast (from this package)
- pep505
Note that after using python3 -m build to build the wheel, it is necessary
to manually add the parsinghook.pth file to the wheel, with (for example):
cd src
zip -g ../dist/parsinghook-*-py3-none-any.whl parsinghook.pth
cd ..If installing from source, the src/parsinghook.pth file must be placed in your
site-packages directory.
In the future, the parsing comment might be updated to support optional
arguments to parsers, e.g.:
# -*- parsing: parsinghook.dumpast colorize=True -*-In the future, additional magic comments might be supported such as:
# -*- mutator: <mutation-module> -*-Which would allow other modules to modify the AST after the initial parsing.
This package stands on the shoulders of giants.
The parsinghook.hook.activate() function is based on André Roberge's
ideas package.