This chapter is taken from book A Primer on Scientific Programming with Python by H. P. Langtangen, 4th edition, Springer, 2014.

Writing IPython notebooks

The IPython notebook is a splendid interactive tool for doing science, but it can also be used as a platform for developing Python code. You can either run it locally on your computer or in a web service like SageMathCloud or Wakari. Installation on your computer is trivial on Ubuntu, just sudo apt-get install ipython-notebook, and also on Windows and Mac by using Anaconda or Enthought Canopy for the Python installation.

The interface to the notebook is a web browser: you write all the code and see all the results in the browser window. There are excellent YouTube videos on how to use the IPython notebook, so here we provide a very quick "step zero" to get anyone started.

A simple program in the notebook

Start the IPython notebook locally by the command ipython notebook or go to SageMathCloud or Wakari as described above. The default input area is a cell for Python code. Type 

g = 9.81
v0 = 5
t = 0.6
y = v0*t - 0.5*g*t**2
in a cell and run the cell by clicking on Run Selected (notebook running locally on your machine) or on the "play" button (notebook running in the cloud). This action will execute the Python code and initialize the variables g, v0, t, and y. You can then write print y in a new cell, execute that cell, and see the output of this statement in the browser. It is easy to go back to a cell, edit the code, and re-execute it.

To download the notebook to your computer, choose the File - Download as menu and select the type of file to be downloaded: the original notebook format (.ipynb file extension) or a plain Python program version of the notebook (.py file extension).

Mixing text, mathematics, code, and graphics

The real strength of IPython notebooks arises when you want to write a report to document how a problem can be explored and solved. As a teaser, open a new notebook, click in the first cell, and choose Markdown as format (notebook running locally) or switch from Code to Markdown in the pull-down menu (notebook in the cloud). The cell is now a text field where you can write text with Markdown syntax. Mathematics can be entered as LaTeX code. Try some text with inline mathematics and an equation on a separate line: 

Plot the curve $y=f(x)$, where

$$
f(x) = e^{-x}\sin (2\pi x),\quad x\in [0, 4]
$$
Execute the cell and you will see nicely typeset mathematics in the browser. In the new cell, add some code to plot \( f(x) \): 

import numpy as np
import matplotlib.pyplot as plt
%matplotlib inline  # make plots inline in the notebook

x = np.linspace(0, 4, 101)
y = np.exp(-x)*np.sin(2*pi*x)
plt.plot(x, y, 'b-')
plt.xlabel('x'); plt.ylabel('y')
Executing these statements results in a plot in the browser, see Figure 2. It was popular to start the notebook by ipython notebook --pylab to import everything from numpy and matplotlib.pyplot and make all plots inline, but the --pylab option is now officially discouraged. If you want the notebook to behave more as MATLAB and not use the np and plt prefix, you can instead of the first three lines above write %pylab.

Figure 2: Example on an IPython notebook.

Different ways of running Python programs

Python programs are compiled and interpreted by another program called python. To run a Python program, you need to tell the operating system that your program is to be interpreted by the python program. This section explains various ways of doing this.

Executing Python programs in iPython

The simplest and most flexible way of executing a Python program is to run it inside IPython. You start IPython either by the command ipython in a terminal window, or by double-clicking the IPython program icon (on Windows). Then, inside IPython, you can run a program prog.py by 

In [1]: run prog.py arg1 arg2
where arg1 and arg2 are command-line arguments.

This method of running Python programs works the same way on all platforms. One additional advantage of running programs under IPython is that you can automatically enter the Python debugger if an exception is raised (see the document Debugging in Python [11]). Although we advocate running Python programs under IPython in this document, you can also run them directly under specific operating systems. This is explained next for Unix, Windows, and Mac OS X.

Executing Python programs in Unix

There are two ways of executing a Python program prog.py in Unix-based systems. The first explicitly tells which Python interpreter to use: 

Unix> python prog.py arg1 arg2
Here, arg1 and arg2 are command-line arguments.

There may be many Python interpreters on your computer system, usually corresponding to different versions of Python or different sets of additional packages and modules. The Python interpreter (python) used in the command above is the first program with the name python appearing in the folders listed in your PATH environment variable. A specific python interpreter, say in /home/hpl/local/bin, can easily be used as default choice by putting this folder name first in the PATH variable. PATH is normally controlled in the .bashrc file. Alternatively, we may specify the interpreter's complete file path when running prog.py: 

Unix> /home/hpl/bin/python prog.py arg1 arg2

