moving to scripting

Getting started with scripting in Python

Learning objectives

By the end of this tutorial you should: - Understand when and why to use notebooks. - Understand when and why to write Python scripts or modules.

When to use notebooks versus scripts

Jupyter notebooks are a fantastic tool for sharing and demonstrating code, but they are also often misused in ways that limits their effectiveness. As you begin to work on larger projects you will likely encounter this problem, where you eventually reach a stage at which your notebook becomes cluttered with many cell blocks containing functions definitions, but very few cells in the notebook are actually being used to call and explore those functions. Thus, your notebook is serving more as a script than as an interactive document. This is not the intended use for notebooks.

Instead, notebooks are best used as either (1) a scratchpad in which to test code and write functions; or (2) an interactive document for sharing demonstrations of code. The former should be considered a sort of temporary document, something that you use only until the functions have been well tested, at which point you often want to export them to scripts. The second usage is your end product: a publishable interactive tutorial. The best way to reconcile these two forms of usage is to move your polished code (e.g., your many def functions) into a separate set of scripts (a module), which can then be imported into the jupyter notebook.

This is a first step on the way to developing a full-fledged software package in Python.

What is a script?

A script is just a text file that contains computer code. The file can have any name, but will usually end with a suffix that corresponds to the type of code contained within it; for example, Python files should end with .py. Most languages also have a number of additional conventions about how files should be organized into folders, and/or other content in the files that indicates the type of code that is inside of them. These are usually not mandatory, but are good practice.

Python scripts are generally used in two ways: as an executable, meaning that it is meant to be run from the command line; or as an importable module, meaning that it contains code that is meant to be imported and used by another file. A single script can actually serve both of these purposes.

The format of a Python script

Below is an example Python script. It includes the following:

1. shebang: this is the text on the first line of the file. This tells your shell what language the script is written in. It is mostly an older convention, and will have no effect given the way we will write and execute modern Python code.

2. A module level docstring. This is a string at the top of the file that describes the content. This could list the classes or functions that are available to be imported and used from the module, or how to use it as an executable.

3. import statements.

4. The code itself. Here you put class and function definitions.

5. __main__: This is a special section at the bottom of a script where you put executable code. It is optional, not all scripts are meant to be executable. You can put code here that will only be run when the script is called as an executable (see example below), but it will not be run when the file is imported (when the class and functions are loaded by another Python script).

#!/usr/bin/env python
"""
A description of what this script contains.
"""

import builtins

# this is where the module-type code goes
class Example:
    "This is where classes should go"
    def __init__(self):
        pass

def example_func():
    "This is where stand-alone functions should go"
    pass

# this is where executable-type code goes, this code is not 
# executed if this script is only imported.
if __name__ == "__main__":
    print("this code is not run when this file is imported.")

Running a Python script as an executable

There are several ways to execute a Python script. The simplest is to call the python program from your terminal with the script as the target. (Side note, your version of python will usually also have an alias called python3 to make it clear that it is not the older python2). Copy the code above into a script and call it example_script.py. Then execute it in your terminal like below. You can see from this example that the code we wrote in the section called __main__ printed text to stdout, as intended.

python example_script.py

Do not be intimidated by the double underscores in this final section. In Python special variable are often named in this way, and are referred to as dunders. The naming convention is strange, but you get used to it.

---

Continue to the next tutorial.