1
<!doctype HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
2
<html><head><title>Using the Open Scripting Architecture from Python</title></head>
4
<h1>Using the Open Scripting Architecture from Python</h1>
7
<p><b>NOTE:</b> this document describes the OSA support that is shipped with
8
the core python distribution. Most users are better of with the more
9
userfriendly <a href="http://freespace.virgin.net/hamish.sanderson/appscript.html">appscript library</a>.
11
<p>OSA support in Python is still not 100% complete, but
12
there is already enough in place to allow you to do some nifty things
13
with other programs from your python program. </p>
17
In this example, we will look at a scriptable application, extract its
18
“AppleScript Dictionary,” generate a Python interface package from
19
the dictionary, and use that package to control the application.
20
The application we are going to script is Disk Copy, Apple's standard
21
utility for making copies of floppies, creating files that are mountable
24
to concentrate on the OSA details, we won’t bother with a real
25
user-interface for our application. </p>
29
<em>When we say “AppleScript” in this document we actually mean
30
“the Open Scripting Architecture.” There is nothing
31
AppleScript-specific in the Python implementation. Most of this document
32
focuses on the classic Mac OS; <a href="#osx">Mac OS X</a> users have some
33
additional tools.</em>
36
<h2>Python OSA architecture</h2>
38
<p>Open Scripting suites and inheritance can be modelled rather nicely
39
with Python packages, so we generate
40
a package for each application we want to script. Each suite defined in
41
the application becomes a module in the
42
package, and the package main module imports everything from all the
43
submodules and glues together all the classes (in Python terminology—
44
events in OSA terminology or verbs in AppleScript terminology). </p>
47
A suite in an OSA application can extend the functionality of a standard
48
suite. This is implemented in Python by importing everything from the
49
module that implements the standard suites and overriding anything that has
50
been extended. The standard suites live in the StdSuite package. </p>
53
This all sounds complicated, but the good news is that basic
54
scripting is actually pretty simple. You can do strange and wondrous things
55
with OSA scripting once you fully understand it. </p>
57
<h2>Creating the Python interface package</h2>
60
<p>There is a tool in the standard distribution that can automatically
61
generate the interface packages. This tool is called
62
<code>gensuitemodule.py</code>, and lives in <code>Mac:scripts</code>.
63
It looks through a file
64
for an ‘AETE’ or ‘AEUT’ resource,
65
the internal representation of the
66
AppleScript dictionary, and parses the resource to generate the suite
68
When we start <code>gensuitemodule</code>, it asks us for an input file;
70
we point it to the Disk Copy executable. </p>
73
Next, <code>gensuitemodule</code> wants a folder where it will store the
74
package it is going to generate.
75
Note that this is the package folder, not the parent folder, so we
76
navigate to <code>Python:Mac:Demo:applescript</code>, create a folder
77
<code>Disk_Copy</code>, and select that. </p>
80
We next specify the folder from which <code>gensuitemodule</code>
81
should import the standard suites. Here,
82
we always select <code>Python:Mac:Lib:lib-scriptpackages:StdSuites</code>. (There is
83
one exception to this rule: when you are generating <code>StdSuites</code> itself
84
you select <code>_builtinSuites</code>.)
88
It starts parsing the AETE resource, and for
89
each AppleEvent suite it finds, <code>gensuitemodule.py</code>
90
prompts us for the filename of the
91
resulting python module. Remember to change folders for the first
92
module—you don't want to clutter up, say, the
95
interfaces. If you want to skip a suite, press <code>cancel</code> and the process
96
continues with the next suite. </p>
102
<li>Run <code>gensuitemodule</code>.</li>
104
<li>Select the application (or OSAX) for which you would like a Python interface.</li>
106
<li>Select the package folder where the interface modules should be
109
<li>Specify the folder <code>Python:Mac:Lib:lib-scriptpackages:StdSuites</code>
110
to import the standard suites (or <code>_builtinSuites</code> if you are
111
generating <code>StdSuites</code> itself). </li>
113
<li>Save the generated suites (use <code>cancel</code> to skip a suite).</li>
124
<li>The interface package may occasionally need some editing by hand. For example,
125
<code>gensuitemodule</code> does not handle all Python reserved words, so
127
one of the AppleScript verbs is a Python reserved word, a <code>SyntaxError</code>
128
may be raised when the package is imported.
129
Simply rename the class into something acceptable, if this happens;
130
take a look at how the
131
<code>print</code> verb is handled (automatically by <code>gensuitemodule</code>)
132
in the standard suites. But: f you need to edit your package this should be considered a
133
bug in gensuitemodule, so please report it so it can be fixed in future releases.
137
<li>If you want to re-create the StdSuite modules,
138
you should look in one of two places. With versions of AppleScript older than 1.4.0
139
(which first shipped with OS 9.0), you will find the
140
AEUT resources in <code>System Folder:Extensions:Scripting
141
Additions:Dialects:English Dialect</code>. For newer versions, you will
142
find them in <code>System Folder:Extensions:Applescript</code>.
145
<li>Since MacPython 2.0, this new structure, with packages
146
per application and submodules per suite, is used. Older MacPythons had a
147
single level of modules, with uncertain semantics. With the new structure,
148
it is possible for programs to override standard suites, as programs often do.
152
<li><code>Gensuitemodule.py</code> may ask you questions
153
like “Where is enum 'xyz ' declared?”.
154
This is either due to a misunderstanding on my part or (rather too commonly)
155
bugs in the AETE resources. Pressing <code>cancel</code> is usually the
156
right choice: it will cause the specific enum not to be treated as an enum
157
but as a “normal” type. As things like fsspecs and TEXT strings clearly are
158
not enumerators, this is correct. If someone understands what is really going on
159
here, please let me know.</li>
165
<h2>The Python interface package contents</h2>
168
Let’s glance at the
169
<a href="applescript/Disk_Copy">Disk_Copy</a> package just created. You
170
may want to open Script Editor alongside to see how it
171
interprets the dictionary.
176
The main package module is in <code>__init__.py</code>.
177
The only interesting bit is the <code>Disk_Copy</code> class, which
178
includes the event handling classes from the individual suites. It also
179
inherits <code>aetools.TalkTo</code>, which is a base class that handles all
180
details on how to start the program and talk to it, and a class variable
181
<code>_signature</code> which is the default application this class will talk
182
to (you can override this in various ways when you instantiate your class, see
183
<code>aetools.py</code> for details).
187
The <a href="applescript/Disk_Copy/Special_Events.py">Special_Events</a>
188
module is a nice example of a suite module.
189
The <code>Special_Events_Events</code> class is the bulk of the code
190
generated. For each verb, it contains a method. Each method knows what
191
arguments the verb expects, and it makes use of keyword
192
arguments to present a palatable
193
interface to the python programmer.
195
Notice that each method
196
calls some routines from <code>aetools</code>, an auxiliary module
197
living in <code>Mac:Lib</code>.
198
The other thing to notice is that each method calls
199
<code>self.send</code>. This comes from the <code>aetools.TalkTo</code>
204
After the big class, there are a number of little class declarations. These
205
declarations are for the (AppleEvent) classes and properties in the suite.
206
They allow you to create object IDs, which can then be passed to the verbs.
208
when scripting the popular email program Eudora,
209
you would use <code>mailbox("inbox").message(1).sender</code>
210
to get the name of the sender of the first message in mailbox
212
also possible to specify this as <code>sender(message(1, mailbox("inbox")))</code>,
213
which is sometimes needed because these classes don’t always inherit correctly
214
from baseclasses, so you may have to use a class or property from another
218
Next we get the enumeration dictionaries, which allow you to pass
219
english names as arguments to verbs, so you don't have to bother with the 4-letter
220
type code. So, you can say
222
diskcopy.create(..., filesystem="Mac OS Standard")
224
as it is called in Script Editor, instead of the cryptic lowlevel
226
diskcopy.create(..., filesystem="Fhfs")
230
Finally, we get the “table of contents” of the module, listing all
232
by code, which is used by <code>gensuitemodule</code> itself: if you use this
233
suite as a base package in a later run this is how it knows what is defined in this
234
suite, and what the Python names are.
241
<li>The <code>aetools</code> module contains some other nifty
242
AppleEvent tools as well. Have a look at it sometime, there is (of
243
course) no documentation yet.
246
<li>There are also some older object specifiers for standard objects in aetools.
247
You use these in the form <code>aetools.Word(10,
248
aetools.Document(1))</code>, where the corresponding AppleScript
249
terminology would be <code>word 10 of the first
250
document</code>. Examine
251
<code>aetools</code> and <code>aetools.TalkTo</code>
253
the comments at the end of your suite module if you need to create
254
more than the standard object specifiers.
262
<h2>Using a Python suite module</h2>
265
Now that we have created the suite module, we can use it in a Python script.
266
In older MacPython distributions this used to be a rather
267
complicated affair, but with the package scheme and with the application signature
268
known by the package it is very simple: you import the package and instantiate
271
talker = Disk_Copy.Disk_Copy(start=1)
273
You will usually specify the <code>start=1</code>: it will run the application if it is
275
You may want to omit it if you want to talk to the application
276
only if it is already running, or if the application is something like the Finder.
277
Another way to ensure that the application is running is to call <code>talker._start()</code>.
281
Looking at the sourcefile <a
282
href="applescript/makedisk.py">makedisk.py</a>, we see that it starts
283
with some imports. Naturally, one of these is the Python interface to Disk
287
The main program itself is a wonder of simplicity: we create the
288
object (<code>talker</code>) that talks to Disk Copy,
289
create a disk, and mount it. The bulk of
290
the work is done by <code>talker</code> and the Python interface package we
294
The exception handling does warrant a few comments, though. Since
295
AppleScript is basically a connectionless RPC protocol,
297
when we create the <code>talker</code> object. Hence, if the destination application
298
is not running, we will not notice until we send our first
299
command (avoid this as described above). There is another thing to note about errors returned by
300
AppleScript calls: <code>MacOS.Error</code> is raised for
301
all of the errors that are known to be <code>OSErr</code>-type errors,
303
server generated errors raise <code>aetools.Error</code>. </p>
305
<h2>Scripting Additions</h2>
308
If you want to use any of the scripting additions (or OSAXen, in
309
everyday speech) from a Python program, you can use the same method
310
as for applications, i.e. run <code>gensuitemodule</code> on the
311
OSAX (commonly found in <code>System Folder:Scripting Additions</code>
312
or something similar). There is one minor gotcha: the application
313
signature to use is <code>MACS</code>. You will need to edit the main class
314
in the <code>__init__.py</code> file of the created package and change the value
315
of <code>_signature</code> to <code>MACS</code>, or use a subclass to the
320
There are two minor points to watch out for when using <code>gensuitemodule</code>
321
on OSAXen: they appear all to define the class <code>System_Object_Suite</code>,
322
and a lot of them have the command set in multiple dialects. You have to
323
watch out for name conflicts and make sure you select a reasonable dialect
324
(some of the non-English dialects cause <code>gensuitemodule</code> to generate incorrect
327
Despite these difficulties, OSAXen offer a lot of possibilities. Take a
328
look at some of the OSAXen in the Scripting Additions folder, or
329
<A HREF="http://www.osaxen.com/index.php">download</A> some from the net.
331
<h2>Further Reading</h2>
334
If you want to look at more involved examples of applescripting, look at the standard
335
modules <code>findertools</code> and <code>nsremote</code>, or (possibly better, as it
336
is more involved) <code>fullbuild</code> from the <code>Mac:scripts</code> folder.
339
<h2><a name="alternatives">Alternatives</a></h2>
341
<h3><a name="osx">Mac OS X</a></h3>
344
Under Mac OS X, the above still works, but with some new difficulties.
345
The application package structure can hide the ‘AETE’ or
346
‘AEUT’ resource from <code>gensuitemodule</code>, so that,
347
for example, it cannot generate an OSA interface to iTunes. Script
348
Editor gets at the dictionary of such programs using a ‘Get
349
AETE’ AppleEvent, if someone wants to donate code to use the same
350
method for gensuitemodule: by all means!
354
One alternative is available through the Unix command line version of python.
355
Apple has provided the <code>osacompile</code> and <code>osascript</code> tools,
356
which can be used to compile and execute scripts written in OSA languages. See the
357
man pages for more details.
added
removed
Mac/Demo/applescript.html
