This tutorial assumes:
The Python Tutorial demonstrates how to use the Komodo debugger and interactive shell to explore a Python program. In particular, this tutorial examines a Python script that preprocesses files (similar to the C preprocessor). In this tutorial you will:
On the File menu, click Open|Project and select python_tutorial.kpf from the python_tutorials subdirectory. The location differs depending on your operating system.
Mac OS X
All files included in the tutorial project are displayed on the Projects tab in the Left Pane.
The following components are included in the python_tutorial.kpf project file:
On the Projects tab, double-click the preprocess.py file. This file opens in the Editor Pane; a tab at the top of the pane displays the filename.
In this step, you will analyze the Python program preprocess.py in sections. This program is an advanced Python script that is best addressed by focusing on certain areas within the code. Be sure that line numbers are enabled in Komodo (View|View Line Numbers) and that preprocess.py is displayed in the Komodo Editor.
About Preprocessors: A preprocessor is a program that examines a file for specific statements called "directive statements". These directive statements are interpreted, and the resulting program output is conditional based on those statements. In languages like C/C++, preprocessing is a common step applied to source files before compilation. The Python preprocessor.py program mimics a C/C++ preprocessor using similar directive statements.
About Directive Statements: Preprocessor directive statements are dependent on the preprocessor program they are used within. In the preprocessor.py program, a directive is preceded with a pound sign (#), and is located alone on a line of code. Placing a directive on a unique line ensures the statement is included in a file without breaking file syntax rules. Valid preprocessor.py directives include:
#define <var>[=<value>] #undef <var> #if <expr> #elif <expr> #else #endif #error <error string>
Komodo Tip: Notice that syntax elements are displayed in different colors. You can adjust the display options for language elements in the Preferences dialog box.
Komodo Tip: See Explore Python with the Interactive Shell to examine these docstrings, and other Python elements, using the Komodo interactive shell.
Komodo Tip: Click on the minus symbol to the left of line 3. The entire section of nested help code is collapsed. This is called Code Folding.
os: operating system dependant helper routines
sys: functions for interacting with the Python interpreter
getopt: parses command line options
types: defines names for all type symbols in the standard Python interpreter
re: evaluates regular expressions
pprint: supports pretty-print output
logging: writes errors to a log file
contenttype module is used by the
preprocess.py program and is not included in a standard
contenttypemodule and imports the
Komodo Tip: To interact directly with
PreprocessErrorclass inherits from the Python
PreprocessErrorclass is thrown by the
preprocessmodule when an error occurs
Komodo Tip: Click the mouse pointer on the closing parenthesis ")" on line 72. Notice that its color changes to a bold red. The opening brace is displayed the same way. This is called "Brace Matching". Related features in Komodo are Jump to Matching Brace and Select to Matching Brace, available via the Code menu.
logis a global object used to log debug messages and error messages
Komodo Tip: On line 95, enter:
_commentGroupsis a mapping of file type (as returned by
content.types) to opening and closing comments delimiters
_commentGroupsis prefixed with an underscore to indicate that it is private to the
preprocess.pymodule). This is a common technique used in variable, function, and class naming in Python coding).
Note that preprocessor directives recognized by the
preprocess.py module are hidden in programming
Komodo Tip: Use the Code tab, located in the Left Pane, to browse the general program structure of all currently open files. For each file, the code browser shows a tree of classes, functions, methods and imported modules. Python instance attributes are also displayed.
_evaluate methodis private to the
preprocess method examines the directives in
the sample source file and outputs the modified processed
preprocess method takes three parameters as
Examines how programming comments are delimited (started and ended) based on the type of file (for example, HTML, C++, Python).
getContentTypeis called (imported earlier from the
contenttype.pymodule) to determine the language type of the file
This section defines advanced regular expressions for finding preprocessor directives in the input file.
Komodo Tip: Use the Komodo Rx Toolkit to build, edit, or test regular expressions. New to regular expressions? The Regular Expressions Primer is a tutorial for those wanting to learn more about regex syntax.
This block of code implements a basic state machine. The input
file is scanned line by line looking for preprocessor directives
with the patterns defined above (
stmtRes). This code
determines whether each line should be skipped or written to the
main method takes the text entered at the
command line and uses the
getopt module to parse the
data into arguments. These arguments are then passed into the
-D) set as command line arguments
mainmethod when preprocess.py is executed as a program
In this step, you will analyze the Python program contenttype.py in sections. This Python script is best addressed by focusing on certain areas within the code. Be sure that line numbers are enabled in Komodo (View|View Line Numbers) and that contenttype.py is displayed in the Komodo Editor Pane.
On the Projects tab, double-click the contenttype.py file. This file opens in the Editor Pane; a tab at the top of the pane displays the filename.
contenttype.py module is used by the main
program, preprocess.py, to identify what programming
language a particular file is written in based on the file
extension and several other tests.
loggingis not a standard module; it is new in Python 2.3
This section outlines the usage of the private
_getContentTypesFile method located in the
_getContentTypesFileis a private method that cannot be accessed from outside of the
This section outlines the usage of the private
_getContentTypesRegistry method located in the
content.typesfile and scans it to calculate three mappings to return, as follows:
file suffix -> content type (i.e. ".cpp", a C++ implementation file) regex -> content type (i.e. ".*\.html?", an HTML file) filename -> content type (i.e. "Makefile", a Makefile)
_getContentTypesRegistryis a private method that cannot be accessed from outside of the
content.typesfile; if none is specified in the parameter for the method,
_getContentTypesFileis called to find the system default
content.typesfile on a line-by-line basis
content.typesfile and returns the mappings
This section outlines the usage of the public
getContentType method located in the
getContentType("my_web_page.htm")returns "HTML" )
getContentTypeis the only publicly accessible method in the module
_getContentTypesRegistryis called to load the
content.typesfile and to load the mappings
filenameMapis first checked to determine if the whole filename can be used to find a match
To start, generate simple output by running the program with the preprocess current file run command, included in the python_tutorial.kpf project.
<head> <title>Hello World</title> </head>
Python Tutorial Tip: For more
information about the
Komodo Tip: For more infomation on using run commands in Komodo, see the Run Command Tutorial.
Generate output by running the program through the debugger without setting any breakpoints.
Troubleshooting: "Why is this error message displayed?"
preprocess: error: incorrect number of arguments: argv=['C:\\path_to_tutorial\\preprocess.py']
This error message is the expected output by the preprocess.py program when no source file or arguments are specified before it is run. The following instructions explain how to specify a file at the command line.
helloworld.html. Click OK.
Troubleshooting: "Why is this error message displayed?"
<html> <head> <title>Hello World</title> </head> <body> preprocess: error: helloworld.html:5: #error: "SAY_BYE is not defined, use '-D' option"
This error message is the expected output by the preprocess.py program when no command-line arguments are specified with the source file helloworld.html. The following instructions explain how to specify a command-line argument with the source file to be processed.
-D SAY_BYE helloworld.html. Click OK.
<html> <head> <title>Hello World</title> </head> <body> <p>Hello, World!</p> </body> </html>
In the helloworld.html file, if
print "Hello, World!"). This demonstrates how the preprocess.py program can be used to process files written in different language types.
In this step you will add breakpoints to the program and "debug" it. Adding breakpoints lets you run the program in sections, making it easier to watch variables and view the output as it is generated.
-D "SAY_BYE" helloworld.html. Click OK.
Komodo Tip: Debugger commands can be accessed from the Debug menu, by shortcut keys, or from the Debug Toolbar. For a summary of debugger commands, see the Debugger Command List.
infilevariable. This variable contains the name of the file specified above (helloworld.html).
Komodo Tip: What do the debugger commands do?
preprocessmethod. "Step In" is a debugger command that causes the debugger to enter a function called from the current line.
contentTypeis assigned the source file's (helloworld.html) type (HTML). "Step Over" is a debugger command that executes the current line of code. If the line of code calls a function or method, the function or method is executed in the background and the debugger pauses at the line that follows the original line.
contentTypevariable. This variable contains the type of the source file; the type is "HTML" for helloworld.html.
lineNumin the text box. Click OK. Notice that the
lineNumvariable and its value are displayed in the Watch tab. The
lineNumvariable is the line number of the line currently being processed in the source file helloworld.html. Follow the above steps again to enter a watch for the variable
linevariable contains the actual text of the line currently being processed.
In this step you will use the interactive shell to explore the
contenttype module. The Komodo interactive shell
helps you test, debug, and examine your program. See Interactive
Shell for more information.
If starting this section of the tutorial with currently open Python shells, please follow the steps below to ensure the Python shell's current directory is the Python Tutorial directory.
Start using the interactive shell with the Python Tutorial project files:
contenttypemodule imported successfully.
help (contenttype)is redisplayed, enter
.getContentTypeat the end of the command. The entire command is as follows:
getContentTypemethod are printed to the shell screen. The ability to instantly access help on specific Python functions is a powerful use for the interactive shell.
contenttypemodule uses several tests to determine the data type used within a file. The test that determined that test.txt is a text file simply analyzed the file extension.
ASPN, the ActiveState Programmer Network, a source of numerous resources for Python programmers, including:
There are many Python tutorials and beginner Python sites on the Internet, including:
The preprocess.py program in this tutorial is a simplified version of another Python preprocess.py script available via http://starship.python.net/crew/tmick/#preprocess. The version available on starship.python.net is an advanced portable multi-language file preprocessor.