The new wax_off script is a great success

[Edward K. Ream]

The script is in the leo/scripts folder. The script creates stub files from existing annotations, then removes all function annotations.

wax_off.py is a stand-alone script, not a Leo script.

This script turns the mypy development process on its head. Instead of creating stub files with stubgen or make_stub_files, you can now add mypy annotations directly in your source files (in a separate branch, naturally). Working only with the original sources is much more convenient than tweaking stub files.

When you are done, you can use wax_off.py to "move" the clutter from def lines to stub files. So you can get the benefits of mypy with minimal clutter. In most cases, the remaining "clutter" (annotations of var types) turns out to be excellent documentation.

As a result, both the stubgen or make_stub_files projects are practically obsolete.

Note that mypy will look in the same directory as the .py file to find the corresponding stub (.pyi) file. Leo's core folder now contains two stubs: leoAst.pyi and leoNodes.pyi.

Tweaking the stub files

The wax_off script knows very little about python. wax_off is a pattern matcher.

Most importantly, wax_off moves def lines (and class lines) to the stub file with the existing indentation (leading white space). As a result, mypy may complain about syntax errors in the stub file:

1. If a class (like an exception class) has no methods, the class line should be followed by '...', but wax_off doesn't add the '...'. You must do that yourself.

2. If a function/method contains an inner def, mypy will also complain. I just commented out those inner defs. They aren't needed anyway: mypy handles local attributes very well.

Summary

The wax_off script allows devs to add full annotations for functions and methods directly in the source files themselves. When mypy is happy, you just run wax_off to move the def lines into stub files. wax_off then "declutters" the def lines.

The result is the best of all approaches. It's easy to add annotations, and it's easy to remove them.

All questions and comments welcome.

Edward