Fred Drake | 45aa573 | 2000-10-14 05:09:42 +0000 | [diff] [blame] | 1 | \chapter{Using Python on the Macintosh \label{using}} |
| 2 | \sectionauthor{Bob Savage}{bobsavage@mac.com} |
| 3 | |
| 4 | Using Python on the Macintosh can seem like something completely |
| 5 | different than using it on a \UNIX-like or Windows system. Most of the |
| 6 | Python documentation, both the ``official'' documentation and |
| 7 | published books, describe only how Python is used on these systems, |
| 8 | causing confusion for the new user of MacPython. This chapter gives a |
| 9 | brief introduction to the specifics of using Python on a Macintosh. |
| 10 | |
| 11 | |
| 12 | \section{Getting and Installing MacPython \label{getting}} |
| 13 | |
| 14 | The most recent release version as well as possible newer experimental |
| 15 | versions are best found at the MacPython page maintained by Jack |
| 16 | Jansen: \url{http://www.cwi.nl/~jack/macpython.html}. |
| 17 | |
| 18 | |
| 19 | Please refer to the \file{README} included with your distribution for |
| 20 | the most up-to-date instructions. |
| 21 | |
| 22 | |
| 23 | \section{Entering the interactive Interpreter |
| 24 | \label{interpreter}} |
| 25 | |
| 26 | The interactive interpreter that you will see used in Python |
| 27 | documentation is started by double-clicking the |
| 28 | \program{PythonInterpreter} icon, which looks like a 16-ton weight |
| 29 | falling. You should see the version information and the |
Fred Drake | 2441366 | 2001-04-13 17:32:49 +0000 | [diff] [blame] | 30 | \samp{>\code{>}>~} prompt. Use it exactly as described in the |
| 31 | standard documentation. |
Fred Drake | 45aa573 | 2000-10-14 05:09:42 +0000 | [diff] [blame] | 32 | |
| 33 | |
| 34 | \section{How to run a Python script} |
| 35 | |
| 36 | There are several ways to run an existing Python script; two common |
| 37 | ways to run a Python script are ``drag and drop'' and ``double |
| 38 | clicking''. Other ways include running it from within the IDE (see |
| 39 | Section \ref{IDE}), or launching via AppleScript. |
| 40 | |
| 41 | |
| 42 | \subsection{Drag and drop} |
| 43 | |
| 44 | One of the easiest ways to launch a Python script is via ``Drag and |
| 45 | Drop''. This is just like launching a text file in the Finder by |
| 46 | ``dragging'' it over your word processor's icon and ``dropping'' it |
| 47 | there. Make sure that you use an icon referring to the |
| 48 | \program{PythonInterpreter}, not the \program{IDE} or \program{Idle} |
| 49 | icons which have different behaviour which is described below. |
| 50 | |
| 51 | Some things that might have gone wrong: |
| 52 | |
| 53 | \begin{itemize} |
| 54 | \item |
| 55 | A window flashes after dropping the script onto the |
| 56 | \program{PythonInterpreter}, but then disappears. Most likely this is a |
| 57 | configuration issue; your \program{PythonInterpreter} is setup to exit |
| 58 | immediately upon completion, but your script assumes that if it prints |
| 59 | something that text will stick around for a while. To fix this, see |
Fred Drake | 8e850ee | 2000-10-14 05:24:20 +0000 | [diff] [blame] | 60 | section \ref{defaults}. |
Fred Drake | 45aa573 | 2000-10-14 05:09:42 +0000 | [diff] [blame] | 61 | |
| 62 | \item |
| 63 | After dropping the script onto the \program{PythonInterpreter}, a |
| 64 | window appeared which said: ``File contains \code{\e r} characters |
| 65 | (incorrect line endings?)''. That script probably originated on a |
| 66 | \UNIX{} or Windows machine. You will need to change the line endings |
| 67 | to the standard Mac usage. One way to do this is to open the file in |
| 68 | \program{BBedit} |
| 69 | (\url{http://www.barebones.com/products/bbedit_lite.html}) which can |
| 70 | easily change the line endings between Mac, DOS, and \UNIX\ styles. |
| 71 | |
| 72 | \item |
| 73 | When you waved the script icon over the \program{PythonInterpreter}, |
| 74 | the \program{PythonInterpreter} icon did not hilight. Most likely the |
| 75 | Creator code and document type is unset (or set incorrectly) -- this |
| 76 | often happens when a file originates on a non-Mac computer. See |
Fred Drake | 8e850ee | 2000-10-14 05:24:20 +0000 | [diff] [blame] | 77 | section \ref{creator-code} for more details. |
Fred Drake | 45aa573 | 2000-10-14 05:09:42 +0000 | [diff] [blame] | 78 | \end{itemize} |
| 79 | |
| 80 | |
| 81 | \subsection{Set Creator and Double Click \label{creator-code}} |
| 82 | |
| 83 | If the script that you want to launch has the appropriate Creator Code |
| 84 | and File Type you can simply double-click on the script to launch it. |
| 85 | To be ``double-clickable'' a file needs to be of type \samp{TEXT}, |
| 86 | with a creator code of \samp{Pyth}. |
| 87 | |
| 88 | Setting the creator code and filetype can be done with the IDE (see |
| 89 | sections \ref{IDEwrite} and \ref{IDEapplet}), with an editor with a |
| 90 | Python mode (\program{BBEdit}) -- see section |
| 91 | \ref{scripting-with-BBedit}, or with assorted other Mac utilities, but |
| 92 | a script (\file{fixfiletypes.py}) has been included in the MacPython |
| 93 | distribution, making it possible to set the proper Type and Creator |
| 94 | Codes with Python. |
| 95 | |
| 96 | The \file{fixfiletypes.py} script will change the file type and |
| 97 | creator codes for the indicated directory. To use |
| 98 | \file{fixfiletypes.py}: |
| 99 | |
| 100 | \begin{enumerate} |
| 101 | \item |
| 102 | Locate it in the \file{scripts} folder of the \file{Mac} folder of the |
| 103 | MacPython distribution. |
| 104 | |
| 105 | \item |
| 106 | Put all of the scripts that you want to fix in a folder with nothing |
| 107 | else in it. |
| 108 | |
| 109 | \item |
| 110 | Double-click on the \file{fixfiletypes.py} icon. |
| 111 | |
| 112 | \item |
| 113 | Navigate into the folder of files you want to fix, and press the |
| 114 | ``Select current folder'' button. |
| 115 | \end{enumerate} |
| 116 | |
| 117 | |
| 118 | \section{Simulating command line arguments |
| 119 | \label{argv}} |
| 120 | |
| 121 | There are two ways to simulate command-line arguments with MacPython. |
| 122 | |
| 123 | \begin{enumerate} |
| 124 | \item via Interpreter options |
| 125 | \begin{itemize} % nestable? I hope so! |
| 126 | \item Hold the option-key down when launching your script. This will |
| 127 | bring up a dialog box of Python Interpreter options. |
| 128 | \item Click ``Set \UNIX-style command line..'' button. |
| 129 | \item Type the arguments into the ``Argument'' field. |
| 130 | \item Click ``OK'' |
| 131 | \item Click ``Run''. |
| 132 | \end{itemize} % end |
| 133 | |
| 134 | \item via drag and drop |
| 135 | If you save the script as an applet (see Section \ref{IDEapplet}), you |
| 136 | can also simulate some command-line arguments via |
| 137 | ``Drag-and-Drop''. In this case, the names of the files that were |
| 138 | dropped onto the applet will be appended to \code{sys.argv}, so that |
| 139 | it will appear to the script as though they had been typed on a |
| 140 | command line. As on \UNIX\ systems, the first item in \code{sys.srgv} is |
| 141 | the path to the applet, and the rest are the files dropped on the |
| 142 | applet. |
| 143 | \end{enumerate} |
| 144 | |
| 145 | |
| 146 | \section{Creating a Python script} |
| 147 | |
| 148 | Since Python scripts are simply text files, they can be created in any |
| 149 | way that text files can be created, but some special tools also exist |
| 150 | with extra features. |
| 151 | |
| 152 | |
| 153 | \subsection{In an editor} |
| 154 | |
| 155 | You can create a text file with any word processing program such as |
| 156 | \program{MSWord} or \program{AppleWorks} but you need to make sure |
| 157 | that the file is saved as ``\ASCII'' or ``plain text''. |
| 158 | |
| 159 | |
| 160 | \subsubsection{Editors with Python modes} |
| 161 | |
| 162 | Several text editors have additional features that add functionality |
| 163 | when you are creating a Python script. These can include coloring |
| 164 | Python keywords to make your code easier to read, module browsing, or |
| 165 | a built-in debugger. These include \program{Alpha}, \program{Pepper}, |
| 166 | and \program{BBedit}, and the MacPython IDE (Section \ref{IDE}). |
| 167 | |
| 168 | %\subsubsection{Alpha} |
| 169 | % **NEED INFO HERE** |
| 170 | |
| 171 | \subsubsection{BBedit \label{scripting-with-BBedit}} |
| 172 | |
| 173 | If you use \program{BBEdit} to create your scripts you will want to tell it about the Python creator code so that |
| 174 | you can simply double click on the saved file to launch it. |
| 175 | \begin{itemize} |
| 176 | \item Launch \program{BBEdit}. |
| 177 | \item Select ``Preferences'' from the ``Edit'' menu. |
| 178 | \item Select ``File Types'' from the scrolling list. |
| 179 | \item click on the ``Add...'' button and navigate to |
| 180 | \program{PythonInterpreter} in the main directory of the |
| 181 | MacPython distribution; click ``open''. |
| 182 | \item Click on the ``Save'' button in the Preferences panel. |
| 183 | \end{itemize} |
| 184 | % Are there additional BBedit Python-specific features? I'm not aware of any. |
| 185 | |
| 186 | %\subsubsection{IDE} |
| 187 | %You can use the \program{Python IDE} supplied in the MacPython Distribution to create longer Python scripts |
| 188 | %-- see Section \ref{IDEwrite} for details. |
| 189 | |
| 190 | %\subsubsection{IDLE} |
| 191 | %Idle is an IDE for Python that was written in Python, using TKInter. You should be able to use it on a Mac by following |
| 192 | %the standard documentation, but see Section \ref{TKInter} for guidance on using TKInter with MacPython. |
| 193 | |
| 194 | %\subsubsection{Pepper} |
| 195 | % **NEED INFO HERE** |
| 196 | |
| 197 | |
| 198 | \section{The IDE\label{IDE}} |
| 199 | |
| 200 | The \program{Python IDE} (Integrated Development Environment) is a |
| 201 | separate application that acts as a text editor for your Python code, |
| 202 | a class browser, a graphical debugger, and more. |
| 203 | |
| 204 | |
| 205 | \subsection{Using the ``Python Interactive'' window} |
| 206 | |
| 207 | Use this window like you would the \program{PythonInterpreter}, except |
| 208 | that you cannot use the ``Drag and drop'' method above. Instead, |
| 209 | dropping a script onto the \program{Python IDE} icon will open the |
Fred Drake | 3808045 | 2001-11-01 19:48:01 +0000 | [diff] [blame^] | 210 | file in a separate script window (which you can then execute manually |
Fred Drake | 45aa573 | 2000-10-14 05:09:42 +0000 | [diff] [blame] | 211 | -- see section \ref{IDEexecution}). |
| 212 | |
| 213 | |
| 214 | \subsection{Writing a Python Script \label{IDEwrite}} |
| 215 | |
| 216 | In addition to using the \program{Python IDE} interactively, you can |
| 217 | also type out a complete Python program, saving it incrementally, and |
| 218 | execute it or smaller selections of it. |
| 219 | |
| 220 | You can create a new script, open a previously saved script, and save |
| 221 | your currently open script by selecting the appropriate item in the |
| 222 | ``File'' menu. Dropping a Python script onto the |
| 223 | \program{Python IDE} will open it for editting. |
| 224 | |
| 225 | If you try to open a script with the \program{Python IDE} but either |
| 226 | can't locate it from the ``Open'' dialog box, or you get an error |
| 227 | message like ``Can't open file of type ...'' see section |
Fred Drake | 8e850ee | 2000-10-14 05:24:20 +0000 | [diff] [blame] | 228 | \ref{creator-code}. |
Fred Drake | 45aa573 | 2000-10-14 05:09:42 +0000 | [diff] [blame] | 229 | |
| 230 | When the \program{Python IDE} saves a script, it uses the creator code |
| 231 | settings which are available by clicking on the small black triangle |
| 232 | on the top right of the document window, and selecting ``save |
| 233 | options''. The default is to save the file with the \program{Python |
| 234 | IDE} as the creator, this means that you can open the file for editing |
| 235 | by simply double-clicking on its icon. You might want to change this |
| 236 | behaviour so that it will be opened by the |
| 237 | \program{PythonInterpreter}, and run. To do this simply choose |
| 238 | ``Python Interpreter'' from the ``save options''. Note that these |
| 239 | options are associated with the \emph{file} not the application. |
| 240 | |
| 241 | |
| 242 | \subsection{Executing a script from within the IDE |
| 243 | \label{IDEexecution}} |
| 244 | |
| 245 | You can run the script in the frontmost window of the \program{Python |
| 246 | IDE} by hitting the run all button. You should be aware, however that |
| 247 | if you use the Python convention \samp{if __name__ == "__main__":} the |
| 248 | script will \emph{not} be ``__main__'' by default. To get that |
| 249 | behaviour you must select the ``Run as __main__'' option from the |
| 250 | small black triangle on the top right of the document window. Note |
| 251 | that this option is associated with the \emph{file} not the |
| 252 | application. It \emph{will} stay active after a save, however; to shut |
| 253 | this feature off simply select it again. |
| 254 | |
| 255 | |
| 256 | \subsection{``Save as'' versus ``Save as Applet'' |
| 257 | \label{IDEapplet}} |
| 258 | |
| 259 | When you are done writing your Python script you have the option of |
| 260 | saving it as an ``applet'' (by selecting ``Save as applet'' from the |
| 261 | ``File'' menu). This has a significant advantage in that you can drop |
| 262 | files or folders onto it, to pass them to the applet the way |
| 263 | command-line users would type them onto the command-line to pass them |
| 264 | as arguments to the script. However, you should make sure to save the |
Fred Drake | 3808045 | 2001-11-01 19:48:01 +0000 | [diff] [blame^] | 265 | applet as a separate file, do not overwrite the script you are |
Fred Drake | 45aa573 | 2000-10-14 05:09:42 +0000 | [diff] [blame] | 266 | writing, because you will not be able to edit it again. |
| 267 | |
| 268 | Accessing the items passed to the applet via ``drag-and-drop'' is done |
| 269 | using the standard \member{sys.argv} mechanism. See the general |
| 270 | documentation for more |
| 271 | % need to link to the appropriate place in non-Mac docs |
| 272 | |
| 273 | Note that saving a script as an applet will not make it runnable on a |
| 274 | system without a Python installation. |
| 275 | |
| 276 | %\subsection{Debugger} |
| 277 | % **NEED INFO HERE** |
| 278 | |
| 279 | %\subsection{Module Browser} |
| 280 | % **NEED INFO HERE** |
| 281 | |
| 282 | %\subsection{Profiler} |
| 283 | % **NEED INFO HERE** |
| 284 | % end IDE |
| 285 | |
| 286 | %\subsection{The ``Scripts'' menu} |
| 287 | % **NEED INFO HERE** |
| 288 | |
| 289 | \section{Configuration \label{configuration}} |
| 290 | |
| 291 | The MacPython distribution comes with \program{EditPythonPrefs}, an |
| 292 | applet which will help you to customize the MacPython environment for |
| 293 | your working habits. |
| 294 | |
| 295 | \subsection{EditPythonPrefs\label{EditPythonPrefs}} |
| 296 | |
| 297 | \program{EditPythonPrefs} gives you the capability to configure Python |
| 298 | to behave the way you want it to. There are two ways to use |
| 299 | \program{EditPythonPrefs}, you can use it to set the preferences in |
| 300 | general, or you can drop a particular Python engine onto it to |
| 301 | customize only that version. The latter can be handy if, for example, |
| 302 | you want to have a second copy of the \program{PythonInterpreter} that |
| 303 | keeps the output window open on a normal exit even though you prefer |
| 304 | to normally not work that way. |
| 305 | |
| 306 | To change the default preferences, simply double-click on |
| 307 | \program{EditPythonPrefs}. To change the preferences only for one copy |
| 308 | of the Interpreter, drop the icon for that copy onto |
| 309 | \program{EditPythonPrefs}. You can also use \program{EditPythonPrefs} |
| 310 | in this fashion to set the preferences of the \program{Python IDE} and |
Fred Drake | 8e850ee | 2000-10-14 05:24:20 +0000 | [diff] [blame] | 311 | any applets you create -- see section %s \ref{BuildApplet} and |
Fred Drake | 45aa573 | 2000-10-14 05:09:42 +0000 | [diff] [blame] | 312 | \ref{IDEapplet}. |
| 313 | |
| 314 | \subsection{Adding modules to the Module Search Path |
| 315 | \label{search-path}} |
| 316 | |
| 317 | When executing an \keyword{import} statement, Python looks for modules |
| 318 | in places defined by the \member{sys.path} To edit the |
| 319 | \member{sys.path} on a Mac, launch \program{EditPythonPrefs}, and |
| 320 | enter them into the largish field at the top (one per line). |
| 321 | |
| 322 | Since MacPython defines a main Python directory, the easiest thing is |
| 323 | to add folders to search within the main Python directory. To add a |
| 324 | folder of scripts that you created called ``My Folder'' located in the |
| 325 | main Python Folder, enter \samp{\$(PYTHON):My Folder} onto a new line. |
| 326 | |
| 327 | To add the Desktop under OS 9 or below, add |
| 328 | \samp{StartupDriveName:Desktop Folder} on a new line. |
| 329 | |
| 330 | \subsection{Default startup options \label{defaults}} |
| 331 | |
| 332 | % I'm assuming that there exists some other documentation on the |
| 333 | % rest of the options so I only go over a couple here. |
| 334 | |
| 335 | The ``Default startup options...'' button in the |
| 336 | \program{EditPythonPrefs} dialog box gives you many options including |
| 337 | the ability to keep the ``Output'' window open after the script |
| 338 | terminates, and the ability to enter interactive mode after the |
| 339 | termination of the run script. The latter can be very helpful if you |
| 340 | want to examine the objects that were created during your script. |
| 341 | |
| 342 | %\section{Nifty Tools} |
| 343 | %There are many other tools included with the MacPython |
| 344 | %distribution. In addition to those discussed here, make |
| 345 | %sure to check the \file{Mac} directory. |
| 346 | |
| 347 | %\subsection{BuildApplet \label{BuildApplet}} |
| 348 | % **NEED INFO HERE** |
| 349 | |
| 350 | %\subsection{BuildApplication} |
| 351 | % **NEED INFO HERE** |
| 352 | |
| 353 | %\section{TKInter on the Mac \label{TKInter}} |
| 354 | |
| 355 | %TKinter is installed by default with the MacPython distribution, but |
| 356 | %you may need to add the \file{lib-tk} folder to the Python Path (see |
| 357 | %section \ref{search-path}). Also, it is important that you do not |
| 358 | %try to launch Tk from within the \program{Python IDE} because the two |
| 359 | %event loops will collide -- always run a script which uses Tkinter |
| 360 | %with the \program{PythonInterpreter} instead -- see section |
| 361 | %\ref{interpreter}. |
| 362 | |
| 363 | %\section{CGI on the Mac with Python \label{CGI}} |
| 364 | %**NEED INFO HERE** |
| 365 | |
| 366 | \section{Mac OS X} |
| 367 | |
| 368 | At the time of this writing Mac OS X had just been released as a |
| 369 | Public Beta. Efforts are under way to bring MacPython to Mac OS X. The |
| 370 | MacPython release \version{1.5.2c1} runs quite well within the |
| 371 | ``Classic'' environment. A ``Carbon'' port of the MacPython code is |
| 372 | being prepared for release, and several people have made a command |
| 373 | line version available to the ``Darwin'' layer (which is accessible |
| 374 | via Terminal.app). |