Mac/Demo/applescript.html

   1 <HTML><HEAD><TITLE>Using Open Scripting Extension from Python</TITLE></HEAD>
   2 <BODY>
   3 <H1>Using Open Scripting Extension from Python</H1>
   4 <HR>
   5
   6 OSA support in Python is still far from complete, and what
   7 support there is is likely to change in the forseeable future. Still,
   8 there is already enough in place to allow you to do some nifty things
   9 to other programs from your python program.  <P>
  10
  11 <CITE>
  12 Actually, when we say "AppleScript" in this document we actually mean
  13 "the Open Scripting Architecture", there is nothing
  14 AppleScript-specific in the Python implementation. <p>
  15 </CITE>
  16
  17 In this example, we will look at a scriptable application, extract its
  18 "AppleScript Dictionary" and generate a Python interface module from
  19 that and use that module to control the application. Because we want
  20 to concentrate on the OSA details we don't bother with a real
  21 user-interface for our application. <p>
  22
  23 The application we are going to script is Eudora Light, a free mail
  24 program from <A HREF="http://www.qualcomm.com">QualComm</A>. This is a
  25 very versatile mail-reader, and QualComm has an accompanying
  26 commercial version once your needs outgrow Eudora Light. Our program
  27 will tell Eudora to send queued mail, retrieve mail or quit. <p>
  28
  29 <H2>Creating the Python interface module</H2>
  30
  31 There is a tool in the standard distribution that looks through a file
  32 for an 'AETE' or 'AEUT' resource, the internal representation of the
  33 AppleScript dictionary. This tool is called
  34 <CODE>gensuitemodule.py</CODE>, and lives in
  35 <CODE>Mac:scripts</CODE>. When we start it, it asks us for an input
  36 file and we point it to the Eudora Light executable. It starts parsing
  37 the AETE resource, and for each AppleEvent suite it finds it prompts
  38 us for the filename of the resulting python module. Remember to change
  39 folders for the first module, you don't want to clutter up the Eudora
  40 folder with your python interfaces. If you want to skip a suite you
  41 press cancel and the process continues with the next suite. In the
  42 case of Eudora, you do <EM>not</EM> want to generate the Required
  43 suite, because it will be empty. AppleScript understands that an empty
  44 suite means "incorporate the whole standard suite by this name",
  45 gensuitemodule does not currently understand this. Creating the empty
  46 <CODE>Required_Suite.py</CODE> would hide the correct module of that
  47 name from our application. <p>
  48
  49 <BLOCKQUOTE>
  50 Time for a sidebar. If you want to re-create
  51 <CODE>Required_Suite.py</CODE> or one of the other standard modules
  52 you should look in <CODE>System Folder:Extensions:Scripting
  53 Additions:Dialects:English Dialect</CODE>, that is where the core
  54 AppleEvent dictionaries live. Also, if you are looking for the
  55 <CODE>Finder_Suite</CODE> interface: don't look in the finder (it has
  56 an old System 7.0 scripting suite), look at the extension <CODE>Finder
  57 Scripting Extension</CODE>. <p>
  58 </BLOCKQUOTE>
  59
  60 Let's glance at the <A
  61 HREF="scripting/Eudora_Suite.py">Eudora_Suite.py</A> just created. You
  62 may want to open Script Editor alongside, and have a look at how it
  63 interprets the dictionary. EudoraSuite.py starts with some
  64 boilerplate, then come some dictionaries implementing the OSA
  65 Enumerations, then a big class definition with methods for each
  66 AppleScript Verb and finally some comments. The Enumerations we will
  67 skip, it suffices to know that whenever you have to pass an enumerator
  68 to a method you can pass the english name and don't have to bother
  69 with the 4-letter type code. So, you can say
  70 <CODE><PRE>
  71         eudora.notice(occurrence="mail_arrives")
  72 </PRE></CODE>
  73 instead of the rather more cryptic
  74 <CODE><PRE>
  75         eudora.notice(occurrence="wArv")
  76 </PRE></CODE>
  77
  78 The <CODE>Eudora_Suite</CODE> class is the bulk of the code
  79 generated. For each verb it contains a method. Each method knows what
  80 arguments the verb expects, and it makes handy use of the keyword
  81 argument scheme introduced in Python 1.3 to present a palatable
  82 interface to the python programmer. You will see that each method
  83 calls some routines from <CODE>aetools</CODE>, an auxiliary module
  84 living in <CODE>Lib:toolbox</CODE> which contains some other nifty
  85 AppleEvent tools as well. Have a look at it sometime, there is (of
  86 course) no documentation yet. <p>
  87
  88 The other thing you notice is that each method calls
  89 <CODE>self.send</CODE>, but no such method is defined. You will have
  90 to provide it by subclassing or multiple inheritance, as we shall see
  91 later. <p>
  92
  93 The module ends with some comments. Sadly, gensuitemodule is not yet
  94 able to turn the Object Specifiers into reasonable Python code. For
  95 now, if you need object specifiers, you will have to use the routines
  96 defined in <CODE>aetools.py</CODE> (and <CODE>aetypes.py</CODE>, which
  97 it incorporates). You use these in the form <CODE>aetools.Word(10,
  98 aetools.Document(1))</CODE> where the corresponding AppleScript
  99 terminology would be <CODE>word 10 of the first
 100 document</CODE>. Examine the two modules mentioned above along with
 101 the comments at the end of your suite module if you need to create
 102 more than the standard object specifiers. <p>
 103
 104 <H2>Using a Python suite module</H2>
 105
 106 Now that we have created the suite module we can use it in an
 107 application. We do this by creating a class that inherits
 108 <CODE>Eudora_Suite</CODE> and the <CODE>TalkTo</CODE> class from
 109 <CODE>aetools</CODE>. The <CODE>TalkTo</CODE> class is basically a
 110 container for the <CODE>send</CODE> method used by the methods from
 111 the suite classes. <p>
 112
 113 Actually, our class will also inherit <CODE>Required_Suite</CODE>,
 114 because we also need functionality from that suite: the quit
 115 command. Gensuitemodule could have created this completely derived
 116 class for us, since it has access to all information needed to build
 117 the class but unfortunately it does not do so at the moment. All in
 118 all, the heart of our program looks like this:
 119 <CODE><PRE>
 120         import Eudora_Suite, Required_Suite, aetools
 121
 122         class Eudora(aetools.TalkTo, Required_Suite.Required_Suite, \
 123                                 Eudora_Suite.Eudora_Suite):
 124                 pass
 125 </PRE></CODE>
 126
 127 Yes, our class body is <CODE>pass</CODE>, all functionality is already
 128 provided by the base classes, the only thing we have to do is glue it
 129 together in the right way. <p>
 130
 131 Looking at the sourcefile <A
 132 HREF="scripting/testeudora.py">testeudora.py</A> we see that it starts
 133 with some imports. Then we get the class definition
 134 for our main object and a constant giving the signature of Eudora. <p>
 135
 136 This, again, needs a little explanation. There are various ways to
 137 describe to AppleScript which program we want to talk to, but the
 138 easiest one to use (from Python, at least) is creator
 139 signature. Application name would be much nicer, but Python currently
 140 does not have a module that interfaces to the Finder database (which
 141 would allow us to map names to signatures). The other alternative,
 142 <CODE>ChooseApplication</CODE> from the program-to-program toolbox, is
 143 also not available from Python at the moment. <p>
 144
 145 The main program itself is a wonder of simplicity. We create the
 146 object that talks to Eudora (passing the signature as argument), ask
 147 the user what she wants and call the appropriate method of the talker
 148 object. The use of keyword arguments with the same names as used by
 149 AppleScript make passing the parameters a breeze. <p>
 150
 151 The exception handling does need a few comments, though. Since
 152 AppleScript is basically a connectionless RPC protocol nothing happens
 153 when we create to talker object. Hence, if the destination application
 154 is not running we will not notice until we send our first
 155 command. There is another thing to note about errors returned by
 156 AppleScript calls: even though <CODE>MacOS.Error</CODE> is raised not
 157 all of the errors are actually <CODE>OSErr</CODE>-type errors, some
 158 are error codes returned by the server application. In that case, the
 159 error message will be incorrect. <p>
 160
 161 That concludes our simple example. Again, let me emphasize that
 162 scripting support in Python is not very complete at the moment, and
 163 the details of how to use AppleEvents will definitely change in the
 164 near future. This will not only fix all the ideosyncracies noted in
 165 this document but also break existing programs, since the current
 166 suite organization will have to change to fix some of the problems.
 167 Still, if you want to experiment with AppleEvents right now: go ahead!
 168 <p>