mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-04 00:48:58 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

Clarified working directory stuff, added some paragraphs on using

Browse source 
import and reload() to run scripts.
This commit is contained in:
Jack Jansen 1996-04-15 12:25:44 +00:00
parent d544d0126d
commit bd9565a3e5
1 changed files with 257 additions and 175 deletions
Download patch file Download diff file Expand all files Collapse all files

432
Mac/Demo/using.html
View file

@ -7,104 +7,154 @@
<EM>(preliminary)</EM>
<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>
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 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. <p>
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. <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) or
<CODE>Python68K</CODE> (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. <p>
The name of the interpreter may differ on different installations: it
may be called <CODE>Python</CODE>, <CODE>PythonPPC</CODE> (for powerpc
macs) or <CODE>Python68K</CODE> (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. <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:
This should give you a text window with an informative version string
and a prompt, something like the following:
<PRE>
Python 1.3.3 (Apr 7 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>
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.
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>
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>
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>
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>
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>
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>
<CITE>
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. </CITE>
<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>
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>
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>
<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.
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>
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>
@ -114,166 +164,198 @@ The options modify the interpreters behaviour in the following way:
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 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>
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>
The default options are also settable on a system-wide basis, see the section on
<A HREF="#preferences">editing preferences</A>. <p>
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>
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. The "standard file" folder does <EM>not</EM> 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 <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>
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>
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>
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>
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.
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 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>
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>
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>
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.
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 only
supported on PowerPC macintoshes, and are created using the <CODE>mkapplet</CODE>
program. You create an applet by dropping the python source script onto mkapplet.
The <CODE>Demo</CODE> folder contains an example of a more involved applet with its
own resource file, etc. <p>
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 <CODE>mkapplet</CODE> program. You create an
applet by dropping the python source script onto mkapplet. The
<CODE>Demo</CODE> folder contains an example of 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. <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. <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>
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.
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.
<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>
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>
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> 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. <p>
Finally, the <CODE>Demo</CODE> 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. <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>
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>
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>
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, 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. <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, 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. <p>
<HR>
<A HREF="http://www.cwi.nl/~jack">Jack Jansen</A>,
<A HREF="mailto:jack@cwi.nl">jack@cwi.nl</A>, 7-Apr-1996.
<A HREF="mailto:jack@cwi.nl">jack@cwi.nl</A>, 15-Apr-1996.
</BODY>
</HTML>