blob: 5f2009732b3f4ff67b9a52e5d68cbca1185da1d7 [file] [log] [blame]
Jack Jansen5f962c21996-04-10 14:52:59 +00001<HTML>
2<HEAD>
3<TITLE>Using Python on the Macintosh</TITLE>
4</HEAD>
5<BODY>
6<H1>Using Python on the Macintosh</H1>
7<EM>(preliminary)</EM>
8<HR>
9
Jack Jansenbd9565a1996-04-15 12:25:44 +000010This document is an introduction to using Python on the Apple
11Macintosh. It does not introduce the language itself, for this you
12should refer to the <A
13HREF="http://www.python.org/doc/tut/tut.html">Python Tutorial</A> by
14Guido van Rossum. This guide more-or-less replaces chapter two of the
15tutorial, and provides some additional material. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +000016
Jack Jansenbd9565a1996-04-15 12:25:44 +000017The document refers to Python 1.3.3 or higher, some of the features
18(like setting applet options) will not work in earlier versions of
19Python. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +000020
21<h2>Invoking the interpreter</h2>
22
Jack Jansenbd9565a1996-04-15 12:25:44 +000023The name of the interpreter may differ on different installations: it
24may be called <CODE>Python</CODE>, <CODE>PythonPPC</CODE> (for powerpc
25macs) or <CODE>Python68K</CODE> (indeed, for 68K macs). It will always
26be recognizable by the "16 ton" icon, though. You start the
27interpreter in interactive mode by double-clicking it. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +000028
29<img src="html.icons/python.gif"><p>
30
Jack Jansenbd9565a1996-04-15 12:25:44 +000031This should give you a text window with an informative version string
32and a prompt, something like the following:
Jack Jansen5f962c21996-04-10 14:52:59 +000033<PRE>
34Python 1.3.3 (Apr 7 1996) [CW PPC w/GUSI]
35Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
36&gt;&gt;&gt;
37</PRE>
Jack Jansenbd9565a1996-04-15 12:25:44 +000038The version string tells you the version of Python, whether it was
39built for PPC or 68K macs and possibly some options used to build the
40interpreter. If you find a bug or have a question about how the
41interpreter works it is a good idea to include the version information
42in your message. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +000043
Jack Jansenbd9565a1996-04-15 12:25:44 +000044At the prompt you can type interactive python commands. See the
45tutorial for more information. The interactive window works
46more-or-less like a Communication Toolbox or Telnet window: you type
47commands at the bottom and terminate them with the <EM>[return]</EM>
48or <EM>[enter]</EM> key. Interpreter feedback also appears at the
49bottom of the window, and the contents scroll as output is added. You
50can use copy and paste in the normal way, but be sure to paste only at
51the bottom of the document.
Jack Jansen5f962c21996-04-10 14:52:59 +000052
53<h2>Creating Python scripts</h2>
54
Jack Jansenbd9565a1996-04-15 12:25:44 +000055The Python interpreter works in a way that is different from what you
56would expect of a macintosh program: the interpreter is just that: an
57interpreter. There is no builtin editor or other development
58support. Hence, to create a Python script you need an external text
59editor. For a first script you can use any editor that can create
60plain, unstyled text files, such as <CODE>SimpleText</CODE>. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +000061
Jack Jansenbd9565a1996-04-15 12:25:44 +000062For more serious scripts, though, it is advisable to use a programmers
63editor, such as <CODE>BBEdit</CODE> or <CODE>Alpha</CODE>. BBEdit is
64my favorite: it comes in a commercial version but also in a
65fully-functional free version <CODE>BBEdit Lite</CODE>. You can
66download it from the <A HREF="http://www.barebones.com/">BareBones</A>
67site. The free version will probably provide all the functionality
68you will ever need. Besides the standard edit facilities it has
69multi-file searches and many other goodies that can be very handy when
70editing programs. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +000071
Jack Jansenbd9565a1996-04-15 12:25:44 +000072After you have created your script in the editor of your choice you
73drop it on the interpreter. This will start the interpreter executing
74the script, again with a console window in which the output appears
75and in which you can type input if the script requires it. Normally
76the interpreter will close the window and quit as soon as the script
77is done executing, see below under <A HREF="#startup">startup
78options</A> for a way to change this. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +000079
Jack Jansenbd9565a1996-04-15 12:25:44 +000080It is a good idea to have the names of all your scripts end in
81<CODE>.py</CODE>. While this is not necessary for standalone scripts
82it is needed for modules, and it is probably a good idea to start the
83habit now. <p>
84
85If you do not like to start the Python interpreter afresh for each
86edit-run cycle you can use the <CODE>import</CODE> statement and
87<CODE>reload()</CODE> function to speed things up in some cases. Here
88is Guido's original comment for how to do this, from the 1.1 release
89notes: <P>
90
91<CITE>
92
93Make sure the program is a module file (filename must be a Python
94identifier followed by '<CODE>.py</CODE>'). You can then import it
95when you test it for the first time. There are now three
96possibilities: it contains a syntax error; it gets a runtime error
97(unhandled exception); or it runs OK but gives wrong results. (If it
98gives correct results, you are done testing and don't need to read the
99rest of this paragraph. :-) Note that the following is not
100Mac-specific -- it's just that on UNIX it's easier to restart the
101entire script so it's rarely useful. <P>
102
103Recovery from a syntax error is easy: edit the file and import it
104again. <P>
105
106Recovery from wrong output is almost as easy: edit the file and,
107instead of importing it, call the function <CODE>reload()</CODE> with
108the module name as argument (e.g., if your module is called
109<CODE>foo</CODE>, type <CODE>reload(foo)</CODE>). <P>
110
111Recovery from an exception is trickier. Once the syntax is correct, a
112'module' entry is placed in an internal table, and following import
113statements will not re-read the file, even if the module's
114initialization terminated with an error (one reason why this is done
115is so that mutually recursive modules are initialized only once). You
116must therefore force re-reading the module with <CODE>reload()</CODE>,
117however, if this happens the first time you try to import the module,
118the import statement itself has not completed, and your workspace does
119not know the module name (even though the internal table of moduesl
120does!). The trick is to first import the module again, then reload
121it. For instance, <CODE>import foo; reload(foo)</CODE>. Because the
122module object already exists internally, the import statement does not
123attempt to execute the module again -- it just places it in your
124workspace. </CITE>
Jack Jansen5f962c21996-04-10 14:52:59 +0000125
126<h2>Clickable python scripts</h2>
127
Jack Jansenbd9565a1996-04-15 12:25:44 +0000128If you create your script with the correct creator and type, creator
129<CODE>'Pyth'</CODE> and type <CODE>'TEXT'</CODE>, you can double-click
130your script and it will automatically invoke the interpreter. If you
131use BBEdit you can tell it about the Python file type by adding it to
132the "file types" sections of the preferences. Then, if you save a file
133for the first time you can tell BBEdit to save the file as a Python
134script through the "options" choice of the save dialog. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000135
Jack Jansenbd9565a1996-04-15 12:25:44 +0000136The <CODE>Scripts</CODE> folder contains a script
137<CODE>fixfiletypes</CODE> that will recursively traverse a folder and
138set the correct creator and type for all files ending in
139<CODE>.py</CODE>. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000140
141<h2>Interaction with the user</h2>
142
Jack Jansenbd9565a1996-04-15 12:25:44 +0000143Normally, the interpreter will check for user input (mouse clicks,
144keyboard input) every once in a while, so it is possible to switch to
145other applications while a script runs. It is also possible to
146interrupt the interpreter with the standard command-period keypress,
147this will raise the <CODE>KeyboardInterrupt</CODE> exception. Scripts
148may, however, turn off this behaviour to facilitate their own event
149handling. Such scripts can only be killed with the
150command-option-escape shortcut.
Jack Jansen5f962c21996-04-10 14:52:59 +0000151
152<h2><A NAME="startup">startup options</A></h2>
153
Jack Jansenbd9565a1996-04-15 12:25:44 +0000154If the <EM>option</EM> key is depressed when Python starts executing
155the interpreter will bring up an options dialog thru which you can
156influence the way the interpreter behaves. Keep the option key
157depressed until the dialog comes up. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000158
159<img src="html.icons/options.gif"><p>
160
161The options modify the interpreters behaviour in the following way:
162<ul>
163<li> the interpreter goes to interactive mode (in stead of
164exiting) after a script has terminated normally,
165<li> for every module imported a line is printed telling you where the
166module was loaded from,
Jack Jansenbd9565a1996-04-15 12:25:44 +0000167<li> do not print the values of expressions executed as statements in
168an interactive python,
Jack Jansen5f962c21996-04-10 14:52:59 +0000169<li> do not buffer stdout and stderr,
170<li> print some debugging output during the parsing phase,
171<li> keep the output window open when a script terminates.
172</ul>
Jack Jansenbd9565a1996-04-15 12:25:44 +0000173In addition, you can enter a unix-style command line which is passed
174to the script in <CODE>sys.argv</CODE>. Sys.argv[0] is always the name
175of the script being executed, additional values can be passed
176here. Quoting works as expected. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000177
Jack Jansenbd9565a1996-04-15 12:25:44 +0000178The default options are also settable on a system-wide basis, see the
179section on <A HREF="#preferences">editing preferences</A>. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000180
181<h2>Module search path</h2>
182
Jack Jansenbd9565a1996-04-15 12:25:44 +0000183The module search path, <CODE>sys.path</CODE>, contains the folders
184python will search when you import a module. The path is settable on a
185system-wide basis (see the preferences section), and normally
186comprises the current folder (where the script lives), the
187<CODE>Lib</CODE> folder and some of its subfolders and possibly some
188more. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000189
190<h2>Working folder</h2>
191
Jack Jansenbd9565a1996-04-15 12:25:44 +0000192The unix concept of a <I>working directory</I> does not translate
193directly to a similar concept on the Macintosh. To facilitate easy
194porting and the use of relative pathnames in scripts the interpreter
195simulates a working directory. When a script is started the initial
196working directory is the folder where the script lives. In case of an
197interactive interpreter the working directory is the folder where the
198interpreter lives. <P>
199
200By the way: the "standard file" folder, the folder that is presented
201to the user initially for an <I>open</I> or <I>save</I> dialog, does
202<EM>not</EM> follow the Python working directory. Which folder is
203initially shown to the user is usually one of (a) the application
204folder, (b) the "Documents" folder or (c) the folder most recently
205used for such a dialog (in any Python program). This is standard MacOS
206behaviour, so don't blame Python for it. The exact behaviour is
207settable through a control panel since System 7.5.
Jack Jansen5f962c21996-04-10 14:52:59 +0000208
209<h2>Interactive startup file</h2>
210
Jack Jansenbd9565a1996-04-15 12:25:44 +0000211If the folder containing the interpreter contains a file named
212<CODE>PythonStartup</CODE> this file is executed when you start an
213interactive interpreter. In this file you could import modules you
214often use and other such things. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000215
216
217<h2>Compiled python scripts</h2>
218
Jack Jansenbd9565a1996-04-15 12:25:44 +0000219Once a python module has been imported the interpreter creates a
220compiled version which is stored in a file with the ".py" extension
221replaced by ".pyc". These compiled files, with creator
222<CODE>'Pyth'</CODE> and type <CODE>'PYC '</CODE> load faster when
223imported (because they do not have to be parsed). The <CODE>Lib</CODE>
224folder contains a script <CODE>compileall.py</CODE>, running this
225script will cause all modules along the python search path to be
226precompiled, which will speed up your programs. Compiled files are
227also double-clickable. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000228
229<h2>Python resources</h2>
230
Jack Jansenbd9565a1996-04-15 12:25:44 +0000231MacPython has the ability to collect a number of compiled modules
232together in the resource fork of a single file. This feature is useful
233if you distribute a python program and want to minimize clutter: you
234can put all the needed modules in a single file (which could even be
235the interpreter itself). <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000236
Jack Jansenbd9565a1996-04-15 12:25:44 +0000237If the module search path contains a filename as one of its entries
238(as opposed to a folder name, which is the normal case) this file will
239be searched for a resource with type <CODE>'PYC '</CODE> and a name
240matching the module being imported. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000241
Jack Jansenbd9565a1996-04-15 12:25:44 +0000242The <CODE>scripts</CODE> folder contains a script
243<CODE>PackLibDir</CODE> which will convert a number of modules (or
244possibly a complete subtree full of modules) into such a resource
245file.
Jack Jansen5f962c21996-04-10 14:52:59 +0000246
247<h2><A NAME="preferences">Setting interpreter preferences</A></h2>
248
Jack Jansenbd9565a1996-04-15 12:25:44 +0000249The python interpreter keeps a preferences file in the standard
250location in the system folder. In this preferences file it remembers
251the default module search path and the default settings for the
252runtime options. The preferences are settable via
253<CODE>EditPythonPrefs</CODE>. For PPC python this is a standalone
254program living in the main Python folder, for 68K python it is a
255script in the <CODE>Scripts</CODE> folder. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000256
Jack Jansenbd9565a1996-04-15 12:25:44 +0000257The interface to edit the preferences is rather clunky for the current
258release. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000259
260<img src="html.icons/preferences.gif"><p>
261
Jack Jansenbd9565a1996-04-15 12:25:44 +0000262In the editable text field at the top you enter the initial module
263search path, using newline as a separator. There are two special
264values you can use here: an initial substring <CODE>$(PYTHON)</CODE>
265will expand to the Python home folder and a value of
266<CODE>$(APPLICATION)</CODE> will expand to the the python application
267itself. Note that the text field may extend "beyond the bottom" even
268though it does not have a scroll bar. Using the arrow keys works,
269though.<p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000270
Jack Jansenbd9565a1996-04-15 12:25:44 +0000271The Python home folder $(PYTHON) is initially, when you execute the
272interpreter for the first time, set to the folder where the
273interpreter lives. You can change it here. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000274
Jack Jansenbd9565a1996-04-15 12:25:44 +0000275Finally, you can set the default startup options here, through a
276sub-dialog.
Jack Jansen5f962c21996-04-10 14:52:59 +0000277
278<h2>Applets</h2>
279
Jack Jansenbd9565a1996-04-15 12:25:44 +0000280An applet is a fullblown application written in Python, similar to an
281AppleScript applet (and completely different from a Java
282applet). Applets are currently only supported on PowerPC macintoshes,
283and are created using the <CODE>mkapplet</CODE> program. You create an
284applet by dropping the python source script onto mkapplet. The
285<CODE>Demo</CODE> folder contains an example of a more involved applet
286with its own resource file, etc. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000287
Jack Jansenbd9565a1996-04-15 12:25:44 +0000288Note that while an applet behaves as a fullblown Macintosh application
289it is not self-sufficient, so distributing it to a machine without an
290installed Python interpreter will not work: it needs the shared python
291execution engine <CODE>PythonCore</CODE>, and probably various modules
292from the Lib and PlugIns folders. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000293
294<h2>Customizing applets</h2>
295
Jack Jansenbd9565a1996-04-15 12:25:44 +0000296Applets can have their own settings for the startup options and module
297search path. Dropping an applet on the <CODE>EditPythonPrefs</CODE>
298application allows you to set these, in the same way as
299double-clicking EditPythonPrefs allows you to set the system-wide
300defaults. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000301
Jack Jansenbd9565a1996-04-15 12:25:44 +0000302Actually, not only applets but also the interpreter itself can have
303non-default settings for path and options. If you make a copy of the
304interpreter and drop this copy onto EditPythonPrefs you will have an
305interpreter that has a different set of default settings.
Jack Jansen5f962c21996-04-10 14:52:59 +0000306
307<h2>Where to go from here</h2>
308
Jack Jansenbd9565a1996-04-15 12:25:44 +0000309The previously mentioned <A
310HREF="http://www.python.org/doc/tut/tut.html">Python Tutorial</A> is
311an excellent place to start reading if you have never used Python
312before. Other documentation such as the library reference manual is
313indexed at the <A HREF="http://www.python.org/doc/">Python
314Documentation</A> page. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000315
Jack Jansenbd9565a1996-04-15 12:25:44 +0000316There are some <A HREF="index.html">annotated sample programs</A>
317available that show some mac-specific issues, like use of various
318toolboxes and creation of Python applets. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000319
Jack Jansenbd9565a1996-04-15 12:25:44 +0000320Finally, the <CODE>Demo</CODE> folder in the Macintosh distribution
321contains a number of other example programs. Most of these are only
322very lightly documented, but they may help you to understand some
323aspects of using Python. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000324
325The best way to contact fellow Macintosh Python programmers is to join
Jack Jansenbd9565a1996-04-15 12:25:44 +0000326the MacPython Special Interest Group mailing list. Send a message with
327"info" in the body to <A
328HREF="mailto:pythonmac-sig-request@python.org">pythonmac-sig-request@python.org</A>
329or view the <A
330HREF="http://www.python.org/sigs/pythonmac-sig/">Pythonmac SIG
331page</A> on the <A HREF="http://www.python.org">www.python.org</A> WWW
332server. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000333
334<h2>Troubleshooting</h2>
335
Jack Jansenbd9565a1996-04-15 12:25:44 +0000336Python is a rather safe language, and hence it should be difficult to
337crash the interpreter of the system with a Python script. There is an
338exception to this rule, though: the modules that interface to the
339system toolboxes (windowing, quickdraw, etc) do very little error
340checking and therefore a misbehaving program using these modules may
341indeed crash the system. Such programs are unfortunately rather
342difficult to debug, since the crash does not generate the standard
343Python stack trace, obviously, and since debugging print statements
344will often interfere with the operation of the program. There is
345little to do about this currently. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000346
Jack Jansenbd9565a1996-04-15 12:25:44 +0000347Probably the most common cause of problems with modules ported from
348other systems is the Mac end-of-line convention. Where unix uses
349linefeed, 0x0d, to separate lines the mac uses carriage return,
3500x0a. To complicate matters more a lot of mac programming editors like
351BBEdit and emacs will work happily with both conventions, so the file
352will appear to be correct in the editor but cause strange errors when
353imported. BBEdit has a popup menu which allows you to inspect (and
354set) the end-of-line convention used in a file. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000355
356<HR>
357<A HREF="http://www.cwi.nl/~jack">Jack Jansen</A>,
Jack Jansenbd9565a1996-04-15 12:25:44 +0000358<A HREF="mailto:jack@cwi.nl">jack@cwi.nl</A>, 15-Apr-1996.
Jack Jansen5f962c21996-04-10 14:52:59 +0000359
360</BODY>
361</HTML>