blob: e7aa0f43f036bc8f8e1149e5fac93fdf0fbbdbf6 [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 Jansen08365421996-04-19 15:56:08 +000017There is currently no good tutorial for the mac-specific features of
18Python, but to whet your appetite: it has interfaces to many MacOS
19toolboxes (quickdraw, sound, quicktime, open scripting, etc) and
20various portable toolboxes are available too (Tk, stdwin, complex
21numbers, image manipulation, etc). Some <A HREF="index.html">
22annotated sample programs</A> are available to give you an idea of
23Python's power. <P>
24
Jack Jansenbd9565a1996-04-15 12:25:44 +000025The document refers to Python 1.3.3 or higher, some of the features
26(like setting applet options) will not work in earlier versions of
27Python. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +000028
29<h2>Invoking the interpreter</h2>
30
Jack Jansenbd9565a1996-04-15 12:25:44 +000031The name of the interpreter may differ on different installations: it
32may be called <CODE>Python</CODE>, <CODE>PythonPPC</CODE> (for powerpc
33macs) or <CODE>Python68K</CODE> (indeed, for 68K macs). It will always
34be recognizable by the "16 ton" icon, though. You start the
Jack Jansen08365421996-04-19 15:56:08 +000035interpreter in interactive mode by double-clicking its icon: <p>
Jack Jansen5f962c21996-04-10 14:52:59 +000036
37<img src="html.icons/python.gif"><p>
38
Jack Jansenbd9565a1996-04-15 12:25:44 +000039This should give you a text window with an informative version string
40and a prompt, something like the following:
Jack Jansen5f962c21996-04-10 14:52:59 +000041<PRE>
42Python 1.3.3 (Apr 7 1996) [CW PPC w/GUSI]
43Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
44&gt;&gt;&gt;
45</PRE>
Jack Jansenbd9565a1996-04-15 12:25:44 +000046The version string tells you the version of Python, whether it was
47built for PPC or 68K macs and possibly some options used to build the
48interpreter. If you find a bug or have a question about how the
49interpreter works it is a good idea to include the version information
50in your message. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +000051
Jack Jansenbd9565a1996-04-15 12:25:44 +000052At the prompt you can type interactive python commands. See the
53tutorial for more information. The interactive window works
54more-or-less like a Communication Toolbox or Telnet window: you type
55commands at the bottom and terminate them with the <EM>[return]</EM>
56or <EM>[enter]</EM> key. Interpreter feedback also appears at the
57bottom of the window, and the contents scroll as output is added. You
58can use copy and paste in the normal way, but be sure to paste only at
59the bottom of the document.
Jack Jansen5f962c21996-04-10 14:52:59 +000060
61<h2>Creating Python scripts</h2>
62
Jack Jansenbd9565a1996-04-15 12:25:44 +000063The Python interpreter works in a way that is different from what you
64would expect of a macintosh program: the interpreter is just that: an
65interpreter. There is no builtin editor or other development
66support. Hence, to create a Python script you need an external text
67editor. For a first script you can use any editor that can create
68plain, unstyled text files, such as <CODE>SimpleText</CODE>. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +000069
Jack Jansenbd9565a1996-04-15 12:25:44 +000070For more serious scripts, though, it is advisable to use a programmers
71editor, such as <CODE>BBEdit</CODE> or <CODE>Alpha</CODE>. BBEdit is
72my favorite: it comes in a commercial version but also in a
73fully-functional free version <CODE>BBEdit Lite</CODE>. You can
74download it from the <A HREF="http://www.barebones.com/">BareBones</A>
75site. The free version will probably provide all the functionality
76you will ever need. Besides the standard edit facilities it has
77multi-file searches and many other goodies that can be very handy when
78editing programs. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +000079
Jack Jansenbd9565a1996-04-15 12:25:44 +000080After you have created your script in the editor of your choice you
81drop it on the interpreter. This will start the interpreter executing
82the script, again with a console window in which the output appears
83and in which you can type input if the script requires it. Normally
84the interpreter will close the window and quit as soon as the script
85is done executing, see below under <A HREF="#startup">startup
86options</A> for a way to change this. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +000087
Jack Jansenbd9565a1996-04-15 12:25:44 +000088It is a good idea to have the names of all your scripts end in
89<CODE>.py</CODE>. While this is not necessary for standalone scripts
90it is needed for modules, and it is probably a good idea to start the
91habit now. <p>
92
93If you do not like to start the Python interpreter afresh for each
94edit-run cycle you can use the <CODE>import</CODE> statement and
95<CODE>reload()</CODE> function to speed things up in some cases. Here
96is Guido's original comment for how to do this, from the 1.1 release
97notes: <P>
98
Jack Jansen08365421996-04-19 15:56:08 +000099<BLOCKQUOTE>
Jack Jansenbd9565a1996-04-15 12:25:44 +0000100
101Make sure the program is a module file (filename must be a Python
102identifier followed by '<CODE>.py</CODE>'). You can then import it
103when you test it for the first time. There are now three
104possibilities: it contains a syntax error; it gets a runtime error
105(unhandled exception); or it runs OK but gives wrong results. (If it
106gives correct results, you are done testing and don't need to read the
107rest of this paragraph. :-) Note that the following is not
108Mac-specific -- it's just that on UNIX it's easier to restart the
109entire script so it's rarely useful. <P>
110
111Recovery from a syntax error is easy: edit the file and import it
112again. <P>
113
114Recovery from wrong output is almost as easy: edit the file and,
115instead of importing it, call the function <CODE>reload()</CODE> with
116the module name as argument (e.g., if your module is called
117<CODE>foo</CODE>, type <CODE>reload(foo)</CODE>). <P>
118
119Recovery from an exception is trickier. Once the syntax is correct, a
120'module' entry is placed in an internal table, and following import
121statements will not re-read the file, even if the module's
122initialization terminated with an error (one reason why this is done
123is so that mutually recursive modules are initialized only once). You
124must therefore force re-reading the module with <CODE>reload()</CODE>,
125however, if this happens the first time you try to import the module,
126the import statement itself has not completed, and your workspace does
127not know the module name (even though the internal table of moduesl
128does!). The trick is to first import the module again, then reload
129it. For instance, <CODE>import foo; reload(foo)</CODE>. Because the
130module object already exists internally, the import statement does not
131attempt to execute the module again -- it just places it in your
Jack Jansen08365421996-04-19 15:56:08 +0000132workspace. </BLOCKQUOTE>
Jack Jansen5f962c21996-04-10 14:52:59 +0000133
134<h2>Clickable python scripts</h2>
135
Jack Jansenbd9565a1996-04-15 12:25:44 +0000136If you create your script with the correct creator and type, creator
137<CODE>'Pyth'</CODE> and type <CODE>'TEXT'</CODE>, you can double-click
138your script and it will automatically invoke the interpreter. If you
139use BBEdit you can tell it about the Python file type by adding it to
140the "file types" sections of the preferences. Then, if you save a file
141for the first time you can tell BBEdit to save the file as a Python
142script through the "options" choice of the save dialog. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000143
Jack Jansenbd9565a1996-04-15 12:25:44 +0000144The <CODE>Scripts</CODE> folder contains a script
145<CODE>fixfiletypes</CODE> that will recursively traverse a folder and
146set the correct creator and type for all files ending in
147<CODE>.py</CODE>. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000148
Jack Jansen08365421996-04-19 15:56:08 +0000149<BLOCKQUOTE>
150Older releases of Python used the creator code
151<CODE>'PYTH'</CODE> in stead of <CODE>'Pyth'</CODE>. If you still have
152older Python sources on your system and named them with
153<CODE>'.py'</CODE> extension the <CODE>fixfiletypes</CODE> script will
154correct them.
155</BLOCKQUOTE>
156
Jack Jansen5f962c21996-04-10 14:52:59 +0000157<h2>Interaction with the user</h2>
158
Jack Jansenbd9565a1996-04-15 12:25:44 +0000159Normally, the interpreter will check for user input (mouse clicks,
160keyboard input) every once in a while, so it is possible to switch to
161other applications while a script runs. It is also possible to
162interrupt the interpreter with the standard command-period keypress,
163this will raise the <CODE>KeyboardInterrupt</CODE> exception. Scripts
164may, however, turn off this behaviour to facilitate their own event
165handling. Such scripts can only be killed with the
166command-option-escape shortcut.
Jack Jansen5f962c21996-04-10 14:52:59 +0000167
168<h2><A NAME="startup">startup options</A></h2>
169
Jack Jansenbd9565a1996-04-15 12:25:44 +0000170If the <EM>option</EM> key is depressed when Python starts executing
171the interpreter will bring up an options dialog thru which you can
172influence the way the interpreter behaves. Keep the option key
173depressed until the dialog comes up. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000174
175<img src="html.icons/options.gif"><p>
176
177The options modify the interpreters behaviour in the following way:
178<ul>
179<li> the interpreter goes to interactive mode (in stead of
180exiting) after a script has terminated normally,
181<li> for every module imported a line is printed telling you where the
182module was loaded from,
Jack Jansenbd9565a1996-04-15 12:25:44 +0000183<li> do not print the values of expressions executed as statements in
184an interactive python,
Jack Jansen5f962c21996-04-10 14:52:59 +0000185<li> do not buffer stdout and stderr,
186<li> print some debugging output during the parsing phase,
187<li> keep the output window open when a script terminates.
188</ul>
Jack Jansenbd9565a1996-04-15 12:25:44 +0000189In addition, you can enter a unix-style command line which is passed
190to the script in <CODE>sys.argv</CODE>. Sys.argv[0] is always the name
191of the script being executed, additional values can be passed
192here. Quoting works as expected. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000193
Jack Jansenbd9565a1996-04-15 12:25:44 +0000194The default options are also settable on a system-wide basis, see the
195section on <A HREF="#preferences">editing preferences</A>. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000196
197<h2>Module search path</h2>
198
Jack Jansenbd9565a1996-04-15 12:25:44 +0000199The module search path, <CODE>sys.path</CODE>, contains the folders
200python will search when you import a module. The path is settable on a
201system-wide basis (see the preferences section), and normally
202comprises the current folder (where the script lives), the
203<CODE>Lib</CODE> folder and some of its subfolders and possibly some
204more. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000205
206<h2>Working folder</h2>
207
Jack Jansenbd9565a1996-04-15 12:25:44 +0000208The unix concept of a <I>working directory</I> does not translate
209directly to a similar concept on the Macintosh. To facilitate easy
210porting and the use of relative pathnames in scripts the interpreter
211simulates a working directory. When a script is started the initial
212working directory is the folder where the script lives. In case of an
213interactive interpreter the working directory is the folder where the
214interpreter lives. <P>
215
216By the way: the "standard file" folder, the folder that is presented
217to the user initially for an <I>open</I> or <I>save</I> dialog, does
218<EM>not</EM> follow the Python working directory. Which folder is
219initially shown to the user is usually one of (a) the application
220folder, (b) the "Documents" folder or (c) the folder most recently
221used for such a dialog (in any Python program). This is standard MacOS
222behaviour, so don't blame Python for it. The exact behaviour is
223settable through a control panel since System 7.5.
Jack Jansen5f962c21996-04-10 14:52:59 +0000224
225<h2>Interactive startup file</h2>
226
Jack Jansenbd9565a1996-04-15 12:25:44 +0000227If the folder containing the interpreter contains a file named
228<CODE>PythonStartup</CODE> this file is executed when you start an
229interactive interpreter. In this file you could import modules you
230often use and other such things. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000231
232
233<h2>Compiled python scripts</h2>
234
Jack Jansenbd9565a1996-04-15 12:25:44 +0000235Once a python module has been imported the interpreter creates a
236compiled version which is stored in a file with the ".py" extension
237replaced by ".pyc". These compiled files, with creator
238<CODE>'Pyth'</CODE> and type <CODE>'PYC '</CODE> load faster when
239imported (because they do not have to be parsed). The <CODE>Lib</CODE>
240folder contains a script <CODE>compileall.py</CODE>, running this
241script will cause all modules along the python search path to be
242precompiled, which will speed up your programs. Compiled files are
243also double-clickable. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000244
245<h2>Python resources</h2>
246
Jack Jansenbd9565a1996-04-15 12:25:44 +0000247MacPython has the ability to collect a number of compiled modules
248together in the resource fork of a single file. This feature is useful
249if you distribute a python program and want to minimize clutter: you
250can put all the needed modules in a single file (which could even be
251the interpreter itself). <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000252
Jack Jansenbd9565a1996-04-15 12:25:44 +0000253If the module search path contains a filename as one of its entries
254(as opposed to a folder name, which is the normal case) this file will
255be searched for a resource with type <CODE>'PYC '</CODE> and a name
256matching the module being imported. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000257
Jack Jansenbd9565a1996-04-15 12:25:44 +0000258The <CODE>scripts</CODE> folder contains a script
259<CODE>PackLibDir</CODE> which will convert a number of modules (or
260possibly a complete subtree full of modules) into such a resource
261file.
Jack Jansen5f962c21996-04-10 14:52:59 +0000262
263<h2><A NAME="preferences">Setting interpreter preferences</A></h2>
264
Jack Jansenbd9565a1996-04-15 12:25:44 +0000265The python interpreter keeps a preferences file in the standard
266location in the system folder. In this preferences file it remembers
267the default module search path and the default settings for the
268runtime options. The preferences are settable via
269<CODE>EditPythonPrefs</CODE>. For PPC python this is a standalone
270program living in the main Python folder, for 68K python it is a
271script in the <CODE>Scripts</CODE> folder. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000272
Jack Jansenbd9565a1996-04-15 12:25:44 +0000273The interface to edit the preferences is rather clunky for the current
274release. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000275
276<img src="html.icons/preferences.gif"><p>
277
Jack Jansenbd9565a1996-04-15 12:25:44 +0000278In the editable text field at the top you enter the initial module
279search path, using newline as a separator. There are two special
280values you can use here: an initial substring <CODE>$(PYTHON)</CODE>
281will expand to the Python home folder and a value of
282<CODE>$(APPLICATION)</CODE> will expand to the the python application
283itself. Note that the text field may extend "beyond the bottom" even
284though it does not have a scroll bar. Using the arrow keys works,
285though.<p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000286
Jack Jansenbd9565a1996-04-15 12:25:44 +0000287The Python home folder $(PYTHON) is initially, when you execute the
288interpreter for the first time, set to the folder where the
289interpreter lives. You can change it here. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000290
Jack Jansenbd9565a1996-04-15 12:25:44 +0000291Finally, you can set the default startup options here, through a
292sub-dialog.
Jack Jansen5f962c21996-04-10 14:52:59 +0000293
294<h2>Applets</h2>
295
Jack Jansenbd9565a1996-04-15 12:25:44 +0000296An applet is a fullblown application written in Python, similar to an
297AppleScript applet (and completely different from a Java
298applet). Applets are currently only supported on PowerPC macintoshes,
299and are created using the <CODE>mkapplet</CODE> program. You create an
300applet by dropping the python source script onto mkapplet. The
301<CODE>Demo</CODE> folder contains an example of a more involved applet
302with its own resource file, etc. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000303
Jack Jansenbd9565a1996-04-15 12:25:44 +0000304Note that while an applet behaves as a fullblown Macintosh application
305it is not self-sufficient, so distributing it to a machine without an
306installed Python interpreter will not work: it needs the shared python
307execution engine <CODE>PythonCore</CODE>, and probably various modules
308from the Lib and PlugIns folders. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000309
310<h2>Customizing applets</h2>
311
Jack Jansenbd9565a1996-04-15 12:25:44 +0000312Applets can have their own settings for the startup options and module
313search path. Dropping an applet on the <CODE>EditPythonPrefs</CODE>
314application allows you to set these, in the same way as
315double-clicking EditPythonPrefs allows you to set the system-wide
316defaults. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000317
Jack Jansenbd9565a1996-04-15 12:25:44 +0000318Actually, not only applets but also the interpreter itself can have
319non-default settings for path and options. If you make a copy of the
320interpreter and drop this copy onto EditPythonPrefs you will have an
321interpreter that has a different set of default settings.
Jack Jansen5f962c21996-04-10 14:52:59 +0000322
323<h2>Where to go from here</h2>
324
Jack Jansenbd9565a1996-04-15 12:25:44 +0000325The previously mentioned <A
326HREF="http://www.python.org/doc/tut/tut.html">Python Tutorial</A> is
327an excellent place to start reading if you have never used Python
328before. Other documentation such as the library reference manual is
329indexed at the <A HREF="http://www.python.org/doc/">Python
330Documentation</A> page. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000331
Jack Jansenbd9565a1996-04-15 12:25:44 +0000332There are some <A HREF="index.html">annotated sample programs</A>
333available that show some mac-specific issues, like use of various
334toolboxes and creation of Python applets. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000335
Jack Jansenbd9565a1996-04-15 12:25:44 +0000336Finally, the <CODE>Demo</CODE> folder in the Macintosh distribution
337contains a number of other example programs. Most of these are only
338very lightly documented, but they may help you to understand some
339aspects of using Python. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000340
341The best way to contact fellow Macintosh Python programmers is to join
Jack Jansenbd9565a1996-04-15 12:25:44 +0000342the MacPython Special Interest Group mailing list. Send a message with
343"info" in the body to <A
344HREF="mailto:pythonmac-sig-request@python.org">pythonmac-sig-request@python.org</A>
345or view the <A
346HREF="http://www.python.org/sigs/pythonmac-sig/">Pythonmac SIG
347page</A> on the <A HREF="http://www.python.org">www.python.org</A> WWW
348server. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000349
350<h2>Troubleshooting</h2>
351
Jack Jansenbd9565a1996-04-15 12:25:44 +0000352Python is a rather safe language, and hence it should be difficult to
353crash the interpreter of the system with a Python script. There is an
354exception to this rule, though: the modules that interface to the
355system toolboxes (windowing, quickdraw, etc) do very little error
356checking and therefore a misbehaving program using these modules may
357indeed crash the system. Such programs are unfortunately rather
358difficult to debug, since the crash does not generate the standard
359Python stack trace, obviously, and since debugging print statements
360will often interfere with the operation of the program. There is
361little to do about this currently. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000362
Jack Jansenbd9565a1996-04-15 12:25:44 +0000363Probably the most common cause of problems with modules ported from
364other systems is the Mac end-of-line convention. Where unix uses
Jack Jansend9585c91996-05-07 15:28:20 +0000365linefeed, 0x0a, to separate lines the mac uses carriage return,
3660x0d. To complicate matters more a lot of mac programming editors like
Jack Jansenbd9565a1996-04-15 12:25:44 +0000367BBEdit and emacs will work happily with both conventions, so the file
368will appear to be correct in the editor but cause strange errors when
369imported. BBEdit has a popup menu which allows you to inspect (and
370set) the end-of-line convention used in a file. <p>
Jack Jansen5f962c21996-04-10 14:52:59 +0000371
372<HR>
373<A HREF="http://www.cwi.nl/~jack">Jack Jansen</A>,
Jack Jansen08365421996-04-19 15:56:08 +0000374<A HREF="mailto:jack@cwi.nl">jack@cwi.nl</A>, 19-Apr-1996.
Jack Jansen5f962c21996-04-10 14:52:59 +0000375
376</BODY>
377</HTML>