Improve type stubs

[jwortmann]

In the type stubs for sublime.py and sublime_plugin.py:

• Adds docstrings, which are shown in the hover popups
• Adds several missing API methods that were added over time in ST
• Adds missing function parameters that were added over time in ST
• Fixes many many bugs for the type annotations
• Uses conventions from https://typing.readthedocs.io/en/latest/source/stubs.html, e.g. int | str instead of Union[int, str]

This also revealed a few inaccuracies in the code (return value of View.sheet(), use of deprecated constant, etc.), which I have fixed too.

There is also a wrong type annotation in the current code base at

LSP/plugin/goto_diagnostic.py

Line 258 in fe32c17

def confirm(self, value: Optional[Tuple[int, Diagnostic]]) -> None:

because the value can never be a tuple, even if it was provided as a tuple for the ListInputItem constructor at

LSP/plugin/goto_diagnostic.py

Line 249 in fe32c17

list_items.append(sublime.ListInputItem(text, (i, diagnostic), annotation=annotation, kind=kind))

A tuple is incompatible with sublime.Value, it still works here, but internally it is converted to a list. You can confirm this with a little plugin like this:

import sublime
import sublime_plugin


class InputHandlerTestCommand(sublime_plugin.WindowCommand):

    def run(self, arg1):
        pass

    def input(self, args):
        if 'arg1' not in args:
            return MyListInputHandler()

class MyListInputHandler(sublime_plugin.ListInputHandler):

    def name(self):
        return 'arg1'

    def list_items(self):
        return [sublime.ListInputItem('test', ("foo", 42))]

    def confirm(self, value):
        print(value)
        print(isinstance(value, tuple))
        print(isinstance(value, list))

Result:

['foo', 42]
False
True

I fixed this type incompatibility in the last commit (it looks a little bit ugly though, but I didn't want to extra add a new TypedDict for this).

[rchl]

I wouldn't mind a typed dict like

DiagnosticInputItem = TypedDict('DiagnosticInputItem', {
    'index': int,
    'diagnostic': Diagnostic
}, total=True)

(been testing it so wrote it already)

but... this still throws type error due to it being incompatible with Dict[str, Any]. So if we'd need more hacks on top of that then it defeats the point.

[rchl]

Trying to compete with https://github.com/jfcherng-sublime/ST-API-stubs with those? ;)

[rchl]

I won't verify every modification in stubs manually but it looks pretty good.

[jwortmann]

Trying to compete with https://github.com/jfcherng-sublime/ST-API-stubs with those? ;)

Yeah, but those stubs only target the 3.8 API environment, and they use a few custom type definitions/aliases which would show up in the hover popup. At first I actually considered to start with jfcherng's stubs, but then it turned out to be easier to just take the original sublime.py/sublime_plugin.py files from the 3.8 API, and go through all classes and functions by comparing them to the same files from the 3.3 API. There are a few function parameters with different names and also some functions are missing. And I optimized most of the docstrings to have nice formatting in the hover popup, etc.

When LSP switches to the 3.8 API it should be relatively simple to go through the files again, in order to add the new enums, change the parameter names that are different, and to add the functions that are exclusive to the 3.8 API.

---

Btw, I had hoped that you would squash the commits in this PR, because they are not really important and a bit of a mess, but nevermind :-)

[rchl]

Btw, I had hoped that you would squash the commits in this PR, because they are not really important and a bit of a mess, but nevermind :-)

I have force-pushed now. Watch out for conflicts.