Using Open Scripting Extension from Python

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.

Actually, when we say "AppleScript" in this document we actually mean "the Open Scripting Architecture", there is nothing AppleScript-specific in the Python implementation.

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.

The application we are going to script is Eudora Light, a free mail program from QualComm. 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.

Creating the Python interface module

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 gensuitemodule.py, and lives in Mac:scripts. 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 not want to generate the Required and Standard suites, because they are identical to the standard ones which are pregenerated (and empty in the eudora binary). AppleScript understands that an empty suite means "incorporate the whole standard suite by this name", gensuitemodule does not currently understand this. Creating the empty Required_Suite.py would hide the correct module of that name from our application.

Gensuitemodule may ask you questions like "Where is enum 'xyz ' declared?". For the first time, cancel out of this dialog after taking down the enum (or class or prop) name. After you've created all the suites look for these codes, in the suites generated here and in the standard suites. If you've found them all run gensuitemodule again and point it to the right file for each declaration. Gensuitemodule will generate the imports to make the reference work.

Time for a sidebar. If you want to re-create Required_Suite.py or one of the other standard modules you should look in System Folder:Extensions:Scripting Additions:Dialects:English Dialect, that is where the core AppleEvent dictionaries live. Also, if you are looking for the Finder_Suite interface: don't look in the finder (it has an old System 7.0 scripting suite), look at the extension Finder Scripting Extension.

Let's glance at the Eudora_Suite.py 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 a big class definition with methods for each AppleScript Verb, then some small class definitions and then some dictionary initializations.

The Eudora_Suite 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 aetools, an auxiliary module living in Lib:toolbox which contains some other nifty AppleEvent tools as well. Have a look at it sometime, there is (of course) no documentation yet.

The other thing you notice is that each method calls self.send, but no such method is defined. You will have to provide it by subclassing or multiple inheritance, as we shall see later.

After the big class we get a number of little class declarations. These declarations are for the (appleevent) classes and properties in the suite. They allow you to create object IDs, which can then be passed to the verbs. For instance, to get the name of the sender of the first message in mailbox inbox you would use mailbox("inbox").message(1).sender. It is also possible to specify this as sender(message(1, mailbox("inbox"))), which is sometimes needed because these classes don't inherit correctly from baseclasses, so you may have to use a class or property from another suite.

There are also some older object specifiers for standard objects in aetools. You use these in the form aetools.Word(10, aetools.Document(1)) where the corresponding AppleScript terminology would be word 10 of the first document. 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.
Next we get the enumeration dictionaries, which allow you to pass english names as arguments to verbs, so you don't have to bother with the 4-letter type code. So, you can say 
	eudora.notice(occurrence="mail_arrives")
instead of the rather more cryptic 
	eudora.notice(occurrence="wArv")

Finally, we get the "table of contents" of the module, listing all classes and such by code, which is used by gensuitemodule.

Using a Python suite module

Now that we have created the suite module we can use it in an application. We do this by creating a class that inherits Eudora_Suite and the TalkTo class from aetools. The TalkTo class is basically a container for the send method used by the methods from the suite classes.

Actually, our class will also inherit Required_Suite, 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: 

	import Eudora_Suite, Required_Suite, aetools
	
	class Eudora(Eudora_Suite.Eudora_Suite, Required_Suite.Required_Suite, \
				aetools.TalkTo):
		pass
Yes, our class body is pass, all functionality is already provided by the base classes, the only thing we have to do is glue it together in the right way.

Looking at the sourcefile testeudora.py 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.

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, ChooseApplication from the program-to-program toolbox, is also not available from Python at the moment.

If you specify the application by creator you can specify an optional start parameter, which will cause the application to be started if it is not running.

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.

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: MacOS.Error is raised for all of the errors that are known to be OSErr-type errors, server generated errors raise aetools.Error.

Scripting Additions

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 gensuitemodule on the OSAX (commonly found in System Folder:Extensions:Scripting Additions or something similar), define a class which inherits the generated class and aetools.TalkTo and instantiate it. The application signature to use is 'MACS'.

There are two minor points to watch out for when using gensuitemodule on OSAXen: they appear all to define the class System_Object_Suite, 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).

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!