forked fromDonJayamanne/pythonVSCode
- Notifications
You must be signed in to change notification settings - Fork1.2k
VS Code Extension API
Brett Cannon edited this pageJan 14, 2021 ·1 revision
TheVS Code extension API is divided into two distinct parts (conceptually):
- registration of handlers by which VS Code requests actions or data from an extension
- functions (and types, constants, etc.) by which an extension requests actions or data from VS Code
In addition to that concrete API, VS Code defines several other ways that extensions may interact with it or provide it resources:
- the
package.jsonfile (a superset of the npm package.json) defines static data about the extension. Thisincludes commands, settings, language configuration, and debugger definitions. (Note that a number of items from that static data can be extended or overridden via the API.) - debug adapters (via "DAP") interact with VS Code (which acts as the debug client) to support debugging operations. They help make debuggers more independent from VS Code and its extensions.
- Language Servers (via "LSP") consolidate much of the language-specific functionality provided by registered handlers in the VS Code API, effectively replacing those handlers. As with debug adapters, this allows such language services to be more independent from VS Code and its extensions.
The Python extension for VS Code takes adavantage of all of the above.
Note: hypothetically, an extension could be written in Python, either directly or with a light typescript wrapper around the VS Code API. I'm just saying...
Usage:
- `src/client/extension.ts'
- debug.registerDebugConfigurationProvider (+1)
- languages.registerCodeActionsProvider (+1)
- languages.registerDocumentFormattingEditProvider
- languages.registerDocumentRangeFormattingEditProvider
- languages.setLanguageConfiguration
src/client/activation/jedi.ts- commands.registerCommand (+2)
- languages.registerCodeLensProvider (+2)
- languages.registerCompletionItemProvider (+1)
- languages.registerDefinitionProvider
- languages.registerDocumentSymbolProvider
- languages.registerHoverProvider
- languages.registerOnTypeFormattingEditProvider
- languages.registerReferenceProvider
- languages.registerRenameProvider
- languages.registerSignatureHelpProvider
src/client/common/application/debugService.ts- debug.registerDebugAdapterDescriptorFactory
- debug.registerDebugAdapterTrackerFactory
- debug.registerDebugConfigurationProvider (+1)
- in other files:
- commands.registerCommand (3, incl. jedi)
- languages.registerCodeLensProvider (3, incl. jedi)
- languages.registerCompletionItemProvider (2, incl. jedi)
- languages.registerCodeActionsProvider (2, incl. extension.ts)
- commands.registerTextEditorCommand (1)
- languages.registerWorkspaceSymbolProvider (1)
- window.registerTreeDataProvider (1)
USED (by hook)
commands.registerCommand ------------------------------ src/client/activation/jedi.ts src/client/common/application/commandManager.ts src/client/providers/simpleRefactorProvider.ts src/client/providers/simpleRefactorProvider.ts commands.registerTextEditorCommand ------------------------------ src/client/common/application/commandManager.ts debug.registerDebugAdapterDescriptorFactory ------------------------------ src/client/common/application/debugService.ts debug.registerDebugAdapterTrackerFactory ------------------------------ src/client/common/application/debugService.ts debug.registerDebugConfigurationProvider ------------------------------ src/client/common/application/debugService.ts src/client/extension.tslanguages.registerCodeActionsProvider------------------------------ src/client/extension.ts src/client/providers/codeActionProvider/main.tslanguages.registerCodeLensProvider------------------------------ src/client/activation/jedi.ts src/client/datascience/datascience.ts src/client/testing/codeLenses/main.tslanguages.registerCompletionItemProvider------------------------------ src/client/activation/jedi.ts src/client/common/application/languageService.tslanguages.registerDefinitionProvider------------------------------ src/client/activation/jedi.tslanguages.registerDocumentFormattingEditProvider------------------------------ src/client/extension.tslanguages.registerDocumentRangeFormattingEditProvider------------------------------ src/client/extension.tslanguages.registerDocumentSymbolProvider------------------------------ src/client/activation/jedi.tslanguages.registerHoverProvider------------------------------ src/client/activation/jedi.tslanguages.registerOnTypeFormattingEditProvider------------------------------ src/client/activation/jedi.tslanguages.registerReferenceProvider------------------------------ src/client/activation/jedi.tslanguages.registerRenameProvider------------------------------ src/client/activation/jedi.tslanguages.registerSignatureHelpProvider------------------------------ src/client/activation/jedi.tslanguages.registerSignatureHelpProvider------------------------------ src/client/activation/jedi.tslanguages.registerWorkspaceSymbolProvider------------------------------ src/client/workspaceSymbols/main.tslanguages.setLanguageConfiguration------------------------------ src/client/extension.tswindow.registerTreeDataProvider------------------------------ src/client/datascience/liveshare/liveshareProxy.tstotal used: 21
NOT USED
languages.registerCallHierarchyProvider languages.registerColorProvider languages.registerDeclarationProvider languages.registerDocumentHighlightProvider languages.registerDocumentLinkProvider languages.registerFoldingRangeProvider languages.registerImplementationProvider languages.registerSelectionRangeProvider languages.registerTypeDefinitionProvider tasks.registerTaskProvider window.registerUriHandler window.registerWebviewPanelSerializer workspace.registerFileSystemProvider workspace.registerTaskProvider workspace.registerTextDocumentContentProvidertotal not used: 15
USED (by file)
src/client/activation/jedi.ts------------------------------ commands.registerCommand languages.registerCodeLensProvider languages.registerCompletionItemProvider languages.registerDefinitionProvider languages.registerDocumentSymbolProvider languages.registerHoverProvider languages.registerOnTypeFormattingEditProvider languages.registerReferenceProvider languages.registerRenameProvider languages.registerSignatureHelpProvidersrc/client/common/application/commandManager.ts------------------------------ commands.registerCommand commands.registerTextEditorCommandsrc/client/common/application/debugService.ts------------------------------ debug.registerDebugAdapterDescriptorFactory debug.registerDebugAdapterTrackerFactory debug.registerDebugConfigurationProvidersrc/client/common/application/languageService.ts------------------------------ languages.registerCompletionItemProvidersrc/client/datascience/datascience.ts------------------------------ languages.registerCodeLensProvidersrc/client/datascience/liveshare/liveshareProxy.ts------------------------------ window.registerTreeDataProvidersrc/client/extension.ts------------------------------ debug.registerDebugConfigurationProvider languages.registerCodeActionsProvider languages.registerDocumentFormattingEditProvider languages.registerDocumentRangeFormattingEditProvider languages.setLanguageConfigurationsrc/client/providers/codeActionProvider/main.ts------------------------------ languages.registerCodeActionsProvidersrc/client/providers/simpleRefactorProvider.ts------------------------------ commands.registerCommand commands.registerCommandsrc/client/testing/codeLenses/main.ts------------------------------ languages.registerCodeLensProvidersrc/client/workspaceSymbols/main.ts------------------------------ languages.registerWorkspaceSymbolProvidertotal files using hooks: 11
script to analyze our usage of the VS Code API
# XXX Find all "known" hooks (in node_modules/@types/vscode/index.d.ts).# XXX Find all other uses of the VS Code API.importreimporttextwrapdef_regex_join_options(opts,indent=' '):returnf'\n{indent}|\n{indent}'.join(opts)######################################## helpers for hooksdeffind_known_hooks():# For now we hard-code the list.return ['tasks.registerTaskProvider','commands.registerCommand','commands.registerTextEditorCommand','window.registerTreeDataProvider',# <T>'window.registerUriHandler','window.registerWebviewPanelSerializer','workspace.registerFileSystemProvider','workspace.registerTaskProvider','workspace.registerTextDocumentContentProvider','languages.registerCallHierarchyProvider','languages.registerCodeActionsProvider','languages.registerCodeLensProvider','languages.registerColorProvider','languages.registerCompletionItemProvider','languages.registerDeclarationProvider','languages.registerDefinitionProvider','languages.registerDocumentFormattingEditProvider','languages.registerDocumentHighlightProvider','languages.registerDocumentLinkProvider','languages.registerDocumentRangeFormattingEditProvider','languages.registerDocumentSymbolProvider','languages.registerFoldingRangeProvider','languages.registerHoverProvider','languages.registerImplementationProvider','languages.registerOnTypeFormattingEditProvider','languages.registerReferenceProvider','languages.registerRenameProvider','languages.registerSelectionRangeProvider','languages.registerSignatureHelpProvider','languages.registerSignatureHelpProvider','languages.registerTypeDefinitionProvider','languages.registerWorkspaceSymbolProvider','languages.setLanguageConfiguration','debug.registerDebugAdapterDescriptorFactory','debug.registerDebugAdapterTrackerFactory','debug.registerDebugConfigurationProvider', ]defiter_hooks(srclines,*,known=None,alts=None):ifnotknown:known=find_known_hooks()_hooks= (v.replace('.','\.')forvinknown+list(altsor ()))regex=re.compile(textwrap.dedent(rf''' ^ .*? \b ({_regex_join_options(_hooks,' ')} ) \s* (?: < [^>]+ > \s* )? [(] '''),re.VERBOSE )forlineinsrclines:m=regex.match(line)ifnotm:continuehook,=m.groups()yieldalts.get(hook,hook)ifaltselsehookdeffind_all_hooks(filenames,*,known=None,alts=None):ifnotknown:known=find_known_hooks()forfilenameinfilenamesor ():withopen(filename)assrcfile:forhookiniter_hooks(srcfile,known=known,alts=alts):yieldfilename,hookdefanalyze_found_hooks(results):hooks= {}files= {}forfilename,hookinresults:try:found=hooks[hook]exceptKeyError:found=hooks[hook]= []iffilenamenotinfound:found.append(filename)try:found=files[filename]exceptKeyError:found=files[filename]= []found.append(hook)returnhooks,files######################################## commands# hooksHOOKS_ALTS= {'.registerTreeDataProvider':'window.registerTreeDataProvider',}defcmd_hooks(filenames,show=None):try:run_cmd=CMD_HOOKS_SHOW[showor'summary']exceptKeyError:raiseValueError(f'unsupported --show{show!r}')ifrun_cmdisNone:raiseNotImplementedError(show)known=find_known_hooks()run_cmd(find_all_hooks(filenames,known=known,alts=HOOKS_ALTS),filenames=filenames,known=known, )defcmd_hooks_raw(results,**ignored):total=0forfilename,hookinresults:# We do not sort.print(f'{filename:50}{hook}')total+=1print('----')print(f'total:{total}')print()defcmd_hooks_by_hook(results,known,**ignored):hooks,_=analyze_found_hooks(results)forhookinsorted(hooks,key=lambdah: (-len(hooks[h]),h)):found=hooks.get(hook, ())ifnotfound:continueprint()print(f'{hook} ({len(hooks[hook])})')print('------------------------------')forfilenameinsorted(found):print(' ',filename)print()defcmd_hooks_by_file(results,**ignored):_,files=analyze_found_hooks(results)forfilenameinsorted(files,key=lambdaf: (-len(files[f]),f)):print()print(f'{filename} ({len(files[filename])})')print('------------------------------')forhookinsorted(files[filename]):print(' ',hook)print()HOOKS_EXPECTED= ['commands.registerCommand','commands.registerTextEditorCommand','window.registerTreeDataProvider','languages.registerCodeActionsProvider','languages.registerCodeLensProvider','languages.registerCompletionItemProvider','languages.registerDefinitionProvider','languages.registerDocumentFormattingEditProvider','languages.registerDocumentRangeFormattingEditProvider','languages.registerDocumentSymbolProvider','languages.registerHoverProvider','languages.registerOnTypeFormattingEditProvider','languages.registerReferenceProvider','languages.registerRenameProvider','languages.registerSignatureHelpProvider','languages.registerSignatureHelpProvider','languages.registerWorkspaceSymbolProvider','languages.setLanguageConfiguration','debug.registerDebugAdapterDescriptorFactory','debug.registerDebugAdapterTrackerFactory','debug.registerDebugConfigurationProvider',]defcmd_hooks_summary(results,known,filenames,**ignored):single=len(filenames)==1hooks,files=analyze_found_hooks(results)print()print(f'using{len(hooks)} hooks:')forhookinsorted(hooks,key=lambdah: (-len(hooks[h]),h)):ifsingle:print(f' ',hook)else:print(f'{len(hooks[hook]):>2}{hook}')iflen(filenames)>100:# an approximation of "all"missing=set(HOOKS_EXPECTED)-set(hooks)ifmissing:print()print(f'expected but not found ({len(missing)}):')forhookinsorted(missing):print(' ',hook)notused=set(known)-set(hooks)ifnotused:print()print(f'not used ({len(notused)}):')forhookinsorted(notused):print(' ',hook)ifnotsingle:print()print(f'found{len(files)} files using hooks:')forfilenameinsorted(files,key=lambdaf: (-len(files[f]),f)):print(f'{len(files[filename]):>2}{filename}')CMD_HOOKS_SHOW= {'raw':cmd_hooks_raw,'hooks':cmd_hooks_by_hook,'files':cmd_hooks_by_file,'summary':cmd_hooks_summary,}# apidefcmd_api(filenames,show=None):try:run_cmd=CMD_API_SHOW[showor'summary']exceptKeyError:raiseValueError(f'unsupported --show{show!r}')ifrun_cmdisNone:raiseNotImplementedError(show)run_cmd(filenames)CMD_API_SHOW= {'raw':None,'hooks':None,'files':None,'summary':None,}# the registryCOMMANDS= {'hooks':cmd_hooks,'api':cmd_api,}COMMANDS_DEFAULT='hooks'SHOW= {'hooks':CMD_HOOKS_SHOW,'api':CMD_API_SHOW,}######################################## the scriptimportsysdefparse_args(argv=sys.argv[1:],prog=sys.argv[0]):importargparse# Set up the "default" command.ifargvandargv[0]notinCOMMANDS:if'.'inargv[0]orargv[0].startswith('-'):# This doesn't guard against "--".if'-h'inargvor'--help'inargv:argv= ['--help']else:# Use a sensible default for now.argv.insert(0,COMMANDS_DEFAULT)parser=argparse.ArgumentParser(prog=prog, )subs=parser.add_subparsers(dest='cmd')forcmdinsorted(COMMANDS):sub=subs.add_parser(cmd)ifcmdinSHOW:sub.add_argument('--show',choices=sorted(SHOW[cmd]),default='summary', )sub.add_argument('filenames',nargs='+')args=parser.parse_args(argv)ns=vars(args)cmd=ns.pop('cmd')returncmd,nsdefmain(cmd,**cmd_kwargs):try:run_cmd=COMMANDS[cmd]exceptKeyError:raiseValueError(f'unsupported --cmd{cmd!r}')run_cmd(**cmd_kwargs)if__name__=='__main__':cmd,kwargs=parse_args()main(cmd,**kwargs)