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/CAMF8tS11x1mOFZdJaS%3Dpyvk-EzqVacJNq1DcmYv1FNf%2BTQnVrQ%40mail.gmail.com.
