Blame - Mac/Demo/using.html - platform/external/python/cpython3

blob: 872bb9e99f8d69d91c0b0c775223e5714d3723c7 [file] [log] [blame]

Jack Jansen	5f962c2	1996-04-10 14:52:59 +0000	[diff] [blame]	1	<HTML>
				2	<HEAD>
				3	<TITLE>Using Python on the Macintosh</TITLE>
				4	</HEAD>
				5	<BODY>
				6	<H1>Using Python on the Macintosh</H1>
				7	<EM>(preliminary)</EM>
				8	<HR>
				9
				10	This document is an introduction to using Python on the Apple Macintosh.
				11	It does not introduce the language itself, for this you should refer
				12	to the <A HREF="http://www.python.org/doc/tut/tut.html">Python Tutorial</A>
				13	by Guido van Rossum. This guide
				14	more-or-less replaces chapter two of the tutorial, and provides some
				15	additional material. <p>
				16
				17	The document refers to Python 1.3.3 or higher, some of the features (like
				18	setting applet options) will not work in earlier versions of Python. <p>
				19
				20	<h2>Invoking the interpreter</h2>
				21
				22	The name of the interpreter may differ on different installations: it may
				23	be called <CODE>Python</CODE>, <CODE>PythonPPC</CODE> (for powerpc macs) or
				24	<CODE>Python68K</CODE> (indeed, for 68K macs). It will always be recognizable by
				25	the "16 ton" icon, though. You start the interpreter in interactive mode by
				26	double-clicking it. <p>
				27
				28	<img src="html.icons/python.gif"><p>
				29
				30	This should give you a text window with an informative version string and a prompt,
				31	something like the following:
				32	<PRE>
				33	Python 1.3.3 (Apr 7 1996) [CW PPC w/GUSI]
				34	Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
				35	>>>
				36	</PRE>
				37	The version string tells you the version of Python, whether it was built for
				38	PPC or 68K macs and possibly some options used to build the interpreter. If
				39	you find a bug or have a question about how the interpreter works it is a good
				40	idea to include the version information in your message. <p>
				41
				42	At the prompt you can type interactive python commands. See the tutorial for
				43	more information. The interactive window works more-or-less like a Communication
				44	Toolbox or Telnet window: you type commands at the bottom and terminate them with
				45	the <EM>[return]</EM> or <EM>[enter]</EM> key. Interpreter feedback also appears
				46	at the bottom of the window, and the contents scroll as output is added. You can
				47	use copy and paste in the normal way, but be sure to paste only at the bottom
				48	of the document.
				49
				50	<h2>Creating Python scripts</h2>
				51
				52	The Python interpreter works in a way that is different from what you would
				53	expect of a macintosh program: the interpreter is just that: an interpreter.
				54	There is no builtin editor or other development support. Hence, to create
				55	a Python script you need an external text editor. For a first script you
				56	can use any editor that can create plain, unstyled text files, such as
				57	<CODE>SimpleText</CODE>. <p>
				58
				59	For more serious scripts, though, it is advisable to use a programmers editor,
				60	such as <CODE>BBEdit</CODE> or <CODE>Alpha</CODE>. BBEdit is my favorite: it comes in a
				61	commercial version but also in a fully-functional free version
				62	<CODE>BBEdit Lite</CODE>. You can download it from the
				63	<A HREF="http://www.barebones.com/">BareBones</A> site.
				64	The free version will probably provide all the functionality you will ever need.
				65	Besides the standard edit facilities it has multi-file searches and many other
				66	goodies that can be very handy when editing programs. <p>
				67
				68	After you have created your script in the editor of your choice you drop it on
				69	the interpreter. This will start the interpreter executing the script, again with
				70	a console window in which the output appears and in which you can type input if
				71	the script requires it. Normally the interpreter will close the window and quit
				72	as soon as the script is done executing, see below under
				73	<A HREF="#startup">startup options</A>
				74	for a way to change this. <p>
				75
				76	It is a good idea to have the names of all your scripts end in <CODE>.py</CODE>. While
				77	this is not necessary for standalone scripts it is needed for modules, and it is
				78	probably a good idea to start the habit now. <p>
				79
				80	<h2>Clickable python scripts</h2>
				81
				82	If you create your script with the correct creator and type, creator <CODE>'Pyth'</CODE>
				83	and type <CODE>'TEXT'</CODE>, you can double-click your script and it will automatically
				84	invoke the interpreter. If you use BBEdit you can tell it about the Python file
				85	type by adding it to the "file types" sections of the preferences. Then, if you save
				86	a file for the first time you can tell BBEdit to save the file as a Python script
				87	through the "options" choice of the save dialog. <p>
				88
				89	The <CODE>Scripts</CODE> folder contains a script <CODE>fixfiletypes</CODE> that will
				90	recursively traverse a folder and set the correct creator and type for all files
				91	ending in <CODE>.py</CODE>. <p>
				92
				93	<h2>Interaction with the user</h2>
				94
				95	Normally, the interpreter will check for user input (mouse clicks, keyboard
				96	input) every once in a while, so it is possible to switch to other applications
				97	while a script runs. It is also possible to interrupt the interpreter with
				98	the standard command-period keypress, this will raise the <CODE>KeyboardInterrupt</CODE>
				99	exception. Scripts may, however, turn off this behaviour to facilitate their
				100	own event handling. Such scripts can only be killed with the command-option-escape
				101	shortcut.
				102
				103	<h2><A NAME="startup">startup options</A></h2>
				104
				105	If the <EM>option</EM> key is depressed when Python starts executing the
				106	interpreter will bring up an options dialog thru which you can influence the way
				107	the interpreter behaves. Keep the option key depressed until the dialog comes up. <p>
				108
				109	<img src="html.icons/options.gif"><p>
				110
				111	The options modify the interpreters behaviour in the following way:
				112	<ul>
				113	<li> the interpreter goes to interactive mode (in stead of
				114	exiting) after a script has terminated normally,
				115	<li> for every module imported a line is printed telling you where the
				116	module was loaded from,
				117	<li> do not print the values of expressions executed as statements in an
				118	interactive python,
				119	<li> do not buffer stdout and stderr,
				120	<li> print some debugging output during the parsing phase,
				121	<li> keep the output window open when a script terminates.
				122	</ul>
				123	In addition, you can enter a unix-style command line which is passed to the script
				124	in <CODE>sys.argv</CODE>. Sys.argv[0] is always the name of the script being executed,
				125	additional values can be passed here. Quoting works as expected. <p>
				126
				127	The default options are also settable on a system-wide basis, see the section on
				128	<A HREF="#preferences">editing preferences</A>. <p>
				129
				130	<h2>Module search path</h2>
				131
				132	The module search path, <CODE>sys.path</CODE>, contains the folders python will search
				133	when you import a module. The path is settable on a system-wide basis (see the
				134	preferences section), and normally comprises the current folder (where the script
				135	lives), the <CODE>Lib</CODE> folder and some of its subfolders and possibly some more. <p>
				136
				137	<h2>Working folder</h2>
				138
				139	The unix concept of a <I>working directory</I> does not translate directly to
				140	a similar concept on the Macintosh. To facilitate easy porting and the use of
				141	relative pathnames in scripts the interpreter simulates a working directory. When
				142	a script is started the initial working directory is the folder where the script
				143	lives. In case of an interactive interpreter the working directory is the folder
				144	where the interpreter lives. The "standard file" folder does <EM>not</EM> follow
				145	the working directory, it follows the standard MacOS rules (which are settable
				146	through a control panel since MacOS 7.5).
				147
				148	<h2>Interactive startup file</h2>
				149
				150	If the folder containing the interpreter contains a file named <CODE>PythonStartup</CODE>
				151	this file is executed when you start an interactive interpreter. In this file you
				152	could import modules you often use and other such things. <p>
				153
				154
				155	<h2>Compiled python scripts</h2>
				156
				157	Once a python module has been imported the interpreter creates a compiled version
				158	which is stored in a file with the ".py" extension replaced by ".pyc". These
				159	compiled files, with creator <CODE>'Pyth'</CODE> and type <CODE>'PYC '</CODE> load faster
				160	when imported (because they do not have to be parsed). The <CODE>Lib</CODE> folder
				161	contains a script <CODE>compileall.py</CODE>, running this script will cause all modules
				162	along the python search path to be precompiled, which will speed up your programs.
				163	Compiled files are also double-clickable. <p>
				164
				165	<h2>Python resources</h2>
				166
				167	MacPython has the ability to collect a number of compiled modules together
				168	in the resource fork of a single file. This feature is useful if you
				169	distribute a python program and want to minimize clutter: you can put all the
				170	needed modules in a single file (which could even be the interpreter itself). <p>
				171
				172	If the module search path contains a filename as one of its entries (as opposed to
				173	a folder name, which is the normal case) this file will be searched for a resource
				174	with type <CODE>'PYC '</CODE> and a name matching the module being imported. <p>
				175
				176	The <CODE>scripts</CODE> folder contains a script <CODE>PackLibDir</CODE> which will convert
				177	a number of modules (or possibly a complete subtree full of modules) into such a
				178	resource file.
				179
				180	<h2><A NAME="preferences">Setting interpreter preferences</A></h2>
				181
				182	The python interpreter keeps a preferences file in the standard location in the
				183	system folder. In this preferences file it remembers the default module search
				184	path and the default settings for the runtime options. The preferences are settable
				185	via <CODE>EditPythonPrefs</CODE>. For PPC python this is a standalone program living
				186	in the main Python folder, for 68K python it is a script in the <CODE>Scripts</CODE>
				187	folder. <p>
				188
				189	The interface to edit the preferences is rather clunky for the current release. <p>
				190
				191	<img src="html.icons/preferences.gif"><p>
				192
				193	In the editable text field at the top you enter the initial module search path,
				194	using newline as a separator. There are two special values you can use here:
				195	an initial substring <CODE>$(PYTHON)</CODE> will expand to the Python home folder
				196	and a value of <CODE>$(APPLICATION)</CODE> will expand to the the python application
				197	itself. Note that the text field may extend "beyond the bottom" even though it
				198	does not have a scroll bar. Using the arrow keys works, though.<p>
				199
				200	The Python home folder $(PYTHON) is initially, when you execute the interpreter
				201	for the first time, set to the folder where the interpreter lives. You can change it
				202	here. <p>
				203
				204	Finally, you can set the default startup options here, through a sub-dialog.
				205
				206	<h2>Applets</h2>
				207
				208	An applet is a fullblown application written in Python, similar to an AppleScript
				209	applet (and completely different from a Java applet). Applets are currently only
				210	supported on PowerPC macintoshes, and are created using the <CODE>mkapplet</CODE>
				211	program. You create an applet by dropping the python source script onto mkapplet.
				212	The <CODE>Demo</CODE> folder contains an example of a more involved applet with its
				213	own resource file, etc. <p>
				214
				215	Note that while an applet behaves as a fullblown Macintosh application it is
				216	not self-sufficient, so distributing it to a machine without an installed Python
				217	interpreter will not work: it needs the shared python execution engine
				218	<CODE>PythonCore</CODE>, and probably various modules from the Lib and PlugIns folders. <p>
				219
				220	<h2>Customizing applets</h2>
				221
				222	Applets can have their own settings for the startup options and module search
				223	path. Dropping an applet on the <CODE>EditPythonPrefs</CODE>
				224	application allows you to set
				225	these, in the same way as double-clicking EditPythonPrefs allows you to set
				226	the system-wide defaults. <p>
				227
				228	Actually, not only applets but also the interpreter itself can have non-default
				229	settings for path and options. If you make a copy of the interpreter and drop
				230	this copy onto EditPythonPrefs you will have an interpreter that has a different
				231	set of default settings.
				232
				233	<h2>Where to go from here</h2>
				234
				235	The previously mentioned <A HREF="http://www.python.org/doc/tut/tut.html">Python
				236	Tutorial</A> is an excellent place to start reading if you have never used
				237	Python before. Other documentation such as the library reference manual is
				238	indexed at the <A HREF="http://www.python.org/doc/">Python Documentation</A>
				239	page. <p>
				240
				241	There are some <A HREF="index.html">annotated sample programs</A> available
				242	that show some mac-specific issues, like use of various toolboxes and creation
				243	of Python applets. <p>
				244
				245	Finally, the <CODE>Demo</CODE> folder in the Macintosh distribution contains
				246	a number of other example programs. Most of these are only very lightly documented,
				247	but they may help you to understand some aspects of using Python. <p>
				248
				249	The best way to contact fellow Macintosh Python programmers is to join
				250	the MacPython Special Interest Group mailing list. Send a message with "info"
				251	in the body to <A HREF="mailto:pythonmac-sig-request@python.org">pythonmac-sig-request@python.org</A>
				252	or view the <A HREF="http://www.python.org/sigs/pythonmac-sig/">Pythonmac SIG page</A> on the
				253	<A HREF="http://www.python.org">www.python.org</A> WWW server. <p>
				254
				255	<h2>Troubleshooting</h2>
				256
				257	Python is a rather safe language, and hence it should be difficult to crash the
				258	interpreter of the system with a Python script. There is an exception to this rule,
				259	though: the modules that interface to the system toolboxes (windowing, quickdraw,
				260	etc) do very little error checking and therefore a misbehaving program using these
				261	modules may indeed crash the system. Such programs are unfortunately rather
				262	difficult to debug, since the crash does not generate the standard Python stack
				263	trace, obviously, and since debugging print statements will often interfere with
				264	the operation of the program. There is little to do about this currently. <p>
				265
				266	Probably the most common cause of problems with modules ported from other
				267	systems is the Mac end-of-line convention. Where unix uses linefeed, 0x0d, to
				268	separate lines the mac uses carriage return, 0x0a. To complicate matters more
				269	a lot of mac programming editors like BBEdit and emacs will work happily with
				270	both conventions, so the file will appear to be correct in the editor but cause
				271	strange errors when imported. BBEdit has a popup menu which allows you to inspect
				272	(and set) the end-of-line convention used in a file. <p>
				273
				274	<HR>
				275	<A HREF="http://www.cwi.nl/~jack">Jack Jansen</A>,
				276	<A HREF="mailto:jack@cwi.nl">jack@cwi.nl</A>, 7-Apr-1996.
				277
				278	</BODY>
				279	</HTML>