+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 Python Tutorial by +Guido van Rossum. This guide more-or-less replaces chapter two of the +tutorial, and provides some additional material.
-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.
+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.
Python, PythonPPC (for powerpc macs) or
-Python68K (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.
+The name of the interpreter may differ on different installations: it
+may be called Python, PythonPPC (for powerpc
+macs) or Python68K (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.
-This should give you a text window with an informative version string and a prompt, -something like the following: +This should give you a text window with an informative version string +and a prompt, something like the following:
Python 1.3.3 (Apr 7 1996) [CW PPC w/GUSI] Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam >>>-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.
+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.
-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 [return] or [enter] 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. +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 [return] +or [enter] 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.
SimpleText.
+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 SimpleText.
-For more serious scripts, though, it is advisable to use a programmers editor,
-such as BBEdit or Alpha. BBEdit is my favorite: it comes in a
-commercial version but also in a fully-functional free version
-BBEdit Lite. You can download it from the
-BareBones 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.
+For more serious scripts, though, it is advisable to use a programmers
+editor, such as BBEdit or Alpha. BBEdit is
+my favorite: it comes in a commercial version but also in a
+fully-functional free version BBEdit Lite. You can
+download it from the BareBones
+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.
-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 -startup options -for a way to change this.
+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 startup +options for a way to change this.
-It is a good idea to have the names of all your scripts end in .py. 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.
+It is a good idea to have the names of all your scripts end in
+.py. 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.
+
+If you do not like to start the Python interpreter afresh for each
+edit-run cycle you can use the import statement and
+reload() function to speed things up in some cases. Here
+is Guido's original comment for how to do this, from the 1.1 release
+notes:
+
+
+
+Make sure the program is a module file (filename must be a Python
+identifier followed by '
+
+Recovery from a syntax error is easy: edit the file and import it
+again.
+
+Recovery from wrong output is almost as easy: edit the file and,
+instead of importing it, call the function
+
+Recovery from an exception is trickier. Once the syntax is correct, a
+'module' entry is placed in an internal table, and following import
+statements will not re-read the file, even if the module's
+initialization terminated with an error (one reason why this is done
+is so that mutually recursive modules are initialized only once). You
+must therefore force re-reading the module with .py'). You can then import it
+when you test it for the first time. There are now three
+possibilities: it contains a syntax error; it gets a runtime error
+(unhandled exception); or it runs OK but gives wrong results. (If it
+gives correct results, you are done testing and don't need to read the
+rest of this paragraph. :-) Note that the following is not
+Mac-specific -- it's just that on UNIX it's easier to restart the
+entire script so it's rarely useful. reload() with
+the module name as argument (e.g., if your module is called
+foo, type reload(foo)). reload(),
+however, if this happens the first time you try to import the module,
+the import statement itself has not completed, and your workspace does
+not know the module name (even though the internal table of moduesl
+does!). The trick is to first import the module again, then reload
+it. For instance, import foo; reload(foo). Because the
+module object already exists internally, the import statement does not
+attempt to execute the module again -- it just places it in your
+workspace.
'Pyth'
-and type 'TEXT', 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.
+If you create your script with the correct creator and type, creator
+'Pyth' and type 'TEXT', 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.
-The Scripts folder contains a script fixfiletypes that will
-recursively traverse a folder and set the correct creator and type for all files
-ending in .py.
+The Scripts folder contains a script
+fixfiletypes that will recursively traverse a folder and
+set the correct creator and type for all files ending in
+.py.
KeyboardInterrupt
-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.
+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 KeyboardInterrupt 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.
+If the option 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.
@@ -114,166 +164,198 @@
sys.argv. Sys.argv[0] is always the name of the script being executed,
-additional values can be passed here. Quoting works as expected.
+In addition, you can enter a unix-style command line which is passed
+to the script in sys.argv. Sys.argv[0] is always the name
+of the script being executed, additional values can be passed
+here. Quoting works as expected.
-The default options are also settable on a system-wide basis, see the section on -editing preferences.
+The default options are also settable on a system-wide basis, see the +section on editing preferences.
sys.path, 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 Lib folder and some of its subfolders and possibly some more.
+The module search path, sys.path, 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
+Lib folder and some of its subfolders and possibly some
+more.
+ +By the way: the "standard file" folder, the folder that is presented +to the user initially for an open or save dialog, does +not follow the Python working directory. Which folder is +initially shown to the user is usually one of (a) the application +folder, (b) the "Documents" folder or (c) the folder most recently +used for such a dialog (in any Python program). This is standard MacOS +behaviour, so don't blame Python for it. The exact behaviour is +settable through a control panel since System 7.5.
PythonStartup
-this file is executed when you start an interactive interpreter. In this file you
-could import modules you often use and other such things.
+If the folder containing the interpreter contains a file named
+PythonStartup this file is executed when you start an
+interactive interpreter. In this file you could import modules you
+often use and other such things.
'Pyth' and type 'PYC ' load faster
-when imported (because they do not have to be parsed). The Lib folder
-contains a script compileall.py, 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.
+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
+'Pyth' and type 'PYC ' load faster when
+imported (because they do not have to be parsed). The Lib
+folder contains a script compileall.py, 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.
+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).
-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 'PYC ' and a name matching the module being imported.
+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 'PYC ' and a name
+matching the module being imported.
-The scripts folder contains a script PackLibDir which will convert
-a number of modules (or possibly a complete subtree full of modules) into such a
-resource file.
+The scripts folder contains a script
+PackLibDir which will convert a number of modules (or
+possibly a complete subtree full of modules) into such a resource
+file.
EditPythonPrefs. For PPC python this is a standalone program living
-in the main Python folder, for 68K python it is a script in the Scripts
-folder.
+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
+EditPythonPrefs. For PPC python this is a standalone
+program living in the main Python folder, for 68K python it is a
+script in the Scripts folder.
-The interface to edit the preferences is rather clunky for the current release.
+The interface to edit the preferences is rather clunky for the current +release.
-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 $(PYTHON) will expand to the Python home folder
-and a value of $(APPLICATION) 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.
+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 $(PYTHON)
+will expand to the Python home folder and a value of
+$(APPLICATION) 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.
-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.
+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.
-Finally, you can set the default startup options here, through a sub-dialog. +Finally, you can set the default startup options here, through a +sub-dialog.
mkapplet
-program. You create an applet by dropping the python source script onto mkapplet.
-The Demo folder contains an example of a more involved applet with its
-own resource file, etc.
+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 mkapplet program. You create an
+applet by dropping the python source script onto mkapplet. The
+Demo folder contains an example of a more involved applet
+with its own resource file, etc.
-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
-PythonCore, and probably various modules from the Lib and PlugIns folders.
+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 PythonCore, and probably various modules
+from the Lib and PlugIns folders.
EditPythonPrefs
-application allows you to set
-these, in the same way as double-clicking EditPythonPrefs allows you to set
-the system-wide defaults.
+Applets can have their own settings for the startup options and module
+search path. Dropping an applet on the EditPythonPrefs
+application allows you to set these, in the same way as
+double-clicking EditPythonPrefs allows you to set the system-wide
+defaults.
-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. +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.
+The previously mentioned Python Tutorial 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 Python +Documentation page.
-There are some annotated sample programs available -that show some mac-specific issues, like use of various toolboxes and creation -of Python applets.
+There are some annotated sample programs +available that show some mac-specific issues, like use of various +toolboxes and creation of Python applets.
-Finally, the Demo 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.
+Finally, the Demo 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.
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 pythonmac-sig-request@python.org -or view the Pythonmac SIG page on the -www.python.org WWW server.
+the MacPython Special Interest Group mailing list. Send a message with +"info" in the body to pythonmac-sig-request@python.org +or view the Pythonmac SIG +page on the www.python.org WWW +server.
+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.
-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.
+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.