280 lines
14 KiB
HTML
280 lines
14 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<TITLE>Using Python on the Macintosh</TITLE>
|
|
</HEAD>
|
|
<BODY>
|
|
<H1>Using Python on the Macintosh</H1>
|
|
<EM>(preliminary)</EM>
|
|
<HR>
|
|
|
|
This document is an introduction to using Python on the Apple Macintosh.
|
|
It does not introduce the language itself, for this you should refer
|
|
to the <A HREF="http://www.python.org/doc/tut/tut.html">Python Tutorial</A>
|
|
by Guido van Rossum. This guide
|
|
more-or-less replaces chapter two of the tutorial, and provides some
|
|
additional material. <p>
|
|
|
|
The document refers to Python 1.3.3 or higher, some of the features (like
|
|
setting applet options) will not work in earlier versions of Python. <p>
|
|
|
|
<h2>Invoking the interpreter</h2>
|
|
|
|
The name of the interpreter may differ on different installations: it may
|
|
be called <CODE>Python</CODE>, <CODE>PythonPPC</CODE> (for powerpc macs) or
|
|
<CODE>Python68K</CODE> (indeed, for 68K macs). It will always be recognizable by
|
|
the "16 ton" icon, though. You start the interpreter in interactive mode by
|
|
double-clicking it. <p>
|
|
|
|
<img src="html.icons/python.gif"><p>
|
|
|
|
This should give you a text window with an informative version string and a prompt,
|
|
something like the following:
|
|
<PRE>
|
|
Python 1.3.3 (Apr 7 1996) [CW PPC w/GUSI]
|
|
Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
|
|
>>>
|
|
</PRE>
|
|
The version string tells you the version of Python, whether it was built for
|
|
PPC or 68K macs and possibly some options used to build the interpreter. If
|
|
you find a bug or have a question about how the interpreter works it is a good
|
|
idea to include the version information in your message. <p>
|
|
|
|
At the prompt you can type interactive python commands. See the tutorial for
|
|
more information. The interactive window works more-or-less like a Communication
|
|
Toolbox or Telnet window: you type commands at the bottom and terminate them with
|
|
the <EM>[return]</EM> or <EM>[enter]</EM> key. Interpreter feedback also appears
|
|
at the bottom of the window, and the contents scroll as output is added. You can
|
|
use copy and paste in the normal way, but be sure to paste only at the bottom
|
|
of the document.
|
|
|
|
<h2>Creating Python scripts</h2>
|
|
|
|
The Python interpreter works in a way that is different from what you would
|
|
expect of a macintosh program: the interpreter is just that: an interpreter.
|
|
There is no builtin editor or other development support. Hence, to create
|
|
a Python script you need an external text editor. For a first script you
|
|
can use any editor that can create plain, unstyled text files, such as
|
|
<CODE>SimpleText</CODE>. <p>
|
|
|
|
For more serious scripts, though, it is advisable to use a programmers editor,
|
|
such as <CODE>BBEdit</CODE> or <CODE>Alpha</CODE>. BBEdit is my favorite: it comes in a
|
|
commercial version but also in a fully-functional free version
|
|
<CODE>BBEdit Lite</CODE>. You can download it from the
|
|
<A HREF="http://www.barebones.com/">BareBones</A> site.
|
|
The free version will probably provide all the functionality you will ever need.
|
|
Besides the standard edit facilities it has multi-file searches and many other
|
|
goodies that can be very handy when editing programs. <p>
|
|
|
|
After you have created your script in the editor of your choice you drop it on
|
|
the interpreter. This will start the interpreter executing the script, again with
|
|
a console window in which the output appears and in which you can type input if
|
|
the script requires it. Normally the interpreter will close the window and quit
|
|
as soon as the script is done executing, see below under
|
|
<A HREF="#startup">startup options</A>
|
|
for a way to change this. <p>
|
|
|
|
It is a good idea to have the names of all your scripts end in <CODE>.py</CODE>. While
|
|
this is not necessary for standalone scripts it is needed for modules, and it is
|
|
probably a good idea to start the habit now. <p>
|
|
|
|
<h2>Clickable python scripts</h2>
|
|
|
|
If you create your script with the correct creator and type, creator <CODE>'Pyth'</CODE>
|
|
and type <CODE>'TEXT'</CODE>, you can double-click your script and it will automatically
|
|
invoke the interpreter. If you use BBEdit you can tell it about the Python file
|
|
type by adding it to the "file types" sections of the preferences. Then, if you save
|
|
a file for the first time you can tell BBEdit to save the file as a Python script
|
|
through the "options" choice of the save dialog. <p>
|
|
|
|
The <CODE>Scripts</CODE> folder contains a script <CODE>fixfiletypes</CODE> that will
|
|
recursively traverse a folder and set the correct creator and type for all files
|
|
ending in <CODE>.py</CODE>. <p>
|
|
|
|
<h2>Interaction with the user</h2>
|
|
|
|
Normally, the interpreter will check for user input (mouse clicks, keyboard
|
|
input) every once in a while, so it is possible to switch to other applications
|
|
while a script runs. It is also possible to interrupt the interpreter with
|
|
the standard command-period keypress, this will raise the <CODE>KeyboardInterrupt</CODE>
|
|
exception. Scripts may, however, turn off this behaviour to facilitate their
|
|
own event handling. Such scripts can only be killed with the command-option-escape
|
|
shortcut.
|
|
|
|
<h2><A NAME="startup">startup options</A></h2>
|
|
|
|
If the <EM>option</EM> key is depressed when Python starts executing the
|
|
interpreter will bring up an options dialog thru which you can influence the way
|
|
the interpreter behaves. Keep the option key depressed until the dialog comes up. <p>
|
|
|
|
<img src="html.icons/options.gif"><p>
|
|
|
|
The options modify the interpreters behaviour in the following way:
|
|
<ul>
|
|
<li> the interpreter goes to interactive mode (in stead of
|
|
exiting) after a script has terminated normally,
|
|
<li> for every module imported a line is printed telling you where the
|
|
module was loaded from,
|
|
<li> do not print the values of expressions executed as statements in an
|
|
interactive python,
|
|
<li> do not buffer stdout and stderr,
|
|
<li> print some debugging output during the parsing phase,
|
|
<li> keep the output window open when a script terminates.
|
|
</ul>
|
|
In addition, you can enter a unix-style command line which is passed to the script
|
|
in <CODE>sys.argv</CODE>. Sys.argv[0] is always the name of the script being executed,
|
|
additional values can be passed here. Quoting works as expected. <p>
|
|
|
|
The default options are also settable on a system-wide basis, see the section on
|
|
<A HREF="#preferences">editing preferences</A>. <p>
|
|
|
|
<h2>Module search path</h2>
|
|
|
|
The module search path, <CODE>sys.path</CODE>, contains the folders python will search
|
|
when you import a module. The path is settable on a system-wide basis (see the
|
|
preferences section), and normally comprises the current folder (where the script
|
|
lives), the <CODE>Lib</CODE> folder and some of its subfolders and possibly some more. <p>
|
|
|
|
<h2>Working folder</h2>
|
|
|
|
The unix concept of a <I>working directory</I> does not translate directly to
|
|
a similar concept on the Macintosh. To facilitate easy porting and the use of
|
|
relative pathnames in scripts the interpreter simulates a working directory. When
|
|
a script is started the initial working directory is the folder where the script
|
|
lives. In case of an interactive interpreter the working directory is the folder
|
|
where the interpreter lives. The "standard file" folder does <EM>not</EM> follow
|
|
the working directory, it follows the standard MacOS rules (which are settable
|
|
through a control panel since MacOS 7.5).
|
|
|
|
<h2>Interactive startup file</h2>
|
|
|
|
If the folder containing the interpreter contains a file named <CODE>PythonStartup</CODE>
|
|
this file is executed when you start an interactive interpreter. In this file you
|
|
could import modules you often use and other such things. <p>
|
|
|
|
|
|
<h2>Compiled python scripts</h2>
|
|
|
|
Once a python module has been imported the interpreter creates a compiled version
|
|
which is stored in a file with the ".py" extension replaced by ".pyc". These
|
|
compiled files, with creator <CODE>'Pyth'</CODE> and type <CODE>'PYC '</CODE> load faster
|
|
when imported (because they do not have to be parsed). The <CODE>Lib</CODE> folder
|
|
contains a script <CODE>compileall.py</CODE>, running this script will cause all modules
|
|
along the python search path to be precompiled, which will speed up your programs.
|
|
Compiled files are also double-clickable. <p>
|
|
|
|
<h2>Python resources</h2>
|
|
|
|
MacPython has the ability to collect a number of compiled modules together
|
|
in the resource fork of a single file. This feature is useful if you
|
|
distribute a python program and want to minimize clutter: you can put all the
|
|
needed modules in a single file (which could even be the interpreter itself). <p>
|
|
|
|
If the module search path contains a filename as one of its entries (as opposed to
|
|
a folder name, which is the normal case) this file will be searched for a resource
|
|
with type <CODE>'PYC '</CODE> and a name matching the module being imported. <p>
|
|
|
|
The <CODE>scripts</CODE> folder contains a script <CODE>PackLibDir</CODE> which will convert
|
|
a number of modules (or possibly a complete subtree full of modules) into such a
|
|
resource file.
|
|
|
|
<h2><A NAME="preferences">Setting interpreter preferences</A></h2>
|
|
|
|
The python interpreter keeps a preferences file in the standard location in the
|
|
system folder. In this preferences file it remembers the default module search
|
|
path and the default settings for the runtime options. The preferences are settable
|
|
via <CODE>EditPythonPrefs</CODE>. For PPC python this is a standalone program living
|
|
in the main Python folder, for 68K python it is a script in the <CODE>Scripts</CODE>
|
|
folder. <p>
|
|
|
|
The interface to edit the preferences is rather clunky for the current release. <p>
|
|
|
|
<img src="html.icons/preferences.gif"><p>
|
|
|
|
In the editable text field at the top you enter the initial module search path,
|
|
using newline as a separator. There are two special values you can use here:
|
|
an initial substring <CODE>$(PYTHON)</CODE> will expand to the Python home folder
|
|
and a value of <CODE>$(APPLICATION)</CODE> will expand to the the python application
|
|
itself. Note that the text field may extend "beyond the bottom" even though it
|
|
does not have a scroll bar. Using the arrow keys works, though.<p>
|
|
|
|
The Python home folder $(PYTHON) is initially, when you execute the interpreter
|
|
for the first time, set to the folder where the interpreter lives. You can change it
|
|
here. <p>
|
|
|
|
Finally, you can set the default startup options here, through a sub-dialog.
|
|
|
|
<h2>Applets</h2>
|
|
|
|
An applet is a fullblown application written in Python, similar to an AppleScript
|
|
applet (and completely different from a Java applet). Applets are currently only
|
|
supported on PowerPC macintoshes, and are created using the <CODE>mkapplet</CODE>
|
|
program. You create an applet by dropping the python source script onto mkapplet.
|
|
The <CODE>Demo</CODE> folder contains an example of a more involved applet with its
|
|
own resource file, etc. <p>
|
|
|
|
Note that while an applet behaves as a fullblown Macintosh application it is
|
|
not self-sufficient, so distributing it to a machine without an installed Python
|
|
interpreter will not work: it needs the shared python execution engine
|
|
<CODE>PythonCore</CODE>, and probably various modules from the Lib and PlugIns folders. <p>
|
|
|
|
<h2>Customizing applets</h2>
|
|
|
|
Applets can have their own settings for the startup options and module search
|
|
path. Dropping an applet on the <CODE>EditPythonPrefs</CODE>
|
|
application allows you to set
|
|
these, in the same way as double-clicking EditPythonPrefs allows you to set
|
|
the system-wide defaults. <p>
|
|
|
|
Actually, not only applets but also the interpreter itself can have non-default
|
|
settings for path and options. If you make a copy of the interpreter and drop
|
|
this copy onto EditPythonPrefs you will have an interpreter that has a different
|
|
set of default settings.
|
|
|
|
<h2>Where to go from here</h2>
|
|
|
|
The previously mentioned <A HREF="http://www.python.org/doc/tut/tut.html">Python
|
|
Tutorial</A> is an excellent place to start reading if you have never used
|
|
Python before. Other documentation such as the library reference manual is
|
|
indexed at the <A HREF="http://www.python.org/doc/">Python Documentation</A>
|
|
page. <p>
|
|
|
|
There are some <A HREF="index.html">annotated sample programs</A> available
|
|
that show some mac-specific issues, like use of various toolboxes and creation
|
|
of Python applets. <p>
|
|
|
|
Finally, the <CODE>Demo</CODE> folder in the Macintosh distribution contains
|
|
a number of other example programs. Most of these are only very lightly documented,
|
|
but they may help you to understand some aspects of using Python. <p>
|
|
|
|
The best way to contact fellow Macintosh Python programmers is to join
|
|
the MacPython Special Interest Group mailing list. Send a message with "info"
|
|
in the body to <A HREF="mailto:pythonmac-sig-request@python.org">pythonmac-sig-request@python.org</A>
|
|
or view the <A HREF="http://www.python.org/sigs/pythonmac-sig/">Pythonmac SIG page</A> on the
|
|
<A HREF="http://www.python.org">www.python.org</A> WWW server. <p>
|
|
|
|
<h2>Troubleshooting</h2>
|
|
|
|
Python is a rather safe language, and hence it should be difficult to crash the
|
|
interpreter of the system with a Python script. There is an exception to this rule,
|
|
though: the modules that interface to the system toolboxes (windowing, quickdraw,
|
|
etc) do very little error checking and therefore a misbehaving program using these
|
|
modules may indeed crash the system. Such programs are unfortunately rather
|
|
difficult to debug, since the crash does not generate the standard Python stack
|
|
trace, obviously, and since debugging print statements will often interfere with
|
|
the operation of the program. There is little to do about this currently. <p>
|
|
|
|
Probably the most common cause of problems with modules ported from other
|
|
systems is the Mac end-of-line convention. Where unix uses linefeed, 0x0d, to
|
|
separate lines the mac uses carriage return, 0x0a. To complicate matters more
|
|
a lot of mac programming editors like BBEdit and emacs will work happily with
|
|
both conventions, so the file will appear to be correct in the editor but cause
|
|
strange errors when imported. BBEdit has a popup menu which allows you to inspect
|
|
(and set) the end-of-line convention used in a file. <p>
|
|
|
|
<HR>
|
|
<A HREF="http://www.cwi.nl/~jack">Jack Jansen</A>,
|
|
<A HREF="mailto:jack@cwi.nl">jack@cwi.nl</A>, 7-Apr-1996.
|
|
|
|
</BODY>
|
|
</HTML>
|