Doc/mac/using.tex

   1 \chapter{Using Python on a Macintosh \label{using}}
   2 \sectionauthor{Bob Savage}{bobsavage@mac.com}
   3
   4 Python on a Macintosh running Mac OS X is in principle very similar to
   5 Python on any other \UNIX platform, but there are a number of additional
   6 features such as the IDE and the Package Manager that are worth pointing out.
   7
   8 Python on Mac OS 9 or earlier can be quite different from Python on
   9 Unix or Windows, but is beyond the scope of this manual, as that platform
  10 is no longer supported, starting with Python 2.4. See
  11 \url{http://www.cwi.nl/\textasciitilde jack/macpython} for installers
  12 for the latest 2.3 release for Mac OS 9 and related documentation.
  13
  14 \section{Getting and Installing MacPython \label{getting-OSX}}
  15
  16 Mac OS X 10.3 comes with Python 2.3 pre-installed by Apple.
  17 This installation does not come with the IDE and other additions, however,
  18 so to get these you need to install the \program{MacPython for Panther additions}
  19 from the MacPython website, \url{http://www.cwi.nl/\textasciitilde jack/macpython}.
  20
  21 For MacPython 2.4, or for any MacPython on earlier releases of Mac OS X,
  22 you need to install a full distribution from the same website.
  23
  24 What you get after installing is a number of things:
  25
  26 \begin{itemize}
  27     \item A \file{MacPython-2.3} folder in your \file{Applications}
  28     folder. In here you find the PythonIDE Integrated Development Environment;
  29     PythonLauncher, which handles double-clicking Python scripts from
  30     the Finder; and the Package Manager.
  31
  32     \item A fairly standard \UNIX{} commandline Python interpreter in
  33     \file{/usr/local/bin/python}, but without the usual
  34     \file{/usr/local/lib/python}.
  35
  36     \item A framework \file{/Library/Frameworks/Python.framework}, where
  37     all the action really is, but which you usually do not have to be aware of.
  38 \end{itemize}
  39
  40 To uninstall MacPython you can simply remove these three things.
  41
  42 If you use the ``additions'' installer to install on top of an existing
  43 Apple-Python you will not get the framework and the commandline interpreter,
  44 as they have been installed by Apple already, in
  45 \file{/System/Library/Frameworks/Python.framework} and
  46 \file{/usr/bin/python}, respectively. You should in principle never modify
  47 or delete these, as they are Apple-controlled and may be used by Apple- or
  48 third-party software.
  49
  50 PythonIDE contains an Apple Help Viewer book called "MacPython Help"
  51 which you can access through its help menu. If you are completely new to
  52 Python you should start reading the IDE introduction in that document.
  53
  54 If you are familiar with Python on other \UNIX{} platforms you should
  55 read the section on running Python scripts from the \UNIX{} shell.
  56
  57 \subsection{How to run a Python script}
  58
  59 Your best way to get started with Python on Mac OS X is through the PythonIDE
  60 integrated development environment, see section \ref{IDE} and use the Help
  61 menu when the IDE is running.
  62
  63 If you want to run Python scripts from the Terminal window command line
  64 or from the Finder you first need an editor to create your script.
  65 Mac OS X comes with a number of standard \UNIX{} command line editors,
  66 \program{vim} and \program{emacs} among them. If you want a more Mac-like
  67 editor \program{BBEdit} or \program{TextWrangler} from Bare Bones Software
  68 (see \url{http://www.barebones.com/products/bbedit/index.shtml}) are
  69 good choices.  \program{AppleWorks} or any other
  70 word processor that can save files in ASCII is also a possibility, including
  71 \program{TextEdit} which is included with OS X.
  72
  73 To run your script from the Terminal window you must make sure that
  74 \file{/usr/local/bin} is in your shell search path.
  75
  76 To run your script from the Finder you have two options:
  77 \begin{itemize}
  78     \item Drag it to \program{PythonLauncher}
  79     \item Select \program{PythonLauncher} as the default application
  80     to open your script (or any .py script) through the finder Info window
  81     and double-click it.
  82 \end{itemize}
  83
  84 PythonLauncher has various preferences to control how your script is launched.
  85 Option-dragging allows you to change these for one invocation, or use its
  86 Preferences menu to change things globally.
  87
  88 \subsection{Running scripts with a GUI \label{osx-gui-scripts}}
  89
  90 There is one Mac OS X quirk that you need to be aware of: programs
  91 that talk to the Aqua window manager (in other words, anything that has a GUI)
  92 need to be run in a special way. Use \program{pythonw} instead of \program{python}
  93 to start such scripts.
  94
  95 \subsection{configuration}
  96
  97 MacPython honours all standard \UNIX{} environment variables such as
  98 \envvar{PYTHONPATH}, but setting these variables for programs started
  99 from the Finder is non-standard
 100 as the Finder does not read your \file{.profile} or \file{.cshrc} at startup.
 101 You need to create a file \file{\textasciitilde /.MacOSX/environment.plist}.
 102 See Apple's Technical Document QA1067 for details.
 103
 104 Installing additional Python packages is most easily done through the
 105 Package Manager, see the MacPython Help Book for details.
 106
 107
 108 \section{The IDE\label{IDE}}
 109
 110 The \program{Python IDE} (Integrated Development Environment) is a
 111 separate application that acts as a text editor for your Python code,
 112 a class browser, a graphical debugger, and more.
 113
 114 The online Python Help contains a quick walkthrough of the IDE that
 115 shows the major features and how to use them.
 116
 117 \subsection{Using the ``Python Interactive'' window}
 118
 119 Use this window like you would use a normal \UNIX{} command line
 120 interpreter.
 121
 122 \subsection{Writing a Python Script \label{IDEwrite}}
 123
 124 In addition to using the \program{Python IDE} interactively, you can
 125 also type out a complete Python program, saving it incrementally, and
 126 execute it or smaller selections of it.
 127
 128 You can create a new script, open a previously saved script, and save
 129 your currently open script by selecting the appropriate item in the
 130 ``File'' menu. Dropping a Python script onto the
 131 \program{Python IDE} will open it for editing.
 132
 133 When the \program{Python IDE} saves a script, it uses the creator code
 134 settings which are available by clicking on the small black triangle
 135 on the top right of the document window, and selecting ``save
 136 options''. The default is to save the file with the \program{Python
 137 IDE} as the creator, this means that you can open the file for editing
 138 by simply double-clicking on its icon. You might want to change this
 139 behaviour so that it will be opened by the
 140 \program{PythonLauncher}, and run. To do this simply choose
 141 ``PythonLauncher'' from the ``save options''. Note that these
 142 options are associated with the \emph{file} not the application.
 143
 144
 145 \subsection{Executing a script from within the IDE
 146             \label{IDEexecution}}
 147
 148 You can run the script in the frontmost window of the \program{Python
 149 IDE} by hitting the run all button.  You should be aware, however that
 150 if you use the Python convention \samp{if __name__ == "__main__":} the
 151 script will \emph{not} be ``__main__'' by default. To get that
 152 behaviour you must select the ``Run as __main__'' option from the
 153 small black triangle on the top right of the document window.  Note
 154 that this option is associated with the \emph{file} not the
 155 application. It \emph{will} stay active after a save, however; to shut
 156 this feature off simply select it again.
 157
 158
 159 \subsection{``Save as'' versus ``Save as Applet''
 160             \label{IDEapplet}}
 161
 162 When you are done writing your Python script you have the option of
 163 saving it as an ``applet'' (by selecting ``Save as applet'' from the
 164 ``File'' menu). This has a significant advantage in that you can drop
 165 files or folders onto it, to pass them to the applet the way
 166 command-line users would type them onto the command-line to pass them
 167 as arguments to the script. However, you should make sure to save the
 168 applet as a separate file, do not overwrite the script you are
 169 writing, because you will not be able to edit it again.
 170
 171 Accessing the items passed to the applet via ``drag-and-drop'' is done
 172 using the standard \member{sys.argv} mechanism. See the general
 173 documentation for more
 174 % need to link to the appropriate place in non-Mac docs
 175
 176 Note that saving a script as an applet will not make it runnable on a
 177 system without a Python installation.
 178
 179 %\subsection{Debugger}
 180 % **NEED INFO HERE**
 181
 182 %\subsection{Module Browser}
 183 % **NEED INFO HERE**
 184
 185 %\subsection{Profiler}
 186 % **NEED INFO HERE**
 187 % end IDE
 188
 189 %\subsection{The ``Scripts'' menu}
 190 % **NEED INFO HERE**
 191
 192 \section{The Package Manager}
 193
 194 Historically MacPython came with a number of useful extension packages
 195 included, because most Macintosh users do not have access to a development
 196 environment and C compiler. For Mac OS X that bundling is no longer done,
 197 but a new mechanism has been made available to allow easy access to
 198 extension packages.
 199
 200 The Python Package Manager helps you installing additional packages
 201 that enhance Python. It determines the exact MacOS version  and Python
 202 version you have and uses that information to download  a database that
 203 has packages that are tested and tried on that combination. In other
 204 words: if something is in your Package Manager  window but does not work
 205 you are free to blame the database maintainer.
 206
 207 PackageManager then checks which of the packages you have installed  and
 208 which ones are not. This should also work when you have installed packages
 209 outside of PackageManager.  You can select packages and install them,
 210 and PackageManager will work out the requirements and install these too.
 211
 212 Often PackageManager will list a package in two flavors: binary  and
 213 source. Binary should always work, source will only work if  you have
 214 installed the Apple Developer Tools. PackageManager will warn  you about
 215 this, and also about other external dependencies.
 216
 217 PackageManager is available as a separate application and also  as a
 218 function of the IDE, through the File->Package Manager menu  entry.