Another approach (top-down again)

By albert on 2013-06-28 19:53:55 +0200

One approach to reading a Python story is to identify their building blocks and the ways they can be combined. Another approach is to examine the general structure of a text (also known as "program", "module" or "script").

Earlier I mentioned packages and modules. When you think of a Python program as a story, you might say that a module compares to a story, and a package compares to a book. In terms of this analogy, to read the story (execute the program) we don't need the book (the package) but it's a nice way to keep interrelated stories organized and ship them together.

As so many things, a Python story starts at the top of the page, though not necessarily with the story itself. Sometimes you see some weird looking lines starting with #!:

#! /usr/bin/env python
# -*- coding: utf-8 -*-

They're not really essential for understanding Python, but since they're there, I'll explain them anyway: the first is to tell the system where to find Python, the second is for telling how the text is translated into bits and bytes the way the computer understands them. So they're not so much instructions for you the reader, as they are for the computer the reader. In Python, this type of instructions are kept to a minimum because they interfere with understanding the rest. But this is at the start of the program, so they're easy to ignore.

Another preliminary to the actual story is some text, in the form of a series of comments

# ultimate.py
# a program to end all programs
# usage: lather, rinse and repeat

or plain text enclosed in quotes

""hello.py: a program to say hello to the world

function: print greeting and leave
usage: python hello.py
"""

When well written, one might consider this a summary of what's to follow. The comment form may be nice, but the string form is special. It's called a docstring and it's supposed to explain what the program does, how it's supposed to be invoked and things like that. What's special about docstrings is that they can be shown without opening the program source: Python has special functions for that, like a built-in help function (we'll talk more about this later). So while docstrings aren't essential for the correct functioning of the program, and can be freely left out, they're incredibly useful. Better yet, the docstring trick works also for the building blocks of the program, the functions and classes. More about this later as well.

Next in our story come some sentences that are not so much part of the story, but about what extra stuff is used in building the story. They may not even be there at all but contrary to literary texts, the stuff that other stories contain and we consider well known here, needs to be made known anyway. Thankfully not by rewriting it, but by referring to the other text. In Python, this is done wtith the import statement and there are a few ways this can be done:

import hello
import hello as hi
from hello import greet_function, wave_goodbye_function
from hello import *

The last way has its uses but is generally considered bad taste. Once we know how importing works this will become clear.