Running and Quitting

Overview

Teaching: 15 min
Exercises: 0 min

Questions

• How can I run Python code?

Objectives

• Launch the JupyterLab server.

• Create a new Python script.

• Create a Jupyter notebook.

• Shutdown the JupyterLab server.

• Understand the difference between a Python script and a Jupyter notebook.

• Create Markdown cells in a notebook.

• Create and run Python cells in a notebook.

Getting Started with JupyterLab

While many software developers will often use an integrated development environment (IDE) or a text editor to create and edit their Python programs we will be using JupyterLab during this lesson.

JupyterLab is an application with a web-based user interface from Project Jupyter that enables you to work with documents and activities such as Jupyter notebooks, text editors, terminals, or even custom components in a flexible, integrated, and extensible manner. JupyterLab requires a reasonably up-to-date browser (ideally a current version of Chrome, Safari, or Firefox); Internet Explorer versions 9 and below are not supported.

JupyterLab is included as part of the the Anaconda Python distribution. If you have not already installed the Anaconda Python distribution, see the setup instructions.

Even though JupyterLab is a web-based application, it runs locally on your machine and does not require an internet connection.

• The JupyterLab server sends messages to your web browser.
• The JupyterLab server does the work and the web browser renders the result.
• You will type code into the browser and see the result when the web page talks to the JupyterLab server.

JupyterLab? What about Jupyter notebooks?

JupyterLab is the next stage in the evolution of the Jupyter Notebook. If you have prior experience working with Jupyter notebooks, then you will have a a good idea of what to expect from JupyterLab.

Experienced users of Jupyter notebooks interested in a more detailed discussion of the similarities and differences between the JupyterLab and Jupyter notebook user interfaces can find more information in the JupyterLab user interface documentation.

Starting JupyterLab

For this workshop, we call JupyterLab using the virtual environment we installed.

cd ~/Desktop/workshoppython
pipenv run jupyter lab

The JupyterLab Interface

JupyterLab has many features found in traditional integrated development environments (IDEs) but is focused on providing flexible building blocks for interactive, exploratory computing.

The JupyterLab Interface consists of the Menu Bar, a collapsable Left Side Bar, and the Main Work Area which contains tabs of documents and activities.

Menu Bar

The Menu Bar at the top of JupyterLab has the top-level menus that expose various actions available in JupyterLab along with their keyboard shortcuts (where applicable). The following menus are included by default.

• File: Actions related to files and directories such as New, Open, Close, Save, etc. The File menu also includes the Quit action used to shutdown the JupyterLab server.
• Edit: Actions related to editing documents and other activities such as Undo, Cut, Copy, Paste, etc.
• View: Actions that alter the appearance of JupyterLab.
• Run: Actions for running code in different activities such as notebooks and code consoles (discussed below).
• Kernel: Actions for managing kernels which, as mentioned above, are separate processes for running code.
• Tabs: A list of the open documents and activities in the dock panel.
• Settings: Common JupyterLab settings can be configured using this menu. There is also an Advanced Settings Editor option in the dropdown menu that provides more fine-grained control of JupyterLab settings and configuration options.
• Help: A list of JupyterLab and kernel help links.

A screenshot of the default Menu Bar is provided below.

Left Sidebar

The left sidebar contains a number of commonly-used tabs, such as a file browser (showing the contents of the directory in which the JupyterLab server was launched!), a list of running kernels and terminals, the command palette, and a list of open tabs in the main work area. A screenshot of the default Left Side Bar is provided below.

The left sidebar can be collapsed or expanded by selecting “Show Left Sidebar” in the View menu or by clicking on the active sidebar tab.

Main Work Area

The main work area in JupyterLab enables you to arrange documents (notebooks, text files, etc.) and other activities (terminals, code consoles, etc.) into panels of tabs that can be resized or subdivided. A screenshot of the default Menu Bar is provided below.

Drag a tab to the center of a tab panel to move the tab to the panel. Subdivide a tab panel by dragging a tab to the left, right, top, or bottom of the panel. The work area has a single current activity. The tab for the current activity is marked with a colored top border (blue by default).

Creating a Jupyter Notebook

To open a new notebook click the Python 3 icon under the Notebook header in the Launcher tab in the main work area. You can also create a new notebook by selecting New -> Notebook from the File menu in the Menu Bar.

Additional notes on Jupyter notebooks.

• Notebook files have the extension .ipynb to distinguish them from plain-text Python programs.
• Notebooks can be exported as Python scripts that can be run from the command line.

Below is a screenshot of a Jupyter notebook running inside JupyterLab. If you are interested in more details, then see the official notebook documentation.

How It’s Stored

• The notebook file is stored in a format called JSON.
• Just like a webpage, what’s saved looks different from what you see in your browser.
• But this format allows Jupyter to mix source code, text, and images, all in one file.

Arranging Documents into Panels of Tabs

In the JupyterLab Main Work Area you can arrange documents into panels of tabs. Here is an example from the official documentation:

First, create a text file, Python console, and terminal window and arrange then into three panels in the main work area. Next, create a notebook, terminal window, and text file and arrange then into three panels in the main work area. Finally, create your own combination of panels and tabs. What combination of panels and tabs do you think will be most useful for your workflow?

Solution

After creating the necessary tabs, you can drag one of the tabs to the center of a panel to move the tab to the panel; next you can subdivide a tab panel by dragging a tab to the left, right, top, or bottom of the panel.

Use the Jupyter Notebook for editing and running Python.

