\chapter{Using Python on the Macintosh \label{using}}

\sectionauthor{Bob Savage}{bobsavage@mac.com}

Using Python on the Macintosh can seem like something completely

different than using it on a \UNIX-like or Windows system. Most of the

Python documentation, both the ``official'' documentation and

published books, describe only how Python is used on these systems,

causing confusion for the new user of MacPython. This chapter gives a

brief introduction to the specifics of using Python on a Macintosh.

\section{Getting and Installing MacPython \label{getting}}

The most recent release version as well as possible newer experimental

versions are best found at the MacPython page maintained by Jack

Jansen: \url{http://www.cwi.nl/~jack/macpython.html}.

Please refer to the \file{README} included with your distribution for

the most up-to-date instructions.

\section{Entering the interactive Interpreter

\label{interpreter}}

The interactive interpreter that you will see used in Python

documentation is started by double-clicking the

\program{PythonInterpreter} icon, which looks like a 16-ton weight

falling. You should see the version information and the

\samp{>\code{>}>~} prompt. Use it exactly as described in the

standard documentation.

\section{How to run a Python script}

There are several ways to run an existing Python script; two common

ways to run a Python script are ``drag and drop'' and ``double

clicking''. Other ways include running it from within the IDE (see

Section \ref{IDE}), or launching via AppleScript.

\subsection{Drag and drop}

One of the easiest ways to launch a Python script is via ``Drag and

Drop''. This is just like launching a text file in the Finder by

``dragging'' it over your word processor's icon and ``dropping'' it

there. Make sure that you use an icon referring to the

\program{PythonInterpreter}, not the \program{IDE} or \program{Idle}

icons which have different behaviour which is described below.

Some things that might have gone wrong:

\begin{itemize}

A window flashes after dropping the script onto the

\program{PythonInterpreter}, but then disappears. Most likely this is a

configuration issue; your \program{PythonInterpreter} is setup to exit

immediately upon completion, but your script assumes that if it prints

something that text will stick around for a while. To fix this, see

section \ref{defaults}.

After dropping the script onto the \program{PythonInterpreter}, a

window appeared which said: ``File contains \code{\e r} characters

(incorrect line endings?)''. That script probably originated on a

\UNIX{} or Windows machine. You will need to change the line endings

to the standard Mac usage. One way to do this is to open the file in

\program{BBedit}

(\url{http://www.barebones.com/products/bbedit_lite.html}) which can

easily change the line endings between Mac, DOS, and \UNIX\ styles.

When you waved the script icon over the \program{PythonInterpreter},

the \program{PythonInterpreter} icon did not hilight. Most likely the

Creator code and document type is unset (or set incorrectly) -- this

often happens when a file originates on a non-Mac computer. See

section \ref{creator-code} for more details.

\end{itemize}

\subsection{Set Creator and Double Click \label{creator-code}}

If the script that you want to launch has the appropriate Creator Code

and File Type you can simply double-click on the script to launch it.

To be ``double-clickable'' a file needs to be of type \samp{TEXT},

with a creator code of \samp{Pyth}.

Setting the creator code and filetype can be done with the IDE (see

sections \ref{IDEwrite} and \ref{IDEapplet}), with an editor with a

Python mode (\program{BBEdit}) -- see section

\ref{scripting-with-BBedit}, or with assorted other Mac utilities, but

a script (\file{fixfiletypes.py}) has been included in the MacPython

distribution, making it possible to set the proper Type and Creator

Codes with Python.

The \file{fixfiletypes.py} script will change the file type and

creator codes for the indicated directory. To use

\file{fixfiletypes.py}:

\begin{enumerate}

Locate it in the \file{scripts} folder of the \file{Mac} folder of the

MacPython distribution.

Put all of the scripts that you want to fix in a folder with nothing

else in it.

Double-click on the \file{fixfiletypes.py} icon.

Navigate into the folder of files you want to fix, and press the

``Select current folder'' button.

\end{enumerate}

\section{Simulating command line arguments

\label{argv}}

There are two ways to simulate command-line arguments with MacPython.

\begin{enumerate}

\item via Interpreter options

\begin{itemize} % nestable? I hope so!

\item Hold the option-key down when launching your script. This will

bring up a dialog box of Python Interpreter options.

\item Click ``Set \UNIX-style command line..'' button.

\item Type the arguments into the ``Argument'' field.

\item Click ``OK''

\item Click ``Run''.

\end{itemize} % end

\item via drag and drop

If you save the script as an applet (see Section \ref{IDEapplet}), you

can also simulate some command-line arguments via

``Drag-and-Drop''. In this case, the names of the files that were

dropped onto the applet will be appended to \code{sys.argv}, so that

it will appear to the script as though they had been typed on a

command line. As on \UNIX\ systems, the first item in \code{sys.srgv} is

the path to the applet, and the rest are the files dropped on the

applet.

\end{enumerate}

\section{Creating a Python script}

Since Python scripts are simply text files, they can be created in any

way that text files can be created, but some special tools also exist

with extra features.

\subsection{In an editor}

You can create a text file with any word processing program such as

\program{MSWord} or \program{AppleWorks} but you need to make sure

that the file is saved as ``\ASCII'' or ``plain text''.

\subsubsection{Editors with Python modes}

Several text editors have additional features that add functionality

when you are creating a Python script. These can include coloring

Python keywords to make your code easier to read, module browsing, or

a built-in debugger. These include \program{Alpha}, \program{Pepper},

and \program{BBedit}, and the MacPython IDE (Section \ref{IDE}).

\subsubsection{BBedit \label{scripting-with-BBedit}}

If you use \program{BBEdit} to create your scripts you will want to tell it about the Python creator code so that

you can simply double click on the saved file to launch it.

\begin{itemize}

\item Launch \program{BBEdit}.

\item Select ``Preferences'' from the ``Edit'' menu.

\item Select ``File Types'' from the scrolling list.

\item click on the ``Add...'' button and navigate to

\program{PythonInterpreter} in the main directory of the

MacPython distribution; click ``open''.

\item Click on the ``Save'' button in the Preferences panel.

\end{itemize}

\section{The IDE\label{IDE}}

The \program{Python IDE} (Integrated Development Environment) is a

separate application that acts as a text editor for your Python code,

a class browser, a graphical debugger, and more.

\subsection{Using the ``Python Interactive'' window}

Use this window like you would the \program{PythonInterpreter}, except

that you cannot use the ``Drag and drop'' method above. Instead,

dropping a script onto the \program{Python IDE} icon will open the

file in a separate script window (which you can then execute manually

-- see section \ref{IDEexecution}).

\subsection{Writing a Python Script \label{IDEwrite}}

In addition to using the \program{Python IDE} interactively, you can

also type out a complete Python program, saving it incrementally, and

execute it or smaller selections of it.

You can create a new script, open a previously saved script, and save

your currently open script by selecting the appropriate item in the

``File'' menu. Dropping a Python script onto the

\program{Python IDE} will open it for editting.

If you try to open a script with the \program{Python IDE} but either

can't locate it from the ``Open'' dialog box, or you get an error

message like ``Can't open file of type ...'' see section

\ref{creator-code}.

When the \program{Python IDE} saves a script, it uses the creator code

settings which are available by clicking on the small black triangle

on the top right of the document window, and selecting ``save

options''. The default is to save the file with the \program{Python

IDE} as the creator, this means that you can open the file for editing

by simply double-clicking on its icon. You might want to change this

behaviour so that it will be opened by the

\program{PythonInterpreter}, and run. To do this simply choose

``Python Interpreter'' from the ``save options''. Note that these

options are associated with the \emph{file} not the application.

\subsection{Executing a script from within the IDE

\label{IDEexecution}}

You can run the script in the frontmost window of the \program{Python

IDE} by hitting the run all button. You should be aware, however that

if you use the Python convention \samp{if __name__ == "__main__":} the

script will \emph{not} be ``__main__'' by default. To get that

behaviour you must select the ``Run as __main__'' option from the

small black triangle on the top right of the document window. Note

that this option is associated with the \emph{file} not the

application. It \emph{will} stay active after a save, however; to shut

this feature off simply select it again.

\subsection{``Save as'' versus ``Save as Applet''

\label{IDEapplet}}

When you are done writing your Python script you have the option of

saving it as an ``applet'' (by selecting ``Save as applet'' from the

``File'' menu). This has a significant advantage in that you can drop

files or folders onto it, to pass them to the applet the way

command-line users would type them onto the command-line to pass them

as arguments to the script. However, you should make sure to save the

applet as a separate file, do not overwrite the script you are

writing, because you will not be able to edit it again.

Accessing the items passed to the applet via ``drag-and-drop'' is done

using the standard \member{sys.argv} mechanism. See the general

documentation for more

Note that saving a script as an applet will not make it runnable on a

system without a Python installation.

\section{Configuration \label{configuration}}

The MacPython distribution comes with \program{EditPythonPrefs}, an

applet which will help you to customize the MacPython environment for

your working habits.

\subsection{EditPythonPrefs\label{EditPythonPrefs}}

\program{EditPythonPrefs} gives you the capability to configure Python

to behave the way you want it to. There are two ways to use

\program{EditPythonPrefs}, you can use it to set the preferences in

general, or you can drop a particular Python engine onto it to

customize only that version. The latter can be handy if, for example,

you want to have a second copy of the \program{PythonInterpreter} that

keeps the output window open on a normal exit even though you prefer

to normally not work that way.

To change the default preferences, simply double-click on

\program{EditPythonPrefs}. To change the preferences only for one copy

of the Interpreter, drop the icon for that copy onto

\program{EditPythonPrefs}. You can also use \program{EditPythonPrefs}

in this fashion to set the preferences of the \program{Python IDE} and

any applets you create -- see section %s \ref{BuildApplet} and

\ref{IDEapplet}.

\subsection{Adding modules to the Module Search Path

\label{search-path}}

When executing an \keyword{import} statement, Python looks for modules

in places defined by the \member{sys.path} To edit the

\member{sys.path} on a Mac, launch \program{EditPythonPrefs}, and

enter them into the largish field at the top (one per line).

Since MacPython defines a main Python directory, the easiest thing is

to add folders to search within the main Python directory. To add a

folder of scripts that you created called ``My Folder'' located in the

main Python Folder, enter \samp{\$(PYTHON):My Folder} onto a new line.

To add the Desktop under OS 9 or below, add

\samp{StartupDriveName:Desktop Folder} on a new line.

\subsection{Default startup options \label{defaults}}

The ``Default startup options...'' button in the

\program{EditPythonPrefs} dialog box gives you many options including

the ability to keep the ``Output'' window open after the script

terminates, and the ability to enter interactive mode after the

termination of the run script. The latter can be very helpful if you

want to examine the objects that were created during your script.

\section{Mac OS X}

At the time of this writing Mac OS X had just been released as a

Public Beta. Efforts are under way to bring MacPython to Mac OS X. The

MacPython release \version{1.5.2c1} runs quite well within the

``Classic'' environment. A ``Carbon'' port of the MacPython code is

being prepared for release, and several people have made a command

line version available to the ``Darwin'' layer (which is accessible

via Terminal.app).