[Pythonmac-SIG] "Official" Mac python Docs Project

[Bob Savage]

This is a multi-part message in MIME format.

------=_NextPart_000_000B_01C02EDE.C43CA4E0
Content-Type: text/plain;
	charset="iso-8859-1"
Content-Transfer-Encoding: 7bit

Chris, here's the "finished" version (meaning I probably won't be able to
get any more done this week).

** Areas that still need work **
   \subsubsection{Alpha}
   \subsubsection{Pepper}
   \subsection{Debugger}
   \subsection{Module Browser}
   \subsection{Profiler}
   \subsection{The ``Scripts'' menu}
   \subsection{BuildApplet}
   \subsection{BuildApplication}
   \section{CGI on the Mac with Python}

Of these the only ones I have any real experience with are the Module
Browser and the Debugger. I'll probably need help with the other areas, so
I'm sending this to the list as well in hopes that someone will volunteer to
write something about the missing bits.

All, if someone has time to read this and thinks I am in error about
something, or can contribute something about CGIs or whatever, please let me
know so I can get the changes in to Chris by Friday night (so he has some
time to assemble things before sending them in before the big release).

thx,

Bob

------=_NextPart_000_000B_01C02EDE.C43CA4E0
Content-Type: application/octet-stream;
	name="PythonOnTheMac.tex"
Content-Transfer-Encoding: quoted-printable
Content-Disposition: attachment;
	filename="PythonOnTheMac.tex"

\chapter{Python on the Mac}
\sectionauthor{Bob Savage}{bobsavage@mac.com}
\label{PythonOnTheMac}
Using Python on the Macintosh can seem like something completely =
different than
using it on a Unix-like or Windows system. Most of the Python
documentation, both the ``official'' documentation and published books, =
describe
only how Python is used on these systems, causing confusion for
the new user of MacPython. This chapter gives a brief introduction to
the specifics of using Python on a Macintosh.

