Adjustments for ST4

[FichteFoll]

Sublime Text 4 included a lot of changes relevant to us, notably the addition of a Python 3.8 plugin host (and later 3.13, potentially 3.14) and a couple changes to the API like making settings iterable.

Python 3.8

Compat/types

• Remove enum, pathlib, and typing from _compat and import the native versions instead. (f3c0e89)
• Possibly use from __future__ import annotations. (13f7637)
• Simplify/update some type annotations.

Other

• Make SettingsDict.update's other argument positional-only. (abbba87)

Sublime 4 API

Flags

New values for existing enums

• PopupOption: KEEP_ON_SELECTION_MODIFIED, HIDE_ON_CHARACTER_EVENT.
• OpenFileOption: ADD_TO_SELECTION, REPLACE_MRU, SEMI_TRANSIENT
• CompletionOptions: DYNAMIC_COMPLETIONS, INHIBIT_REORDER
• QuickPanelOption: WANT_EVENT

All enums have been deprecated in 2.1.

New enums

• CompletionFormat: TEXT, SNIPPET, COMMAND
• KindId: AMBIGUOUS, KEYWORD, TYPE, FUNCTION, NAMESPACE, NAVIGATION, MARKUP, VARIABLE, SNIPPET, COLOR_*
• Maybe one for the preconstructed kind tuples as well.
• SymbolSource: ANY, INDEX, OPEN_FILES
• SymbolType: ANY, DEFINITION, REFERENCE

We will not add new enums.

Syntax

• Reimplement list_syntaxes and get_syntax_for_scope using sublime.list_syntaxes and sublime.find_syntax_by_scope.
• Return sublime.Syntax instead of SyntaxInfo namedtuple.

Settings

• Implement methods requiring iterability. (Could there be performance concerns here?) (04a53ee)

Panels

• Reimplement Panel.exists() using View.element()?????

show_selection_panel

• Handle QuickPanelItem arguments.
• Add placeholder argument.
• Handle WANT_EVENT (i.e. make sure we pass the correct number of arguments in either case).

Ecosystem

• Create a dependency for Sublime type stubs and use it rather than bundling stubs here.
• Update UnitTesting if needed.

[Thom1729]

I went through the current API docs to produce a hopefully-complete list.

Details

Python 3.8

Compat/types

• Remove enum, pathlib, and typing from _compat and import the native versions instead.
• Simplify/update some type annotations. Possibly use from __future__ import annotations.

Other

• Make SettingsDict.update's other argument positional-only.

Sublime 4 API

Flags

New values for existing enums

• PopupOption: KEEP_ON_SELECTION_MODIFIED, HIDE_ON_CHARACTER_EVENT.
• OpenFileOption: ADD_TO_SELECTION, REPLACE_MRU, SEMI_TRANSIENT
• CompletionOptions: DYNAMIC_COMPLETIONS, INHIBIT_REORDER
• QuickPanelOption: WANT_EVENT

New enums

• CompletionFormat: TEXT, SNIPPET, COMMAND
• KindId: AMBIGUOUS, KEYWORD, TYPE, FUNCTION, NAMESPACE, NAVIGATION, MARKUP, VARIABLE, SNIPPET, COLOR_*
• Maybe one for the preconstructed kind tuples as well.
• SymbolSource: ANY, INDEX, OPEN_FILES
• SymbolType: ANY, DEFINITION, REFERENCE

Syntax

• Reimplement list_syntaxes and get_syntax_for_scope using sublime.list_syntaxes and sublime.find_syntax_by_scope.
• Return sublime.Syntax instead of SyntaxInfo namedtuple.

Settings

• Implement methods requiring iterability. (Could there be performance concerns here?)

Panels

• Reimplement Panel.exists() using View.element()?????

show_selection_panel

• Handle QuickPanelItem arguments.
• Add placeholder argument.
• Handle WANT_EVENT (i.e. make sure we pass the correct number of arguments in either case).

Ecosystem

• Create a dependency for Sublime type stubs and use it rather than bundling stubs here.
• Update UnitTesting if needed.

list was added to the OP for better tracking

[FichteFoll]

Feel free to edit my initial post with these and track them there.

[deathaxe]

Given all enum types are available natively as of ST4135, flags module is obsolete and just kept for backward compatibility reasons. Hence there's probably no need to add more enum types.

[deathaxe]

SettingsDict feels obsolete, too. With sublime.Settings.to_dict() being available, there's probably no point in extending SettingsDict any further. Maybe even mark it deprecated.

[FichteFoll]

One of the primary goals of SettingsDict was to enable the usage of ChainMap for dynamic setting fallbacks, which you can also achieve with the to_dict() method but which requires creating a new dict copy for each access since it wouldn't be dynamic otherwise. I'd need to think about this for a bit more before I agree with marking it as deprecated.

[FichteFoll]

I still feel like SettingsDict has some usefulness, so I added the iteration-based methods in #201. See also #139 for more details.

Regarding enums, I agree that we should not add more now that they are already provided as enums natively.

There are some enums that provide additional functionality, notably QueryContextOperator, but I'm not too fond of the functionality it provides and it does not warrant keeping the entire module around. I would rather consider exposing this functionality under a different API, though I do not know which currently.

The other features provided by the custom enum metaclass seem hardly useful and can be easily be reproduced by slightly different usage of the native enums.

[deathaxe]

The kind of excessive decorator use seems rather uncommon, in general, which may explain why it is not accessible enough for most devs and thus not used.

[FichteFoll]

Well, the documentation is quite clear on this imo, but I agree that the implementation (that I never really looked into before) does seem needlessly complicated compared to the few features it provides.