1 <!doctype HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> 2 <html><head><title>Using the Open Scripting Architecture from Python</title></head> 3 <body> 4 <h1>Using the Open Scripting Architecture from Python</h1> 5 <hr> 6 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>. 10 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> 14 15 16 <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 22 as disk images, etc. 23 Because we want 24 to concentrate on the OSA details, we won’t bother with a real 25 user-interface for our application. </p> 26 27 28 <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> 34 </p> 35 36 <h2>Python OSA architecture</h2> 37 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> 45 46 <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> 51 52 <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> 56 57 <h2>Creating the Python interface package</h2> 58 59 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 67 modules. 68 When we start <code>gensuitemodule</code>, it asks us for an input file; 69 for our example, 70 we point it to the Disk Copy executable. </p> 71 72 <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> 78 79 <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>.) 85 </p> 86 87 <p> 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 93 Disk Copy folder 94 with your python 95 interfaces. If you want to skip a suite, press <code>cancel</code> and the process 96 continues with the next suite. </p> 97 98 <h3>Summary</h3> 99 100 <ol> 101 102 <li>Run <code>gensuitemodule</code>.</li> 103 104 <li>Select the application (or OSAX) for which you would like a Python interface.</li> 105 106 <li>Select the package folder where the interface modules should be 107 stored.</li> 108 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> 112 113 <li>Save the generated suites (use <code>cancel</code> to skip a suite).</li> 114 115 116 </ol> 117 118 119 <h3>Notes</h3> 120 121 122 <ul> 123 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 126 if 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. 134 </li> 135 136 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>. 143 </li> 144 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. 149 150 </li> 151 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> 160 161 </ul> 162 163 164 165 <h2>The Python interface package contents</h2> 166 167 <p> 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. 172 </p> 173 174 175 <p> 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). 184 </p> 185 186 <p> 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. 194 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> 200 baseclass. </p> 201 202 203 <p> 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. 207 For instance, 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 211 inbox. It is 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 215 suite. </p> 216 217 <p> 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 221 <code> 222 diskcopy.create(..., filesystem="Mac OS Standard") 223 </code> 224 as it is called in Script Editor, instead of the cryptic lowlevel 225 <code> 226 diskcopy.create(..., filesystem="Fhfs") 227 </code></p> 228 229 <p> 230 Finally, we get the “table of contents” of the module, listing all 231 classes and such 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. 235 </p> 236 237 <h3>Notes</h3> 238 239 <ul> 240 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. 244 </li> 245 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> 252 along with 253 the comments at the end of your suite module if you need to create 254 more than the standard object specifiers. 255 </li> 256 257 </ul> 258 259 260 261 262 <h2>Using a Python suite module</h2> 263 264 <p> 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 269 the class, e.g. 270 <code> 271 talker = Disk_Copy.Disk_Copy(start=1) 272 </code> 273 You will usually specify the <code>start=1</code>: it will run the application if it is 274 not already running. 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>. 278 </p> 279 280 <p> 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 284 Copy.</p> 285 286 <p> 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 291 just created.</p> 292 293 <p> 294 The exception handling does warrant a few comments, though. Since 295 AppleScript is basically a connectionless RPC protocol, 296 nothing happens 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, 302 while 303 server generated errors raise <code>aetools.Error</code>. </p> 304 305 <h2>Scripting Additions</h2> 306 307 <p> 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 316 same effect. 317 </p> 318 319 <p> 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 325 Python code). </p> 326 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. 330 331 <h2>Further Reading</h2> 332 333 <p> 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. 337 </p> 338 339 <h2><a name="alternatives">Alternatives</a></h2> 340 341 <h3><a name="osx">Mac OS X</a></h3> 342 343 <p> 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! 351 </p> 352 353 <p> 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. 358 </p> 359 360 361 </body> 362 </html> 363