The other way of executing Python programs in Unix consists of just writing the name of the file: 

Unix> ./prog.py arg1 arg2
The leading ./ is needed to tell that the program is located in the current folder. You can also just write 

Unix> prog.py arg1 arg2
but then you need to have the dot in the PATH variable, which is not recommended for security reasons.

In the two latter commands there is no information on which Python interpreter to use. This information must be provided in the first line of the program, normally as 

#!/usr/bin/env python
This looks like a comment line, and behaves indeed as a comment line when we run the program as python prog.py. However, when we run the program as ./prog.py, the first line beginning with #! tells the operating system to use the program specified in the rest of the first line to interpret the program. In this example, we use the first python program encountered in the folders in your PATH variable. Alternatively, a specific python program can be specified as 

#!/home/hpl/special/tricks/python

Executing Python programs in Windows

In a DOS or PowerShell window you can always run a Python program by 

PowerShell> python prog.py arg1 arg2
if prog.py is the name of the program, and arg1 and arg2 are command-line arguments. The extension .py can be dropped: 

PowerShell> python prog arg1 arg2
If there are several Python installations on your system, a particular installation can be specified: 

PowerShell> E:\hpl\myprogs\Python2.7.5\python prog arg1 arg2

Files with a certain extension can in Windows be associated with a file type, and a file type can be associated with a particular program to handle the file. For example, it is natural to associate the extension .py with Python programs. The corresponding program needed to interpret .py files is then python.exe. When we write just the name of the Python program file, as in 

PowerShell> prog arg1 arg2
the file is always interpreted by the specified python.exe program. The details of getting .py files to be interpreted by python.exe go as follows: 

PowerShell> assoc .py=PyProg
PowerShell> ftype PyProg=python.exe "%1" %*
Depending on your Python installation, such file extension bindings may already be done. You can check this with 

PowerShell> assoc | find "py"
To see the programs associated with a file type, write ftype name where name is the name of the file type as specified by the assoc command. Writing help ftype and help assoc prints out more information about these commands along with examples.

One can also run Python programs by writing just the basename of the program file, i.e., prog.py instead of prog.py, if the file extension is registered in the PATHEXT environment variable.

Double-clicking Python files

The usual way of running programs in Windows is to double click on the file icon. This does not work well with Python programs without a graphical user interface. When you double click on the icon for a file prog.py, a DOS window is opened, prog.py is interpreted by some python.exe program, and when the program terminates, the DOS window is closed. There is usually too little time for the user to observe the output in this short-lived DOS window.

One can always insert a final statement that pauses the program by waiting for input from the user: 

raw_input('Type CR:')
or 

sys.stdout.write('Type CR:'); sys.stdin.readline()
The program will hang until the user presses the Return key. During this pause the DOS window is visible and you can watch the output from previous statements in the program.

The downside of including a final input statement is that you must always hit Return before the program terminates. This is inconvenient if the program is moved to a Unix-type machine. One possibility is to let this final input statement be active only when the program is run in Windows: 

if sys.platform[:3] == 'win':
    raw_input('Type CR:')

Python programs that have a graphical user interface can be double-clicked in the usual way if the file extension is .pyw.

Executing Python programs in Mac OS X

Since a variant of Unix is used as core in the Mac OS X operating system, you can always launch a Unix terminal and use the techniques from the section Executing Python programs in Unix to run Python programs.

Making a complete stand-alone executable

Python programs need a Python interpreter and usually a set of modules to be installed on the computer system. Sometimes this is inconvenient, for instance when you want to give your program to somebody who does not necessarily have Python or the required set of modules installed.

Fortunately, there are tools that can create a stand-alone executable program out of a Python program. This stand-alone executable can be run on every computer that has the same type of operating system and the same chip type. Such a stand-alone executable is a bundling of the Python interpreter and the required modules, along with your program, in a single file.

The leading tool for creating a stand-alone executable (or alternatively a folder with all necessary files) is PyInstaller. Say you have program myprog.py that you want to distribute to people without the necessary Python environment on their computer. You run 

Terminal> pyinstaller --onefile myprog.py
and a folder dist is created with the (big) stand-alone executable file myprog (or myprog.exe in Windows).

Doing operating system tasks in Python

Python has extensive support for operating system tasks, such as file and folder management. The great advantage of doing operating system tasks in Python and not directly in the operating system is that the Python code works uniformly on Unix/Linux, Windows, and Mac (there are exceptions, but they are few). Below we list some useful operations that can be done inside a Python program or in an interactive session.