More useful error messages for jupyter not being installed (#3234)

Author: rchiodo

.travis.yml

@@ -95,7 +95,6 @@ script:
     fi
   - if [ $FUNCTIONAL_TEST == "true" ]; then
         python -m pip install --upgrade -r functionalTestRequirements.txt;
-        npm run cover:enable;
         npm run test:functional;
     fi
   - if [ $SINGLE_WORKSPACE_TEST == "true" ]; then

PYTHON_INTERACTIVE_TROUBLESHOOTING.md

@@ -0,0 +1,50 @@
+# Trouble shooting the Python Interactive Window
+
+This document is intended to help troubleshoot problems in the Python Interactive Window.
+
+---
+## Jupyter Not Installed
+This error can happen when you 
+
+* Don't have Jupyter installed
+* Have picked the wrong Python environment (one that doesn't have Jupyter installed).
+
+### The first step is to verify you are running the Python environment you want. 
+
+You can do this by either selecting it in the dropdown at the bottom of VS Code:
+
+![selector](resources/PythonSelector.png)
+
+Or by running some Python code in VS Code Python terminal:
+```python
+import sys
+sys.version
+```
+
+### The second step (if changing the Python version doesn't work) is to install Jupyter
+
+You can do this in a number of different ways:
+
+#### Anaconda
+
+Anaconda is a popular Python distribution. It makes it super easy to get Jupyter up and running. 
+
+If you're already using Anaconda, follow these steps to get jupyter
+1. Start anaconda environment
+1. Run 'conda install jupyter'
+1. Restart VS Code
+1. Pick the conda version of Python in the python selector
+
+Otherwise you can install Anaconda and pick the default options
+https://www.anaconda.com/download
+
+
+#### Pip
+
+You can also install Jupyter using pip. This is a little more work because you have to specify a number of sub packages too
+
+1. python -m pip install jupyter
+1. python -m pip install notebook
+1. python -m pip install nbconvert
+1. Restart VS Code
+1. Pick the Python environment you did the pip install in

package.nls.json

@@ -75,8 +75,9 @@
     "DataScience.notebookCheckForImportNo": "Later",
     "DataScience.notebookCheckForImportDontAskAgain": "Don't Ask Again",
     "DataScience.notebookCheckForImportTitle": "Do you want to import the Jupyter Notebook into Python code?",
-    "DataScience.jupyterNotSupported": "Jupyter is not installed",
-    "DataScience.jupyterNbConvertNotSupported": "Jupyter nbconvert is not installed",
+    "DataScience.jupyterNotSupported": "Running cells requires Jupyter notebooks to be installed.",
+    "DataScience.jupyterNbConvertNotSupported": "Importing notebooks requires Jupyter nbconvert to be installed.",
+    "DataScience.pythonInteractiveHelpLink" : "Get more help",
     "DataScience.importingFormat": "Importing {0}",
     "DataScience.startingJupyter": "Starting Jupyter Server",
     "Interpreters.RefreshingInterpreters": "Refreshing Python Interpreters",

resources/PythonSelector.png

@@ -44,6 +44,7 @@ export namespace DataScience {
     export const notebookCheckForImportDontAskAgain = localize('DataScience.notebookCheckForImportDontAskAgain', 'Don\'t Ask Again');
     export const jupyterNotSupported = localize('DataScience.jupyterNotSupported', 'Jupyter is not installed');
     export const jupyterNbConvertNotSupported = localize('DataScience.jupyterNbConvertNotSupported', 'Jupyter nbconvert is not installed');
+    export const pythonInteractiveHelpLink = localize('DataScience.pythonInteractiveHelpLink', 'See [https://aka.ms/pyaiinstall] for help on installing jupyter.');
     export const importingFormat = localize('DataScience.importingFormat', 'Importing {0}');
     export const startingJupyter = localize('DataScience.startingJupyter', 'Starting Jupyter Server');
     export const runAllCellsLensCommandTitle = localize('python.command.python.datascience.runallcells.title', 'Run all cells');

src/client/common/utils/localize.ts

@@ -58,3 +58,7 @@ export namespace Telemetry {
     export const ExpandAll = 'DATASCIENCE.EXPAND_ALL';
     export const CollapseAll = 'DATASCIENCE.COLLAPSE_ALL';
 }
+
+export namespace HelpLinks {
+    export const PythonInteractiveHelpLink = 'https://aka.ms/pyaiinstall';
+}

src/client/datascience/constants.ts

@@ -5,10 +5,12 @@ import { CodeLens, Command, Position, Range, Selection, TextDocument, TextEditor
 
 import { IApplicationShell, ICommandManager } from '../../common/application/types';
 import { ContextKey } from '../../common/contextKey';
+import { ILogger } from '../../common/types';
 import * as localize from '../../common/utils/localize';
 import { IServiceContainer } from '../../ioc/types';
 import { captureTelemetry } from '../../telemetry';
 import { Commands, EditorContexts, RegExpValues, Telemetry } from '../constants';
+import { JupyterInstallError } from '../jupyterInstallError';
 import { ICodeWatcher, IHistoryProvider } from '../types';
 
 export interface ICell {
@@ -24,11 +26,13 @@ export class CodeWatcher implements ICodeWatcher {
     private historyProvider: IHistoryProvider;
     private commandManager: ICommandManager;
     private applicationShell: IApplicationShell;
+    private logger: ILogger;
 
     constructor(serviceContainer: IServiceContainer, document: TextDocument) {
         this.historyProvider = serviceContainer.get<IHistoryProvider>(IHistoryProvider);
         this.commandManager = serviceContainer.get<ICommandManager>(ICommandManager);
         this.applicationShell = serviceContainer.get<IApplicationShell>(IApplicationShell);
+        this.logger = serviceContainer.get<ILogger>(ILogger);
 
         this.document = document;
 
@@ -95,7 +99,7 @@ export class CodeWatcher implements ICodeWatcher {
             try {
                 await activeHistory.addCode(code, this.getFileName(), range.start.line, window.activeTextEditor);
             } catch (err) {
-                this.applicationShell.showErrorMessage(err);
+                this.handleError(err);
             }
 
         }
@@ -156,6 +160,26 @@ export class CodeWatcher implements ICodeWatcher {
         }
     }
 
+    // tslint:disable-next-line:no-any
+    private handleError = (err : any) => {
+        if ((<JupyterInstallError>err).actionTitle !== undefined) {
+            const jupyterError = err as JupyterInstallError;
+
+            // This is a special error that shows a link to open for more help
+            this.applicationShell.showErrorMessage(jupyterError.message, jupyterError.actionTitle).then(v => {
+                // User clicked on the link, open it.
+                if (v === jupyterError.actionTitle) {
+                    this.applicationShell.openUrl(jupyterError.action);
+                }
+            });
+        } else if (err.message) {
+            this.applicationShell.showErrorMessage(err.message);
+        } else {
+            this.applicationShell.showErrorMessage(err.toString());
+        }
+        this.logger.logError(err);
+    }
+
     // User has picked run and advance on the last cell of a document
     // Create a new cell at the bottom and put their selection there, ready to type
     private createNewCell(currentRange: Range): Range {

src/client/datascience/editor-integration/codewatcher.ts

@@ -22,14 +22,14 @@ import * as localize from '../common/utils/localize';
 import { IInterpreterService } from '../interpreter/contracts';
 import { captureTelemetry, sendTelemetryEvent } from '../telemetry';
 import { HistoryMessages, Telemetry } from './constants';
-import { CellState, ICell, ICodeCssGenerator, IHistory, INotebookServer, IStatusProvider } from './types';
+import { JupyterInstallError } from './jupyterInstallError';
+import { CellState, ICell, ICodeCssGenerator, IHistory, IJupyterExecution, INotebookServer, IStatusProvider } from './types';
 
 @injectable()
 export class History implements IWebPanelMessageListener, IHistory {
     private disposed : boolean = false;
     private webPanel : IWebPanel | undefined;
-    // tslint:disable-next-line: no-any
-    private loadPromise: Promise<any>;
+    private loadPromise: Promise<void>;
     private settingsChangedDisposable : Disposable;
     private closedEvent : EventEmitter<IHistory>;
     private unfinishedCells: ICell[] = [];
@@ -44,7 +44,8 @@ export class History implements IWebPanelMessageListener, IHistory {
         @inject(IWebPanelProvider) private provider: IWebPanelProvider,
         @inject(IDisposableRegistry) private disposables: IDisposableRegistry,
         @inject(ICodeCssGenerator) private cssGenerator : ICodeCssGenerator,
-        @inject(IStatusProvider) private statusProvider : IStatusProvider) {
+        @inject(IStatusProvider) private statusProvider : IStatusProvider,
+        @inject(IJupyterExecution) private jupyterExecution: IJupyterExecution) {
 
         // Sign up for configuration changes
         this.settingsChangedDisposable = this.interpreterService.onDidChangeInterpreter(this.onSettingsChanged);
@@ -63,7 +64,7 @@ export class History implements IWebPanelMessageListener, IHistory {
             await this.loadPromise;
 
             // Then show our web panel.
-            if (this.webPanel) {
+            if (this.webPanel && this.jupyterServer) {
                 await this.webPanel.show();
             }
         }
@@ -77,29 +78,38 @@ export class History implements IWebPanelMessageListener, IHistory {
         // Start a status item
         const status = this.setStatus(localize.DataScience.executingCode());
 
-        // Make sure we're loaded first.
-        await this.loadPromise;
+        try {
+            // Make sure we're loaded first.
+            await this.loadPromise;
 
-        // Then show our webpanel
-        await this.show();
+            // Then show our webpanel
+            await this.show();
 
-        if (this.jupyterServer) {
-            // Attempt to evaluate this cell in the jupyter notebook
-            const observable = this.jupyterServer.executeObservable(code, file, line);
-
-            // Sign up for cell changes
-            observable.subscribe(
-                (cells: ICell[]) => {
-                    this.onAddCodeEvent(cells, editor);
-                },
-                (error) => {
-                    status.dispose();
-                    this.applicationShell.showErrorMessage(error);
-                },
-                () => {
-                    // Indicate executing until this cell is done.
-                    status.dispose();
-                });
+            if (this.jupyterServer) {
+                // Attempt to evaluate this cell in the jupyter notebook
+                const observable = this.jupyterServer.executeObservable(code, file, line);
+
+                // Sign up for cell changes
+                observable.subscribe(
+                    (cells: ICell[]) => {
+                        this.onAddCodeEvent(cells, editor);
+                    },
+                    (error) => {
+                        status.dispose();
+                        this.applicationShell.showErrorMessage(error);
+                    },
+                    () => {
+                        // Indicate executing until this cell is done.
+                        status.dispose();
+                    });
+            }
+        } catch (err) {
+            status.dispose();
+
+            // We failed, dispose of ourselves too so that nobody uses us again
+            this.dispose();
+
+            throw err;
         }
     }
 
@@ -366,10 +376,14 @@ export class History implements IWebPanelMessageListener, IHistory {
         this.webPanel = this.provider.create(this, localize.DataScience.historyTitle(), mainScriptPath, css);
     }
 
-    private load = () : Promise<[void, void]> => {
-        return Promise.all([
-            this.loadWebPanel(),
-            this.loadJupyterServer()
-        ]);
+    private load = async () : Promise<void> => {
+
+        // Check to see if we support jupyter or not. If not quick fail
+        if (!(await this.jupyterExecution.isImportSupported())) {
+            throw new JupyterInstallError(localize.DataScience.jupyterNotSupported(), localize.DataScience.pythonInteractiveHelpLink());
+        }
+
+        // Otherwise wait for both
+        await Promise.all([this.loadJupyterServer(), this.loadWebPanel()]);
     }
 }

src/client/datascience/history.ts

@@ -58,7 +58,7 @@ export class JupyterImporter implements INotebookImporter {
             return result.stdout;
         }
 
-        throw localize.DataScience.jupyterNotSupported();
+        throw new Error(localize.DataScience.jupyterNbConvertNotSupported());
     }
 
     public dispose = () => {

src/client/datascience/jupyterImporter.ts

@@ -0,0 +1,16 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+'use strict';
+import '../common/extensions';
+import { HelpLinks } from './constants';
+
+export class JupyterInstallError extends Error {
+    public action: string;
+    public actionTitle: string;
+
+    constructor(message: string, actionFormatString: string) {
+        super(message);
+        this.action = HelpLinks.PythonInteractiveHelpLink;
+        this.actionTitle = actionFormatString.format(HelpLinks.PythonInteractiveHelpLink);
+    }
+}