Discuss: Always write Black-compatible sentinels

[Edward K. Ream]

Issue #3657 suggests that Leo should always write black-compatible sentinel lines. Leo would no longer need the --black-sentinels command line option.

This post discusses this proposal and asks for your comments.

Background

Black adds a space between the # and @ at the start of Leo's sentinel comments, treating such comments according to the PEP8 guidelines for inline comments.

As a result, Black will continually reformat Leo's external files unless the --black-sentinels command line option was in effect when Leo wrote the external files.

The Black devs do not appear interested in treating Leo's sentinels as exceptions!

Compatibility

For at least the last several years, Leo has been able to read external files containing "blackened" comments. I know of no significant compatibility issues.

Summary

Like it or not, Black is the de-facto standard for formatting Python programs. The Ruff Format tool emulates Black's operation.

Imo, Leo should always write Black-compatible sentinels. Doing so will remove a reason for not using Leo! 

Leonine projects (including Leo!) will notice large diffs when Leo converts sentinel comments to the Black-compatible format. These diffs are a one-time cost of this proposal.

Afaik, this proposal has no other negative consequences.

Your comments, please.

Edward

[Thomas Passin]

My main reaction is to make sure that Leo's read behavior remains backwards compatible with the pre-black sentinel format. People with much older outlines should be able to open them for the indefinite future.  It's also possible that there is some user code that does something with sentinels and assumes there will be no space after the leading '#' character.  So perhaps the  --black-sentinels command line option should remain in reverse:  --black-sentinels=False  would be allowed but not be the default .

With this proviso, the proposal seems sensible.

[Edward K. Ream]

On Sat, Nov 25, 2023 at 7:58 PM Thomas Passin <tbp1...@gmail.com> wrote:

My main reaction is to make sure that Leo's read behavior remains backwards compatible with the pre-black sentinel format. People with much older outlines should be able to open them for the indefinite future.

All recent versions of Leo can read legacy and blackened sentinels.

It's also possible that there is some user code that does something with sentinels and assumes there will be no space after the leading '#' character.  So perhaps the  --black-sentinels command line option should remain in reverse:  --black-sentinels=False  would be allowed but not be the default .

The usual convention would be to create a --no-black-sentinels option. However, I see no need for this option. The --black-sentinels options could have broken existing code, but nobody has complained.

Summary

- There is no need to retain --black-sentinels.
- There is no need for --no-black-sentinels.
- The only likely downsides are the initial diffs.

Edward

[Edward K. Ream]

On Saturday, November 25, 2023 at 7:58:40 PM Thomas wrote:

My main reaction is to make sure that Leo's read behavior remains backwards compatible with the pre-black sentinel format.

Thanks for the continued reminders :-)

The release notes for Leo 6.7.6 will mention possible breaking changes to Leo's API, probably with a link to a more thorough discussion.

You are correct. Changing the format of Leo's sentinels could affect existing scripts or plugins. The release notes should acknowledge that possibility.

Similarly, PR #3645 has the following to-do item: "Discuss all changes to Leo's API, breaking, non-breaking, significant or not."  All those API changes will appear in the more thorough discussion.

As always, there is a tension between simplifying the code (making it easier to maintain) and stability. Imo, none of the changes contemplated for Leo 6.7.6 will cause widespread consternation, but it's always good to acknowledge possible sources of trouble.

Edward

[Edward K. Ream]

Eleven days ago I wrote the following:

> Issue #3657 suggests that Leo should always write black-compatible sentinel lines.

> Leo would no longer need the --black-sentinels command line option.

I've changed my mind. Leo will continue to support the --black-sentinels command-line option.

This option affects only Leo's write code, but  PR #3678 will improve the corresponding read code.

Aha:  there is little need for blackened sentinels!

Those using Leo in an environment that mandates Black formatting are likely using @clean or @auto to avoid using sentinels.

I prefer Orange (Leo's formatter) to Black when formatting Leo's sources. Compatibility with Black is not an issue!

Summary

Few Leonistas will likely ever use the --black-sentinels command-line option, but there is no reason to remove it.

Mandating Black-compatible sentinels would be a blunder.

PR #3678 will make Leo's read code more robust.

Edward