blob: 872bb9e99f8d69d91c0b0c775223e5714d3723c7 [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
10This document is an introduction to using Python on the Apple Macintosh.
11It does not introduce the language itself, for this you should refer
12to the <A HREF="http://www.python.org/doc/tut/tut.html">Python Tutorial</A>
13by Guido van Rossum. This guide
14more-or-less replaces chapter two of the tutorial, and provides some
15additional material. <p>
16
17The document refers to Python 1.3.3 or higher, some of the features (like
18setting applet options) will not work in earlier versions of Python. <p>
19
20<h2>Invoking the interpreter</h2>
21
22The name of the interpreter may differ on different installations: it may
23be called <CODE>Python</CODE>, <CODE>PythonPPC</CODE> (for powerpc macs) or
24<CODE>Python68K</CODE> (indeed, for 68K macs). It will always be recognizable by
25the "16 ton" icon, though. You start the interpreter in interactive mode by
26double-clicking it. <p>
27
28<img src="html.icons/python.gif"><p>
29
30This should give you a text window with an informative version string and a prompt,
31something like the following:
32<PRE>
33Python 1.3.3 (Apr 7 1996) [CW PPC w/GUSI]
34Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
35&gt;&gt;&gt;
36</PRE>
37The version string tells you the version of Python, whether it was built for
38PPC or 68K macs and possibly some options used to build the interpreter. If
39you find a bug or have a question about how the interpreter works it is a good
40idea to include the version information in your message. <p>
41
42At the prompt you can type interactive python commands. See the tutorial for
43more information. The interactive window works more-or-less like a Communication
44Toolbox or Telnet window: you type commands at the bottom and terminate them with
45the <EM>[return]</EM> or <EM>[enter]</EM> key. Interpreter feedback also appears
46at the bottom of the window, and the contents scroll as output is added. You can
47use copy and paste in the normal way, but be sure to paste only at the bottom
48of the document.
49
50<h2>Creating Python scripts</h2>
51
52The Python interpreter works in a way that is different from what you would
53expect of a macintosh program: the interpreter is just that: an interpreter.
54There is no builtin editor or other development support. Hence, to create
55a Python script you need an external text editor. For a first script you
56can use any editor that can create plain, unstyled text files, such as
57<CODE>SimpleText</CODE>. <p>
58
59For more serious scripts, though, it is advisable to use a programmers editor,
60such as <CODE>BBEdit</CODE> or <CODE>Alpha</CODE>. BBEdit is my favorite: it comes in a
61commercial version but also in a fully-functional free version
62<CODE>BBEdit Lite</CODE>. You can download it from the
63<A HREF="http://www.barebones.com/">BareBones</A> site.
64The free version will probably provide all the functionality you will ever need.
65Besides the standard edit facilities it has multi-file searches and many other
66goodies that can be very handy when editing programs. <p>
67
68After you have created your script in the editor of your choice you drop it on
69the interpreter. This will start the interpreter executing the script, again with
70a console window in which the output appears and in which you can type input if
71the script requires it. Normally the interpreter will close the window and quit
72as soon as the script is done executing, see below under
73<A HREF="#startup">startup options</A>
74for a way to change this. <p>
75
76It is a good idea to have the names of all your scripts end in <CODE>.py</CODE>. While
77this is not necessary for standalone scripts it is needed for modules, and it is
78probably a good idea to start the habit now. <p>
79
80<h2>Clickable python scripts</h2>
81
82If you create your script with the correct creator and type, creator <CODE>'Pyth'</CODE>
83and type <CODE>'TEXT'</CODE>, you can double-click your script and it will automatically
84invoke the interpreter. If you use BBEdit you can tell it about the Python file
85type by adding it to the "file types" sections of the preferences. Then, if you save
86a file for the first time you can tell BBEdit to save the file as a Python script
87through the "options" choice of the save dialog. <p>
88
89The <CODE>Scripts</CODE> folder contains a script <CODE>fixfiletypes</CODE> that will
90recursively traverse a folder and set the correct creator and type for all files
91ending in <CODE>.py</CODE>. <p>
92
93<h2>Interaction with the user</h2>
94
95Normally, the interpreter will check for user input (mouse clicks, keyboard
96input) every once in a while, so it is possible to switch to other applications
97while a script runs. It is also possible to interrupt the interpreter with
98the standard command-period keypress, this will raise the <CODE>KeyboardInterrupt</CODE>
99exception. Scripts may, however, turn off this behaviour to facilitate their
100own event handling. Such scripts can only be killed with the command-option-escape
101shortcut.
102
103<h2><A NAME="startup">startup options</A></h2>
104
105If the <EM>option</EM> key is depressed when Python starts executing the
106interpreter will bring up an options dialog thru which you can influence the way
107the interpreter behaves. Keep the option key depressed until the dialog comes up. <p>
108
109<img src="html.icons/options.gif"><p>
110
111The options modify the interpreters behaviour in the following way:
112<ul>
113<li> the interpreter goes to interactive mode (in stead of
114exiting) after a script has terminated normally,
115<li> for every module imported a line is printed telling you where the
116module was loaded from,
117<li> do not print the values of expressions executed as statements in an
118interactive python,
119<li> do not buffer stdout and stderr,
120<li> print some debugging output during the parsing phase,
121<li> keep the output window open when a script terminates.
122</ul>
123In addition, you can enter a unix-style command line which is passed to the script
124in <CODE>sys.argv</CODE>. Sys.argv[0] is always the name of the script being executed,
125additional values can be passed here. Quoting works as expected. <p>
126
127The default options are also settable on a system-wide basis, see the section on
128<A HREF="#preferences">editing preferences</A>. <p>
129
130<h2>Module search path</h2>
131
132The module search path, <CODE>sys.path</CODE>, contains the folders python will search
133when you import a module. The path is settable on a system-wide basis (see the
134preferences section), and normally comprises the current folder (where the script
135lives), the <CODE>Lib</CODE> folder and some of its subfolders and possibly some more. <p>
136
137<h2>Working folder</h2>
138
139The unix concept of a <I>working directory</I> does not translate directly to
140a similar concept on the Macintosh. To facilitate easy porting and the use of
141relative pathnames in scripts the interpreter simulates a working directory. When
142a script is started the initial working directory is the folder where the script
143lives. In case of an interactive interpreter the working directory is the folder
144where the interpreter lives. The "standard file" folder does <EM>not</EM> follow
145the working directory, it follows the standard MacOS rules (which are settable
146through a control panel since MacOS 7.5).
147
148<h2>Interactive startup file</h2>
149
150If the folder containing the interpreter contains a file named <CODE>PythonStartup</CODE>
151this file is executed when you start an interactive interpreter. In this file you
152could import modules you often use and other such things. <p>
153
154
155<h2>Compiled python scripts</h2>
156
157Once a python module has been imported the interpreter creates a compiled version
158which is stored in a file with the ".py" extension replaced by ".pyc". These
159compiled files, with creator <CODE>'Pyth'</CODE> and type <CODE>'PYC '</CODE> load faster
160when imported (because they do not have to be parsed). The <CODE>Lib</CODE> folder
161contains a script <CODE>compileall.py</CODE>, running this script will cause all modules
162along the python search path to be precompiled, which will speed up your programs.
163Compiled files are also double-clickable. <p>
164
165<h2>Python resources</h2>
166
167MacPython has the ability to collect a number of compiled modules together
168in the resource fork of a single file. This feature is useful if you
169distribute a python program and want to minimize clutter: you can put all the
170needed modules in a single file (which could even be the interpreter itself). <p>
171
172If the module search path contains a filename as one of its entries (as opposed to
173a folder name, which is the normal case) this file will be searched for a resource
174with type <CODE>'PYC '</CODE> and a name matching the module being imported. <p>
175
176The <CODE>scripts</CODE> folder contains a script <CODE>PackLibDir</CODE> which will convert
177a number of modules (or possibly a complete subtree full of modules) into such a
178resource file.
179
180<h2><A NAME="preferences">Setting interpreter preferences</A></h2>
181
182The python interpreter keeps a preferences file in the standard location in the
183system folder. In this preferences file it remembers the default module search
184path and the default settings for the runtime options. The preferences are settable
185via <CODE>EditPythonPrefs</CODE>. For PPC python this is a standalone program living
186in the main Python folder, for 68K python it is a script in the <CODE>Scripts</CODE>
187folder. <p>
188
189The interface to edit the preferences is rather clunky for the current release. <p>
190
191<img src="html.icons/preferences.gif"><p>
192
193In the editable text field at the top you enter the initial module search path,
194using newline as a separator. There are two special values you can use here:
195an initial substring <CODE>$(PYTHON)</CODE> will expand to the Python home folder
196and a value of <CODE>$(APPLICATION)</CODE> will expand to the the python application
197itself. Note that the text field may extend "beyond the bottom" even though it
198does not have a scroll bar. Using the arrow keys works, though.<p>
199
200The Python home folder $(PYTHON) is initially, when you execute the interpreter
201for the first time, set to the folder where the interpreter lives. You can change it
202here. <p>
203
204Finally, you can set the default startup options here, through a sub-dialog.
205
206<h2>Applets</h2>
207
208An applet is a fullblown application written in Python, similar to an AppleScript
209applet (and completely different from a Java applet). Applets are currently only
210supported on PowerPC macintoshes, and are created using the <CODE>mkapplet</CODE>
211program. You create an applet by dropping the python source script onto mkapplet.
212The <CODE>Demo</CODE> folder contains an example of a more involved applet with its
213own resource file, etc. <p>
214
215Note that while an applet behaves as a fullblown Macintosh application it is
216not self-sufficient, so distributing it to a machine without an installed Python
217interpreter will not work: it needs the shared python execution engine
218<CODE>PythonCore</CODE>, and probably various modules from the Lib and PlugIns folders. <p>
219
220<h2>Customizing applets</h2>
221
222Applets can have their own settings for the startup options and module search
223path. Dropping an applet on the <CODE>EditPythonPrefs</CODE>
224application allows you to set
225these, in the same way as double-clicking EditPythonPrefs allows you to set
226the system-wide defaults. <p>
227
228Actually, not only applets but also the interpreter itself can have non-default
229settings for path and options. If you make a copy of the interpreter and drop
230this copy onto EditPythonPrefs you will have an interpreter that has a different
231set of default settings.
232
233<h2>Where to go from here</h2>
234
235The previously mentioned <A HREF="http://www.python.org/doc/tut/tut.html">Python
236Tutorial</A> is an excellent place to start reading if you have never used
237Python before. Other documentation such as the library reference manual is
238indexed at the <A HREF="http://www.python.org/doc/">Python Documentation</A>
239page. <p>
240
241There are some <A HREF="index.html">annotated sample programs</A> available
242that show some mac-specific issues, like use of various toolboxes and creation
243of Python applets. <p>
244
245Finally, the <CODE>Demo</CODE> folder in the Macintosh distribution contains
246a number of other example programs. Most of these are only very lightly documented,
247but they may help you to understand some aspects of using Python. <p>
248
249The best way to contact fellow Macintosh Python programmers is to join
250the MacPython Special Interest Group mailing list. Send a message with "info"
251in the body to <A HREF="mailto:pythonmac-sig-request@python.org">pythonmac-sig-request@python.org</A>
252or view the <A HREF="http://www.python.org/sigs/pythonmac-sig/">Pythonmac SIG page</A> on the
253<A HREF="http://www.python.org">www.python.org</A> WWW server. <p>
254
255<h2>Troubleshooting</h2>
256
257Python is a rather safe language, and hence it should be difficult to crash the
258interpreter of the system with a Python script. There is an exception to this rule,
259though: the modules that interface to the system toolboxes (windowing, quickdraw,
260etc) do very little error checking and therefore a misbehaving program using these
261modules may indeed crash the system. Such programs are unfortunately rather
262difficult to debug, since the crash does not generate the standard Python stack
263trace, obviously, and since debugging print statements will often interfere with
264the operation of the program. There is little to do about this currently. <p>
265
266Probably the most common cause of problems with modules ported from other
267systems is the Mac end-of-line convention. Where unix uses linefeed, 0x0d, to
268separate lines the mac uses carriage return, 0x0a. To complicate matters more
269a lot of mac programming editors like BBEdit and emacs will work happily with
270both conventions, so the file will appear to be correct in the editor but cause
271strange errors when imported. BBEdit has a popup menu which allows you to inspect
272(and set) the end-of-line convention used in a file. <p>
273
274<HR>
275<A HREF="http://www.cwi.nl/~jack">Jack Jansen</A>,
276<A HREF="mailto:jack@cwi.nl">jack@cwi.nl</A>, 7-Apr-1996.
277
278</BODY>
279</HTML>