• While it’s common to write Python scripts using a text editor, we are going to use the [Jupyter Notebook][jupyter] for the remainder of this workshop.
• This has several advantages:
  • You can easily type, edit, and copy and paste blocks of code.
  • Tab complete allows you to easily access the names of things you are using and learn more about them.
  • It allows you to annotate your code with links, different sized text, bullets, etc. to make it more accessible to you and your collaborators.
  • It allows you to display figures next to the code that produces them to tell a complete story of the analysis.
• Each notebook contains one or more cells that contain code, text, or images.

Code vs. Text

Jupyter mixes code and text in different types of blocks, called cells. We often use the term “code” to mean “the source code of software written in a language such as Python”. A “code cell” in a Notebook is a cell that contains software; a “text cell” is one that contains ordinary prose written for human beings.

The Notebook has Command and Edit modes.

• If you press Esc and Return alternately, the outer border of your code cell will change from gray to blue.
• These are the Command (gray) and Edit (blue) modes of your notebook.
• Command mode allows you to edit notebook-level features, and Edit mode changes the content of cells.
• When in Command mode (esc/gray),
  • The B key will make a new cell below the currently selected cell.
  • The A key will make one above.
  • The X key will delete the current cell.
  • The Z key will undo your last cell operation (which could be a deletion, creation, etc).
• All actions can be done using the menus, but there are lots of keyboard shortcuts to speed things up.

Command Vs. Edit

In the Jupyter notebook page are you currently in Command or Edit mode?
Switch between the modes. Use the shortcuts to generate a new cell. Use the shortcuts to delete a cell. Use the shortcuts to undo the last cell operation you performed.

Solution

Command mode has a grey border and Edit mode has a green border. Use Esc and Return to switch between modes. You need to be in Command mode (Press Esc if your cell is blue). Type B or A. You need to be in Command mode (Press Esc if your cell is blue). Type X. You need to be in Command mode (Press Esc if your cell is blue). Type Z.

Use the keyboard and mouse to select and edit cells.

• Pressing the Return key turns the border blue and engages Edit mode, which allows you to type within the cell.
• Because we want to be able to write many lines of code in a single cell, pressing the Return key when in Edit mode (blue) moves the cursor to the next line in the cell just like in a text editor.
• We need some other way to tell the Notebook we want to run what’s in the cell.
• Pressing Shift+Return together will execute the contents of the cell.
• Notice that the Return and Shift keys on the right of the keyboard are right next to each other.

The Notebook will turn Markdown into pretty-printed documentation.

• Notebooks can also render Markdown.
  • A simple plain-text format for writing lists, links, and other things that might go into a web page.
  • Equivalently, a subset of HTML that looks like what you’d send in an old-fashioned email.
• Turn the current cell into a Markdown cell by entering the Command mode (Esc/gray) and press the M key.
• In [ ]: will disappear to show it is no longer a code cell and you will be able to write in Markdown.
• Turn the current cell into a Code cell by entering the Command mode (Esc/gray) and press the Y key.

The Notebook will evaluate code and display results

• Running a line of code can have several outcomes:
  • Loading data for use in future code
  • Changing the state of the code environment
  • Storing information for use in future code
  • Returning the results without storing them
• Jupyter will display the results of the final line of code in a cell after executing that cell.

Running Python Cells

What is displayed when a Python cell in a notebook that contains several lines of code is executed? For example, what happens when this cell is executed?

import os
os.getcwd()

Solution (for Mac)

Jupyter returns the output of only the last line.

'/Users/your_username'

Running More Python Cells

Why do you think that nothing is displayed when this cell is executed?

current_dir = os.getcwd()

Solution

Jupyter prints the output of the last line. In this case the last line assigned a value to a variable and did not have output.

Python Syntax: =

In order to parse our input, Python has rules about how it should be written. We can use these same rules when reading code to understand what is happening. As different syntaxes appear, we will point them out in these callout boxes.

In Python, the equals sign = works a little differently than in a math class. = assigns a value to variable, like this:

variable = value

A variable is an object that can hold data. We will experiment with this in the next lesson. For now, we can update the value of the variable

current_dir = 'Downloads'

One of the hardest parts of programming is picking good names for your variables. You tend to read code more often than writing, so it’s very useful to use descriptive variable names.

Running Even More Python Cells

How would you display the data stored as current_dir?

Solution

current_dir

'/Users/your_username'

Running the Last Python Cell for this Lesson

What information is stored as current_dir when this cell is executed?

os.chdir('Desktop')
current_dir = os.getcwd()

Solution

current_dir

'/Users/your_username/Desktop'

After changing directories, os.getcwd() returns a different value than before. This value is than stored in the variable cwd.

Change an Existing Cell from Code to Markdown

What happens if you write some Python in a code cell and then you switch it to a Markdown cell? For example, put the following in a code cell:

os.getcwd()

And then run it with Shift+Return to be sure that it works as a code cell. Now go back to the cell and use Esc then M to switch the cell to Markdown and “run” it with Shift+Return. What happened and how might this be useful?

Solution

The Python code gets treated like Markdown text. The lines appear as if they are part of one contiguous paragraph. This could be useful to temporarily turn on and off cells in notebooks that get used for multiple purposes.

os.getcwd()

Closing JupyterLab

• From the Menu Bar select the “File” menu and the choose “Quit” at the bottom of the dropdown menu. You will be prompted to confirm that you wish to shutdown the JupyterLab server (don’t forget to save your work!). Click “Confirm” to shutdown the JupyterLab server.
• To restart the JupyterLab server you will need to click on its tile from the Anaconda browser.

Closing JupyerLab

Practice closing and restarting the JupyterLab server.

Key Points

• Python scripts are plain text files.

• Use the Jupyter Notebook for editing and running Python.

• The Notebook has Command and Edit modes.

• Use the keyboard and mouse to select and edit cells.

• The Notebook will turn Markdown into pretty-printed documentation.