My two main concerns are 1. Older versions of Leo will be able to read the new files; 2. If Ruff isn't installed or doesn't work (e.g., wrong binary version for Linux?), Leo will still work and be able to read/write external files properly. I mean, beautifying is essentially an optional tweak that has no operational value. So Leo ought to be usable without it. (And yes, I am fairly particular about how my code looks on a page).
On Friday, January 9, 2026 at 9:54:30 AM UTC-5 Edward K. Ream wrote: > On Thu, Jan 8, 2026 at 9:25 PM Thomas Passin <[email protected]> wrote: > > I don't understand. You wrote that it changes the sentinels. We can't >> have that. So which is it? Not changed or changed? And why have another >> dependency if it's not absolutely needed? Will there be a fallback if >> Ruff/Rust isn't installed? How long did the current beautifier take to >> beautify Leo's code base? How long for ruff format? If the difference is >> only a few seconds, it's probably not worth it. >> > > Thanks for your comments, Thomas. Your questions and concerns are valid. > The PR changes virtually every one of Leo's files, so it's worth discussing > why any of those changes are worthwhile. > > My initial posting did not cover many of the nuances, partly because I > wasn't aware of some of them. The motivation for the PR follows. > > *Compatibility* > > Leo has been able to read "blackened" *Python* sentinel comments for at > least several years. Such sentinels start with # @ instead of #@. In > other words, blackened sentinels have exactly one space between the comment > delimiter (#) and the sentinel marker (@). This space is the *only* > difference > between blackened sentinels and Leo's legacy sentinels. > > The PR changes *nothing* about how Leo reads sentinels. The *only *question > is whether Leo will *write *blackened sentinels for Python files. That's > all the PR changes. Previously, Leo wrote legacy sentinels by default. The > -b, and --black-sentinels command-line options would cause Leo to write > blackened sentinels. Again, only for Python files. > > How should Leo *write *sentinels by default? The --black-sentinels > command-line option isn't optimal. Instead, a new setting, say > @bool write-legacy-python-sentinels, will allow each outline to pick the > default operation. The default (in leoSettings.leo) for this setting will > be True, but leoPyRef.leo will specify using blackened sentinels. > > In short, most users will see no change at all. However, *Leo's own code > base* will use blackened sentinels. Furthermore, users will have more > flexibility in choosing which of their external Python files will use > blackened sentinels. The next section explains why these choices matter. > > *Why ruff format should replace Leo's beautify commands* > > The short answer is the ruff format (the speedy version of black) does a > *much* better job of formatting Python code than Leo's homespun beautify > commands. The difference is shocking. And it's more than a bit embarrassing > that Leo's beautifier produces different results than does black. > > I agree that the speed of the beautifier isn't paramount, but ruff format > beats Leo's beautifier all ends up. It's shocking how much more convenient > automatic formatting is. In contrast, Leo's beautifier only adjusts > inter-token whitespace. That's not good enough. But to get the benefits of > better formatting, users *must* accept blackened sentinels. > > And there is one more important point to make. Leo's beautifier is > token-based. It will probably break (or produce suboptimal results) > whenever Python adds any new kind of token. This has happened in the past > whenever Python adds a new kind of statement. It may well happen in the > future. The present PR will preserve Leo's beautifier commands, but a later > PR should remove them. Removing those commands will reduce the > maintenance burden for future Leo devs, including myself. I'm really tired > of tracking new Python language features. > > *Summary* > > Leo has been able to *read *blackened sentinels for several years. The PR > does not change any of the underlying machinery. > > Similarly, Leo's users have been able to choose whether Leo will write > blackened sentinels via a command-line argument. The PR will remove that > command-line argument in favor of a more flexible user setting. The default > will be to write legacy sentinels. > > I strongly prefer using ruff format to beautify Leo's code, but that's > only possible for external files containing blackened sentinels. The > advantages of using ruff format to beautify Leo's code are overwhelming. > How did I ever live with the old way? > > Finally, the PR changes almost all of Leo's files, but ruff format made > most of the changes automatically. The PR will discuss all changes that I > made by hand. In other words, the PR isn't as scary as it looks. > > Edward > -- You received this message because you are subscribed to the Google Groups "leo-editor" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To view this discussion visit https://groups.google.com/d/msgid/leo-editor/be951a83-dcb8-4122-b8eb-904c9367c28cn%40googlegroups.com.
