[Python-checkins] python/dist/src/Mac/OSXResources/app/Resources/English.lproj/Documentation/ide IDE.gif,NONE,1.1 entering_in_new_window.gif,NONE,1.1 hello_world.gif,NONE,1.1 index.html,NONE,1.1 loading_ide.gif,NONE,1.1 making_new_window.gif,NONE,1.1 new_ide_window.gif,NONE,1.1 new_window_made.gif,NONE,1.1 output_window.gif,NONE,1.1 saving_edited_file.gif,NONE,1.1 simple_commands.gif,NONE,1.1 syntax_error.gif,NONE,1.1

jackjansen@users.sourceforge.net jackjansen@users.sourceforge.net
Wed, 02 Jul 2003 02:20:09 -0700


Update of /cvsroot/python/python/dist/src/Mac/OSXResources/app/Resources/English.lproj/Documentation/ide
In directory sc8-pr-cvs1:/tmp/cvs-serv23935/OSXResources/app/Resources/English.lproj/Documentation/ide

Added Files:
	IDE.gif entering_in_new_window.gif hello_world.gif index.html 
	loading_ide.gif making_new_window.gif new_ide_window.gif 
	new_window_made.gif output_window.gif saving_edited_file.gif 
	simple_commands.gif syntax_error.gif 
Log Message:
Moved the IDE tutorial to a directory with a shorter name. The long
name was giving problems with some tar implementations.


--- NEW FILE: IDE.gif ---
(This appears to be a binary file; contents omitted.)

--- NEW FILE: entering_in_new_window.gif ---
(This appears to be a binary file; contents omitted.)

--- NEW FILE: hello_world.gif ---
(This appears to be a binary file; contents omitted.)

--- NEW FILE: index.html ---
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
        "http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
	<title>One Day of MacPython IDE Toying</title>
	<link rel="SHORTCUT ICON" href="../pythonsmall.gif">
	<META NAME="AppleIcon" CONTENT="../pythonsmall.gif">
</head>
<body bgcolor="#ffffff">
		<h1>One Day of MacPython IDE Toying</h1>
		<table>
		<tr>
			<td>
				<img src="IDE.gif" alt="">
			</td>
			<td>
				<p>This document gives a very basic introduction to the
				MacPython <b>I</b>ntegrated <b>D</b>evelopment <b>E</b>nvironment (IDE) on Mac OS. It was
				written specifically for MacPython 2.3 on Mac OS X, but most of
				it  is applicable to MacPython-OS9 too. It is based on 
				<a href="http://www-hkn.eecs.berkeley.edu/~dyoo/python/idle_intro/">&quot;One
				Day of IDLE Toying&quot;</a> by Danny Yoo, which you should read if
				you want to use the cross-platform IDLE Python development
				environment.</p>
	
			</td>
		</tr>
		</table>
		<hr>
		<br style="page-break-after: always">

<p>Ok, let's assume that we've already installed Python. (If not, we can
visit: <a href="http://www.cwi.nl/~jack/macpython.html">http://www.cwi.nl/~jack/macpython.html</a>
or <a href="http://python.org">http://python.org</a>
and download the most recent Python interpreter. Get the Mac OSX binary
installer.) The first thing we'd like to do is actually start running it!
We can do this by opening up the IDE, which should be in Applications
under the newly-created MacPython program folder: </p><p><img
src="loading_ide.gif" border=1 alt="image of IDE icon"></p>

<hr><br style="page-break-after: always">

<p>The IDE starts up and shows an interactive window: </p>
<p><img src="new_ide_window.gif" alt="image of new window"></p>

<p>If the window does not show up (because you have run the IDE before
and closed it: it remembers that between runs) open it with the <tt>Windows-&gt;Python Interactive</tt>
menu entry. </p>

<p>This is the interactive window to the IDE, it allows us to enter
commands directly into Python, and as soon as we enter a command,
Python will execute it and spit its result back to us.  We'll be
using this interactive window a lot when we're exploring Python: it's
very nice because we get back our results immediately.  If it helps,
we can think of it as a very powerful calculator.</p>

<hr><br style="page-break-after: always">

<p>Let's try something now!  As per tradition, let's get Python to say
the immortal words, "Hello World".  <img src="hello_world.gif"
border=1 alt="image of hello world program"></p> <p>Those '<tt>&gt;&gt;&gt;</tt>' signs act as a prompt
for us: Python is ready to read in a new command by giving us that
visual cue.  Also, we notice that as we enter commands, Python will
give us its output immediately.
</p>

<hr><br style="page-break-after: always">

<p>Ok, this seems pretty simple enough.  Let's try a few more
commands.  If we look below:</p>

<p><img src="simple_commands.gif" border=1 alt="image of command window"></p>

<p>we'll see the result of running a few more commands.  Don't worry
too much about knowing the exact rules for making programs yet: the
idea is that we can experiment with Python by typing in commands.  If
things don't work, then we can correct the mistake, and try it
again.</p>

<p>If you got to this point, you now know enough to start playing
around with Python!  Crack open one of the tutorials from the <a
href="http://python.org/doc/Newbies.html">Python For Beginners</a> web
page, and start exploring with the interpreter.  No time limit here.  *grin*</p>

<hr><br style="page-break-after: always">

<p>Now that we've paddled long enough, we might be asking: ok, this is
neat, but if we close down Python and start it up again, how do we get
the computer to remember what we typed?</p>

<p>The solution is a little subtle: we can't directly save what's in
the interpreter window, because it will include both our commands and
the system's responses.  What we'd like is to make a prepared file,
with just our own commands, and to be able to save that file as a
document.  When we're in the mood, we can later open that file and
"run" Python over it, saving us the time of retyping the whole
thing over again.</p>

