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:
See Interactive Shell and Debugging Programs for more information on this Komodo functionality.
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.
Windows
<komodo-install-directory>\lib\support\samples\python_tutorials
Linux
<komodo-install-directory>/lib/support/samples/python_tutorials
Mac OS X
<User-home-directory>/Library/Application Support/Komodo/3.x/samples/python_tutorials
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.
This section reviews the code in preprocess.py and contenttype.py.
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 routinessys
: functions for
interacting with the Python interpretergetopt
: parses command
line optionstypes
: defines names for
all type symbols in the standard Python interpreterre
: evaluates regular
expressionspprint
: supports
pretty-print outputlogging
: writes errors to
a log fileThe custom contenttype
module is used by the
preprocess.py program and is not included in a standard
Python installation.
contenttype
module and imports the
getContentType
method
Komodo Tip: To interact directly with
the |
PreprocessError
class inherits from the Python
Exception
classPreprocessError
class is
thrown by the preprocess
module 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. |
log
is a global object used to log debug
messages and error messages
Komodo Tip: On line 95, enter:
|
_commentGroups
is a mapping of file type (as
returned by content.types
) to opening and closing
comments delimiterspreprocess.py
module
(_commentGroups
is prefixed with an underscore to
indicate that it is private to the preprocess.py
module). 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
language-specific comments.
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 method
is private to the
preprocess
moduleThe preprocess
method examines the directives in
the sample source file and outputs the modified processed
text.
The preprocess
method takes three parameters as
input:
infile
stdout
); outfile=sys.stdout
defines={}
Examines how programming comments are delimited (started and ended) based on the type of file (for example, HTML, C++, Python).
getContentType
is called (imported earlier
from the contenttype.py
module) to determine the
language type of the file_commentGroups
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
output file.
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
"preprocess" method.
-D
) set
as command line argumentspreprocess
methodmain
method when
preprocess.py is executed as a programIn 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.
The 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.
re
, os
, sys
,
logging
)logging
is not a standard module; it is new in
Python 2.3This section outlines the usage of the private
_getContentTypesFile
method located in the
contenttype
module.
content.types
file_getContentTypesFile
is a private method that
cannot be accessed from outside of the contenttype
moduleThis section outlines the usage of the private
_getContentTypesRegistry
method located in the
contenttype
module.
content.types
file 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)
_getContentTypesRegistry
is a private method
that cannot be accessed from outside of the
contenttype
module.content.types
file; if none is specified in
the parameter for the method,
_getContentTypesFile
is called to find the
system defaultcontent.types
file on a line-by-line
basiscontent.types
file and returns the
mappingsThis section outlines the usage of the public
getContentType
method located in the
contenttype
module.
getContentType("my_web_page.htm")
returns "HTML"
)getContentType
is the only publicly accessible
method in the module_getContentTypesRegistry
is called to load the
content.types
file and to load the
mappingsfilenameMap
is first checked to determine if
the whole filename can be used to find a matchThis section reviews how to run the preprocess.py program using both a run command and the Komodo debugger.
To start, generate simple output by running the program with the preprocess current file run command, included in the python_tutorial.kpf project.
-D SAY_BYE
['path_to_file\\python_tutorials\\helloworld.html']
<html>
<head> <title>Hello World</title>
</head>
<body>
<p>Hello, World!</p>
</body>
</html>
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.
Troubleshooting: Specifying <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. |
infile
variable. This
variable contains the name of the file specified above
(helloworld.html).
Komodo Tip: What do the debugger commands do?
|
preprocess
method. "Step In" is a debugger command
that causes the debugger to enter a function called from the
current line.getContentType
is called.contentType
is 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.contentType
variable. This
variable contains the type of the source file; the type is
"HTML" for helloworld.html.lineNum
in the
text box. Click OK. Notice that the
lineNum
variable and its value are displayed in
the Watch tab. The lineNum
variable 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
line
. The line
variable 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:
import
contenttype
contenttype
module imported successfully.help (contenttype)
help (contenttype)
is redisplayed,
enter .getContentType
at the end of the command.
The entire command is as follows:help (contenttype.getContentType)
getContentType
method are printed to the shell
screen. The ability to instantly access help on specific Python
functions is a powerful use for the interactive shell.contenttype.getContentType("helloworld.html")
HTML
.contenttype.getContentType("helloworld.py")
Python
.contenttype.getContentType("test.txt")
Text
. The contenttype
module 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.