1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
|
<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>Mac:scripts</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>
<BLOCKQUOTE>
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>
</BLOCKQUOTE>
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>Lib:toolbox</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. 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>
If you specify the application by creator you can specify an optional
<CODE>start</CODE> parameter, which will cause the application to be
started if it is not running. <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: <CODE>MacOS.Error</CODE> is raised for
all of the errors that are known to be <CODE>OSErr</CODE>-type errors,
server generated errors raise <CODE>aetools.Error</CODE>. <p>
<H2>Scripting Additions</H2>
If you want to use any of the scripting additions (or OSAXen, in
everyday speech) from a Python program you can use the same method
as for applications, i.e. run <CODE>gensuitemodule</CODE> on the
OSAX (commonly found in <CODE>System Folder:Extensions:Scripting Additions</CODE>
or something similar), define a class which inherits the generated
class and <CODE>aetools.TalkTo</CODE> and instantiate it. The application
signature to use is <CODE>'MACS'</CODE>. <P>
There are two minor points to watch out for when using gensuitemodule
on OSAXen: they appear all to define the class <CODE>System_Object_Suite</CODE>,
and a lot of them have the command set in multiple dialects. You have to
watch out for name conflicts, so, and make sure you select a reasonable dialect
(some of the non-english dialects cause gensuitemodule to generate incorrect
Python code). <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>
|
