Comments please: PR #4490 beautifies Leo with ruff format

[Edward K. Ream]

I created Leo's beautify commands to have more control over formatting. But now I've changed my mind. Leo should use ruff format, a super-fast version of black.

ruff format is faster, does a better (more standard) job of formatting, and is continually being improved. The only drawback is that ruff format changes all of Leo's sentinel comments. Imo, it's time to pay that one-time price.

The deciding factor was seeing that ruff format supports comment pragmas, # fmt: on, # fmt: off, and # fmt: skip, that simulate Leo's @beautify and @nobeautify directives.

PR #4490 contains the work.

Your comments, please.

Edward

[Thomas Passin]

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.

[Edward K. Ream]

On Thu, Jan 8, 2026 at 9:25 PM Thomas Passin <tbp1...@gmail.com> 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

[Thomas Passin]

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

[Edward K. Ream]

On Fri, Jan 9, 2026 at 11:49 AM Thomas Passin <tbp1...@gmail.com> wrote:

My two main concerns are 

1. Older versions of Leo will be able to read the new files;

All versions of Leo in the last several years will be able to read the files with blackened sentinels.

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.

Neither ruff nor black needs to be installed in order for Leo to read blackened sentinels. Leo alone is responsible for reading external files.

Edward

[Thomas Passin]

On Friday, January 9, 2026 at 1:56:49 PM UTC-5 Edward K. Ream wrote:

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.

Neither ruff nor black needs to be installed in order for Leo to read blackened sentinels. Leo alone is responsible for reading external files.

Great! Now I'm happy. 

[Edward K. Ream]

>> Neither ruff nor black needs to be installed in order for Leo to read blackened sentinels. Leo alone is responsible for reading external files.

> Great! Now I'm happy.

I'm glad to hear it. It's important that everyone understands and approves of the plan.

Edward