Import Export

Summary

There are a number of import / export scenarios handled by the Jupyter Extension.

1. Import a file to Python script
2. Export a notebook file / IW to Python script
3. Export a notebook file / IW to PDF
4. Export a notebook file / IW to HTML
5. Save a IW session as a notebook

Entry Points

These scenarios come from a few different entry points, but flow through most of the same code paths to accomplish their work.

Importing a notebook can be accessed via the Jupyter: Import Jupyter Notebook command or via right click menu on a notebook file in VS Code's explorer.

Exporting notebook files can be accessed via the export commands or via the export button in the notebook menu bar.

Converting the IW to a notebook file is done via the Save button in the IW menu bar.

File Converter

The heart of these import and export commands is the fileConverter class.

FileConverter

This class can perform a fast plain text conversion to .py just in typescript or conversions to .py, html, or pdf by calling out to have nbconvert perform the conversion.

        if (
            format === ExportFormat.python &&
            this.configuration.getSettings(sourceDocument.uri).pythonExportMethod !== 'nbconvert'
        ) {
            // Unless selected by the setting use plain conversion for python script convert
            await this.performPlainExport(format, sourceDocument, target, token);
        } else {
            await this.performNbConvertExport(sourceDocument, format, target, candidateInterpreter, token);
        }

Plain Text Conversion

The plain text conversion is performed by this class: ExportToPythonPlain

The Jupyter: Python Export Method controls this usage. If you have it set to direct it copies over the contents of cells directly. If you have it set for commentMagics it comments out single line shell magic commands as they are not valid in the .py file. And if you have it set to nbconvert it uses nbconvert for the .py conversion instead of the plain export.

The plain export was added as the nbconvert method (while more accurate is also harder to setup and slower and more error prone to execute.

NB Convert Conversion

.py, HTML, and PDF conversion can all be handled by the nbconvert python package. When this command is run it first looks for nbconvert in the currently active kernel environment, then it falls back to checked for nbconvert in the globally configured jupyter interpreter environment (Jupyter: Select Interpreter to start Jupyter Server). This was done so that the current environment gets priority, but the globally env can always be used so you don't need to install nbconvert all over the place.

Of note here, we use a template file to control settings for how nbconvert does this conversion. This template file format changed with nbconvert versions, so there is a version check here to use the correct style of conversion.

PDF Conversion

Converting to pdf is just a simple command that we pass to nbconvert. But it's very difficult to set up. Nbconvert uses LaTeX for PDF rendering, so you need to install a complete TeX environment to use this.

Installing TeX