Mac/Demo/using.html - platform/external/python/cpython2 - Gitiles

 <HTML>
 <HEAD>
 <TITLE>Using Python 1.4 on the Macintosh</TITLE>
 </HEAD>
 <BODY>
 <H1>Using Python 1.4 on the Macintosh</H1>
 <HR>

 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 <A
 HREF="http://www.python.org/doc/tut/tut.html">Python Tutorial</A> by
 Guido van Rossum. This guide more-or-less replaces chapter two of the
 tutorial, and provides some additional material. <p>

 The tutorial, along with other indispensible documentation like the
 library reference and such, is also available in a number of different
 formats at <a href="ftp://ftp.python.org/pub/python/doc">
 ftp://ftp.python.org/pub/python/doc</a>. The Adobe Acrobat <code>.pdf</code>
 files are probably a good choice for reading or printing the documents
 from your mac. <p>

 There is currently no good tutorial for the mac-specific features of
 Python, but to whet your appetite: it has interfaces to many MacOS
 toolboxes (quickdraw, sound, quicktime, open scripting, etc) and
 various portable toolboxes are available too (Tk, stdwin, complex
 numbers, image manipulation, etc). Some <A HREF="index.html">
 annotated sample programs</A> are available to give you an idea of
 Python's power. <P>

 <h2>Invoking the interpreter</h2>

 The name of the interpreter may differ on different installations: it
 may be called <CODE>Python</CODE>, <CODE>PythonPPC</CODE> (for powerpc
 macs), <CODE>PythonCFM68K</CODE> or<CODE>Python68K</CODE> (both for 68K macs).
 It will always
 be recognizable by the "16 ton" icon, though. You start the
 interpreter in interactive mode by double-clicking its icon: <p>

 <img src="html.icons/python.gif"><p>

 This should give you a text window with an informative version string
 and a prompt, something like the following:
 <PRE>
 Python 1.4 (Oct  27 1996)  [CW PPC w/GUSI]
 Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
 &gt;&gt;&gt;
 </PRE>
 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. <p>

 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 <EM>[return]</EM>
 or <EM>[enter]</EM> 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.

 <h2>Creating Python scripts</h2>

 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 <CODE>SimpleText</CODE>. <p>

 For more serious scripts, though, it is advisable to use a programmers
 editor, such as <CODE>BBEdit</CODE> or <CODE>Alpha</CODE>. BBEdit is
 my favorite: it comes in a commercial version but also in a
 fully-functional free version <CODE>BBEdit Lite</CODE>. You can
 download it from the <A HREF="http://www.barebones.com/">BareBones</A>
 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. <p>

 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 <A HREF="#startup">startup
 options</A> for a way to change this. <p>

 <blockquote>
 There is a BBEdit extension available that allows you to run Python
 scripts more-or-less straight from your bbedit source window. Check
 out the <code>Mac:Tools:BBPy</code> folder.
 </blockquote>

 It is a good idea to have the names of all your scripts end in
 <CODE>.py</CODE>. 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. <p>

 If you do not like to start the Python interpreter afresh for each
 edit-run cycle you can use the <CODE>import</CODE> statement and
 <CODE>reload()</CODE> 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: <P>

 <BLOCKQUOTE>

 Make sure the program is a module file (filename must be a Python
 identifier followed by '<CODE>.py</CODE>').  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. <P>

 Recovery from a syntax error is easy: edit the file and import it
 again. <P>

 Recovery from wrong output is almost as easy: edit the file and,
 instead of importing it, call the function <CODE>reload()</CODE> with
 the module name as argument (e.g., if your module is called
 <CODE>foo</CODE>, type <CODE>reload(foo)</CODE>). <P>

 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 <CODE>reload()</CODE>,
 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, <CODE>import foo; reload(foo)</CODE>.  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.  </BLOCKQUOTE>

 <h2>Clickable python scripts</h2>

 If you create your script with the correct creator and type, creator
 <CODE>'Pyth'</CODE> and type <CODE>'TEXT'</CODE>, 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. <p>

 The <CODE>Scripts</CODE> folder contains a script
 <CODE>fixfiletypes</CODE> that will recursively traverse a folder and
 set the correct creator and type for all files ending in
 <CODE>.py</CODE>. <p>

 <BLOCKQUOTE>
 Older releases of Python used the creator code
 <CODE>'PYTH'</CODE> in stead of <CODE>'Pyth'</CODE>. If you still have
 older Python sources on your system and named them with
 <CODE>'.py'</CODE> extension the <CODE>fixfiletypes</CODE> script will
 correct them.
 </BLOCKQUOTE>

 <h2>Interaction with the user</h2>

 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 <CODE>KeyboardInterrupt</CODE> 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.

 <h2><A NAME="startup">startup options</A></h2>

 If the <EM>option</EM> 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. <p>

 <img src="html.icons/options.gif"><p>

 The options modify the interpreters behaviour in the following way:
 <ul>
 <li> the interpreter goes to interactive mode (in stead of
 exiting) after a script has terminated normally,
 <li> for every module imported a line is printed telling you where the
 module was loaded from,
 <li> do not print the values of expressions executed as statements in
 an interactive python,
 <li> do not buffer stdout and stderr,
 <li> print some debugging output during the parsing phase,
 <li> keep the output window open when a script terminates.
 </ul>
 In addition, you can enter a unix-style command line which is passed
 to the script in <CODE>sys.argv</CODE>. Sys.argv[0] is always the name
 of the script being executed, additional values can be passed
 here. Quoting works as expected. <p>

 <BLOCKQUOTE>
 <EM>Warning:</EM> redirecting standard input or standard output in the
 command-line dialog does not work. This is due to circumstances beyond my
 control, hence I cannot say when this will be fixed.
 </BLOCKQUOTE>

 The default options are also settable on a system-wide basis, see the
 section on <A HREF="#preferences">editing preferences</A>. <p>

 <h2>Module search path</h2>

 The module search path, <CODE>sys.path</CODE>, 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
 <CODE>Lib</CODE> folder and some of its subfolders and possibly some
 more. <p>

 <h2>Working folder</h2>

 The unix concept of a <I>working directory</I> 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.  <P>

 By the way: the "standard file" folder, the folder that is presented
 to the user initially for an <I>open</I> or <I>save</I> dialog, does
 <EM>not</EM> 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.

 <h2>Interactive startup file</h2>

 If the folder containing the interpreter contains a file named
 <CODE>PythonStartup</CODE> this file is executed when you start an
 interactive interpreter. In this file you could import modules you
 often use and other such things. <p>


 <h2>Compiled python scripts</h2>

 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
 <CODE>'Pyth'</CODE> and type <CODE>'PYC '</CODE> load faster when
 imported (because they do not have to be parsed). The <CODE>Lib</CODE>
 folder contains a script <CODE>compileall.py</CODE>, 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. <p>

 <h2>Python resources</h2>

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

 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 <CODE>'PYC '</CODE> and a name
 matching the module being imported. <p>

 The <CODE>scripts</CODE> folder contains a script
 <CODE>PackLibDir</CODE> which will convert a number of modules (or
 possibly a complete subtree full of modules) into such a resource
 file.

 <h2><A NAME="preferences">Setting interpreter preferences</A></h2>

 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
 <CODE>EditPythonPrefs</CODE>. For PPC python this is a standalone
 program living in the main Python folder, for 68K python it is a
 script in the <CODE>Scripts</CODE> folder. <p>

 The interface to edit the preferences is rather clunky for the current
 release. <p>

 <img src="html.icons/preferences.gif"><p>

 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 <CODE>$(PYTHON)</CODE>
 will expand to the Python home folder and a value of
 <CODE>$(APPLICATION)</CODE> 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.<p>

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

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

 <h2>Applets</h2>

 An applet is a fullblown application written in Python, similar to an
 AppleScript applet (and completely different from a Java
 applet). Applets are currently supported on PowerPC macintoshes and on
 68K macintoshes if you use the CFM68K version of the interpreter,
 and are created using the <CODE>mkapplet</CODE> program. You create an
 applet by dropping the python source script onto mkapplet.
 <a href="example2.html">Example 2</a> is a more involved applet
 with its own resource file, etc. <p>

 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 <CODE>PythonCore</CODE>, and probably various modules
 from the Lib and PlugIns folders. Distributing it to a machine that does
 have a Python system (of the same release and architecture) will work. <p>

 <h2>Customizing applets</h2>

 Applets can have their own settings for the startup options and module
 search path. Dropping an applet on the <CODE>EditPythonPrefs</CODE>
 application allows you to set these, in the same way as
 double-clicking EditPythonPrefs allows you to set the system-wide
 defaults. <p>

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

 <h2>Where to go from here</h2>

 The previously mentioned <A
 HREF="http://www.python.org/doc/tut/tut.html">Python Tutorial</A> 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 <A HREF="http://www.python.org/doc/">Python
 Documentation</A> page. <p>

 There are some <A HREF="index.html">annotated sample programs</A>
 available that show some mac-specific issues, like use of various
 toolboxes and creation of Python applets. <p>

 Finally, the <CODE>Demo</CODE> and <CODE>Mac:Demo</CODE>
 folders 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. <p>

 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 <A
 HREF="mailto:pythonmac-sig-request@python.org">pythonmac-sig-request@python.org</A>
 or view the <A
 HREF="http://www.python.org/sigs/pythonmac-sig/">Pythonmac SIG
 page</A> on the <A HREF="http://www.python.org">www.python.org</A> WWW
 server. <p>

 <h2>Troubleshooting</h2>

 A rather baffling error message can be "PythonCore not found" when you
 start the interpreter and you are sure that PythonCore is available. The
 message should actually say "Not enough memory in the system heap to
 load PythonCore".
 Blame Apple for the confusing message. <p>

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

 Probably the most common cause of problems with modules ported from
 other systems is the Mac end-of-line convention. Where unix uses
 linefeed, 0x0a, to separate lines the mac uses carriage return,
 0x0d. 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. <p>

 Python attempts to keep its preferences file up-to-date even when you
 move the Python folder around, etc. If this fails the effect will be
 that Python cannot start or, worse, that it does work but it cannot find
 any standard modules. In this case, start Python examine <code>sys.path</code>.
 If it is incorrect remove any Python preferences file from the system
 folder and start the interpreter <em>while the interpreter sits in the main
 Python folder</em>. This will regenerate the preferences file. <p>

 <h2>Where to go from here</h2>

 The next section to check out is the <a href="index.html">annotated sample programs</a>.<p>

 <HR>
 <A HREF="http://www.cwi.nl/~jack">Jack Jansen</A>,
 <A HREF="mailto:jack@cwi.nl">jack@cwi.nl</A>, 20-Nov-1996.

 </BODY>
 </HTML>
	<HTML>
	<HEAD>
	<TITLE>Using Python 1.4 on the Macintosh</TITLE>
	</HEAD>
	<BODY>
	<H1>Using Python 1.4 on the Macintosh</H1>
	<HR>

	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 <A
	HREF="http://www.python.org/doc/tut/tut.html">Python Tutorial</A> by
	Guido van Rossum. This guide more-or-less replaces chapter two of the
	tutorial, and provides some additional material. <p>

	The tutorial, along with other indispensible documentation like the
	library reference and such, is also available in a number of different
	formats at <a href="ftp://ftp.python.org/pub/python/doc">
	ftp://ftp.python.org/pub/python/doc</a>. The Adobe Acrobat <code>.pdf</code>
	files are probably a good choice for reading or printing the documents
	from your mac. <p>

	There is currently no good tutorial for the mac-specific features of
	Python, but to whet your appetite: it has interfaces to many MacOS
	toolboxes (quickdraw, sound, quicktime, open scripting, etc) and
	various portable toolboxes are available too (Tk, stdwin, complex
	numbers, image manipulation, etc). Some <A HREF="index.html">
	annotated sample programs</A> are available to give you an idea of
	Python's power. <P>

	<h2>Invoking the interpreter</h2>

	The name of the interpreter may differ on different installations: it
	may be called <CODE>Python</CODE>, <CODE>PythonPPC</CODE> (for powerpc
	macs), <CODE>PythonCFM68K</CODE> or<CODE>Python68K</CODE> (both for 68K macs).
	It will always
	be recognizable by the "16 ton" icon, though. You start the
	interpreter in interactive mode by double-clicking its icon: <p>

	<img src="html.icons/python.gif"><p>

	This should give you a text window with an informative version string
	and a prompt, something like the following:
	<PRE>
	Python 1.4 (Oct 27 1996) [CW PPC w/GUSI]
	Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
	>>>
	</PRE>
	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. <p>

	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 <EM>[return]</EM>
	or <EM>[enter]</EM> 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.

	<h2>Creating Python scripts</h2>

	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 <CODE>SimpleText</CODE>. <p>

	For more serious scripts, though, it is advisable to use a programmers
	editor, such as <CODE>BBEdit</CODE> or <CODE>Alpha</CODE>. BBEdit is
	my favorite: it comes in a commercial version but also in a
	fully-functional free version <CODE>BBEdit Lite</CODE>. You can
	download it from the <A HREF="http://www.barebones.com/">BareBones</A>
	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. <p>

	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 <A HREF="#startup">startup
	options</A> for a way to change this. <p>

	<blockquote>
	There is a BBEdit extension available that allows you to run Python
	scripts more-or-less straight from your bbedit source window. Check
	out the <code>Mac:Tools:BBPy</code> folder.
	</blockquote>

	It is a good idea to have the names of all your scripts end in
	<CODE>.py</CODE>. 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. <p>

	If you do not like to start the Python interpreter afresh for each
	edit-run cycle you can use the <CODE>import</CODE> statement and
	<CODE>reload()</CODE> 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: <P>

	<BLOCKQUOTE>

	Make sure the program is a module file (filename must be a Python
	identifier followed by '<CODE>.py</CODE>'). 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. <P>

	Recovery from a syntax error is easy: edit the file and import it
	again. <P>

	Recovery from wrong output is almost as easy: edit the file and,
	instead of importing it, call the function <CODE>reload()</CODE> with
	the module name as argument (e.g., if your module is called
	<CODE>foo</CODE>, type <CODE>reload(foo)</CODE>). <P>

	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 <CODE>reload()</CODE>,
	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, <CODE>import foo; reload(foo)</CODE>. 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. </BLOCKQUOTE>

	<h2>Clickable python scripts</h2>

	If you create your script with the correct creator and type, creator
	<CODE>'Pyth'</CODE> and type <CODE>'TEXT'</CODE>, 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. <p>

	The <CODE>Scripts</CODE> folder contains a script
	<CODE>fixfiletypes</CODE> that will recursively traverse a folder and
	set the correct creator and type for all files ending in
	<CODE>.py</CODE>. <p>

	<BLOCKQUOTE>
	Older releases of Python used the creator code
	<CODE>'PYTH'</CODE> in stead of <CODE>'Pyth'</CODE>. If you still have
	older Python sources on your system and named them with
	<CODE>'.py'</CODE> extension the <CODE>fixfiletypes</CODE> script will
	correct them.
	</BLOCKQUOTE>

	<h2>Interaction with the user</h2>

	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 <CODE>KeyboardInterrupt</CODE> 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.

	<h2><A NAME="startup">startup options</A></h2>

	If the <EM>option</EM> 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. <p>

	<img src="html.icons/options.gif"><p>

	The options modify the interpreters behaviour in the following way:
	<ul>
	<li> the interpreter goes to interactive mode (in stead of
	exiting) after a script has terminated normally,
	<li> for every module imported a line is printed telling you where the
	module was loaded from,
	<li> do not print the values of expressions executed as statements in
	an interactive python,
	<li> do not buffer stdout and stderr,
	<li> print some debugging output during the parsing phase,
	<li> keep the output window open when a script terminates.
	</ul>
	In addition, you can enter a unix-style command line which is passed
	to the script in <CODE>sys.argv</CODE>. Sys.argv[0] is always the name
	of the script being executed, additional values can be passed
	here. Quoting works as expected. <p>

	<BLOCKQUOTE>
	<EM>Warning:</EM> redirecting standard input or standard output in the
	command-line dialog does not work. This is due to circumstances beyond my
	control, hence I cannot say when this will be fixed.
	</BLOCKQUOTE>

	The default options are also settable on a system-wide basis, see the
	section on <A HREF="#preferences">editing preferences</A>. <p>

	<h2>Module search path</h2>

	The module search path, <CODE>sys.path</CODE>, 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
	<CODE>Lib</CODE> folder and some of its subfolders and possibly some
	more. <p>

	<h2>Working folder</h2>

	The unix concept of a <I>working directory</I> 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. <P>

	By the way: the "standard file" folder, the folder that is presented
	to the user initially for an <I>open</I> or <I>save</I> dialog, does
	<EM>not</EM> 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.

	<h2>Interactive startup file</h2>

	If the folder containing the interpreter contains a file named
	<CODE>PythonStartup</CODE> this file is executed when you start an
	interactive interpreter. In this file you could import modules you
	often use and other such things. <p>


	<h2>Compiled python scripts</h2>

	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
	<CODE>'Pyth'</CODE> and type <CODE>'PYC '</CODE> load faster when
	imported (because they do not have to be parsed). The <CODE>Lib</CODE>
	folder contains a script <CODE>compileall.py</CODE>, 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. <p>

	<h2>Python resources</h2>

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

	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 <CODE>'PYC '</CODE> and a name
	matching the module being imported. <p>

	The <CODE>scripts</CODE> folder contains a script
	<CODE>PackLibDir</CODE> which will convert a number of modules (or
	possibly a complete subtree full of modules) into such a resource
	file.

	<h2><A NAME="preferences">Setting interpreter preferences</A></h2>

	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
	<CODE>EditPythonPrefs</CODE>. For PPC python this is a standalone
	program living in the main Python folder, for 68K python it is a
	script in the <CODE>Scripts</CODE> folder. <p>

	The interface to edit the preferences is rather clunky for the current
	release. <p>

	<img src="html.icons/preferences.gif"><p>

	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 <CODE>$(PYTHON)</CODE>
	will expand to the Python home folder and a value of
	<CODE>$(APPLICATION)</CODE> 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.<p>

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

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

	<h2>Applets</h2>

	An applet is a fullblown application written in Python, similar to an
	AppleScript applet (and completely different from a Java
	applet). Applets are currently supported on PowerPC macintoshes and on
	68K macintoshes if you use the CFM68K version of the interpreter,
	and are created using the <CODE>mkapplet</CODE> program. You create an
	applet by dropping the python source script onto mkapplet.
	<a href="example2.html">Example 2</a> is a more involved applet
	with its own resource file, etc. <p>

	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 <CODE>PythonCore</CODE>, and probably various modules
	from the Lib and PlugIns folders. Distributing it to a machine that does
	have a Python system (of the same release and architecture) will work. <p>

	<h2>Customizing applets</h2>

	Applets can have their own settings for the startup options and module
	search path. Dropping an applet on the <CODE>EditPythonPrefs</CODE>
	application allows you to set these, in the same way as
	double-clicking EditPythonPrefs allows you to set the system-wide
	defaults. <p>

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

	<h2>Where to go from here</h2>

	The previously mentioned <A
	HREF="http://www.python.org/doc/tut/tut.html">Python Tutorial</A> 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 <A HREF="http://www.python.org/doc/">Python
	Documentation</A> page. <p>

	There are some <A HREF="index.html">annotated sample programs</A>
	available that show some mac-specific issues, like use of various
	toolboxes and creation of Python applets. <p>

	Finally, the <CODE>Demo</CODE> and <CODE>Mac:Demo</CODE>
	folders 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. <p>

	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 <A
	HREF="mailto:pythonmac-sig-request@python.org">pythonmac-sig-request@python.org</A>
	or view the <A
	HREF="http://www.python.org/sigs/pythonmac-sig/">Pythonmac SIG
	page</A> on the <A HREF="http://www.python.org">www.python.org</A> WWW
	server. <p>

	<h2>Troubleshooting</h2>

	A rather baffling error message can be "PythonCore not found" when you
	start the interpreter and you are sure that PythonCore is available. The
	message should actually say "Not enough memory in the system heap to
	load PythonCore".
	Blame Apple for the confusing message. <p>

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

	Probably the most common cause of problems with modules ported from
	other systems is the Mac end-of-line convention. Where unix uses
	linefeed, 0x0a, to separate lines the mac uses carriage return,
	0x0d. 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. <p>

	Python attempts to keep its preferences file up-to-date even when you
	move the Python folder around, etc. If this fails the effect will be
	that Python cannot start or, worse, that it does work but it cannot find
	any standard modules. In this case, start Python examine <code>sys.path</code>.
	If it is incorrect remove any Python preferences file from the system
	folder and start the interpreter <em>while the interpreter sits in the main
	Python folder</em>. This will regenerate the preferences file. <p>

	<h2>Where to go from here</h2>

	The next section to check out is the <a href="index.html">annotated sample programs</a>.<p>

	<HR>
	<A HREF="http://www.cwi.nl/~jack">Jack Jansen</A>,
	<A HREF="mailto:jack@cwi.nl">jack@cwi.nl</A>, 20-Nov-1996.

	</BODY>
	</HTML>