ENB: PR #4576 removes all confusion between wrappers and widgets

[Edward K. Ream]

PR #4576 is a milestone in Leo's code base:

- It completely replaces the dreaded "Wrapper" annotation with concrete annotations.

- It resolves many "Widget" annotations to more specific and concrete annotations.

- The remaining "Widget" annotations seem natural:

  They describe args that can range over a wide variety of actual gui widgets.

I completed this PR in just two days. The workflow was remarkably straightforward:

- I changed annotations one at a time, then ran mypy and other tests.

- When in doubt, I traced the annotated value to see what its class was.

This workflow highlighted several places where various wrapper classes could be simplified. Afaik, I made only one botch. Eating my own dog food quickly revealed my mistake.

Summary

For at least ten years, I have wanted to resolve the confusion between Leo's wrapper and widget classes. This PR succeeds beyond my fondest hopes.

This PR must be tested thoroughly. I plan to merge the PR only after releasing Leo 6.8.8, coming in about 10 days. I welcome all comments and suggestions.

Edward

[jkn]

I like the sound of this!

[Edward K. Ream]

On Tuesday, March 31, 2026 at 2:46:50 PM UTC-5 jkn wrote:

I like the sound of this!

I'm glad you like it :-) I've spent most of today revising annotations and adding runtime checkers.

Some generic Widget annotations remain. They are just an alias for Any. I'm not sure they can all be removed, but I'm working on it.

Today's work featured new g.checkWidget, g.checkTextWidget, and g.checkClass functions. They test the ground truth (the live widgets) not the annotations (which are not necessarily correct!) Each new checker verifies that the objects have the expected types. Early implementations are hacks, but they are revealing nevertheless.

The PR now calls one of the checkers in each method containing a widget-based annotation. In essence, the checkers are ever-present unit tests. 

There is no rush to complete the PR: I'll release it after Leo 6.8.8 goes out the door. But already the PR reveals patterns that I never expected to see.

Edward

[Edward K. Ream]

On Tuesday, March 31, 2026 at 4:01:09 PM UTC-5 Edward K. Ream wrote:

> Some generic Widget annotations remain. They are just an alias for Any. I'm not sure they can all be removed, but I'm working on it.

Last night, while talking to Rebecca, I had a head-slapping moment. Doh, neither annotations nor mypy existed when I created Leo so many years ago. So how did I design Leo so it could support multiple guis? The answer, Leo's core interacts with the body pane via the so-called high-level interface. I had forgotten that the StringTextWrapper embodies that interface.

In short, annotations in Leo's core should use StringTextWrapper instead of QTextEditWrapper! Annotations involving Leo's Qt gui should continue to use  QTextEditWrapper.

Early this morning I made this change. It had to be made in one go, so it was a bit nerve-wracking, but it worked. 

There are six places where the annotation is StringTextWrapper | QTextEditWrapper. All seem reasonable.

> Today's work featured new g.checkWidget, g.checkTextWidget, and g.checkClass functions.

And now these functions can be made more specific, with the addition of a new g.checkQTextWidget function.

Do you see? g.checkTextWidget should be able to warn if the following "assertion" fails:

isinstance(w, StringTextWrapper) or issubclass(w, StringTextWrapper)

That's not so easy to do directly in mypy annotations! And there will be a similar check in g.checkQTextWidget.

Summary

Today's work is a milestone in Leo's codebase. For the first time ever, Leo's annotations reveal the design principle behind Leo's widget classes.

I now have more leverage in resolving the remaining Widget (Any) annotations. The g.check* functions can now be made stronger.

Edward

P.S. mypy continues to be one of my favorite tools. I might tell the mypy devs (once again) how much I enjoy their work.

EKR

[Edward K. Ream]

On Wednesday, April 1, 2026 at 7:40:07 AM UTC-5 Edward K. Ream wrote:

> Today's work is a milestone in Leo's codebase. For the first time ever, Leo's annotations reveal the design principle behind Leo's widget classes.

Not quite yet :-) Yesterday's work revealed several problems.

I'll soon add new g.check methods and new kinds of annotations.

And OMG: I had forgotten about info issue #1585.

I'll say more later--it's the middle of the night here. 

Edward