When Pythons Attack: Common Mistakes of Python Programmers (1)

This is a reconstruction of a page originally located at oreilly.com. That site went through a purge in summer 2018, which deleted historical pages and redirected their URLs to its new homepage—a page best described as an inane sales pitch for the company's subscription-based website, geared more towards middle management and corporate budgets than to readers of books. In the process, the site dropped both still-read articles and a memorial to a still-respected editor. Whether the cuts were unwitting or crass, history can never be truly erased in a world with web-page saves. For more articles restored, see the list here.

In this article, I will chronicle some of the most common mistakes made by both new and veteran Python programmers, to help you avoid them in your own work.

First of all, I should explain that these come straight from first-hand experience. I earn my living as a Python trainer. Over the last seven years, I've had the privilege of teaching over 100 Python classes, to over 1,000 students — and have watched most of them make the same mistakes. That is, these are things that I've seen real Python beginners do, hundreds of times. In fact, some are so common they are virtually guaranteed to crop up when you are first starting out.

"What's that?" you say. "You can make lots of mistakes in Python, too?" Well, yes. Python may be one of the simplest and most flexible programming languages out there, but it is still a programming language. It still has syntax, datatypes, and the occasional dark corner inhabited by enchanters named Tim.

The good news is that once you learn Python, many pitfalls are avoided naturally, thanks to the clean design of the language. Python has a minimal set of interactions between its components, which helps reduce bugs. It also has a simple syntax, which means there is less opportunity to make mistakes in the first place. And when you do make a mistake, Python's runtime error detection and reporting helps you recover quickly.

But programming Python still isn't quite an automatic task, and forewarned is forearmed. So without further delay, let's jump into the nitty-gritty. The next three sections group mistakes into pragmatics, coding, and programming at large. If you'd like to read more about common Python mistakes and how to avoid them, all of these and more are described further in the new O'Reilly book, Learning Python, 2nd Edition.

Pragmatic Mistakes

Let's start out with the basics; things that people who are just learning how to program tend to get tripped up on, even before they delve into syntax. If you've already done a bit of programming, most of these may seem very simple; if you've ever tried to teach programming to novices, they probably won't.

Type Python Code at the Interactive Prompt

You can type only Python code, and not system commands, at the >>> interactive prompt. It's not that uncommon to see people enter emacs, ls, or edit commands at this prompt, but they are not Python code. There are ways to run system commands from within Python code (for example, os.system and os.popen), but they are not as direct as simply typing the command itself. If you want to launch a Python file from the interactive prompt, use import file, not the system command python file.py.

Print Statements are Required in Files (Only)

Because the interactive interpreter automatically prints the results of expressions, you do not need to type complete print statements interactively. This is a nice feature, but remember that within a code file, you generally must use print statements to see output.

Beware of Automatic Extensions on Windows

If you use the Notepad program to code program files on Windows, be careful to pick type All Files when it comes time to save your file, and give your file a .py suffix explicitly. Otherwise, Notepad saves your file with a .txt extension, making it difficult to run in some launching schemes. Worse, Word and WordPad add formatting characters by default that are not legal Python syntax. As a rule of thumb, always pick All Files and save as simple text on Windows, or use more programmer-friendly text editors such as IDLE. In IDLE, remember to type .py file extensions manually when saving.

Program-File Icon Click Pitfalls on Windows

On Windows, you can launch a Python program file by clicking on it, but this can be error-prone. First of all, the program's output window disappears as soon as the program finishes; to keep it open, try adding a raw_input() call at the bottom of the file. Also, keep in mind that the output window goes away if there is a program error; to see your error messages, run your program in other ways--from a system command line, by interactive imports, with IDLE menu options, and so on.

Imports Work Only the First Time

You can run a file by importing it at the interactive prompt, but this works only once per session; subsequent imports simply return the already-loaded module. To force Python to reload and rerun a file's code, call the reload(module) function instead. And while you're at it, be sure to use parentheses for reload, but not import.

Blank Lines Matter at the Interactive Prompt (Only)

Blank lines and comment lines are always ignored everywhere in module files, but a blank line ends a compound statement when typing code at the interactive prompt. In other words, a blank line tells the interactive prompt that you've finished a compound statement; don't hit the Enter key on a line by itself until you're really done. Conversely, you really do want to type a blank line to terminate the compound statement interactively, before starting a new statement--the interactive prompt runs one statement at a time.

Coding Mistakes

Once you start writing Python code in earnest, the next batch of pitfalls starts becoming more dangerous — these are basic coding mistakes that span language features, and often snare the unwitting programmer.

Don't Forget the Colons

This is easily the most common beginner's coding mistake: don't forget to type a : at the end of compound statement headers (the first line of an if, while, for, etc.). You probably will at first anyhow, but it will soon become an unconscious habit. Typically, 75 percent of students in classes have been burned by this one by the end of the day.

Initialize Your Variables

In Python, you cannot use a name within an expression until it has been assigned a value. This is on purpose: it helps to prevent common typo mistakes, and avoids the ambiguous question of what an automatic default should be (0, None, "", [], ?). Remember to initialize counters to 0, list accumulators to [], and so on.

Start in Column 1

Be sure to start top-level, unnested code all the way to the left, in column 1. That includes unnested code typed into module files, as well as unnested code typed at the interactive prompt. Python uses indentation to delimit blocks of nested code, so white space to the left of your code means a nested block. White space is generally ignored everywhere, except for indentation.

Indent Consistently

Avoid mixing tabs and spaces in the indentation of a given single block, unless you know what every system that touches your code may do with tabs. Otherwise, what you see in your editor may not be what Python sees when it counts tabs as a number of spaces. It's safer to use all tabs or all spaces for each block; how many is up to you.

Always Use Parentheses to Call a Function

You must add parentheses after a function name to call it, whether it takes arguments or not. That is, use function(), not function. Python functions are simply objects that have a special operation, a call, that you trigger with the parentheses. Like all objects, they can also be assigned to variables, and used indirectly: x = function; x().

In Python training, this seems to occur most often with files. It's common to see beginners type file.close to close a file, rather than file.close(); because it's legal to reference a function without calling it, the first version without parenthesis succeeds silently, but does not close the file!

Don't Use Extensions or Paths in Imports

Use directory paths and file extensions in system command lines (e.g.,

python 
dir/mod.py

), but not in import statements. That is, say import mod, not

import 
mod.py

or import dir/mod.py. In practice, this is probably the second most common beginner mistake. Because modules may have other suffixes besides .py (.pyc, for instance), hardcoding a particular suffix is not only illegal syntax, it doesn't make sense.

Platform-specific directory-path syntax comes from your module search path settings, not the import statement. You can use dots in filenames to refer to package subdirectories (e.g., import dir1.dir2.mod), but the leftmost directory still must be found via the module search path, and no other path syntax can appear in imports. The incorrect statement import mod.py is assumed by Python to be a package import--it imports the module mod, and then tries to find a module named py within a directory named mod, and winds up generating a potentially confusing error message.