From bd9565a3e58f9837bae937a7dbf6246e93efc320 Mon Sep 17 00:00:00 2001 From: Jack Jansen Date: Mon, 15 Apr 1996 12:25:44 +0000 Subject: [PATCH] Clarified working directory stuff, added some paragraphs on using import and reload() to run scripts. --- Mac/Demo/using.html | 442 ++++++++++++++++++++++++++------------------ 1 file changed, 262 insertions(+), 180 deletions(-) diff --git a/Mac/Demo/using.html b/Mac/Demo/using.html index 872bb9e99f..5f2009732b 100644 --- a/Mac/Demo/using.html +++ b/Mac/Demo/using.html @@ -7,104 +7,154 @@ (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.

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

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.

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

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

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

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

+ +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 reload() with +the module name as argument (e.g., if your module is called +foo, type reload(foo)).

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

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.

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

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

+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 @@ The options modify the interpreters behaviour in the following way: 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 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.

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

    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.

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

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

    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.

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

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

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

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

    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.

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

    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.

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

    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.

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

    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.

    +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. +jack@cwi.nl, 15-Apr-1996. -- 2.50.1