feat: FastAPI debugger (#14606)

* feat: fastapi debugger
* feat: fastapi debugger
* add tests
* add news
* fix vscode settings
* remove eslinter ignore
* extract filename without extension from path.basename
* remove linter ignore from test file
* fix linter
* change python version for fastapi
* change python version for uvicorn
* add coverage to base.ts
* remove unused linter ignore comment
* fix name of variable that reflects main.py location

Author: Kludex

.eslintignore

@@ -847,6 +847,7 @@ src/client/common/insidersBuild/downloadChannelService.ts
 src/client/common/insidersBuild/downloadChannelRules.ts
 
 src/client/debugger/extension/configuration/providers/moduleLaunch.ts
+src/client/debugger/extension/configuration/providers/fastapiLaunch.ts
 src/client/debugger/extension/configuration/providers/flaskLaunch.ts
 src/client/debugger/extension/configuration/providers/fileLaunch.ts
 src/client/debugger/extension/configuration/providers/remoteAttach.ts

build/conda-functional-requirements.txt

@@ -12,6 +12,8 @@ pydocstyle
 nose
 pytest==4.6.9 # Last version of pytest with Python 2.7 support
 rope
+fastapi ; python_version>='3.6'
+uvicorn ; python_version>='3.6'
 flask
 django
 isort
@@ -23,4 +25,4 @@ beakerx
 py4j
 bqplot
 K3D
-debugpy
+debugpy

build/test-requirements.txt

@@ -13,6 +13,8 @@ nose
 pytest<6 ; python_version > '2.7'  # Tests currently fail against pytest 6.
 rope
 flask
+fastapi ; python_version > '2.7'
+uvicorn ; python_version > '2.7'
 django
 isort
 

news/1 Enhancements/14247.md

@@ -0,0 +1,2 @@
+FastAPI debugger feature.
+(thanks [Marcelo Trylesinski](https://github.com/kludex/))

package.nls.json

@@ -42,6 +42,7 @@
     "python.snippet.launch.attach.label": "Python: Remote Attach",
     "python.snippet.launch.attachpid.label": "Python: Attach using Process Id",
     "python.snippet.launch.django.label": "Python: Django",
+    "python.snippet.launch.fastapi.label": "Python: FastAPI",
     "python.snippet.launch.flask.label": "Python: Flask",
     "python.snippet.launch.pyramid.label": "Python: Pyramid Application",
     "Pylance.proposePylanceMessage": "Try out a new faster, feature-rich language server for Python by Microsoft, Pylance! Install the extension now.",
@@ -107,8 +108,7 @@
     "Installer.noCondaOrPipInstaller": "There is no Conda or Pip installer available in the selected environment.",
     "Installer.noPipInstaller": "There is no Pip installer available in the selected environment.",
     "Installer.searchForHelp": "Search for help",
-    "Installer.couldNotInstallLibrary":
-        "Could not install {0}. If pip is not available, please use the package manager of your choice to manually install this library into your Python environment.",
+    "Installer.couldNotInstallLibrary": "Could not install {0}. If pip is not available, please use the package manager of your choice to manually install this library into your Python environment.",
     "Installer.dataScienceInstallPrompt": "Data Science library {0} is not installed. Install?",
     "diagnostics.removedPythonPathFromSettings": "We removed the \"python.pythonPath\" setting from your settings.json file as the setting is no longer used by the Python extension. You can get the path of your selected interpreter in the Python output channel. [Learn more](https://aka.ms/AA7jfor).",
     "diagnostics.warnSourceMaps": "Source map support is enabled in the Python Extension, this will adversely impact performance of the extension.",
@@ -155,6 +155,11 @@
     "debug.djangoEnterManagePyPathTitle": "Debug Django",
     "debug.djangoEnterManagePyPathPrompt": "Enter the path to manage.py ('${workspaceFolderToken}' points to the root of the current workspace folder)",
     "debug.djangoEnterManagePyPathInvalidFilePathError": "Enter a valid Python file path",
+    "debug.debugFastAPIConfigurationLabel": "FastAPI",
+    "debug.debugFastAPIConfigurationDescription": "Launch and debug a FastAPI web application",
+    "debug.fastapiEnterAppPathOrNamePathTitle": "Debug FastAPI",
+    "debug.fastapiEnterAppPathOrNamePathPrompt": "Enter the path to the application, e.g. 'main.py' or 'main'",
+    "debug.fastapiEnterAppPathOrNamePathInvalidNameError": "Enter a valid name",
     "debug.debugFlaskConfigurationLabel": "Flask",
     "debug.debugFlaskConfigurationDescription": "Launch and debug a Flask web application",
     "debug.flaskEnterAppPathOrNamePathTitle": "Debug Flask",

src/client/common/utils/localize.ts

@@ -453,6 +453,21 @@ export namespace DebugConfigStrings {
             invalid: localize('debug.djangoEnterManagePyPathInvalidFilePathError')
         };
     }
+    export namespace fastapi {
+        export const snippet = {
+            name: localize('python.snippet.launch.fastapi.label')
+        };
+        // tslint:disable-next-line:no-shadowed-variable
+        export const selectConfiguration = {
+            label: localize('debug.debugFastAPIConfigurationLabel'),
+            description: localize('debug.debugFastAPIConfigurationDescription')
+        };
+        export const enterAppPathOrNamePath = {
+            title: localize('debug.fastapiEnterAppPathOrNamePathTitle'),
+            prompt: localize('debug.fastapiEnterAppPathOrNamePathPrompt'),
+            invalid: localize('debug.fastapiEnterAppPathOrNamePathInvalidNameError')
+        };
+    }
     export namespace flask {
         export const snippet = {
             name: localize('python.snippet.launch.flask.label')

src/client/debugger/extension/configuration/debugConfigurationService.ts

@@ -121,6 +121,11 @@ export class PythonDebugConfigurationService implements IDebugConfigurationServi
                 type: DebugConfigurationType.launchDjango,
                 description: DebugConfigStrings.django.selectConfiguration.description()
             },
+            {
+                label: DebugConfigStrings.fastapi.selectConfiguration.label(),
+                type: DebugConfigurationType.launchFastAPI,
+                description: DebugConfigStrings.fastapi.selectConfiguration.description()
+            },
             {
                 label: DebugConfigStrings.flask.selectConfiguration.label(),
                 type: DebugConfigurationType.launchFlask,

src/client/debugger/extension/configuration/providers/fastapiLaunch.ts

@@ -0,0 +1,70 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+'use strict';
+
+import { inject, injectable } from 'inversify';
+import * as path from 'path';
+import { WorkspaceFolder } from 'vscode';
+import { IFileSystem } from '../../../../common/platform/types';
+import { DebugConfigStrings } from '../../../../common/utils/localize';
+import { MultiStepInput } from '../../../../common/utils/multiStepInput';
+import { sendTelemetryEvent } from '../../../../telemetry';
+import { EventName } from '../../../../telemetry/constants';
+import { DebuggerTypeName } from '../../../constants';
+import { LaunchRequestArguments } from '../../../types';
+import { DebugConfigurationState, DebugConfigurationType, IDebugConfigurationProvider } from '../../types';
+
+@injectable()
+export class FastAPILaunchDebugConfigurationProvider implements IDebugConfigurationProvider {
+    constructor(@inject(IFileSystem) private fs: IFileSystem) {}
+    public isSupported(debugConfigurationType: DebugConfigurationType): boolean {
+        return debugConfigurationType === DebugConfigurationType.launchFastAPI;
+    }
+    public async buildConfiguration(input: MultiStepInput<DebugConfigurationState>, state: DebugConfigurationState) {
+        const application = await this.getApplicationPath(state.folder);
+        let manuallyEnteredAValue: boolean | undefined;
+        const config: Partial<LaunchRequestArguments> = {
+            name: DebugConfigStrings.fastapi.snippet.name(),
+            type: DebuggerTypeName,
+            request: 'launch',
+            module: 'uvicorn',
+            args: ['main:app'],
+            jinja: true
+        };
+
+        if (!application) {
+            const selectedPath = await input.showInputBox({
+                title: DebugConfigStrings.fastapi.enterAppPathOrNamePath.title(),
+                value: 'main.py',
+                prompt: DebugConfigStrings.fastapi.enterAppPathOrNamePath.prompt(),
+                validate: (value) =>
+                    Promise.resolve(
+                        value && value.trim().length > 0
+                            ? undefined
+                            : DebugConfigStrings.fastapi.enterAppPathOrNamePath.invalid()
+                    )
+            });
+            if (selectedPath) {
+                manuallyEnteredAValue = true;
+                config.args = [`${path.basename(selectedPath, '.py').replace('/', '.')}:app`];
+            }
+        }
+
+        sendTelemetryEvent(EventName.DEBUGGER_CONFIGURATION_PROMPTS, undefined, {
+            configurationType: DebugConfigurationType.launchFastAPI,
+            autoDetectedFastAPIMainPyPath: !!application,
+            manuallyEnteredAValue
+        });
+        Object.assign(state.config, config);
+    }
+    protected async getApplicationPath(folder: WorkspaceFolder | undefined): Promise<string | undefined> {
+        if (!folder) {
+            return;
+        }
+        const defaultLocationOfManagePy = path.join(folder.uri.fsPath, 'main.py');
+        if (await this.fs.fileExists(defaultLocationOfManagePy)) {
+            return 'main.py';
+        }
+    }
+}

src/client/debugger/extension/configuration/providers/providerFactory.ts

@@ -11,6 +11,9 @@ import { IDebugConfigurationProviderFactory } from '../types';
 export class DebugConfigurationProviderFactory implements IDebugConfigurationProviderFactory {
     private readonly providers: Map<DebugConfigurationType, IDebugConfigurationProvider>;
     constructor(
+        @inject(IDebugConfigurationProvider)
+        @named(DebugConfigurationType.launchFastAPI)
+        fastapiProvider: IDebugConfigurationProvider,
         @inject(IDebugConfigurationProvider)
         @named(DebugConfigurationType.launchFlask)
         flaskProvider: IDebugConfigurationProvider,
@@ -35,6 +38,7 @@ export class DebugConfigurationProviderFactory implements IDebugConfigurationPro
     ) {
         this.providers = new Map<DebugConfigurationType, IDebugConfigurationProvider>();
         this.providers.set(DebugConfigurationType.launchDjango, djangoProvider);
+        this.providers.set(DebugConfigurationType.launchFastAPI, fastapiProvider);
         this.providers.set(DebugConfigurationType.launchFlask, flaskProvider);
         this.providers.set(DebugConfigurationType.launchFile, fileProvider);
         this.providers.set(DebugConfigurationType.launchModule, moduleProvider);

src/client/debugger/extension/configuration/resolvers/base.ts

@@ -180,6 +180,10 @@ export abstract class BaseConfigurationResolver<T extends DebugConfiguration>
         return pathMappings;
     }
 
+    protected isDebuggingFastAPI(debugConfiguration: Partial<LaunchRequestArguments & AttachRequestArguments>) {
+        return debugConfiguration.module && debugConfiguration.module.toUpperCase() === 'FASTAPI' ? true : false;
+    }
+
     protected isDebuggingFlask(debugConfiguration: Partial<LaunchRequestArguments & AttachRequestArguments>) {
         return debugConfiguration.module && debugConfiguration.module.toUpperCase() === 'FLASK' ? true : false;
     }
@@ -195,6 +199,7 @@ export abstract class BaseConfigurationResolver<T extends DebugConfiguration>
             console: debugConfiguration.console,
             hasEnvVars: typeof debugConfiguration.env === 'object' && Object.keys(debugConfiguration.env).length > 0,
             django: !!debugConfiguration.django,
+            fastapi: this.isDebuggingFastAPI(debugConfiguration),
             flask: this.isDebuggingFlask(debugConfiguration),
             hasArgs: Array.isArray(debugConfiguration.args) && debugConfiguration.args.length > 0,
             isLocalhost: this.isLocalHost(debugConfiguration.host),

src/client/debugger/extension/configuration/resolvers/launch.ts

@@ -154,9 +154,10 @@ export class LaunchConfigurationResolver extends BaseConfigurationResolver<Launc
         if (this.platformService.isWindows) {
             this.debugOption(debugOptions, DebugOptions.FixFilePathCase);
         }
+        const isFastAPI = this.isDebuggingFastAPI(debugConfiguration);
         const isFlask = this.isDebuggingFlask(debugConfiguration);
         if (
-            (debugConfiguration.pyramid || isFlask) &&
+            (debugConfiguration.pyramid || isFlask || isFastAPI) &&
             debugOptions.indexOf(DebugOptions.Jinja) === -1 &&
             debugConfiguration.jinja !== false
         ) {

src/client/debugger/extension/serviceRegistry.ts

@@ -18,6 +18,7 @@ import { LaunchJsonCompletionProvider } from './configuration/launch.json/comple
 import { InterpreterPathCommand } from './configuration/launch.json/interpreterPathCommand';
 import { LaunchJsonUpdaterService } from './configuration/launch.json/updaterService';
 import { DjangoLaunchDebugConfigurationProvider } from './configuration/providers/djangoLaunch';
+import { FastAPILaunchDebugConfigurationProvider } from './configuration/providers/fastapiLaunch';
 import { FileLaunchDebugConfigurationProvider } from './configuration/providers/fileLaunch';
 import { FlaskLaunchDebugConfigurationProvider } from './configuration/providers/flaskLaunch';
 import { ModuleLaunchDebugConfigurationProvider } from './configuration/providers/moduleLaunch';
@@ -86,6 +87,11 @@ export function registerTypes(serviceManager: IServiceManager) {
         DjangoLaunchDebugConfigurationProvider,
         DebugConfigurationType.launchDjango
     );
+    serviceManager.addSingleton<IDebugConfigurationProvider>(
+        IDebugConfigurationProvider,
+        FastAPILaunchDebugConfigurationProvider,
+        DebugConfigurationType.launchFastAPI
+    );
     serviceManager.addSingleton<IDebugConfigurationProvider>(
         IDebugConfigurationProvider,
         FlaskLaunchDebugConfigurationProvider,

src/client/debugger/extension/types.ts

@@ -40,6 +40,7 @@ export enum DebugConfigurationType {
     launchFile = 'launchFile',
     remoteAttach = 'remoteAttach',
     launchDjango = 'launchDjango',
+    launchFastAPI = 'launchFastAPI',
     launchFlask = 'launchFlask',
     launchModule = 'launchModule',
     launchPyramid = 'launchPyramid',

src/client/telemetry/index.ts

@@ -448,6 +448,12 @@ export interface IEventNamePropertyMapping {
          * @type {boolean}
          */
         django: boolean;
+        /**
+         * Whether the user is debugging `fastapi`.
+         *
+         * @type {boolean}
+         */
+        fastapi: boolean;
         /**
          * Whether the user is debugging `flask`.
          *
@@ -557,6 +563,12 @@ export interface IEventNamePropertyMapping {
          * @type {boolean}
          */
         autoDetectedPyramidIniPath?: boolean;
+        /**
+         * Carries `true` if we are able to auto-detect main.py path for FastAPI, `false` otherwise
+         *
+         * @type {boolean}
+         */
+        autoDetectedFastAPIMainPyPath?: boolean;
         /**
          * Carries `true` if we are able to auto-detect app.py path for Flask, `false` otherwise
          *

src/test/debugger/extension/configuration/providers/fastapiLaunch.unit.test.ts

@@ -0,0 +1,90 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+'use strict';
+
+import { expect } from 'chai';
+import * as path from 'path';
+import { anything, instance, mock, when } from 'ts-mockito';
+import { Uri, WorkspaceFolder } from 'vscode';
+import { FileSystem } from '../../../../../client/common/platform/fileSystem';
+import { IFileSystem } from '../../../../../client/common/platform/types';
+import { DebugConfigStrings } from '../../../../../client/common/utils/localize';
+import { MultiStepInput } from '../../../../../client/common/utils/multiStepInput';
+import { DebuggerTypeName } from '../../../../../client/debugger/constants';
+import { FastAPILaunchDebugConfigurationProvider } from '../../../../../client/debugger/extension/configuration/providers/fastapiLaunch';
+import { DebugConfigurationState } from '../../../../../client/debugger/extension/types';
+
+suite('Debugging - Configuration Provider FastAPI', () => {
+    let fs: IFileSystem;
+    let provider: TestFastAPILaunchDebugConfigurationProvider;
+    let input: MultiStepInput<DebugConfigurationState>;
+    class TestFastAPILaunchDebugConfigurationProvider extends FastAPILaunchDebugConfigurationProvider {
+        // tslint:disable-next-line:no-unnecessary-override
+        public async getApplicationPath(folder: WorkspaceFolder): Promise<string | undefined> {
+            return super.getApplicationPath(folder);
+        }
+    }
+    setup(() => {
+        fs = mock(FileSystem);
+        input = mock<MultiStepInput<DebugConfigurationState>>(MultiStepInput);
+        provider = new TestFastAPILaunchDebugConfigurationProvider(instance(fs));
+    });
+    test("getApplicationPath should return undefined if file doesn't exist", async () => {
+        const folder = { uri: Uri.parse(path.join('one', 'two')), name: '1', index: 0 };
+        const appPyPath = path.join(folder.uri.fsPath, 'main.py');
+        when(fs.fileExists(appPyPath)).thenResolve(false);
+
+        const file = await provider.getApplicationPath(folder);
+
+        expect(file).to.be.equal(undefined, 'Should return undefined');
+    });
+    test('getApplicationPath should find path', async () => {
+        const folder = { uri: Uri.parse(path.join('one', 'two')), name: '1', index: 0 };
+        const appPyPath = path.join(folder.uri.fsPath, 'main.py');
+
+        when(fs.fileExists(appPyPath)).thenResolve(true);
+
+        const file = await provider.getApplicationPath(folder);
+
+        expect(file).to.be.equal('main.py');
+    });
+    test('Launch JSON with valid python path', async () => {
+        const folder = { uri: Uri.parse(path.join('one', 'two')), name: '1', index: 0 };
+        const state = { config: {}, folder };
+        provider.getApplicationPath = () => Promise.resolve('xyz.py');
+
+        await provider.buildConfiguration(instance(input), state);
+
+        const config = {
+            name: DebugConfigStrings.fastapi.snippet.name(),
+            type: DebuggerTypeName,
+            request: 'launch',
+            module: 'uvicorn',
+            args: ['main:app'],
+            jinja: true
+        };
+
+        expect(state.config).to.be.deep.equal(config);
+    });
+    test('Launch JSON with selected app path', async () => {
+        const folder = { uri: Uri.parse(path.join('one', 'two')), name: '1', index: 0 };
+        const state = { config: {}, folder };
+        provider.getApplicationPath = () => Promise.resolve(undefined);
+
+        when(input.showInputBox(anything())).thenResolve('main');
+
+        await provider.buildConfiguration(instance(input), state);
+
+        const config = {
+            name: DebugConfigStrings.fastapi.snippet.name(),
+            type: DebuggerTypeName,
+            request: 'launch',
+            module: 'uvicorn',
+            args: ['main:app'],
+            jinja: true
+        };
+
+        expect(state.config).to.be.deep.equal(config);
+    });
+});

src/test/debugger/extension/configuration/providers/providerFactory.unit.test.ts

@@ -20,6 +20,7 @@ suite('Debugging - Configuration Provider Factory', () => {
             mappedProviders.set(item.value, (item.value as any) as IDebugConfigurationProvider);
         });
         factory = new DebugConfigurationProviderFactory(
+            mappedProviders.get(DebugConfigurationType.launchFastAPI)!,
             mappedProviders.get(DebugConfigurationType.launchFlask)!,
             mappedProviders.get(DebugConfigurationType.launchDjango)!,
             mappedProviders.get(DebugConfigurationType.launchModule)!,