From 5f962c2a75a09bd9e35f32c0250abcfd8c738154 Mon Sep 17 00:00:00 2001 From: Jack Jansen Date: Wed, 10 Apr 1996 14:52:59 +0000 Subject: Added a tutorial --- Mac/Demo/index.html | 6 +- Mac/Demo/using.html | 279 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 284 insertions(+), 1 deletion(-) create mode 100644 Mac/Demo/using.html diff --git a/Mac/Demo/index.html b/Mac/Demo/index.html index 9ef4ebd..fda20b7 100644 --- a/Mac/Demo/index.html +++ b/Mac/Demo/index.html @@ -9,6 +9,10 @@ already familiar with Python and, to some extent, with MacOS Toolbox programming. Other readers may find something interesting here too, your mileage may vary.

+There is a companion document Using Python on the Mac +which you should read before starting here: it explains the basics of using +python on the Macintosh.

+ Another set of Macintosh-savvy examples, more aimed at beginners, is maintained by Joseph Strout, at @@ -91,4 +95,4 @@ documentation.

Jack Jansen, -jack@cwi.nl, 6-Mar-1996. +jack@cwi.nl, 7-Apr-1996. diff --git a/Mac/Demo/using.html b/Mac/Demo/using.html new file mode 100644 index 0000000..872bb9e --- /dev/null +++ b/Mac/Demo/using.html @@ -0,0 +1,279 @@ + + +Using Python on the Macintosh + + +

Using Python on the Macintosh

+(preliminary) +

+ +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.

+ +

Invoking the interpreter

+ +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: +

+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.

+ +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. + +

Creating Python scripts

+ +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.

+ +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.

+ +

Clickable python scripts

+ +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.

+ +

Interaction with the user

+ +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. + +

startup options

+ +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.

+ +

+ +The options modify the interpreters behaviour in the following way: +

the interpreter goes to interactive mode (in stead of +exiting) after a script has terminated normally, +
for every module imported a line is printed telling you where the +module was loaded from, +
do not print the values of expressions executed as statements in an +interactive python, +
do not buffer stdout and stderr, +
print some debugging output during the parsing phase, +
keep the output window open when a script terminates. +

+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.

+ +

Module search path

+ +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.

+ +

Working folder

+ +The unix concept of a working directory 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 not follow +the working directory, it follows the standard MacOS rules (which are settable +through a control panel since MacOS 7.5). + +

Interactive startup file

+ +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.

+ + +

Compiled python scripts

+ +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.

+ +

Python resources

+ +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.

+ +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. + +

Setting interpreter preferences

+ +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.

+ +

+ +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.

+ +Finally, you can set the default startup options here, through a sub-dialog. + +

Applets

+ +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.

+ +

Customizing applets

+ +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. + +

Where to go from here

+ +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.

+ +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.

+ +

Troubleshooting

+ +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.

+ +

+Jack Jansen, +jack@cwi.nl, 7-Apr-1996. + + + -- cgit v0.12