Python Parsing Hook

• GitHub: https://github.com/acaos/python-parsinghook
• PyPI: https://pypi.org/project/parsinghook/

This package adds support for easily adding parsing hooks to Python, using a special comment at or near the top of a file.

Usage

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).

Technical Information

Parsing Hooks

Operation

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.

Existing Parsing Hooks

Known existing parsing hooks include:

• parsinghook.dumpast (from this package)
• pep505

Modifying the Wheel / Installing from Source

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.

Future Development

Parser Options

In the future, the parsing comment might be updated to support optional arguments to parsers, e.g.:

# -*- parsing: parsinghook.dumpast colorize=True -*-

Mutators

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.

Thanks and Credits

This package stands on the shoulders of giants.

The parsinghook.hook.activate() function is based on André Roberge's ideas package.