Skip to content

C
cpython
Kaydet (Commit) a6308130 authored tarafından Jack Jansen's avatar Jack Jansen
Dosyalara gözat
Seçenekler

Explanations of the examples here

üst f4875af0
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 445 additions and 0 deletions
Mac/Demo/applescript.html 0 → 100644
Dosyayı görüntüle @ a6308130
<HTML><HEAD><TITLE>Using Open Scripting Extension from Python</TITLE></HEAD>
<BODY>
<H1>Using Open Scripting Extension from Python</H1>
<HR>
OSA support in Python is still far from complete, and what
support there is is likely to change in the forseeable future. Still,
there is already enough in place to allow you to do some nifty things
to other programs from your python program. <P>
<CITE>
Actually, when we say "AppleScript" in this document we actually mean
"the Open Scripting Architecture", there is nothing
AppleScript-specific in the Python implementation. <p>
</CITE>
In this example, we will look at a scriptable application, extract its
"AppleScript Dictionary" and generate a Python interface module from
that and use that module to control the application. Because we want
to concentrate on the OSA details we don't bother with a real
user-interface for our application. <p>
The application we are going to script is Eudora Light, a free mail
program from <A HREF="http://www.qualcomm.com">QualComm</A>. This is a
very versatile mail-reader, and QualComm has an accompanying
commercial version once your needs outgrow Eudora Light. Our program
will tell Eudora to send queued mail, retrieve mail or quit. <p>
<H2>Creating the Python interface module</H2>
There is a tool in the standard distribution that looks through a file
for an 'AETE' or 'AEUT' resource, the internal representation of the
AppleScript dictionary. This tool is called
<CODE>gensuitemodule.py</CODE>, and lives in
<CODE>Tools:bgen:ae</CODE>. When we start it, it asks us for an input
file and we point it to the Eudora Light executable. It starts parsing
the AETE resource, and for each AppleEvent suite it finds it prompts
us for the filename of the resulting python module. Remember to change
folders for the first module, you don't want to clutter up the Eudora
folder with your python interfaces. If you want to skip a suite you
press cancel and the process continues with the next suite. In the
case of Eudora, you do <EM>not</EM> want to generate the Required
suite, because it will be empty. AppleScript understands that an empty
suite means "incorporate the whole standard suite by this name",
gensuitemodule does not currently understand this. Creating the empty
<CODE>Required_Suite.py</CODE> would hide the correct module of that
name from our application. <p>
<CITE>
Time for a sidebar. If you want to re-create
<CODE>Required_Suite.py</CODE> or one of the other standard modules
you should look in <CODE>System Folder:Extensions:Scripting
Additions:Dialects:English Dialect</CODE>, that is where the core
AppleEvent dictionaries live. Also, if you are looking for the
<CODE>Finder_Suite</CODE> interface: don't look in the finder (it has
an old System 7.0 scripting suite), look at the extension <CODE>Finder
Scripting Extension</CODE>. <p>
</CITE>
Let's glance at the <A
HREF="scripting/Eudora_Suite.py">Eudora_Suite.py</A> just created. You
may want to open Script Editor alongside, and have a look at how it
interprets the dictionary. EudoraSuite.py starts with some
boilerplate, then come some dictionaries implementing the OSA
Enumerations, then a big class definition with methods for each
AppleScript Verb and finally some comments. The Enumerations we will
skip, it suffices to know that whenever you have to pass an enumerator
to a method you can pass the english name and don't have to bother
with the 4-letter type code. So, you can say
<CODE><PRE>
eudora.notice(occurrence="mail_arrives")
</PRE></CODE>
instead of the rather more cryptic
<CODE><PRE>
eudora.notice(occurrence="wArv")
</PRE></CODE>
The <CODE>Eudora_Suite</CODE> class is the bulk of the code
generated. For each verb it contains a method. Each method knows what
arguments the verb expects, and it makes handy use of the keyword
argument scheme introduced in Python 1.3 to present a palatable
interface to the python programmer. You will see that each method
calls some routines from <CODE>aetools</CODE>, an auxiliary module
living in <CODE>Tools:bgen:ae</CODE> which contains some other nifty
AppleEvent tools as well. Have a look at it sometime, there is (of
course) no documentation yet. <p>
The other thing you notice is that each method calls
<CODE>self.send</CODE>, but no such method is defined. You will have
to provide it by subclassing or multiple inheritance, as we shall see
later. <p>
The module ends with some comments. Sadly, gensuitemodule is not yet
able to turn the Object Specifiers into reasonable Python code. For
now, if you need object specifiers, you will have to use the routines
defined in <CODE>aetools.py</CODE> (and <CODE>aetypes.py</CODE>, which
it incorporates). You use these in the form <CODE>aetools.Word(10,
aetools.Document(1))</CODE> where the corresponding AppleScript
terminology would be <CODE>word 10 of the first
document</CODE>. Examine the two modules mentioned above along with
the comments at the end of your suite module if you need to create
more than the standard object specifiers. <p>
<H2>Using a Python suite module</H2>
Now that we have created the suite module we can use it in an
application. We do this by creating a class that inherits
<CODE>Eudora_Suite</CODE> and the <CODE>TalkTo</CODE> class from
<CODE>aetools</CODE>. The <CODE>TalkTo</CODE> class is basically a
container for the <CODE>send</CODE> method used by the methods from
the suite classes. <p>
Actually, our class will also inherit <CODE>Required_Suite</CODE>,
because we also need functionality from that suite: the quit
command. Gensuitemodule could have created this completely derived
class for us, since it has access to all information needed to build
the class but unfortunately it does not do so at the moment. All in
all, the heart of our program looks like this:
<CODE><PRE>
import Eudora_Suite, Required_Suite, aetools
class Eudora(aetools.TalkTo, Required_Suite.Required_Suite, \
Eudora_Suite.Eudora_Suite):
pass
</PRE></CODE>
Yes, our class body is <CODE>pass</CODE>, all functionality is already
provided by the base classes, the only thing we have to do is glue it
together in the right way. <p>
Looking at the sourcefile <A
HREF="scripting/testeudora.py">testeudora.py</A> we see that it starts
with some imports (and some <CODE>addpack</CODE> calls to extend
<CODE>sys.path</CODE> to include <CODE>Tools:bgen:ae</CODE>, use of
<CODE>ni</CODE> should be preferred over <CODE>addpack</CODE> but I
have not managed to master it yet). Then we get the class definition
for our main object and a constant giving the signature of Eudora. <p>
This, again, needs a little explanation. There are various ways to
describe to AppleScript which program we want to talk to, but the
easiest one to use (from Python, at least) is creator
signature. Application name would be much nicer, but Python currently
does not have a module that interfaces to the Finder database (which
would allow us to map names to signatures). The other alternative,
<CODE>ChooseApplication</CODE> from the program-to-program toolbox, is
also not available from Python at the moment. <p>
The main program itself is a wonder of simplicity. We create the
object that talks to Eudora (passing the signature as argument), ask
the user what she wants and call the appropriate method of the talker
object. The use of keyword arguments with the same names as used by
AppleScript make passing the parameters a breeze. <p>
The exception handling does need a few comments, though. Since
AppleScript is basically a connectionless RPC protocol nothing happens
when we create to talker object. Hence, if the destination application
is not running we will not notice until we send our first
command. There is another thing to note about errors returned by
AppleScript calls: even though <CODE>MacOS.Error</CODE> is raised not
all of the errors are actually <CODE>OSErr</CODE>-type errors, some
are error codes returned by the server application. In that case, the
error message will be incorrect. <p>
That concludes our simple example. Again, let me emphasize that
scripting support in Python is not very complete at the moment, and
the details of how to use AppleEvents will definitely change in the
near future. This will not only fix all the ideosyncracies noted in
this document but also break existing programs, since the current
suite organization will have to change to fix some of the problems.
Still, if you want to experiment with AppleEvents right now: go ahead!
<p>
Mac/Demo/example1.html 0 → 100644
Dosyayı görüntüle @ a6308130
This diff is collapsed.
Mac/Demo/example2.html 0 → 100644
Dosyayı görüntüle @ a6308130
<HTML><HEAD><TITLE>Using python to create Macintosh applications, part two</TITLE></HEAD>
<BODY>
<H1>Using python to create Macintosh applications, part two</H1>
<HR>
In this document we rewrite the application of the <A
HREF="example1.html">previous example</A> to use modeless dialogs. We
will use an application framework, and we will have a look at creating
applets, standalone applications written in Python. <A
HREF="example2/InterslipControl-2.py">Source</A> and resource file (in
binary and <A HREF="example2/InterslipControl-2.rsrc.hqx">BinHex</A>
form for downloading) are available in the folder <A
HREF="example2">example2</A>. If you want to run the program on your
machine you will also need a new copy of <A
HREF="update-to-1.3/FrameWork.py">FrameWork.py</A>, which has been
updated since the 1.3 release. <p>
Again, we start with ResEdit to create our dialogs. Not only do we
want a main dialog this time but also an "About" dialog, and we
provide the <A NAME="bundle">BNDL resource</A> and related stuff that
an application cannot be without. (Actually, a python applet can be
without, <A HREF="#no-bundle">see below</A>). "Inside Mac" or various
books on macintosh programming will help here. Also, you can refer to
the resource files provided in the Python source distribution for some
of the python-specific points of BNDL programming: the
"appletbundle.rsrc" file is what is used for creating applets if you
don't provide your own resource file. <p>
Let's have a look at InterslipControl-2.rsrc, our resource file. First
off, there's the standard BNDL combo. I've picked 'PYTi' as signature
for the application. I tend to pick PYT plus one lower-case letter for
my signatures. The finder gets confused if you have two applications
with the same signature. This may be due to some incorrectness on the
side of "mkapplet", I am not sure. There is one case when you
definitely need a unique signature: when you create an applet that has
its own data files and you want the user to be able to start your
applet by double-clicking one of the datafiles. <p>
There's little to tell about the BNDL stuff: I basically copied the
generic Python applet icons and pasted in the symbol for
InterSLIP. The two dialogs are equally unexciting: dialog 512 is our
main window which has four static text fields (two of which we will be
modifying during runtime, to show the status of the connection) and
two buttons "connect" and "disconnect". The "quit" and "update status"
buttons have disappeared, because they are handled by a menu choice
and automatically, respectively. <p>
<H2>A modeless dialog application using FrameWork</H2>
On to the source code in <A
HREF="example2/InterslipControl-2.py">InterslipControl-2.py</A>. The
start is similar to our previous example program <A
HREF="example1/InterslipControl-1.py">InterSlipControl-1.py</A>, with
one extra module being imported. To make life more simple we will use
the <CODE>FrameWork</CODE> module, a nifty piece of code that handles
all the gory mac details of event loop programming, menubar
installation and all the other code that is the same for every mac
program in the world. Like most standard modules, FrameWork will run
some sample test code when you invoke it as a main program, so try it
now. It will create a menu bar with an Apple menu with the about box
and a "File" menu with some pythonesque choices (which do nothing
interesting, by the way) and a "Quit" command that works. <p>
<CITE>
A more complete description of <A NAME="framework">FrameWork</A> is
sorely needed, and will (at some point) be incorporated in the
programmers manual or in place of this paragraph. For now you'll have
to make do with the knowledge that you use FrameWork by building your
classes upon the classes provided by it and selectively overriding
methods to extend its functionality (or override the default
behaviour). And you should read the Source, of Course:-) <p>
</CITE>
After the imports we get the definitions of resource-IDs in our
resource file, slightly changed from the previous version of our
program, and the state to string mapping. The main program is also
similar to our previous version, with one important exception: we
first check to see whether our resource is available before opening
the resource file. Why is this? Because later, when we will have
converted the script to an applet, our resources will be available in
the applet file and we don't need the separate resource file
anymore. <p>
Next comes the definition of our main class,
<CODE>InterslipControl</CODE>, which inherits
<CODE>FrameWork.Application</CODE>. The Application class handles the
menu bar and the main event loop and event dispatching. In the
<CODE>__init__</CODE> routine we first let the base class initialize
itself, then we create our modeless dialog and finally we jump into
the main loop. The main loop continues until <CODE>self</CODE> is
raised, which we will do when the user selects "quit". When we create
the instance of <CODE>MyDialog</CODE> (which inherits
<CODE>DialogWindow</CODE>, which inherits <CODE>Window</CODE>) we pass
a reference to the application object, this reference is used to tell
Application about our new window. This enables the event loop to keep
track of all windows and dispatch things like update events and mouse
clicks. <p>
The <CODE>makeusermenus()</CODE> method (which is called sometime
during the Application <CODE>__init__</CODE> routine) creates a File
menu with a Quit command (shortcut command-Q), which will callback to
our quit() method. <CODE>Quit()</CODE>, in turn, raises 'self' which
causes the mainloop to terminate. <p>
Application provides a standard about box, but we override this by
providing our own <CODE>do_about()</CODE> method which shows an about
box from a resource as a modal dialog. This piece of code should look
familiar to you from the previous example program. That do_about is
called when the user selects About from the Apple menu is, again,
taken care of by the __init__ routine of Application. <p>
Our main object finally overrides <CODE>idle()</CODE>, the method
called when no event is available. It passes the call on to our dialog
object to give it a chance to update the status fields, if needed. <p>
The <CODE>MyDialog</CODE> class is the container for our main
window. Initialization is again done by first calling the base class
<CODE>__init__</CODE> function and finally setting two local variables
that are used by <CODE>updatestatus()</CODE> later. <p>
<CODE>Do_itemhit()</CODE> is called when an item is selected in this
dialog by the user. We are passed the item number (and the original
event structure, which we normally ignore). The code is similar to the
main loop of our previous example program: a switch depending on the
item selected. <CODE>Connect()</CODE> and <CODE>disconnect()</CODE>
are again quite similar to our previous example. <p>
<CODE>Updatestatus()</CODE> is different, however. It is now
potentially called many times per second instead of only when the
user presses a button we don't want to update the display every time
since that would cause some quite horrible flashing. Luckily,
<CODE>interslip.status()</CODE> not only provides us with a state and
a message but also with a message sequence number. If neither state
nor message sequence number has changed since the last call there is
no need to update the display, so we just return. For the rest,
nothing has changed. <p>
<H2><IMG SRC="html.icons/mkapplet.gif"><A NAME="applets">Creating applets</A></H2>
Now, if you have a PowerPC Macintosh, let us try to turn the python
script into an applet, a standalone application. Actually,
"standalone" is probably not the correct term here, since an applet
does still depend on a lot of the python environment: the PythonCore
shared library, the Python Preferences file, the python Lib folder and
any other modules that the main module depends on. It is possible to
get rid of all these dependencies except for the dependency on
PythonCore, but at the moment that is still quite difficult so we will
ignore that possibility for now. By standalone we mean here that the
script has the look-and-feel of an application, including the ability
to have its own document types, be droppable, etc. <p>
The easiest way to create an applet is to take your source file and
drop it onto "mkapplet" (normally located in the Python home
folder). This will create an applet with the same name as your python
source with the ".py" stripped. Also, if a resource file with the same
name as your source but with ".rsrc" extension is available the
resources from that file will be copied to your applet too. If there
is no resource file for your script a set of default resources will be
used, and the applet will have the default creator 'PYTa'. The latter
also happens if you do have a resource file but without the BNDL
combo. <A NAME="no-bundle">Actually</A>, for our example that would
have been the most logical solution, since our applet does not have
its own data files. It would have saved us hunting for an unused
creator code. The only reason for using the BNDL in this case is
having the custom icon, but that could have been done by pasting an
icon on the finder Info window, or by providing an custon icon in your
resource file and setting the "custom icon" finder bit. <p>
If you need slightly more control over the mkapplet process you can
double-click mkapplet, and you will get dialogs for source and
destination of the applet. The rest of the process, including locating
the resource file, remains the same. <p>
Note that though our example application completely bypasses the
normal python user interface this is by no means necessary. Any python
script can be turned into an applet, and all the usual features of the
interpreter still work. <p>
That's all for this example, you may now return to the <A HREF="index.html">
table of contents</A> to pick another topic. <p>
Mac/Demo/index.html 0 → 100644
Dosyayı görüntüle @ a6308130
<HTML><HEAD><TITLE>Macintosh Python crash course</TITLE></HEAD>
<BODY>
<H1><IMG SRC="html.icons/python.gif">Macintosh Python crash course</H1>
<HR>
This set of documents provides an introduction to various aspects of
Python programming on the Mac. It is assumed that the reader is
already familiar with Python and, to some extent, with MacOS Toolbox
programming. Other readers may find something interesting here too,
your mileage may vary. <p>
Another set of Macintosh-savvy examples, more aimed at beginners, is
maintained by Joseph Strout, at <A
HREF="http://www-acs.ucsd.edu/~jstrout/python/">
http://www-acs.ucsd.edu/~jstrout/python/</A>.
<P>
The document was actually written while I was working on a "real"
project: creating a single-button application that will allow my
girlfriend to read her mail (which actually pass thry <EM>my</EM>
mailbox, so I get to read it too, but don't tell her:-) without her
having to worry about internet connections, unix commands, etc. The
application, when finished, will connect to the net using InterSLIP,
start a (pseudo-)POP server on unix using rsh and use AppleScript to
tell Eudora to connect to that server and retrieve messages. <p>
<CITE>
If you want to try the examples here you will have to download some
fixes to the 1.3 distribution to your Macintosh. You need an updated
version of <A HREF="update-to-1.3/FrameWork.py">FrameWork.py</A> (to
go in <CODE>Lib:mac</CODE> and updated <A
HREF="update-to-1.3/into-PlugIns.hqx">project templates</A> to go into
the <CODE>PlugIns</CODE> folder for PPC users.
Users of 1.3.1 or later distributions don't need these fixes.<P>
</CITE>
If you are reading this document on the web and would prefer to read
it offline you can transfer the whole stuff (as a BinHexed StuffIt
archive) from <A HREF="complete.hqx"> here</A>. This archive includes
the fixes mentioned in the previous paragraph. <p>
<H2>Table of contents</H2>
<UL>
<LI>
<A HREF="example1.html">Using python to create Macintosh applications,
part one</A> explains how to create a simple modal-dialog application
in Python. It also takes a glance at using the toolbox modules Res and
Dlg, and EasyDialogs for simple question-dialogs.
<LI>
<A HREF="example2.html">Using python to create Macintosh applications,
part two</A> turns the previous example program into a more complete
mac application, using a modeless dialog, menus, etc. It also explains
how to create applets, standalone applications written in Python.
<LI>
In the Python distribution two more examples are included without
explanation. <I>PICTbrowse</I> is an application that locates PICT
resources and displays them, it demonstrates some quickdraw and the
resource and list namagers. <I>Imgbrowse</I> displays image files in
many different formats (gif, tiff, pbm, etc). It shows how to use the
img modules on the mac.
<LI>
<A HREF="plugins.html">Creating a C extension module on the Macintosh</A>
is meant for the hardcore programmer, and shows how to create an
extension module in C. It also handles using Modulator to create the
boilerplate for your module, and creating dynamically-loadable modules
on PowerPC Macs.
<LI>
<A HREF="applescript.html">Using Open Scripting Architecture from Python</A> explains
how to create a Python module interfacing to a scriptable application,
and how to use that module in your python program.
</UL>
At some point in the (possibly distant) future, I will add chapters on
how to use bgen to create modules completely automatic and how to make
your Python program scriptable, but that will have to wait. <p>
<HR>
Please let me know if you miss critical information in this
document. I am quite sure that I will never find the time to turn it
into a complete MacPython programmers guide (which would probably be a
400-page book instead of 5 lousy html-files), but it should contain
at least the information that is neither in the standard Python
documentation nor in Inside Mac or other Mac programmers
documentation. <p>
<HR>
<A HREF="http://www.cwi.nl/~jack">Jack Jansen</A>,
<A HREF="mailto:jack@cwi.nl">jack@cwi.nl</A>, 6-Mar-1996.
Mac/Demo/plugins.html 0 → 100644
Dosyayı görüntüle @ a6308130
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment