ENB: More about improving Leo's annotations

[Edward K. Ream]

This Engineering Notebook post explains:

- Why improving Leo's codebase is worth any temporary pain.

- My plans for future PRs.

Executive Summary

For the first time, full, correct annotations document large parts of Leo's programming API. 

Previously, Leo's naming conventions sufficed, but those conventions concealed many important details. Those details are now explicit.

Background

Recent PRs fully annotate, to mypy's satisfaction, the following modules:

PR1: #4767: leoNodes.py: Annotate p and v.

PR2: #4772: leoGlobals.py: Annotate g.

PR3: #4773: leoCommands.py: Annotate c.

PR4: #4779: leoApp.py and leoConfig.py: Annotate g.app and g.app.config.

Dangers

Any of these PRs could introduce subtle bugs. True, changing only annotations can not (by definition) change Leo's executable code. However, all these PRs do change executable code. Those changes were essential. Some merely quieted mypy complaints. Others fixed newly uncovered quirps or bugs.

Here are my present plans.

PR: Annotate all optional kwargs with the proper syntax.

An easy regex search/replace will convert annotations of the form:

  : x y = None to : x y | None = None

This PR will probably convert all of Leo's core, including core plugins.

PR: Convert tests on None to pythonic tests.

The first comment of issue #4780 gives a motivating example and discusses the subtleties. I won't repeat those comments here. Suffice it to say, this PR could easily introduce bugs. Extreme care will be needed.

This PR will convert string annotations like this:

  : s str = None to : s str = ''

This change is particularly fraught because it requires tests on None with the more pythonic tests:

   if s:

   if not s:

or, for non-strings x:

   if x:

   if not s:

Nevertheless, the benefits are huge. The new code will generalize Leo's API at the code level. Leo's codebase is not the API's only client! mypy simply cannot know about all Leonine scripts and plugins. The code-level changes will:

- Expand the values that scripts and plugins may use as arguments.

- Fail more quickly (and more clearly) for erroneous arguments.

Summary

The series of PRs improves annotations for increasing portions of Leo's API.

The changes to Leo's codebase are undoubtedly risky, but those risks are worth taking. Leo's API will accept more arguments and will fail more quickly (and clearly) for invalid arguments.

All of your questions, comments, and suggestions are welcome. Please keep testing!

Edward