Learning Python (2013)
Part I. Getting Started
Chapter 3. How You Run Programs
OK, it’s time to start running some code. Now that you have a handle on the program execution model, you’re finally ready to start some real Python programming. At this point, I’ll assume that you have Python installed on your computer; if you don’t, see the start of the prior chapter andAppendix A for installation and configuration hints on various platforms. Our goal here is to learn how to run Python program code.
There are multiple ways to tell Python to execute the code you type. This chapter discusses all the program launching techniques in common use today. Along the way, you’ll learn how to both type code interactively, and how to save it in files to be run as often as you like in a variety of ways: with system command lines, icon clicks, module imports, exec calls, menu options in the IDLE GUI, and more.
As for the previous chapter, if you have prior programming experience and are anxious to start digging into Python itself, you may want to skim this chapter and move on to Chapter 4. But don’t skip this chapter’s early coverage of preliminaries and conventions, its overview of debugging techniques, or its first look at module imports—a topic essential to understanding Python’s program architecture, which we won’t revisit until a later part. I also encourage you to see the sections on IDLE and other IDEs, so you’ll know what tools are available when you start developing more sophisticated Python programs.
The Interactive Prompt
This section gets us started with interactive coding basics. Because it’s our first look at running code, we also cover some preliminaries here, such as setting up a working directory and the system path, so be sure to read this section first if you’re relatively new to programming. This section also explains some conventions used throughout the book, so most readers should probably take at least a quick look here.
Starting an Interactive Session
Perhaps the simplest way to run Python programs is to type them at Python’s interactive command line, sometimes called the interactive prompt. There are a variety of ways to start this command line: in an IDE, from a system console, and so on. Assuming the interpreter is installed as an executable program on your system, the most platform-neutral way to start an interactive interpreter session is usually just to type python at your operating system’s prompt, without any arguments. For example:
% python
Python 3.3.0 (v3.3.0:bd8afb90ebf2, Sep 29 2012, 10:57:17) [MSC v.1600 64 bit ...
Type "help", "copyright", "credits" or "license" for more information.
>>> ^Z
Typing the word “python” at your system shell prompt like this begins an interactive Python session; the “%” character at the start of this listing stands for a generic system prompt in this book—it’s not input that you type yourself. On Windows, a Ctrl-Z gets you out of this session; on Unix, try Ctrl-D instead.
The notion of a system shell prompt is generic, but exactly how you access it varies by platform:
§ On Windows, you can type python in a DOS console window—a program named cmd.exe and usually known as Command Prompt. For more details on starting this program, see this chapter’s sidebar Where Is Command Prompt on Windows?.
§ On Mac OS X, you can start a Python interactive interpreter by double-clicking on Applications→Utilities→Terminal, and then typing python in the window that opens up.
§ On Linux (and other Unixes), you might type this command in a shell or terminal window (for instance, in an xterm or console running a shell such as ksh or csh).
§ Other systems may use similar or platform-specific devices. On handheld devices, for example, you might click the Python icon in the home or application window to launch an interactive session.
On most platforms, you can start the interactive prompt in additional ways that don’t require typing a command, but they vary per platform even more widely:
§ On Windows 7 and earlier, besides typing python in a shell window, you can also begin similar interactive sessions by starting the IDLE GUI (discussed later), or by selecting the “Python (command line)” menu option from the Start button menu for Python, as shown in Figure 2-1 inChapter 2. Both spawn a Python interactive prompt with the same functionality obtained with a “python” command.
§ On Windows 8, you don’t have a Start button (at least as I write this), but there are other ways to get to the tools described in the prior bullet, including tiles, Search, File Explorer, and the “All apps” interface on the Start screen. See Appendix A for more pointers on this platform.
§ Other platforms have similar ways to start a Python interactive session without typing commands, but they’re too specific to get into here; see your system’s documentation for details.
Anytime you see the >>> prompt, you’re in an interactive Python interpreter session—you can type any Python statement or expression here and run it immediately. We will in a moment, but first we need to get a few startup details sorted out to make sure all readers are set to go.
WHERE IS COMMAND PROMPT ON WINDOWS?
So how do you start the command-line interface on Windows? Some Windows readers already know, but Unix developers and beginners may not; it’s not as prominent as terminal or console windows on Unix systems. Here are some pointers on finding your Command Prompt, which vary slightly per Windows version.
On Windows 7 and earlier, this is usually found in the Accessories section of the Start→All Programs menu, or you can run it by typing cmd in the Start→Run... dialog box or the Start menu’s search entry field. You can drag out a desktop shortcut to get to it quicker if desired.
On Windows 8, you can access Command Prompt in the menu opened by right-clicking on the preview in the screen’s lower-left corner; in the Windows System section of the “All apps” display reached by right-clicking your Start screen; or by typing cmd or command prompt in the input field of the Search charm pulled down from the screen’s upper-right corner. There are probably additional routes, and touch screens offer similar access. And if you want to forget all that, pin it to your desktop taskbar for easy access next time around.
These procedures are prone to vary over time, and possibly even per computer and user. I’m trying to avoid making this a book on Windows, though, so I’ll cut this topic short here. When in doubt, try the system Help interface (whose usage may differ as much as the tools it provides help for!).
A note to any Unix users reading this sidebar who may be starting to feel like a fish out of water: you may also be interested in the Cygwin system, which brings a full Unix command prompt to Windows. See Appendix A for more pointers.
The System Path
When we typed python in the last section to start an interactive session, we relied on the fact that the system located the Python program for us on its program search path. Depending on your Python version and platform, if you have not set your system’s PATH environment variable to include Python’s install directory, you may need to replace the word “python” with the full path to the Python executable on your machine. On Unix, Linux, and similar, something like /usr/local/bin/python or /usr/bin/python3 will often suffice. On Windows, try typingC:\Python33\python (for version 3.3):
c:\code> c:\python33\python
Python 3.3.0 (v3.3.0:bd8afb90ebf2, Sep 29 2012, 10:57:17) [MSC v.1600 64 bit ...
Type "help", "copyright", "credits" or "license" for more information.
>>> ^Z
Alternatively, you can run a “cd” change-directory command to go to Python’s install directory before typing python—try the cd c:\python33 command on Windows, for example:
c:\code> cd c:\python33
c:\Python33> python
Python 3.3.0 (v3.3.0:bd8afb90ebf2, Sep 29 2012, 10:57:17) [MSC v.1600 64 bit ...
Type "help", "copyright", "credits" or "license" for more information.
>>> ^Z
But you’ll probably want to set your PATH eventually, so a simple “python” suffices. If you don’t know what PATH is or how to set it, see Appendix A—it covers environment variables like this whose usage varies per platform, as well as Python command-line arguments we won’t be using much in this book. The short story for Windows users: see the Advanced settings in the System entry of your Control Panel. If you’re using Python 3.3 and later, this is now automatic on Windows, as the next section explains.
New Windows Options in 3.3: PATH, Launcher
The foregoing section and much of this chapter at large describe the generic state of play for all 2.X and 3.X Pythons prior to version 3.3. Starting with Python 3.3, the Windows installer has an option to automatically add Python 3.3’s directory to your system PATH, if enabled in the installer’s windows. If you use this option, you won’t need to type a directory path or issue a “cd” to run python commands as in the prior section. Be sure to select this option during the install if you want it, as it’s currently disabled by default.
More dramatically, Python 3.3 for Windows ships with and automatically installs the new Windows launcher—a system that comes with new executable programs, py with a console and pyw without, that are placed in directories on your system path, and so may be run out of the box without any PATH configurations, change-directory commands, or directory path prefixes:
c:\code> py
Python 3.3.0 (v3.3.0:bd8afb90ebf2, Sep 29 2012, 10:57:17) [MSC v.1600 64 bit ...
Type "help", "copyright", "credits" or "license" for more information.
>>> ^Z
c:\code> py −2
Python 2.7.3 (default, Apr 10 2012, 23:24:47) [MSC v.1500 64 bit (AMD64)] ...
Type "help", "copyright", "credits" or "license" for more information.
>>> ^Z
c:\code> py −3.1
Python 3.1.4 (default, Jun 12 2011, 14:16:16) [MSC v.1500 64 bit (AMD64)] ...
Type "help", "copyright", "credits" or "license" for more information.
>>> ^Z
As shown in the last two commands here, these executables also accept Python version numbers on the command line (and in Unix-style #! lines at the top of scripts, as discussed later), and are associated to open Python files when clicked just like the original python executable—which is still available and works as before, but is somewhat superseded by the launcher’s new programs.
The launcher is a standard part of Python 3.3, and is available standalone for use with other versions. We’ll see more on this new launcher in this and later chapters, including a brief look at its #! line support here. However, because it is of interest only to Windows users, and even for this group is present only in 3.3 or where installed separately, I’ve collected almost all of the details about the launcher in Appendix B.
If you’ll be working on Windows under Python 3.3 or later, I suggest taking a brief detour to that appendix now, as it provides an alternative, and in some ways better, way to run Python command lines and scripts. At a base level, launcher users can type py instead of python in most of the system commands shown in this book, and may avoid some configuration steps. Especially on computers with multiple Python versions, though, the new launcher gives you more explicit control over which Python runs your code.
Where to Run: Code Directories
Now that I’ve started showing you how to run code, I want to say a few words up front about where to run code. To keep things simple, in this chapter and book at large I’m going to be running code from a working directory (a.k.a. folder) I’ve created on my Windows computer calledC:\code—a subdirectory at the top of my main drive. That’s where I’ll start most interactive sessions, and where I’ll be both saving and running most script files. This also means the files that examples will create will mostly show up in this directory.
If you’ll be working along, you should probably do something similar before we get started. Here are some pointers if you need help getting set up with a working directory on your computer:
§ On Windows, you can make your working code directory in File Explorer or a Command Prompt window. In File Explorer, look for New Folder, see the File menu, or try a right-click. In Command Prompt, type and run a mkdir command, usually after you cd to your desired parent directory (e.g., cd c\: and mkdir code). Your working directory can be located wherever you like and called whatever you wish, and doesn’t have to be C:\code (I chose this name because it’s short in prompts). But running out of one directory will help you keep track of your work and simplify some tasks. For more Windows hints, see this chapter’s sidebar on Command Prompt, as well as Appendix A.
§ On Unix-based systems (including Mac OS X and Linux), your working directory might be in /usr/home and be created by a mkdir command in a shell window or file explorer GUI specific to your platform, but the same concepts apply. The Cygwin Unix-like system for Windows is similar too, though your directory names may vary (/home and /cygdrive/c are candidates).
You can store your code in Python’s install directory too (e.g., C:\Python33 on Windows) to simplify some command lines before setting PATH, but you probably shouldn’t—this is for Python itself, and your files may not survive a move or uninstall.
Once you’ve made your working directory, always start there to work along with the examples in this book. The prompts in this book that show the directory that I’m running code in will reflect my Windows laptop’s working directory; when you see C:\code> or %, think the location and name of your own directory.
What Not to Type: Prompts and Comments
Speaking of prompts, this book sometimes shows system prompts as a generic %, and sometimes in full C:\code> Windows form. The former is meant to be platform agnostic (and derives from earlier editions’ use of Linux), and the latter is used in Windows-specific contexts. I also add a space after system prompts just for readability in this book. When used, the % character at the start of a system command line stands for the system’s prompt, whatever that may be on your machine. For instance, on my machine % stands for C:\code> in Windows Command Prompt, and just$ in my Cygwn install.
To beginners: don’t type the % character (or the C:\code system prompt it sometimes stands for) you see in this book’s interaction listings yourself—this is text the system prints. Type just the text after these system prompts. Similarly, do not type the >>> and ... characters shown at the start of lines in interpreter interaction listings—these are prompts that Python displays automatically as visual guides for interactive code entry. Type just the text after these Python prompts. For instance, the ... prompt is used for continuation lines in some shells, but doesn’t appear in IDLE, and shows up in some but not all of this book’s listings; don’t type it yourself if it’s absent in your interface.
To help you remember this, user inputs are shown in bold in this book, and prompts are not. In some systems these prompts may differ (for instance, the PyPy performance-focused implementation described in Chapter 2 uses four-character >>>> and ....), but the same rules apply. Also keep in mind that commands typed after these system and Python prompts are meant to be run immediately, and are not generally to be saved in the source files we will be creating; we’ll see why this distinction matters ahead.
In the same vein, you normally don’t need to type text that starts with a # character in listings in this book—as you’ll learn, these are comments, not executable code. Except when # is used to introduce a directive at the top of a script for Unix or the Python 3.3 Windows launcher, you can safely ignore the text that follows it (more on Unix and the launcher later in this chapter and in Appendix B).
NOTE
If you’re working along, interactive listings will drop most “...” continuation prompts as of Chapter 17 to aid cut-and-paste of larger code such as functions and classes from ebooks or other; until then, paste or type one line at a time and omit the prompts. At least initially, it’s important to type code manually, to get a feel for syntax details and errors. Some examples will be listed either by themselves or in named files available in the book’s examples package (per the preface), and we’ll switch between listing formats often; when in doubt, if you see “>>>”, it means the code is being typed interactively.
Running Code Interactively
With those preliminaries out of the way, let’s move on to typing some actual code. However it’s started, the Python interactive session begins by printing two lines of informational text giving the Python version number and a few hints shown earlier (which I’ll omit from most of this book’s examples to save space), then prompts for input with >>> when it’s waiting for you to type a new Python statement or expression.
When working interactively, the results of your code are displayed below the >>> input lines after you press the Enter key. For instance, here are the results of two Python print statements (print is really a function call in Python 3.X, but not in 2.X, so the parentheses here are required in 3.X only):
% python
>>> print('Hello world!')
Hello world!
>>> print(2 ** 8)
256
There it is—we’ve just run some Python code (were you expecting the Spanish Inquisition?). Don’t worry about the details of the print statements shown here yet; we’ll start digging into syntax in the next chapter. In short, they print a Python string and an integer, as shown by the output lines that appear after each >>> input line (2 ** 8 means 2 raised to the power 8 in Python).
When coding interactively like this, you can type as many Python commands as you like; each is run immediately after it’s entered. Moreover, because the interactive session automatically prints the results of expressions you type, you don’t usually need to say “print” explicitly at this prompt:
>>> lumberjack = 'okay'
>>> lumberjack
'okay'
>>> 2 ** 8
256
>>> ^Z # Use Ctrl-D (on Unix) or Ctrl-Z (on Windows) to exit
%
Here, the first line saves a value by assigning it to a variable (lumberjack), which is created by the assignment; and the last two lines typed are expressions (lumberjack and 2 ** 8), whose results are displayed automatically. Again, to exit an interactive session like this and return to your system shell prompt, type Ctrl-D on Unix-like machines, and Ctrl-Z on Windows. In the IDLE GUI discussed later, either type Ctrl-D or simply close the window.
Notice the italicized note about this on the right side of this listing (staring with “#” here). I’ll use these throughout to add remarks about what is being illustrated, but you don’t need to type this text yourself. In fact, just like system and Python prompts, you shouldn’t type this when it’s on a system command line; the “#” part is taken as a comment by Python but may be an error at a system prompt.
Now, we didn’t do much in this session’s code—just typed some Python print and assignment statements, along with a few expressions, which we’ll study in detail later. The main thing to notice is that the interpreter executes the code entered on each line immediately, when the Enter key is pressed.
For example, when we typed the first print statement at the >>> prompt, the output (a Python string) was echoed back right away. There was no need to create a source code file, and no need to run the code through a compiler and linker first, as you’d normally do when using a language such as C or C++. As you’ll see in later chapters, you can also run multiline statements at the interactive prompt; such a statement runs immediately after you’ve entered all of its lines and pressed Enter twice to add a blank line.
Why the Interactive Prompt?
The interactive prompt runs code and echoes results as you go, but it doesn’t save your code in a file. Although this means you won’t do the bulk of your coding in interactive sessions, the interactive prompt turns out to be a great place to both experiment with the language and test program files on the fly.
Experimenting
Because code is executed immediately, the interactive prompt is a perfect place to experiment with the language and will be used often in this book to demonstrate smaller examples. In fact, this is the first rule of thumb to remember: if you’re ever in doubt about how a piece of Python code works, fire up the interactive command line and try it out to see what happens.
For instance, suppose you’re reading a Python program’s code and you come across an expression like 'Spam!' * 8 whose meaning you don’t understand. At this point, you can spend 10 minutes wading through manuals, books, and the Web to try to figure out what the code does, or you can simply run it interactively:
% python
>>> 'Spam!' * 8 # Learning by trying
'Spam!Spam!Spam!Spam!Spam!Spam!Spam!Spam!'
The immediate feedback you receive at the interactive prompt is often the quickest way to deduce what a piece of code does. Here, it’s clear that it does string repetition: in Python * means multiply for numbers, but repeat for strings—it’s like concatenating a string to itself repeatedly (more on strings in Chapter 4).
Chances are good that you won’t break anything by experimenting this way—at least, not yet. To do real damage, like deleting files and running shell commands, you must really try, by importing modules explicitly (you also need to know more about Python’s system interfaces in general before you will become that dangerous!). Straight Python code is almost always safe to run.
For instance, watch what happens when you make a mistake at the interactive prompt:
>>> X # Making mistakes
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
NameError: name 'X' is not defined
In Python, using a variable before it has been assigned a value is always an error—otherwise, if names were filled in with defaults, some errors might go undetected. This means you must initial counters to zero before you can add to them, must initial lists before extending them, and so on; you don’t declare variables, but they must be assigned before you can fetch their values.
We’ll learn more about that later; the important point here is that you don’t crash Python or your computer when you make a mistake this way. Instead, you get a meaningful error message pointing out the mistake and the line of code that made it, and you can continue on in your session or script. In fact, once you get comfortable with Python, its error messages may often provide as much debugging support as you’ll need (you’ll learn more about debugging options in the sidebar Debugging Python Code).
Testing
Besides serving as a tool for experimenting while you’re learning the language, the interactive interpreter is also an ideal place to test code you’ve written in files. You can import your module files interactively and run tests on the tools they define by typing calls at the interactive prompt on the fly.
For instance, the following tests a function in a precoded module that ships with Python in its standard library (it prints the name of the directory you’re currently working in, with a doubled-up backslash that stands for just one), but you can do the same once you start writing module files of your own:
>>> import os
>>> os.getcwd() # Testing on the fly
'c:\\code'
More generally, the interactive prompt is a place to test program components, regardless of their source—you can import and test functions and classes in your Python files, type calls to linked-in C functions, exercise Java classes under Jython, and more. Partly because of its interactive nature, Python supports an experimental and exploratory programming style you’ll find convenient when getting started. Although Python programmers also test with in-file code (and we’ll learn ways to make this simple later in the book), for many, the interactive prompt is still their first line of testing defense.
Usage Notes: The Interactive Prompt
Although the interactive prompt is simple to use, there are a few tips that beginners should keep in mind. I’m including lists of common mistakes like the following in this chapter for reference, but they might also spare you from a few headaches if you read them up front:
§ Type Python commands only. First of all, remember that you can only type Python code at Python’s >>> prompt, not system commands. There are ways to run system commands from within Python code (e.g., with os.system), but they are not as direct as simply typing the commands themselves.
§ print statements are required only in files. 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 it tends to confuse users when they move on to writing code in files: within a code file, you must use print statements to see your output because expression results are not automatically echoed. Remember, you must say print in files, but it’s optional interactively.
§ Don’t indent at the interactive prompt (yet). When typing Python programs, either interactively or into a text file, be sure to start all your unnested statements in column 1 (that is, all the way to the left). If you don’t, Python may print a “SyntaxError” message, because blank space to the left of your code is taken to be indentation that groups nested statements. Until Chapter 10, all statements you write will be unnested, so this includes everything for now. Remember, a leading space generates an error message, so don’t start with a space or tab at the interactive prompt unless it’s nested code.
§ Watch out for prompt changes for compound statements. We won’t meet compound (multiline) statements until Chapter 4 and not in earnest until Chapter 10, but as a preview, you should know that when typing lines 2 and beyond of a compound statement interactively, the prompt may change. In the simple shell window interface, the interactive prompt changes to ... instead of >>> for lines 2 and beyond; in the IDLE GUI interface, lines after the first are instead automatically indented.
You’ll see why this matters in Chapter 10. For now, if you happen to come across a ... prompt or a blank line when entering your code, it probably means that you’ve somehow confused interactive Python into thinking you’re typing a multiline statement. Try hitting the Enter key or a Ctrl-C combination to get back to the main prompt. The >>> and ... prompt strings can also be changed (they are available in the built-in module sys), but I’ll assume they have not been in the book’s example listings.
§ Terminate compound statements at the interactive prompt with a blank line. At the interactive prompt, inserting a blank line (by hitting the Enter key at the start of a line) is necessary to tell interactive Python that you’re done typing the multiline statement. That is, you must press Enter twice to make a compound statement run. By contrast, blank lines are not required in files and are simply ignored if present. If you don’t press Enter twice at the end of a compound statement when working interactively, you’ll appear to be stuck in a limbo state, because the interactive interpreter will do nothing at all—it’s waiting for you to press Enter again!
§ The interactive prompt runs one statement at a time. At the interactive prompt, you must run one statement to completion before typing another. This is natural for simple statements, because pressing the Enter key runs the statement entered. For compound statements, though, remember that you must submit a blank line to terminate the statement and make it run before you can type the next statement.
Entering multiline statements
At the risk of repeating myself, I’ve received multiple emails from readers who’d gotten burned by the last two points, so they probably merit emphasis. I’ll introduce multiline (a.k.a. compound) statements in the next chapter, and we’ll explore their syntax more formally later in this book. Because their behavior differs slightly in files and at the interactive prompt, though, two cautions are in order here.
First, be sure to terminate multiline compound statements like for loops and if tests at the interactive prompt with a blank line. In other words, you must press the Enter key twice, to terminate the whole multiline statement and then make it run. For example (pun not intended):
>>> for x in 'spam':
... print(x) # Press Enter twice here to make this loop run
...
You don’t need the blank line after compound statements in a script file, though; this is required only at the interactive prompt. In a file, blank lines are not required and are simply ignored when present; at the interactive prompt, they terminate multiline statements. Reminder: the ...continuation line prompt in the preceding is printed by Python automatically as a visual guide; it may not appear in your interface (e.g., IDLE), and is sometimes omitted by this book, but do not type it yourself if it’s absent.
Also bear in mind that the interactive prompt runs just one statement at a time: you must press Enter twice to run a loop or other multiline statement before you can type the next statement:
>>> for x in 'spam':
... print(x) # Press Enter twice before a new statement
... print('done')
File "<stdin>", line 3
print('done')
^
SyntaxError: invalid syntax
This means you can’t cut and paste multiple lines of code into the interactive prompt, unless the code includes blank lines after each compound statement. Such code is better run in a file—which brings us to the next section’s topic.
System Command Lines and Files
Although the interactive prompt is great for experimenting and testing, it has one big disadvantage: programs you type there go away as soon as the Python interpreter executes them. Because the code you type interactively is never stored in a file, you can’t run it again without retyping it from scratch. Cut-and-paste and command recall can help some here, but not much, especially when you start writing larger programs. To cut and paste code from an interactive session, you would have to edit out Python prompts, program outputs, and so on—not exactly a modern software development methodology!
To save programs permanently, you need to write your code in files, which are usually known as modules. Modules are simply text files containing Python statements. Once they are coded, you can ask the Python interpreter to execute the statements in such a file any number of times, and in a variety of ways—by system command lines, by file icon clicks, by options in the IDLE user interface, and more. Regardless of how it is run, Python executes all the code in a module file from top to bottom each time you run the file.
Terminology in this domain can vary somewhat. For instance, module files are often referred to as programs in Python—that is, a program is considered to be a series of precoded statements stored in a file for repeated execution. Module files that are run directly are also sometimes calledscripts—an informal term usually meaning a top-level program file. Some reserve the term “module” for a file imported from another file, and “script” for the main file of a program; we generally will here, too (though you’ll have to stay tuned for more on the meaning of “top-level,” imports, and main files later in this chapter).
Whatever you call them, the next few sections explore ways to run code typed into module files. In this section, you’ll learn how to run files in the most basic way: by listing their names in a python command line entered at your computer’s system prompt. Though it might seem primitive to some—and can often be avoided altogether by using a GUI like IDLE, discussed later—for many programmers a system shell command-line window, together with a text editor window, constitutes as much of an integrated development environment as they will ever need, and provides more direct control over programs.
A First Script
Let’s get started. Open your favorite text editor (e.g., vi, Notepad, or the IDLE editor), type the following statements into a new text file named script1.py, and save it in your working code directory that you set up earlier:
# A first Python script
import sys # Load a library module
print(sys.platform)
print(2 ** 100) # Raise 2 to a power
x = 'Spam!'
print(x * 8) # String repetition
This file is our first official Python script (not counting the two-liner in Chapter 2). You shouldn’t worry too much about this file’s code, but as a brief description, this file:
§ Imports a Python module (libraries of additional tools), to fetch the name of the platform
§ Runs three print function calls, to display the script’s results
§ Uses a variable named x, created when it’s assigned, to hold onto a string object
§ Applies various object operations that we’ll begin studying in the next chapter
The sys.platform here is just a string that identifies the kind of computer you’re working on; it lives in a standard Python module called sys, which you must import to load (again, more on imports later).
For color, I’ve also added some formal Python comments here—the text after the # characters. I mentioned these earlier, but should be more formal now that they’re showing up in scripts. Comments can show up on lines by themselves, or to the right of code on a line. The text after a # is simply ignored as a human-readable comment and is not considered part of the statement’s syntax. If you’re copying this code, you can ignore the comments; they are just informative. In this book, we usually use a different formatting style to make comments more visually distinctive, but they’ll appear as normal text in your code.
Again, don’t focus on the syntax of the code in this file for now; we’ll learn about all of it later. The main point to notice is that you’ve typed this code into a file, rather than at the interactive prompt. In the process, you’ve coded a fully functional Python script.
Notice that the module file is called script1.py. As for all top-level files, it could also be called simply script, but files of code you want to import into a client have to end with a .py suffix. We’ll study imports later in this chapter. Because you may want to import them in the future, it’s a good idea to use .py suffixes for most Python files that you code. Also, some text editors detect Python files by their .py suffix; if the suffix is not present, you may not get features like syntax colorization and automatic indentation.
Running Files with Command Lines
Once you’ve saved this text file, you can ask Python to run it by listing its full filename as the first argument to a python command like the following typed at the system shell prompt (don’t type this at Python’s interactive prompt, and read on to the next paragraph if this doesn’t work right away for you):
% python script1.py
win32
1267650600228229401496703205376
Spam!Spam!Spam!Spam!Spam!Spam!Spam!Spam!
Again, you can type such a system shell command in whatever your system provides for command-line entry—a Windows Command Prompt window, an xterm window, or similar. But be sure to run this in the same working directory where you’ve saved your script file (“cd” there first if needed), and be sure to run this at the system prompt, not Python’s “>>>” prompt. Also remember to replace the command’s word “python” with a full directory path as we did before if your PATH setting is not configured, though this isn’t required for the “py” Windows launcher program, and may not be required in 3.3 and later.
Another note to beginners: do not type any of the preceding text in the script1.py source file you created in the prior section. This text is a system command and program output, not program code. The first line here is the shell command used to run the source file, and the lines following it are the results produced by the source file’s print statements. And again, remember that the % stands for the system prompt—don’t type it yourself (not to nag, but it’s a remarkably common early mistake).
If all works as planned, this shell command makes Python run the code in this file line by line, and you will see the output of the script’s three print statements—the name of the underlying platform as known Python, 2 raised to the power 100, and the result of the same string repetition expression we saw earlier (again, more on the meaning of the last two of these in Chapter 4).
If all didn’t work as planned, you’ll get an error message—make sure you’ve entered the code in your file exactly as shown, and try again. The next section has additional options and pointers on this process, and we’ll talk about debugging options in the sidebar Debugging Python Code, but at this point in the book your best bet is probably rote imitation. And if all else fails, you might also try running under the IDLE GUI discussed ahead—a tool that sugarcoats some launching details, though sometimes at the expense of the more explicit control you have when using command lines.
You can also fetch the code examples off the Web if copying grows too tedious or error-prone, though typing some code initially will help you learn to avoid syntax errors. See the preface for details on how to obtain the book’s example files.
Command-Line Usage Variations
Because this scheme uses shell command lines to start Python programs, all the usual shell syntax applies. For instance, you can route the printed output of a Python script to a file to save it for later use or inspection by using special shell syntax:
% python script1.py > saveit.txt
In this case, the three output lines shown in the prior run are stored in the file saveit.txt instead of being printed. This is generally known as stream redirection; it works for input and output text and is available on Windows and Unix-like systems. This is nice for testing, as you can write programs that watch for changes in other programs’ outputs. It also has little to do with Python, though (Python simply supports it), so we will skip further details on shell redirection syntax here.
If you are working on a Windows platform, this example works the same, but the system prompt is normally different as described earlier:
C:\code> python script1.py
win32
1267650600228229401496703205376
Spam!Spam!Spam!Spam!Spam!Spam!Spam!Spam!
As usual, if you haven’t set your PATH environment variable to include the full directory path to python, be sure to include this in your command, or run a change-directory command to go to the path first:
C:\code> C:\python33\python script1.py
win32
1267650600228229401496703205376
Spam!Spam!Spam!Spam!Spam!Spam!Spam!Spam!
Alternatively, if you’re using the Windows launcher new in Python 3.3 (described earlier), a py command will have the same effect, but does not require a directory path or PATH settings, and allows you to specify Python version numbers on the command line too:
c:\code> py −3 script1.py
win32
1267650600228229401496703205376
Spam!Spam!Spam!Spam!Spam!Spam!Spam!Spam!
On all recent versions of Windows, you can also type just the name of your script, and omit the name of Python itself. Because newer Windows systems use the Windows Registry (a.k.a. filename associations) to find a program with which to run a file, you don’t need to name “python” or “py” on the command line explicitly to run a .py file. The prior command, for example, could be simplified to the following on most Windows machines, and will automatically be run by python prior to 3.3, and by py in 3.3 and later—just as though you had clicked on the file’s icon in Explorer (more on this option ahead):
C:\code> script1.py
Finally, remember to give the full path to your script file if it lives in a different directory from the one in which you are working. For example, the following system command line, run from D:\other, assumes Python is in your system path but runs a file located elsewhere:
C:\code> cd D:\other
D:\other> python c:\code\script1.py
If your PATH doesn’t include Python’s directory, you’re not using the Windows launcher’s py program, and neither Python nor your script file is in the directory you’re working in, use full paths for both:
D:\other> C:\Python33\python c:\code\script1.py
Usage Notes: Command Lines and Files
Running program files from system command lines is a fairly straightforward launch option, especially if you are familiar with command lines in general from prior work. It’s also perhaps the most portable way to run Python programs since nearly every computer has some notion of a command line and directory structure. For newcomers, though, here are a few pointers about common beginner traps that might help you avoid some frustration:
§ Beware of automatic extensions on Windows and IDLE. If you use the Notepad program to code program files on Windows, be careful to pick the type All Files when it comes time to save your file, and give the file a .py suffix explicitly. Otherwise, Notepad will save your file with a.txt extension (e.g., as script1.py.txt), making it difficult to use in some schemes; it won’t be importable, for example.
Worse, Windows hides file extensions by default, so unless you have changed your view options you may not even notice that you’ve coded a text file and not a Python file. The file’s icon may give this away—if it doesn’t have a snake of some sort on it, you may have trouble. Uncolored code in IDLE and files that open to edit instead of run when clicked are other symptoms of this problem.
Microsoft Word similarly adds a .doc extension by default; much worse, it adds formatting characters that are not legal Python syntax. As a rule of thumb, always pick All Files when saving under Windows, or use a more programmer-friendly text editor such as IDLE. IDLE does noteven add a .py suffix automatically—a feature some programmers tend to like, but some users do not.
§ Use file extensions and directory paths at system prompts, but not for imports. Don’t forget to type the full name of your file in system command lines—that is, use python script1.py rather than python script1. By contrast, Python’s import statements, which we’ll meet later in this chapter, omit both the .py file suffix and the directory path (e.g., import script1). This may seem trivial, but confusing these two is a common mistake.
At the system prompt, you are in a system shell, not Python, so Python’s module file search rules do not apply. Because of that, you must include both the .py extension and, if necessary, the full directory path leading to the file you wish to run. For instance, to run a file that resides in a different directory from the one in which you are working, you would typically list its full path (e.g., python d:\tests\spam.py). Within Python code, however, you can just say import spam and rely on the Python module search path to locate your file, as described later.
§ Use print statements in files. Yes, we’ve already been over this, but it is such a common mistake that it’s worth repeating at least once here. Unlike in interactive coding, you generally must use print statements to see output from program files. If you don’t see any output, make sure you’ve said “print” in your file. print statements are not required in an interactive session, since Python automatically echoes expression results; prints don’t hurt here, but are superfluous typing.
Unix-Style Executable Scripts: #!
Our next launching technique is really a specialized form of the prior, which, despite this section’s title, can apply to program files run on both Unix and Windows today. Since it has its roots on Unix, let’s begin this story there.
Unix Script Basics
If you are going to use Python on a Unix, Linux, or Unix-like system, you can also turn files of Python code into executable programs, much as you would for programs coded in a shell language such as csh or ksh. Such files are usually called executable scripts. In simple terms, Unix-style executable scripts are just normal text files containing Python statements, but with two special properties:
§ Their first line is special. Scripts usually start with a line that begins with the characters #! (often called “hash bang” or “shebang”), followed by the path to the Python interpreter on your machine.
§ They usually have executable privileges. Script files are usually marked as executable to tell the operating system that they may be run as top-level programs. On Unix systems, a command such as chmod +x file.py usually does the trick.
Let’s look at an example for Unix-like systems. Use your text editor again to create a file of Python code called brian:
#!/usr/local/bin/python
print('The Bright Side ' + 'of Life...') # + means concatenate for strings
The special line at the top of the file tells the system where the Python interpreter lives. Technically, the first line is a Python comment. As mentioned earlier, all comments in Python programs start with a # and span to the end of the line; they are a place to insert extra information for human readers of your code. But when a comment such as the first line in this file appears, it’s special on Unix because the operating system shell uses it to find an interpreter for running the program code in the rest of the file.
Also, note that this file is called simply brian, without the .py suffix used for the module file earlier. Adding a .py to the name wouldn’t hurt (and might help you remember that this is a Python program file), but because you don’t plan on letting other modules import the code in this file, the name of the file is irrelevant. If you give the file executable privileges with a chmod +x brian shell command, you can run it from the operating system shell as though it were a binary program (for the following, either make sure ., the current directory, is in your system PATH setting, or run this with ./brian):
% brian
The Bright Side of Life...
The Unix env Lookup Trick
On some Unix systems, you can avoid hardcoding the path to the Python interpreter in your script file by writing the special first-line comment like this:
#!/usr/bin/env python
...script goes here...
When coded this way, the env program locates the Python interpreter according to your system search path settings (in most Unix shells, by looking in all the directories listed in your PATH environment variable). This scheme can be more portable, as you don’t need to hardcode a Python install path in the first line of all your scripts. That way, if your scripts ever move to a new machine, or your Python ever moves to a new location, you must update just PATH, not all your scripts.
Provided you have access to env everywhere, your scripts will run no matter where Python lives on your system. In fact, this env form is generally recommended today over even something as generic as /usr/bin/python, because some platforms may install Python elsewhere. Of course, this assumes that env lives in the same place everywhere (on some machines, it may be in /sbin, /bin, or elsewhere); if not, all portability bets are off!
The Python 3.3 Windows Launcher: #! Comes to Windows
A note for Windows users running Python 3.2 and earlier: the method described here is a Unix trick, and it may not work on your platform. Not to worry; just use the basic command-line technique explored earlier. List the file’s name on an explicit python command line:[5]
C:\code> python brian
The Bright Side of Life...
In this case, you don’t need the special #! comment at the top (although Python just ignores it if it’s present), and the file doesn’t need to be given executable privileges. In fact, if you want to run files portably between Unix and Microsoft Windows, your life will probably be simpler if you always use the basic command-line approach, not Unix-style scripts, to launch programs.
If you’re using Python 3.3 or later, though, or have its Windows launcher installed separately, it turns out that Unix-style #! lines do mean something on Windows too. Besides offering the py executable described earlier, the new Windows launcher mentioned earlier attempts to parse #!lines to determine which Python version to launch to run your script’s code. Moreover, it allows you to give the version number in full or partial forms, and recognizes most common Unix patterns for this line, including the /usr/bin/env form.
The launcher’s #! parsing mechanism is applied when you run scripts from command lines with the py program, and when you click Python file icons (in which case py is run implicitly by filename associations). Unlike Unix, you do not need to mark files with executable privileges for this to work on Windows, because filename associations achieve similar results.
For example, the first of the following is run by Python 3.X and the second by 2.X (without an explicit number, the launcher defaults to 2.X unless you set a PY_PYTHON environment variable):
c:\code> type robin3.py
#!/usr/bin/python3
print('Run', 'away!...') # 3.X function
c:\code> py robin3.py # Run file per #! line version
Run away!...
c:\code> type robin2.py
#!python2
print 'Run', 'away more!...' # 2.X statement
c:\code> py robin2.py # Run file per #! line version
Run away more!...
This works in addition to passing versions on command lines—we saw this briefly earlier for starting the interactive prompt, but it works the same when launching a script file:
c:\code> py −3.1 robin3.py # Run per command-line argument
Run away!...
The net effect is that the launcher allows Python versions to be specified on both a per-file and per-command basis, by using #! lines and command-line arguments, respectively. At least that’s the very short version of the launcher’s story. If you’re using Python 3.3 or later on Windows or may in the future, I recommend a side trip to the full launcher story in Appendix B if you haven’t made one already.
[5] As we discussed when exploring command lines, all recent Windows versions also let you type just the name of a .py file at the system command line—they use the Registry to determine that the file should be opened with Python (e.g., typing brian.py is equivalent to typing python brian.py). This command-line mode is similar in spirit to the Unix #!, though it is system-wide on Windows, not per-file. It also requires an explicit .py extension: filename associations won’t work without it. Some programs may actually interpret and use a first #! line on Windows much like on Unix (including Python 3.3’s Windows launcher), but the system shell on Windows itself simply ignores it.
Clicking File Icons
If you’re not a fan of command lines, you can generally avoid them by launching Python scripts with file icon clicks, development GUIs, and other schemes that vary per platform. Let’s take a quick look at the first of these alternatives here.
Icon-Click Basics
Icon clicks are supported on most platforms in one form or another. Here’s a rundown of how these might be structured on your computer:
Windows icon clicks
On Windows, the Registry makes opening files with icon clicks easy. When installed, Python uses Windows filename associations to automatically register itself to be the program that opens Python program files when they are clicked. Because of that, it is possible to launch the Python programs you write by simply clicking (or double-clicking) on their file icons with your mouse cursor.
Specifically, a clicked file will be run by one of two Python programs, depending on its extension and the Python you’re running. In Pythons 3.2 and earlier, .py files are run by python.exe with a console (Command Prompt) window, and .pyw files are run by pythonw.exe files without a console. Byte code files are also run by these programs if clicked. Per Appendix B, in Python 3.3 and later (and where it’s installed separately), the new Window’s launchers’s py.exe and pyw.exe programs serve the same roles, opening .py and .pyw files, respectively.
Non-Windows icon clicks
On non-Windows systems, you will probably be able to perform a similar feat, but the icons, file explorer navigation schemes, and more may differ slightly. On Mac OS X, for instance, you might use PythonLauncher in the MacPython (or Python N.M) folder of your Applications folder to run by clicking in Finder.
On some Linux and other Unix systems, you may need to register the .py extension with your file explorer GUI, make your script executable using the #! line scheme of the preceding section, or associate the file MIME type with an application or command by editing files, installing programs, or using other tools. See your file explorer’s documentation for more details.
In other words, icon clicks generally work as you’d expect for your platform, but be sure to see the platform usage documentation “Python Setup and Usage” in Python’s standard manual set for more details as needed.
Clicking Icons on Windows
To illustrate, let’s keep using the script we wrote earlier, script1.py, repeated here to minimize page flipping:
# A first Python script
import sys # Load a library module
print(sys.platform)
print(2 ** 100) # Raise 2 to a power
x = 'Spam!'
print(x * 8) # String repetition
As we’ve seen, you can always run this file from a system command line:
C:\code> python script1.py
win32
1267650600228229401496703205376
Spam!Spam!Spam!Spam!Spam!Spam!Spam!Spam!
However, icon clicks allow you to run the file without any typing at all. To do so, you have to find this file’s icon on your computer. On Windows 8, you might right-click the screen’s lower-left corner to open a File Explorer. On earlier Windows, you can select Computer (or My Computer in XP) in your Start button’s menu. There are additional ways to open a file explorer; once you do, work your way down on the C drive to your working directory.
At this point, you should have a file explorer window similar to that captured in Figure 3-1 (Windows 8 is being used here). Notice how the icons for Python files show up:
§ Source files have white backgrounds on Windows.
§ Byte code files show with black backgrounds.
Per the prior chapter, I created the byte code file in this figure by importing in Python 3.1; 3.2 and later instead store byte code files in the __pycache__ subdirectory also shown here, which I created by importing in 3.3 too. You will normally want to click (or otherwise run) the white source code files in order to pick up your most recent changes, not the byte code files—Python won’t check the source code file for changes if you launch byte code directly. To launch the file here, simply click on the icon for script1.py.
Figure 3-1. On Windows, Python program files show up as icons in file explorer windows and can automatically be run with a double-click of the mouse (though you might not see printed output or error messages this way).
The input Trick on Windows
Unfortunately, on Windows, the result of clicking on a file icon may not be incredibly satisfying. In fact, as it is, this example script might generate a perplexing “flash” when clicked—not exactly the sort of feedback that budding Python programmers usually hope for! This is not a bug, but has to do with the way the Windows version of Python handles printed output.
By default, Python generates a pop-up black DOS console window (Command Prompt) to serve as a clicked file’s input and output. If a script just prints and exits, well, it just prints and exits—the console window appears, and text is printed there, but the console window closes and disappears on program exit. Unless you are very fast, or your machine is very slow, you won’t get to see your output at all. Although this is normal behavior, it’s probably not what you had in mind.
Luckily, it’s easy to work around this. If you need your script’s output to stick around when you launch it with an icon click, simply put a call to the built-in input function at the very bottom of the script in 3.X (in 2.X use the name raw_input instead: see the note ahead). For example:
# A first Python script
import sys # Load a library module
print(sys.platform)
print(2 ** 100) # Raise 2 to a power
x = 'Spam!'
print(x * 8) # String repetition
input() # <== ADDED
In general, input reads and returns the next line of standard input, waiting if there is none yet available. The net effect in this context will be to pause the script, thereby keeping the output window shown in Figure 3-2 open until you press the Enter key.
Figure 3-2. When you click a program’s icon on Windows, you will be able to see its printed output if you include an input call at the very end of the script. But you only need to do so in this one context!
Now that I’ve shown you this trick, keep in mind that it is usually only required for Windows, and then only if your script prints text and exits and only if you will launch the script by clicking its file icon. You should add this call to the bottom of your top-level files if and only if all of these three conditions apply. There is no reason to add this call in any other contexts, such as scripts you’ll run in command lines or the IDLE GUI (unless you’re unreasonably fond of pressing your computer’s Enter key!).[6] That may sound obvious, but it’s been another common mistake in live classes.
Before we move ahead, note that the input call applied here is the input counterpart of using the print function (and 2.X statement) for outputs. It is the simplest way to read user input, and it is more general than this example implies. For instance, input:
§ Optionally accepts a string that will be printed as a prompt (e.g., input('Press Enter to exit'))
§ Returns to your script a line of text read as a string (e.g., nextinput = input())
§ Supports input stream redirections at the system shell level (e.g., python spam.py < input.txt), just as the print statement does for output
We’ll use input in more advanced ways later in this text; for instance, Chapter 10 will apply it in an interactive loop. For now, it will help you see the output of simple scripts that you click to launch.
NOTE
Version skew note: If you are working in Python 2.X, use raw_input() instead of input() in this code. The former was renamed to the latter in Python 3.X. Technically, 2.X has an input function too, but it also evaluates strings as though they are program code typed into a script, and so will not work in this context (an empty string is an error). Python 3.X’s input (and 2.X’sraw_input) simply returns the entered text as a character string, unevaluated. To simulate 2.X’s input in 3.X, use eval(input()).
Be aware, though, that because this runs the entered text as though it were program code, this may have security implications that we’ll largely ignore here, except to say that you should trust the source of the entered text; if you don’t, stick to just plain input in 3.X and raw_input in 2.X.
Other Icon-Click Limitations
Even with the prior section’s input trick, clicking file icons is not without its perils. You also may not get to see Python error messages. If your script generates an error, the error message text is written to the pop-up console window—which then immediately disappears! Worse, adding aninput call to your file will not help this time because your script will likely abort long before it reaches this call. In other words, you won’t be able to tell what went wrong.
When we discuss exceptions later in this book, you’ll learn that it is possible to write code to intercept, process, and recover from errors so that they do not terminate your programs. Watch for the discussion of the try statement later in this book for an alternative way to keep the console window from closing on errors. We’ll also learn how to redirect printed text to files for later inspection when we study print operations. Barring such support in your code, though, errors and prints disappear for clicked programs.
Because of these limitations, it is probably best to view icon clicks as a way to launch programs after they have been debugged, or have been instrumented to write their output to a file and catch and process any important errors. Especially when you’re starting out, I recommend using other techniques—such as system command lines and IDLE (discussed further in the section The IDLE User Interface)—so that you can see generated error messages and view your normal output without resorting to extra coding.
[6] Conversely, it is also possible to completely suppress the pop-up console window (a.k.a. Command Prompt) for clicked files on Windows when you don’t want to see printed text. Files whose names end in a .pyw extension will display only windows constructed by your script, not the default console window. .pyw files are simply .py source files that have this special operational behavior on Windows. They are mostly used for Python-coded user interfaces that build windows of their own, often in conjunction with various techniques for saving printed output and errors to files. As implied earlier, Python achieves this when it is installed by associating a special executable (pythonw.exe in 3.2 and earlier and pyw.exe as of 3.3) to open .pyw files when clicked.
Module Imports and Reloads
So far, I’ve been talking about “importing modules” without really explaining what this term means. We’ll study modules and larger program architecture in depth in Part V, but because imports are also a way to launch programs, this section will introduce enough module basics to get you started.
Import and Reload Basics
In simple terms, every file of Python source code whose name ends in a .py extension is a module. No special code or syntax is required to make a file a module: any such file will do. Other files can access the items a module defines by importing that module—import operations essentially load another file and grant access to that file’s contents. The contents of a module are made available to the outside world through its attributes (a term I’ll define in the next section).
This module-based services model turns out to be the core idea behind program architecture in Python. Larger programs usually take the form of multiple module files, which import tools from other module files. One of the modules is designated as the main or top-level file, or “script”—the file launched to start the entire program, which runs line by line as usual. Below this level, it’s all modules importing modules.
We’ll delve into such architectural issues in more detail later in this book. This chapter is mostly interested in the fact that import operations run the code in a file that is being loaded as a final step. Because of this, importing a file is yet another way to launch it.
For instance, if you start an interactive session (from a system command line or otherwise), you can run the script1.py file you created earlier with a simple import (be sure to delete the input line you added in the prior section first, or you’ll need to press Enter for no reason):
C:\code> C:\python33\python
>>> import script1
win32
1267650600228229401496703205376
Spam!Spam!Spam!Spam!Spam!Spam!Spam!Spam!
This works, but only once per session (really, process—a program run) by default. After the first import, later imports do nothing, even if you change and save the module’s source file again in another window:
...Change script1.py in a text edit window to print 2 ** 16...
>>> import script1
>>> import script1
This is by design; imports are too expensive an operation to repeat more than once per file, per program run. As you’ll learn in Chapter 22, imports must find files, compile them to byte code, and run the code.
If you really want to force Python to run the file again in the same session without stopping and restarting the session, you need to instead call the reload function available in the imp standard library module (this function is also a simple built-in in Python 2.X, but not in 3.X):
>>> from imp import reload # Must load from module in 3.X (only)
>>> reload(script1)
win32
65536
Spam!Spam!Spam!Spam!Spam!Spam!Spam!Spam!
<module 'script1' from '.\\script1.py'>
>>>
The from statement here simply copies a name out of a module (more on this soon). The reload function itself loads and runs the current version of your file’s code, picking up changes if you’ve modified and saved it in another window.
This allows you to edit and pick up new code on the fly within the current Python interactive session. In this session, for example, the second print statement in script1.py was changed in another window to print 2 ** 16 between the time of the first import and the reload call—hence the different result.
The reload function expects the name of an already loaded module object, so you have to have successfully imported a module once before you reload it (if the import reported an error, you can’t yet reload and must import again). Notice that reload also expects parentheses around the module object name, whereas import does not. reload is a function that is called, and import is a statement.
That’s why you must pass the module name to reload as an argument in parentheses, and that’s why you get back an extra output line when reloading—the last output line is just the display representation of the reload call’s return value, a Python module object. We’ll learn more about using functions in general in Chapter 16; for now, when you hear “function,” remember that parentheses are required to run a call.
NOTE
Version skew note: Python 3.X moved the reload built-in function to the imp standard library module. It still reloads files as before, but you must import it in order to use it. In 3.X, run an import imp and use imp.reload(M), or run a from imp import reload and use reload(M), as shown here. We’ll discuss import and from statements in the next section, and more formally later in this book.
If you are working in Python 2.X, reload is available as a built-in function, so no import is required. In Python 2.6 and 2.7, reload is available in both forms—built-in and module function—to aid the transition to 3.X. In other words, reloading is still available in 3.X, but an extra line of code is required to fetch the reload call.
The move in 3.X was likely motivated in part by some well-known issues involving reload and from statements that we’ll encounter in the next section. In short, names loaded with a from are not directly updated by a reload, but names accessed with an import statement are. If your names don’t seem to change after a reload, try using import and module.attribute name references instead.
The Grander Module Story: Attributes
Imports and reloads provide a natural program launch option because import operations execute files as a last step. In the broader scheme of things, though, modules serve the role of libraries of tools, as you’ll learn in detail in Part V. The basic idea is straightforward, though: a module is mostly just a package of variable names, known as a namespace, and the names within that package are called attributes. An attribute is simply a variable name that is attached to a specific object (like a module).
In more concrete terms, importers gain access to all the names assigned at the top level of a module’s file. These names are usually assigned to tools exported by the module—functions, classes, variables, and so on—that are intended to be used in other files and other programs. Externally, a module file’s names can be fetched with two Python statements, import and from, as well as the reload call.
To illustrate, use a text editor to create a one-line Python module file called myfile.py in your working directory, with the following contents:
title = "The Meaning of Life"
This may be one of the world’s simplest Python modules (it contains a single assignment statement), but it’s enough to illustrate the point. When this file is imported, its code is run to generate the module’s attribute. That is, the assignment statement creates a variable and module attribute named title.
You can access this module’s title attribute in other components in two different ways. First, you can load the module as a whole with an import statement, and then qualify the module name with the attribute name to fetch it (note that we’re letting the interpreter print automatically here):
% python # Start Python
>>> import myfile # Run file; load module as a whole
>>> myfile.title # Use its attribute names: '.' to qualify
'The Meaning of Life'
In general, the dot expression syntax object.attribute lets you fetch any attribute attached to any object, and is one of the most common operations in Python code. Here, we’ve used it to access the string variable title inside the module myfile—in other words, myfile.title.
Alternatively, you can fetch (really, copy) names out of a module with from statements:
% python # Start Python
>>> from myfile import title # Run file; copy its names
>>> title # Use name directly: no need to qualify
'The Meaning of Life'
As you’ll see in more detail later, from is just like an import, with an extra assignment to names in the importing component. Technically, from copies a module’s attributes, such that they become simple variables in the recipient—thus, you can simply refer to the imported string this time as title (a variable) instead of myfile.title (an attribute reference).[7]
Whether you use import or from to invoke an import operation, the statements in the module file myfile.py are executed, and the importing component (here, the interactive prompt) gains access to names assigned at the top level of the file. There’s only one such name in this simple example—the variable title, assigned to a string—but the concept will be more useful when you start defining objects such as functions and classes in your modules: such objects become reusable software components that can be accessed by name from one or more client modules.
In practice, module files usually define more than one name to be used in and outside the files. Here’s an example that defines three:
a = 'dead' # Define three attributes
b = 'parrot' # Exported to other files
c = 'sketch'
print(a, b, c) # Also used in this file (in 2.X: print a, b, c)
This file, threenames.py, assigns three variables, and so generates three attributes for the outside world. It also uses its own three variables in a 3.X print statement, as we see when we run this as a top-level file (in Python 2.X print differs slightly, so omit its outer parenthesis to match the output here exactly; watch for a more complete explanation of this in Chapter 11):
% python threenames.py
dead parrot sketch
All of this file’s code runs as usual the first time it is imported elsewhere, by either an import or from. Clients of this file that use import get a module with attributes, while clients that use from get copies of the file’s names:
% python
>>> import threenames # Grab the whole module: it runs here
dead parrot sketch
>>>
>>> threenames.b, threenames.c # Access its attributes
('parrot', 'sketch')
>>>
>>> from threenames import a, b, c # Copy multiple names out
>>> b, c
('parrot', 'sketch')
The results here are printed in parentheses because they are really tuples—a kind of object created by the comma in the inputs (and covered in the next part of this book)—that you can safely ignore for now.
Once you start coding modules with multiple names like this, the built-in dir function starts to come in handy—you can use it to fetch a list of all the names available inside a module. The following returns a Python list of strings in square brackets (we’ll start studying lists in the next chapter):
>>> dir(threenames)
['__builtins__', '__doc__', '__file__', '__name__', '__package__', 'a', 'b', 'c']
The contents of this list have been edited here because they vary per Python version. The point to notice here is that when the dir function is called with the name of an imported module in parentheses like this, it returns all the attributes inside that module. Some of the names it returns are names you get “for free”: names with leading and trailing double underscores (__X__) are built-in names that are always predefined by Python and have special meaning to the interpreter, but they aren’t important at this point in this book. The variables our code defined by assignment—a, b, and c—show up last in the dir result.
Modules and namespaces
Module imports are a way to run files of code, but, as we’ll expand on later in the book, modules are also the largest program structure in Python programs, and one of the first key concepts in the language.
As we’ve seen, Python programs are composed of multiple module files linked together by import statements, and each module file is a package of variables—that is, a namespace. Just as importantly, each module is a self-contained namespace: one module file cannot see the names defined in another file unless it explicitly imports that other file. Because of this, modules serve to minimize name collisions in your code—because each file is a self-contained namespace, the names in one file cannot clash with those in another, even if they are spelled the same way.
In fact, as you’ll see, modules are one of a handful of ways that Python goes to great lengths to package your variables into compartments to avoid name clashes. We’ll discuss modules and other namespace constructs—including local scopes defined by classes and functions—further later in the book. For now, modules will come in handy as a way to run your code many times without having to retype it, and will prevent your file’s names from accidentally replacing each other.
NOTE
import versus from: I should point out that the from statement in a sense defeats the namespace partitioning purpose of modules—because the from copies variables from one file to another, it can cause same-named variables in the importing file to be overwritten, and won’t warn you if it does. This essentially collapses namespaces together, at least in terms of the copied variables.
Because of this, some recommend always using import instead of from. I won’t go that far, though; not only does from involve less typing (an asset at the interactive prompt), but its purported problem is relatively rare in practice. Besides, this is something you control by listing the variables you want in the from; as long as you understand that they’ll be assigned to values in the target module, this is no more dangerous than coding assignment statements—another feature you’ll probably want to use!
Usage Notes: import and reload
For some reason, once people find out about running files using import and reload, many tend to focus on this alone and forget about other launch options that always run the current version of the code (e.g., icon clicks, IDLE menu options, and system command lines). This approach can quickly lead to confusion, though—you need to remember when you’ve imported to know if you can reload, you need to remember to use parentheses when you call reload (only), and you need to remember to use reload in the first place to get the current version of your code to run. Moreover, reloads aren’t transitive—reloading a module reloads that module only, not any modules it may import—so you sometimes have to reload multiple files.
Because of these complications (and others we’ll explore later, including the reload/from issue mentioned briefly in a prior note in this chapter), it’s generally a good idea to avoid the temptation to launch by imports and reloads for now. The IDLE Run→Run Module menu option described in the next section, for example, provides a simpler and less error-prone way to run your files, and always runs the current version of your code. System shell command lines offer similar benefits. You don’t need to use reload if you use any of these other techniques.
In addition, you may run into trouble if you use modules in unusual ways at this point in the book. For instance, if you want to import a module file that is stored in a directory other than the one you’re working in, you’ll have to skip ahead to Chapter 22 and learn about the module search path. For now, if you must import, try to keep all your files in the directory you are working in to avoid complications.[8]
That said, imports and reloads have proven to be a popular testing technique in Python classes, and you may prefer using this approach too. As usual, though, if you find yourself running into a wall, stop running into a wall!
[7] Notice that import and from both list the name of the module file as simply myfile without its .py extension suffix. As you’ll learn in Part V, when Python looks for the actual file, it knows to include the suffix in its search procedure. Again, you must include the .py suffix in system shell command lines, but not in import statements.
[8] If you’re too curious to wait, the short story is that Python searches for imported modules in every directory listed in sys.path—a Python list of directory name strings in the sys module, which is initialized from a PYTHONPATH environment variable, plus a set of standard directories. If you want to import from a directory other than the one you are working in, that directory must generally be listed in your PYTHONPATH setting. For more details, see Chapter 22 and Appendix A.
Using exec to Run Module Files
Strictly speaking, there are more ways to run code stored in module files than have yet been presented here. For instance, the exec(open('module.py').read()) built-in function call is another way to launch files from the interactive prompt without having to import and later reload. Each such exec runs the current version of the code read from a file, without requiring later reloads (script1.py is as we left it after a reload in the prior section):
% python
>>> exec(open('script1.py').read())
win32
65536
Spam!Spam!Spam!Spam!Spam!Spam!Spam!Spam!
...Change script1.py in a text edit window to print 2 ** 32...
>>> exec(open('script1.py').read())
win32
4294967296
Spam!Spam!Spam!Spam!Spam!Spam!Spam!Spam!
The exec call has an effect similar to an import, but it doesn’t actually import the module—by default, each time you call exec this way it runs the file’s code anew, as though you had pasted it in at the place where exec is called. Because of that, exec does not require module reloads after file changes—it skips the normal module import logic.
On the downside, because it works as if you’ve pasted code into the place where it is called, exec, like the from statement mentioned earlier, has the potential to silently overwrite variables you may currently be using. For example, our script1.py assigns to a variable named x. If that name is also being used in the place where exec is called, the name’s value is replaced:
>>> x = 999
>>> exec(open('script1.py').read()) # Code run in this namespace by default
...same output...
>>> x # Its assignments can overwrite names here
'Spam!'
By contrast, the basic import statement runs the file only once per process, and it makes the file a separate module namespace so that its assignments will not change variables in your scope. The price you pay for the namespace partitioning of modules is the need to reload after changes.
NOTE
Version skew note: Python 2.X also includes an execfile('module.py') built-in function, in addition to allowing the form exec(open('module.py')), which both automatically read the file’s content. Both of these are equivalent to the exec(open('module.py').read()) form, which is more complex but runs in both 2.X and 3.X.
Unfortunately, neither of these two simpler 2.X forms is available in 3.X, which means you must understand both files and their read methods to fully understand this technique today (this seems to be a case of aesthetics trouncing practicality in 3.X). In fact, the exec form in 3.X involves so much typing that the best advice may simply be not to do it—it’s usually easier to launch files by typing system shell command lines or by using the IDLE menu options described in the next section.
For more on the file interfaces used by the 3.X exec form, see Chapter 9. For more on exec and its cohorts, eval and compile, see Chapter 10 and Chapter 25.
The IDLE User Interface
So far, we’ve seen how to run Python code with the interactive prompt, system command lines, Unix-style scripts, icon clicks, module imports, and exec calls. If you’re looking for something a bit more visual, IDLE provides a graphical user interface for doing Python development, and it’s a standard and free part of the Python system. IDLE is usually referred to as an integrated development environment (IDE), because it binds together various development tasks into a single view.[9]
In short, IDLE is a desktop GUI that lets you edit, run, browse, and debug Python programs, all from a single interface. It runs portably on most Python platforms, including Microsoft Windows, X Windows (for Linux, Unix, and Unix-like platforms), and the Mac OS (both Classic and OS X). For many, IDLE represents an easy-to-use alternative to typing command lines, a less problem-prone alternative to clicking on icons, and a great way for newcomers to get started editing and running code. You’ll sacrifice some control in the bargain, but this typically becomes important later in your Python career.
IDLE Startup Details
Most readers should be able to use IDLE immediately, as it is a standard component on Mac OS X and most Linux installations today, and is installed automatically with standard Python on Windows. Because platforms specifics vary, though, I need to give a few pointers before we open the GUI.
Technically, IDLE is a Python program that uses the standard library’s tkinter GUI toolkit (named Tkinter in Python 2.X) to build its windows. This makes IDLE portable—it works the same on all major desktop platforms—but it also means that you’ll need to have tkinter support in your Python to use IDLE. This support is standard on Windows, Macs, and Linux, but it comes with a few caveats on some systems, and startup can vary per platform. Here are a few platform-specific tips:
§ On Windows 7 and earlier, IDLE is easy to start—it’s always present after a Python install, and has an entry in the Start button menu for Python in Windows 7 and earlier (see Figure 2-1, shown previously). You can also select it by right-clicking on a Python program icon, and launch it by clicking on the icon for the files idle.pyw or idle.py located in the idlelib subdirectory of Python’s Lib directory. In this mode, IDLE is a clickable Python script that lives in C:\Python33\Lib\idlelib, C:\Python27\Lib\idlelib, or similar, which you can drag out to a shortcut for one-click access if desired.
§ On Windows 8, look for IDLE in your Start tiles, by a search for “idle,” by browsing your “All apps” Start screen display, or by using File Explorer to find the idle.py file mentioned earlier. You may want a shortcut here, as you have no Start button menu in desktop mode (at least today; see Appendix A for more pointers).
§ On Mac OS X everything required for IDLE is present as standard components in your operating system. IDLE should be available to launch in Applications under the MacPython (or Python N.M) program folder. One note here: some OS X versions may require installing updated tkinter support due to subtle version dependencies I’ll spare readers from here; see python.org’s Download page for details.
§ On Linux IDLE is also usually present as a standard component today. It might take the form of an idle executable or script in your path; type this in a shell to check. On some machines, it may require an install (see Appendix A for pointers), and on others you may need to launch IDLE’s top-level script from a command line or icon click: run the file idle.py located in the idlelib subdirectory of Python’s /usr/lib directory (run a find for the exact location).
Because IDLE is just a Python script on the module search path in the standard library, you can also generally run it on any platform and from any directory by typing the following in a system command shell window (e.g., in a Command Prompt on Windows), though you’ll have to seeAppendix A for more on Python’s –m flag, and Part V for more on the “.” package syntax required here (blind trust will suffice at this point in the book):
c:\code> python -m idlelib.idle # Run idle.py in a package on module path
For more on install issues and usage notes for Windows and other platforms, be sure to see both Appendix A as well as the notes for your platform in “Python Setup and Usage” in Python’s standard manuals.
IDLE Basic Usage
Let’s jump into an example. Figure 3-3 shows the scene after you start IDLE on Windows. The Python shell window that opens initially is the main window, which runs an interactive session (notice the >>> prompt). This works like all interactive sessions—code you type here is run immediately after you type it—and serves as a testing and experimenting tool.
Figure 3-3. The main Python shell window of the IDLE development GUI, shown here running on Windows. Use the File menu to begin (New Window) or change (Open...) a source file; use the text edit window’s Run menu to run the code in that window (Run Module).
IDLE uses familiar menus with keyboard shortcuts for most of its operations. To make a new script file under IDLE, use File→New: in the main shell window, select the File pull-down menu, and pick New to open a new text edit window where you can type, save, and run your file’s code. Use File→Open... instead to open a new text edit window displaying an existing file’s code to edit and run.
Although it may not show up fully in this book’s graphics, IDLE uses syntax-directed colorization for the code typed in both the main window and all text edit windows—keywords are one color, literals are another, and so on. This helps give you a better picture of the components in your code (and can even help you spot mistakes—run-on strings are all one color, for example).
To run a file of code that you are editing in IDLE, use Run→Run Module in that file’s text edit window. That is, select the file’s text edit window, open that window’s Run pull-down menu, and choose the Run Module option listed there (or use the equivalent keyboard shortcut, given in the menu). Python will let you know that you need to save your file first if you’ve changed it since it was opened or last saved and forgot to save your changes—a common mistake when you’re knee-deep in coding.
When run this way, the output of your script and any error messages it may generate show up back in the main interactive window (the Python shell window). In Figure 3-3, for example, the three lines after the “RESTART” line near the middle of the window reflect an execution of ourscript1.py file opened in a separate edit window. The “RESTART” message tells us that the user-code process was restarted to run the edited script and serves to separate script output (it does not appear if IDLE is started without a user-code subprocess—more on this mode in a moment).
IDLE Usability Features
Like most GUIs, the best way to learn IDLE may be to test-drive it for yourself, but some key usage points seem to be less than obvious. For example, if you want to repeat prior commands in IDLE’s main interactive window, you can use the Alt-P key combination to scroll backward through the command history, and Alt-N to scroll forward (on some Macs, try Ctrl-P and Ctrl-N instead). Your prior commands will be recalled and displayed, and may be edited and rerun.
You can also recall commands by positioning the cursor on them and clicking and pressing Enter to insert their text at the input prompt, or using standard cut-and-paste operations, though these techniques tend to involve more steps (and can sometimes be triggered accidentally). Outside IDLE, you may be able to recall commands in an interactive session with the arrow keys on Windows.
Besides command history and syntax colorization, IDLE has additional usability features such as:
§ Auto-indent and unindent for Python code in the editor (Backspace goes back one level)
§ Word auto-completion while typing, invoked by a Tab press
§ Balloon help pop ups for a function call when you type its opening “(”
§ Pop-up selection lists of object attributes when you type a “.” after an object’s name and either pause or press Tab
Some of these may not work on every platform, and some can be configured or disabled if you find that their defaults get in the way of your personal coding style.
Advanced IDLE Tools
Besides the basic edit and run functions and the prior section’s usability tools, IDLE provides more advanced features, including a point-and-click program graphical debugger and an object browser. The IDLE debugger is enabled via the Debug menu and the object browser via the File menu. The browser allows you to navigate through the module search path to files and objects in files; clicking on a file or object opens the corresponding source in a text edit window.
You initiate IDLE debugging by selecting the Debug→Debugger menu option in the main window and then starting your script by selecting the Run→Run Module option in the text edit window; once the debugger is enabled, you can set breakpoints in your code that stop its execution by right-clicking on lines in the text edit windows, show variable values, and so on. You can also watch program execution when debugging—the current line of code is noted as you step through your code.
For simpler debugging operations, you can also right-click with your mouse on the text of an error message to quickly jump to the line of code where the error occurred—a trick that makes it simple and fast to repair and run again. In addition, IDLE’s text editor offers a large collection of programmer-friendly tools, including advanced text and file search operations we won’t cover here. Because IDLE uses intuitive GUI interactions, you should experiment with the system live to get a feel for its other tools.
Usage Notes: IDLE
IDLE is free, easy to use, portable, and automatically available on most platforms. I generally recommend it to Python newcomers because it simplifies some startup details and does not assume prior experience with system command lines. However, it is somewhat limited compared to more advanced commercial IDEs, and may seem heavier than a command line to some. To help you avoid some common pitfalls, here is a list of issues that IDLE beginners should bear in mind:
§ You must add “.py” explicitly when saving your files. I mentioned this when talking about files in general, but it’s a common IDLE stumbling block, especially for Windows users. IDLE does not automatically add a .py extension to filenames when files are saved. Be careful to type the.py extension yourself when saving a file for the first time. If you don’t, while you will be able to run your file from IDLE (and system command lines), you will not be able to import it either interactively or from other modules.
§ Run scripts by selecting Run→Run Module in text edit windows, not by interactive imports and reloads. Earlier in this chapter, we saw that it’s possible to run a file by importing it interactively. However, this scheme can grow complex because it requires you to manually reload files after changes. By contrast, using the Run→Run Module menu option in IDLE always runs the most current version of your file, just like running it using a system shell command line. IDLE also prompts you to save your file first, if needed (another common mistake outside IDLE).
§ You need to reload only modules being tested interactively. Like system shell command lines, IDLE’s Run→Run Module menu option always runs the current version of both the top-level file and any modules it imports. Because of this, Run→Run Module eliminates common confusions surrounding imports. You need to reload only modules that you are importing and testing interactively in IDLE. If you choose to use the import and reload technique instead of Run→Run Module, remember that you can use the Alt-P/Alt-N key combinations to recall prior commands.
§ You can customize IDLE. To change the text fonts and colors in IDLE, select the Configure option in the Options menu of any IDLE window. You can also customize key combination actions, indentation settings, autocompletions, and more; see IDLE’s Help pull-down menu for more hints.
§ There is currently no clear-screen option in IDLE. This seems to be a frequent request (perhaps because it’s an option available in similar IDEs), and it might be added eventually. Today, though, there is no way to clear the interactive window’s text. If you want the window’s text to go away, you can either press and hold the Enter key, or type a Python loop to print a series of blank lines (nobody really uses the latter technique, of course, but it sounds more high-tech than pressing the Enter key!).
§ tkinter GUI and threaded programs may not work well with IDLE. Because IDLE is a Python/tkinter program, it can hang if you use it to run certain types of advanced Python/tkinter programs. This has become less of an issue in more recent versions of IDLE that run user code in one process and the IDLE GUI itself in another, but some programs (especially those that use multithreading) might still hang the GUI. Even just calling the tkinter quit function in your code, the normal way to exit a GUI program, may be enough to cause your program’s GUI to hang if run in IDLE (destroy may be better here only). Your code may not exhibit such problems, but as a rule of thumb, it’s always safe to use IDLE to edit GUI programs but launch them using other options, such as icon clicks or system command lines. When in doubt, if your code fails in IDLE, try it outside the GUI.
§ If connection errors arise, try starting IDLE in single-process mode. This issue appears to have gone away in recent Pythons, but may still impact readers using older versions. Because IDLE requires communication between its separate user and GUI processes, it can sometimes have trouble starting up on certain platforms (notably, it fails to start occasionally on some Windows machines, due to firewall software that blocks connections). If you run into such connection errors, it’s always possible to start IDLE with a system command line that forces it to run in single-process mode without a user-code subprocess and therefore avoids communication issues: its -n command-line flag forces this mode. On Windows, for example, start a Command Prompt window and run the system command line idle.py -n from within the directoryC:\Python33\Lib\idlelib (cd there first if needed). A python -m idlelib.idle –n command works from anywhere (see Appendix A for –m).
§ Beware of some IDLE usability features. IDLE does much to make life easier for beginners, but some of its tricks won’t apply outside the IDLE GUI. For instance, IDLE runs your scripts in its own interactive namespace, so variables in your code show up automatically in the IDLE interactive session—you don’t always need to run import commands to access names at the top level of files you’ve already run. This can be handy, but it can also be confusing, because outside the IDLE environment names must always be imported from files explicitly to be used.
When you run a file of code, IDLE also automatically changes to that file’s directory and adds it to the module import search path—a handy feature that allows you to use files and import modules there without search path settings, but also something that won’t work the same when you run files outside IDLE. It’s OK to use such features, but don’t forget that they are IDLE behavior, not Python behavior.
[9] IDLE is officially a corruption of IDE, but it’s really named in honor of Monty Python member Eric Idle. See Chapter 1 if you’re not sure why.
Other IDEs
Because IDLE is free, portable, and a standard part of Python, it’s a nice first development tool to become familiar with if you want to use an IDE at all. Again, I recommend that you use IDLE for this book’s exercises if you’re just starting out, unless you are already familiar with and prefer a command-line-based development mode. There are, however, a handful of alternative IDEs for Python developers, some of which are substantially more powerful and robust than IDLE. Apart from IDLE, here are some of Python’s most commonly used IDEs:
Eclipse and PyDev
Eclipse is an advanced open source IDE GUI. Originally developed as a Java IDE, Eclipse also supports Python development when you install the PyDev (or a similar) plug-in. Eclipse is a popular and powerful option for Python development, and it goes well beyond IDLE’s feature set. It includes support for code completion, syntax highlighting, syntax analysis, refactoring, debugging, and more. Its downsides are that it is a large system to install and may require shareware extensions for some features (this may vary over time). Still, when you are ready to graduate from IDLE, the Eclipse/PyDev combination is worth your attention.
Komodo
A full-featured development environment GUI for Python (and other languages), Komodo includes standard syntax coloring, text editing, debugging, and other features. In addition, Komodo offers many advanced features that IDLE does not, including project files, source-control integration, and regular-expression debugging. At this writing, Komodo is not free, but see the Web for its current status—it is available at http://www.activestate.com from ActiveState, which also offers the ActivePython distribution package mentioned in Appendix A.
NetBeans IDE for Python
NetBeans is a powerful open source development environment GUI with support for many advanced features for Python developers: code completion, automatic indentation and code colorization, editor hints, code folding, refactoring, debugging, code coverage and testing, projects, and more. It may be used to develop both CPython and Jython code. Like Eclipse, NetBeans requires installation steps beyond those of the included IDLE GUI, but it is seen by many as more than worth the effort. Search the Web for the latest information and links.
PythonWin
PythonWin is a free Windows-only IDE for Python that ships as part of ActiveState’s ActivePython distribution (and may also be fetched separately from http://www.python.org resources). It is roughly like IDLE, with a handful of useful Windows-specific extensions added; for example, PythonWin has support for COM objects. Today, IDLE is probably more advanced than PythonWin (for instance, IDLE’s dual-process architecture often prevents it from hanging). However, PythonWin still offers tools for Windows developers that IDLE does not. Seehttp://www.activestate.com for more information.
Wing, Visual Studio, and others
Other IDEs are popular among Python developers too, including the mostly commercial Wing IDE, Microsoft Visual Studio via a plug-in, and PyCharm, PyScripter, Pyshield, and Spyder—but I do not have space to do justice to them here, and more will undoubtedly appear over time. In fact, almost every programmer-friendly text editor has some sort of support for Python development these days, whether it be preinstalled or fetched separately. Emacs and Vim, for instance, have substantial Python support.
IDE choices are often subjective, so I encourage you to browse to find tools that fit your development style and goals. For more information, see the resources available at http://www.python.org or search the Web for “Python IDE” or similar. A search for “Python editors” today leads you to a wiki page that maintains information about dozens of IDE and text-editor options for Python programming.
Other Launch Options
At this point, we’ve seen how to run code typed interactively, and how to launch code saved in files in a variety of ways—system command lines, icon clicks, imports and execs, GUIs like IDLE, and more. That covers most of the techniques in common use, and enough to run the code you’ll see in this book. There are additional ways to run Python code, though, most of which have special or narrow roles. For completeness and reference, the next few sections take a quick look at some of these.
Embedding Calls
In some specialized domains, Python code may be run automatically by an enclosing system. In such cases, we say that the Python programs are embedded in (i.e., run by) another program. The Python code itself may be entered into a text file, stored in a database, fetched from an HTML page, parsed from an XML document, and so on. But from an operational perspective, another system—not you—may tell Python to run the code you’ve created.
Such an embedded execution mode is commonly used to support end-user customization—a game program, for instance, might allow for play modifications by running user-accessible embedded Python code at strategic points in time. Users can modify this type of system by providing or changing Python code. Because Python code is interpreted, there is no need to recompile the entire system to incorporate the change (see Chapter 2 for more on how Python code is run).
In this mode, the enclosing system that runs your code might be written in C, C++, or even Java when the Jython system is used. As an example, it’s possible to create and run strings of Python code from a C program by calling functions in the Python runtime API (a set of services exported by the libraries created when Python is compiled on your machine):
#include <Python.h>
...
Py_Initialize(); // This is C, not Python
PyRun_SimpleString("x = 'brave ' + 'sir robin'"); // But it runs Python code
In this C code snippet, a program coded in the C language embeds the Python interpreter by linking in its libraries, and passes it a Python assignment statement string to run. C programs may also gain access to Python modules and objects and process or execute them using other Python API tools.
This book isn’t about Python/C integration, but you should be aware that, depending on how your organization plans to use Python, you may or may not be the one who actually starts the Python programs you create. Regardless, you can usually still use the interactive and file-based launching techniques described here to test code in isolation from those enclosing systems that may eventually use it.[10]
Frozen Binary Executables
Frozen binary executables, described in Chapter 2, are packages that combine your program’s byte code and the Python interpreter into a single executable program. This approach enables Python programs to be launched in the same ways that you would launch any other executable program (icon clicks, command lines, etc.). While this option works well for delivery of products, it is not really intended for use during program development; you normally freeze just before shipping (after development is finished). See the prior chapter for more on this option.
Text Editor Launch Options
As mentioned previously, although they’re not full-blown IDE GUIs, most programmer-friendly text editors have support for editing, and possibly running, Python programs. Such support may be built in or fetchable on the Web. For instance, if you are familiar with the Emacs text editor, you can do all your Python editing and launching from inside that text editor. See the text editor resources page at http://www.python.org/editors for more details, or search the Web for the phrase “Python editors.”
Still Other Launch Options
Depending on your platform, there may be additional ways that you can start Python programs. For instance, on some Macintosh systems you may be able to drag Python program file icons onto the Python interpreter icon to make them execute, and on some Windows systems you can always start Python scripts with the Run... option in the Start menu. Additionally, the Python standard library has utilities that allow Python programs to be started by other Python programs in separate processes (e.g., os.popen, os.system), and Python scripts might also be spawned in larger contexts like the Web (for instance, a web page might invoke a script on a server); however, these are beyond the scope of the present chapter.
Future Possibilities?
This chapter reflects current practice, but much of the material is both platform- and time-specific. Indeed, many of the execution and launch details presented arose during the shelf life of this book’s various editions. As with program execution options, it’s not impossible that new program launch options may arise over time.
New operating systems, and new versions of existing systems, may also provide execution techniques beyond those outlined here. In general, because Python keeps pace with such changes, you should be able to launch Python programs in whatever way makes sense for the machines you use, both now and in the future—be that by swiping on tablet PCs and smartphones, grabbing icons in a virtual reality, or shouting a script’s name over your coworkers’ conversations.
Implementation changes may also impact launch schemes somewhat (e.g., a full compiler could produce normal executables that are launched much like frozen binaries today). If I knew what the future truly held, though, I would probably be talking to a stockbroker instead of writing these words!
[10] See Programming Python (O’Reilly) for more details on embedding Python in C/C++. The embedding API can call Python functions directly, load modules, and more. Also, note that the Jython system allows Java programs to invoke Python code using a Java-based API (a Python interpreter class).
Which Option Should I Use?
With all these options, true beginners might naturally ask: which one is best for me? In general, you should give the IDLE interface a try if you are just getting started with Python. It provides a user-friendly GUI environment and hides some of the underlying configuration details. It also comes with a platform-neutral text editor for coding your scripts, and it’s a standard and free part of the Python system.
If, on the other hand, you are an experienced programmer, you might be more comfortable with simply the text editor of your choice in one window, and another window for launching the programs you edit via system command lines and icon clicks (in fact, this is how I develop Python programs, but I have a Unix-biased distant past). Because the choice of development environments is very subjective, I can’t offer much more in the way of universal guidelines. In general, whatever environment you like to use will be the best for you to use.
DEBUGGING PYTHON CODE
Naturally, none of my readers or students ever have bugs in their code (insert smiley here), but for less fortunate friends of yours who may, here’s a quick review of the strategies commonly used by real-world Python programmers to debug code, for you to refer to as you start coding in earnest:
§ Do nothing. By this, I don’t mean that Python programmers don’t debug their code—but when you make a mistake in a Python program, you get a very useful and readable error message (you’ll get to see some soon, if you haven’t already). If you already know Python, and especially for your own code, this is often enough—read the error message, and go fix the tagged line and file. For many, this is debugging in Python. It may not always be ideal for larger systems you didn’t write, though.
§ Insert print statements. Probably the main way that Python programmers debug their code (and the way that I debug Python code) is to insert print statements and run again. Because Python runs immediately after changes, this is usually the quickest way to get more information than error messages provide. The print statements don’t have to be sophisticated—a simple “I am here” or display of variable values is usually enough to provide the context you need. Just remember to delete or comment out (i.e., add a # before) the debugging prints before you ship your code!
§ Use IDE GUI debuggers. For larger systems you didn’t write, and for beginners who want to trace code in more detail, most Python development GUIs have some sort of point-and-click debugging support. IDLE has a debugger too, but it doesn’t appear to be used very often in practice—perhaps because it has no command line, or perhaps because adding print statements is usually quicker than setting up a GUI debugging session. To learn more, see IDLE’s Help, or simply try it on your own; its basic interface is described in the section Advanced IDLE Tools. Other IDEs, such as Eclipse, NetBeans, Komodo, and Wing IDE, offer advanced point-and-click debuggers as well; see their documentation if you use them.
§ Use the pdb command-line debugger. For ultimate control, Python comes with a source code debugger named pdb, available as a module in Python’s standard library. In pdb, you type commands to step line by line, display variables, set and clear breakpoints, continue to a breakpoint or error, and so on. You can launch pdb interactively by importing it, or as a top-level script. Either way, because you can type commands to control the session, it provides a powerful debugging tool. pdb also includes a postmortem function (pdb.pm()) that you can run after an exception occurs, to get information from the time of the error. See the Python library manual and Chapter 36 for more details on pdb, and Appendix A for an example or running pdb as a script with Python’s–m command argument.
§ Use Python’s –i command-line argument. Short of adding prints or running under pdb, you can still see what went wrong on errors. If you run your script from a command line and pass a -i argument between python and the name of your script (e.g., python –i m.py), Python will enter into its interactive interpreter mode (the >>> prompt) when your script exits, whether it ends successfully or runs into an error. At this point, you can print the final values of variables to get more details about what happened in your code because they are in the top-level namespace. You can also then import and run the pdb debugger for even more context; its postmortem mode will let you inspect the latest error if your script failed. Appendix A also shows -i in action.
§ Other options. For more specific debugging requirements, you can find additional tools in the open source domain, including support for multithreaded programs, embedded code, and process attachment. The Winpdb system, for example, is a standalone debugger with advanced debugging support and cross-platform GUI and console interfaces.
These options will become more important as we start writing larger scripts. Probably the best news on the debugging front, though, is that errors are detected and reported in Python, rather than passing silently or crashing the system altogether. In fact, errors themselves are a well-defined mechanism known as exceptions, which you can catch and process (more on exceptions in Part VII). Making mistakes is never fun, of course, but take it from someone who recalls when debugging meant getting out a hex calculator and poring over piles of memory dump printouts: Python’s debugging support makes errors much less painful than they might otherwise be.
Chapter Summary
In this chapter, we’ve looked at common ways to launch Python programs: by running code typed interactively, and by running code stored in files with system command lines, file icon clicks, module imports, exec calls, and IDE GUIs such as IDLE. We’ve covered a lot of pragmatic startup territory here. This chapter’s goal was to equip you with enough information to enable you to start writing some code, which you’ll do in the next part of the book. There, we will start exploring the Python language itself, beginning with its core data types—the objects that are the subjects of your programs.
First, though, take the usual chapter quiz to exercise what you’ve learned here. Because this is the last chapter in this part of the book, it’s followed with a set of more complete exercises that test your mastery of this entire part’s topics. For help with the latter set of problems, or just for a refresher, be sure to turn to Appendix D after you’ve given the exercises a try.
Test Your Knowledge: Quiz
1. How can you start an interactive interpreter session?
2. Where do you type a system command line to launch a script file?
3. Name four or more ways to run the code saved in a script file.
4. Name two pitfalls related to clicking file icons on Windows.
5. Why might you need to reload a module?
6. How do you run a script from within IDLE?
7. Name two pitfalls related to using IDLE.
8. What is a namespace, and how does it relate to module files?
Test Your Knowledge: Answers
1. You can start an interactive session on Windows 7 and earlier by clicking your Start button, picking the All Programs option, clicking the Python entry, and selecting the “Python (command line)” menu option. You can also achieve the same effect on Windows and other platforms by typing python as a system command line in your system’s console window (a Command Prompt window on Windows). Another alternative is to launch IDLE, as its main Python shell window is an interactive session. Depending on your platform and Python, if you have not set your system’s PATH variable to find Python, you may need to cd to where Python is installed, or type its full directory path instead of just python (e.g., C:\Python33\python on Windows, unless you’re using the 3.3 launcher).
2. You type system command lines in whatever your platform provides as a system console: a Command Prompt window on Windows; an xterm or terminal window on Unix, Linux, and Mac OS X; and so on. You type this at the system’s prompt, not at the Python interactive interpreter’s “>>>” prompt—be careful not to confuse these prompts.
3. Code in a script (really, module) file can be run with system command lines, file icon clicks, imports and reloads, the exec built-in function, and IDE GUI selections such as IDLE’s Run→Run Module menu option. On Unix, they can also be run as executables with the #! trick, and some platforms support more specialized launching techniques (e.g., drag and drop). In addition, some text editors have unique ways to run Python code, some Python programs are provided as standalone “frozen binary” executables, and some systems use Python code in embedded mode, where it is run automatically by an enclosing program written in a language like C, C++, or Java. The latter technique is usually done to provide a user customization layer.
4. Scripts that print and then exit cause the output file to disappear immediately, before you can view the output (which is why the input trick comes in handy); error messages generated by your script also appear in an output window that closes before you can examine its contents (which is one reason that system command lines and IDEs such as IDLE are better for most development).
5. Python imports (loads) a module only once per process, by default, so if you’ve changed its source code and want to run the new version without stopping and restarting Python, you’ll have to reload it. You must import a module at least once before you can reload it. Running files of code from a system shell command line, via an icon click, or via an IDE such as IDLE generally makes this a nonissue, as those launch schemes usually run the current version of the source code file each time.
6. Within the text edit window of the file you wish to run, select the window’s Run→Run Module menu option. This runs the window’s source code as a top-level script file and displays its output back in the interactive Python shell window.
7. IDLE can still be hung by some types of programs—especially GUI programs that perform multithreading (an advanced technique beyond this book’s scope). Also, IDLE has some usability features that can burn you once you leave the IDLE GUI: a script’s variables are automatically imported to the interactive scope in IDLE and working directories are changed when you run a file, for instance, but Python itself does not take such steps in general.
8. A namespace is just a package of variables (i.e., names). It takes the form of an object with attributes in Python. Each module file is automatically a namespace—that is, a package of variables reflecting the assignments made at the top level of the file. Namespaces help avoid name collisions in Python programs: because each module file is a self-contained namespace, files must explicitly import other files in order to use their names.
Test Your Knowledge: Part I Exercises
It’s time to start doing a little coding on your own. This first exercise session is fairly simple, but it’s designed to make sure you’re ready to work along with the rest of the book, and a few of its questions hint at topics to come in later chapters. Be sure to check Part I in Appendix D for the answers; the exercises and their solutions sometimes contain supplemental information not discussed in the main text, so you should take a peek at the solutions even if you manage to answer all the questions on your own.
1. Interaction. Using a system command line, IDLE, or any other method that works on your platform, start the Python interactive command line (>>> prompt), and type the expression "Hello World!" (including the quotes). The string should be echoed back to you. The purpose of this exercise is to get your environment configured to run Python. In some scenarios, you may need to first run a cd shell command, type the full path to the Python executable, or add its path to your PATH environment variable. If desired, you can set PATH in your .cshrc or .kshrc file to make Python permanently available on Unix systems; on Windows, the environment variable GUI is usually what you want for this. See Appendix A for help with environment variable settings.
2. Programs. With the text editor of your choice, write a simple module file containing the single statement print('Hello module world!') and store it as module1.py. Now, run this file by using any launch option you like: running it in IDLE, clicking on its file icon, passing it to the Python interpreter on the system shell’s command line (e.g., python module1.py), built-in exec calls, imports and reloads, and so on. In fact, experiment by running your file with as many of the launch techniques discussed in this chapter as you can. Which technique seems easiest? (There is no right answer to this, of course.)
3. Modules. Start the Python interactive command line (>>> prompt) and import the module you wrote in exercise 2. Try moving the file to a different directory and importing it again from its original directory (i.e., run Python in the original directory when you import). What happens? (Hint: is there still a module1.pyc byte code file in the original directory, or something similar in a __pycache__ subdirectory there?)
4. Scripts. If your platform supports it, add the #! line to the top of your module1.py module file, give the file executable privileges, and run it directly as an executable. What does the first line need to contain? #! usually only has meaning on Unix, Linux, and Unix-like platforms such as Mac OS X; if you’re working on Windows, instead try running your file by listing just its name in a Command Prompt window without the word “python” before it (this works on recent versions of Windows), via the Start→Run... dialog box, or similar. If you are using Python 3.3 or the Windows launcher that installs with it, experiment with changing your script’s #! line to launch different Python versions you may have installed on your computer (or equivalently, work through the tutorial in Appendix B).
5. Errors and debugging. Experiment with typing mathematical expressions and assignments at the Python interactive command line. Along the way, type the expressions 2 ** 500 and 1 / 0, and reference an undefined variable name as we did early on in this chapter. What happens?
You may not know it yet, but when you make a mistake, you’re doing exception processing: a topic we’ll explore in depth in Part VII. As you’ll learn there, you are technically triggering what’s known as the default exception handler—logic that prints a standard error message. If you do not catch an error, the default handler does and prints the standard error message in response.
Exceptions are also bound up with the notion of debugging in Python. When you’re first starting out, Python’s default error messages on exceptions will probably provide as much error-handling support as you need—they give the cause of the error, as well as showing the lines in your code that were active when the error occurred. For more about debugging, see the sidebar Debugging Python Code.
6. Breaks and cycles. At the Python command line, type:
7. L = [1, 2] # Make a 2-item list
8. L.append(L) # Append L as a single item to itself
9. L # Print L: a cyclic/circular object
What happens? In all recent versions of Python, you’ll see a strange output that we’ll describe in the solutions appendix, and which will make more sense when we study references in the next part of the book. If you’re using a Python version older than 1.5.1, a Ctrl-C key combination will probably help on most platforms. Why do you think your version of Python responds the way it does for this code?
WARNING
If you do have a Python older than Release 1.5.1 (a hopefully rare scenario today!), make sure your machine can stop a program with a Ctrl-C key combination of some sort before running this test, or you may be waiting a long time.
10.Documentation. Spend at least 15 minutes browsing the Python library and language manuals before moving on to get a feel for the available tools in the standard library and the structure of the documentation set. It takes at least this long to become familiar with the locations of major topics in the manual set; once you’ve done this, it’s easy to find what you need. You can find this manual via the Python Start button entry on some Windows, in the Python Docs option on the Help pull-down menu in IDLE, or online at http://www.python.org/doc. I’ll also have a few more words to say about the manuals and other documentation sources available (including PyDoc and the help function) in Chapter 15. If you still have time, go explore the Python website, as well as its PyPI third-party extension repository. Especially check out the Python.org (http://www.python.org) documentation and search pages; they can be crucial resources.