<p>Let's try this.  First, let's start with a clean slate by opening
up a new window.</p> 

<p><img src="making_new_window.gif" border=1 alt="image of making new window"></p>

<p>Here's the result of that menu command:</p>

<p><img src="new_window_made.gif" border=1 alt="image of new window"></p>

<p>We notice that there's nothing in this new window.  What this means
is that this file is purely for our commands: Python won't interject
with its own responses as we enter the program, that is, not until we
tell it to.  This is called an edit window, and it is very similar
to edit windows in other editors such as TextEdit or BBEdit.</p>

<hr><br style="page-break-after: always">

<p>What we wanted to do before was save some of the stuff we had
tried out on the interpreter window.  Let's do that by typing (or
copy/pasting) those commands into our edit window.</p>
<p><img src="entering_in_new_window.gif" border=1 alt="image of entering commands"></p>

<p>Ok, we're done with copying and pasting.  
One big thing to notice
is that we're careful to get rid of the "<tt>&gt;&gt;&gt;</tt>"
prompts because they're not really part of our program.  The
interpreter uses them just to tell us that we're in the interpreter,
but now that we're editing in a separate file, we can remove the
artifacts that the interpreter introduces.
I have added
an extra empty print statement so our output ends with a newline.
</p>

<hr><br style="page-break-after: always">

<p>Let's save the file now.  The Save command is located under the <tt>File</tt> menu:</p>
<p><img src="saving_edited_file.gif" border=1 alt="image of saving file"></p>


<hr><br style="page-break-after: always">

<p>Now that we've saved the program, how do we run the program? Use the
Run All button at the top of the editing window, or the equivalent
menu command <tt>Python-&gt;Run Window</tt>. The output will appear in a new
window called Output Window. </p>

<p>By the way, one thing to notice is that I made a typo: I didn't
quite copy exactly what I had entered in the interpreter window
before.  Does this affect things?</p>

<p><img src="syntax_error.gif" border=1 alt="image of syntax error"></p>

<p>Ooops.  Here is an example of what Python calls a "syntax error".
Python sees that we made a typo, and warns us to take a much closer
look at our program.  The designers of Python feel that having the
system point out the error is better than trying to guess at what the
programmer meant.  Press the Edit button and you will be brought to
the trouble spot. </p>

<p>Python is often perceptive enough to direct us toward the problem,
and in this case, it's telling us that we forgot to put something at
the end of this line.  In this case, we need to add a
quotation mark at the end.  Let's add that in now.</p>

<p>Other errors, which usually occur later, when your program has
already done something, result in a different dialog that allows you
to look at variables and such in addition to showing you where
the error occurred. </p>

<hr><br style="page-break-after: always">

<p>Ok, let's say that we fixed that silly typo.  Let's try to run the
program again. This gives us a new window, the Output window, showing
the output of our program:</p>
<p><img src="output_window.gif" border=1 alt="image of output window"></p>

<hr><br style="page-break-after: always">

<p>As we play with Python, we'll find ourselves "switching modes"
between the Interpreter window and the edit window.  However,
if we try anything more complicated than two or three lines it
is often a good idea to work in an edit window. Align
your edit and output window such that you can see them at the same time.</p>

<p>This is pretty much all we need to know about the MacPython IDE to actually do
interesting things.  There is a lot more to the IDE, here is a quick
breakdown of things to see and explore:</p>

<ul>
	<li>All sorts of edit commands such as find and replace can be
	used in the editor windows. See the <tt>Edit</tt> menu.</li>
	
	<li>The bottom of the edit window has the scrollbar, but at the
	left are two navigation devices: a line number box that you can type
	numbers into to quickly go to a specific place, and a popup menu
	that lists all classes, functions and methods in your file.</li>
	
	<li>Above the vertical scrollbar you find another popup menu, this
	influences how the Run command works. You should try the debugger
	some time! If you do, and you wonder what the new small column on
	the left of your script is: you can click in it to make Python stop
	when it reaches this line so you can inspect things. The profiler
	is also nifty: it shows you where your program is spending its time.</li>
	
	<li>The module browser (<tt>Python-&gt;Module Browser</tt>) shows you all Python
	modules currently loaded. You can look at the contents of the module with
	Browse... and (for modules written in Python) at the source with Source...</li>
	
	<li>The Package Manager (under the <tt>File</tt> menu, also available as a
	separate application) allows you to easily install Python extension packages
	for all sorts of things: scientific computation, image processing,
	building user interfaces and more. </li>
	
	<li>The <tt>Help</tt> menu gives you quick access to both the Python documentation,
	if you have installed it with the Package Manager, and the Apple Developer
	documentation. </li>
	
	<li>The <tt>File-&gt;Save as Applet</tt> menu command saves your script as a MacOSX
	application. This allows you to create a script that you can drop files on,
	and much more. The IDE itself is such an applet, completely written in Python. </li>
	
</ul>
</body>
</html>

--- NEW FILE: loading_ide.gif ---
(This appears to be a binary file; contents omitted.)

--- NEW FILE: making_new_window.gif ---
(This appears to be a binary file; contents omitted.)

--- NEW FILE: new_ide_window.gif ---
(This appears to be a binary file; contents omitted.)

--- NEW FILE: new_window_made.gif ---
(This appears to be a binary file; contents omitted.)

--- NEW FILE: output_window.gif ---
(This appears to be a binary file; contents omitted.)

--- NEW FILE: saving_edited_file.gif ---
(This appears to be a binary file; contents omitted.)

--- NEW FILE: simple_commands.gif ---
(This appears to be a binary file; contents omitted.)

--- NEW FILE: syntax_error.gif ---
(This appears to be a binary file; contents omitted.)