\section{Getting MacPython}
\label{getting}
The most recent release version as well as possible newer experimental =
versions are
best found at the MacPython page maintained by Jack Jansen: =
\url{http://www.cwi.nl/~jack/macpython.html}

\section{Installation}
\label{installation}
Please refer to the README included with your distribution for the most
up-to-date instructions.

\section{Entering the interactive Interpreter}
\label{invoke interpreter}
The interactive interpreter that you will see used in Python =
documentation is started
by double-clicking the \program{PythonInterpreter} icon, which looks =
like a 16 ton
weight falling. You should see the version information and the ``>>>'' =
prompt. Use
it exactly as described in the standard documentation.

\section{How to run a Python script}
There are several ways to run a script that you or someone else has =
written in Python;
two common ways to run a Python script are 'drag and drop' and 'double =
clicking'.
Other ways include running it from within the IDE (see Section =
\ref{IDE}), or launching via AppleScript.

\subsection{Drag and drop}
One of the easiest ways to launch a Python script is via ``Drag and
Drop''. This is just like launching a text file in the Finder by =
``dragging'' it over
your word processor's icon and ``dropping'' it there. Make sure that you =
use an icon
referring to the \program{PythonInterpreter}, not the \program{IDE} or =
\program{Idle} icons which
have different behaviour which is described below.

Some things that might've gone wrong:
\begin{itemize}
\item A window flashes after dropping the script onto the
\program{PythonInterpreter}, but then disappears. Most likely this is a
configuration issue; your \program{PythonInterpreter} is setup to exit
immediately upon completion, but your script assumes that if it prints
something that text will stick around for a while. To fix this, see =
Section \ref{Defaults}.

\item After dropping the script onto the \program{PythonInterpreter}, a =
window appeared which said:
``File contains \verb+\r+ characters (incorrect line endings?)''. That =
script probably originated
on a Unix or Windows machine. You will need to change the line
endings to the standard Mac usage. One way to do this is to open the
file in \program{BBedit}
\url{http://www.barebones.com/products/bbedit_lite.html} which can
easily change the line endings between Mac, DOS, and Unix styles.

\item When you waved the script icon over the
\program{PythonInterpreter}, the \program{PythonInterpreter} icon did
not hilite. Most likely the Creator code and document type is unset (or
set incorrectly) -- This often happens when a file originates on a =
non-Mac computer.
see Section \ref{CreatorCode} for more details.
\end{itemize}

\subsection{Set Creator and Double Click}
\label{CreatorCode}
If the script that you want to launch has the appropriate Creator Code
and File Type you can simply double-click on the script to launch it.
To be ``double-clickable'' a file needs to be of type 'TEXT', with a =
creator code of 'Pyth'.

Setting the creator code and filetype can be done with the IDE -- see =
sections \ref{IDEwrite} and \ref{IDEapplet},
with an editor with a Python mode (\program{BBEdit}) -- see section =
\ref{scripting with BBedit},
or with assorted other Mac utilities, but a script (``fixfiletypes.py'') =
has been included in the MacPython
distribution, making it possible to set the proper Type and Creator =
Codes with Python.

The ``fixfiletypes.py'' script will change the file type and creator =
codes for the indicated directory.
To use ``fixfiletypes.py'':
\begin{enumerate}
\item Locate it in the ``scripts'' folder of the ``Mac'' folder of the =
PythonMac distribution.
\item Put all of the scripts that you want to fix in a folder with =
nothing else in it.
\item Double-click on the fixfiletypes.py icon.
\item Navigate into the folder of files you want to fix, and press the =
``Select current folder'' button.
\item There is no step five!
\end{enumerate}

\section{Simulating command line arguments (\member{sys.argv}) }
\label{argv}
There are multiple ways to simulate command-line arguments with =
PythonMac.
=20
\begin{enumerate}
\item via Interpreter options
\begin{itemize} % nestable? I hope so!
\item Hold the option-key down when launching your script. This will =
bring up a dialog box of=20
Python Interpreter options.
\item Click ``Set Unix-style command line..'' button.=20
\item Type the arguments into the ``Argument'' field.
\item Click ``OK''
\item Click ``Run''.
\end{itemize} % end

\item via drag and drop
If you save the script as an applet (see Section \ref{IDEapplet}), you =
can also simulate some command-line
arguments via ``Drag-and-Drop''.
\end{enumerate}

\section{How to create a Python script}
Since Python scripts are really text files, they can be created in any =
way that text files
can be created, but some special tools also exist with extra features.

\subsection{In an editor}
You can create a text file with any word processing program such as =
\program{MSWord} or \program{AppleWorks}
but you need to make sure that the file is saved as ``ASCII'' or ``plain =
text''.

\subsubsection{Editors with Python modes}
Several text editors have additional features that add functionality =
when you are creating a Python script.
These can include coloring Python keywords to make your code easier to =
read, module browsing, or a built-in
debugger.

\subsubsection{Alpha}
% **NEED INFO HERE**
=20
\subsubsection{BBedit}
\label{scripting with BBedit}
If you use \program{BBEdit} to create your scripts you will want to tell =
it about the Python creator code so that
you can simply double click on the saved file to launch it.
\begin{itemize}
\item Launch \program{BBEdit}.
\item Select ``Preferences'' from the ``Edit'' menu.
\item Select ``File Types'' from the scrolling list.
\item click on the ``Add...'' button and navigate to =
\program{PythonInterpreter} in the main directory of the
MacPython distribution; click ``open''.
\item Click on the ``Save'' button in the Preferences panel.
\end{itemize}
% Are there additional BBedit Python-specific features? I'm not aware of =
any.
=20
\subsubsection{IDE}
You can use the \program{Python IDE} supplied in the MacPython =
Distribution to create longer Python scripts=20
-- see Section \ref{IDEwrite} for details.
=20
\subsection{IDLE}
Idle is an IDE for Python that was written in Python, using TKInter. You =
should be able to use it on a Mac by following
the standard documentation, but see Section \ref{TKInter} for guidance =
on using TKInter with MacPython.

\subsubsection{Pepper}
% **NEED INFO HERE**
=20
\section{The IDE\label{IDE}} % begin main IDE section
The \program{Python IDE} (Integrated Development Environment) is a =
separate
application that acts as a text editor for your Python code, a class
browser, a graphical debugger, and more.

\subsection{Using the ``Python Interactive'' window}
Use this window like you would the \program{PythonInterpreter}, except
that you cannot use the ``Drag and drop'' method above. Instead,
dropping a script onto the \program{Python IDE} icon will open the file =
in a seperate
script window (which you can then execute manually -- see Section =
\ref{IDEexecution}).

\subsection{Writing a Python Script}
\label{IDEwrite}
In addition to using the \program{Python IDE} interactively, you can =
also type out a complete Python program,
saving it incrementally, and execute it or smaller selections of it.

You can create a new script, open a previously saved script, and save =
your currently open script by
selecting the appropriate item in the ``File'' menu. Dropping a Python =
script onto the
\program{Python IDE} will open it for editting.

If you try to open a script with the \program{Python IDE} but either =
can't locate it from the ``Open''=20
dialog box, or you get an error message like ``Can't open file of type =
...'' see Section \ref{CreatorCode}

When the \program{Python IDE} saves a script, it uses the creator code =
settings which are available by
clicking on the small black triangle on the top right of the document =
window, and selecting
``save options''. The default is to save the file with the =
\program{Python IDE} as the creator, this
means that you can open the file for editing by simply double-clicking =
on its icon. You might want to
change this behaviour so that it will be opened by the =
\program{PythonInterpreter}, and run. To do this
simply choose ``Python Interpreter'' from the ``save options''. Note =
that these options are associated
with the \emph{file} not the application.

\subsection{Executing a script from within the IDE}
\label{IDEexecution}
You can run the script in the frontmost window of the \program{Python =
IDE} by hitting the run all button.
You should be aware, however that if you use the Python convention

\verbatim{if __name__ =3D=3D ``__main__'':} % Hopefully this is the =
correct way to do this

the script will \emph{not} be ``__main'' by default. To get that =
behaviour you must select the
``Run as __main__'' option from the small black triangle on the top =
right of the document window.
Note that this option is associated with the \emph{file} not the =
application. It \emph{will} stay active
after a save, however; to shut this feature off simply select it again.
=20
\subsection{``Save as'' versus ``Save as Applet''}
\label{IDEapplet}
When you are done writing your Python script you have the option of =
saving it as an ``applet'' (by selecting
``Save as applet'' from the ``File'' menu). This has a significant =
advantage in that you can drop files or
folders onto it, to pass them to the applet the way command-line users =
would type them onto the command-line
to pass them as arguments to the script. However, you should make sure =
to save the applet as a seperate file,
do not overwrite the script you are writing, because you will not be =
able to edit it again.

Accessing the items passed to the applet via ``drag-and-drop'' is done =
using the standard \member{sys.argv}
mechanism. See the general documentation for more % need to link to the =
appropriate place in non-Mac docs

Note that saving a script as an applet will not make it runnable on a =
system without a Python installation.

\subsection{Debugger}
% **NEED INFO HERE**
=20
\subsection{Module Browser}
% **NEED INFO HERE**
=20
\subsection{Profiler}
% **NEED INFO HERE**
% end IDE

\subsection{The ``Scripts'' menu}
% **NEED INFO HERE**
=20
\section{Configuring}
The MacPython distribution comes with \program{EditPythonPrefs}, an =
applet which will help you to
customize the MacPython environment for your working habits.
=20
\subsection{EditPythonPrefs\label{EditPythonPrefs}}
\program{EditPythonPrefs} gives you the capability to configure Python =
to behave the way you want it to.
There are two ways to use \program{EditPythonPrefs}, you can use it to =
set the preferences in general,
or you can drop a particular Python engine onto it to customize only =
that version. The latter can be handy
if, for example, you want to have a second copy of the =
\program{PythonInterpreter} that keeps the output
window open on a normal exit even though you prefer to normally not work =
that way.

To change the default preferences, simply double-click on =
\program{EditPythonPrefs}. To change the preferences
only for one copy of the Interpreter, drop the icon for that copy onto =
\program{EditPythonPrefs}.
You can also use \program{EditPythonPrefs} in this fashion to set the =
preferences of the \program{Python IDE}
and any applets you create -- see Sections \ref{BuildApplet} and =
\ref{IDEapplet}.

\subsection{Adding modules to the Python Path (\member{sys.path})}
\label{Python Path}
When executing an \keyword{import} statement, Python looks for modules =
in places defined by the \member{sys.path}
To edit the \member{sys.path} on a Mac, launch =
\program{EditPythonPrefs}, and enter them into the largish field at
the top (one per line).

Since MacPython defines a main Python directory, the easiest thing is to =
add folders to
search within the main Python directory. To add a folder of scripts that =
you created called ``My Folder'' located
in the main Python Folder, enter \verbatim{$(PYTHON):My Folder} onto a =
new line.

To add the Desktop under OS 9 or below, add =
\verbatim{StartupDriveName:Desktop Folder} on a new line.

\subsection{Default startup options}
\label{Defaults}
% I'm assuming that there exists some other documentation on the
% rest of the options so I only go over a couple here.
The ``Default startup options...'' button in the =
\program{EditPythonPrefs} dialog box gives you many options=20
including the ability to keep the ``Output'' window open after the =
script terminates, and the ability to enter
interactive mode after the termination of the run script. The latter can =
be very helpful if you want to examine
the objects that were created during your script.

\section{Nifty Tools}
There are many other tools included with the MacPython distribution. In =
addition to those discussed here, make
sure to check the ``Mac'' directory.

\subsection{BuildApplet}
\label{BuildApplet}
% **NEED INFO HERE**

\subsection{BuildApplication}
% **NEED INFO HERE**
=20
\section{TKInter on the Mac}
\label{TKInter}
TKinter is installed by default with the MacPython distribution, but you =
will need to add the ``lib-tk'' folder
to the Python Path see Section \ref{Python Path}. Also, it is important =
that you do not try to launch TK from
within the \program{Python IDE} because the two event loops will collide =
-- always run a script which uses
TKInter with the \program{PythonInterpreter} instead -- see Section =
\ref{invoke interpreter}.
=20
\section{CGI on the Mac with Python\label{CGI}}
**NEED INFO HERE**

\section{Mac OS X}
At the time of this writing Mac OS X had just been released as a Public =
Beta. Efforts are under way to bring
MacPython to Mac OS X. The MacPython release \version{1.5.2c1} runs =
quite well within the ``Classic'' environment.
A ``Carbon'' port of the MacPython code is being prepared for release, =
and several people have made a command line
version  available to the ``Darwin'' layer (which is accessible via =
Terminal.app).
------=_NextPart_000_000B_01C02EDE.C43CA4E0--