| <!doctype HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> |
| <html><head><title>Using the Open Scripting Architecture from Python</title></head> |
| <body> |
| <h1>Using the Open Scripting Architecture from Python</h1> |
| <hr> |
| |
| <p><b>NOTE:</b> this document describes the OSA support that is shipped with |
| the core python distribution. Most users are better of with the more |
| userfriendly <a href="http://freespace.virgin.net/hamish.sanderson/appscript.html">appscript library</a>. |
| |
| <p>OSA support in Python is still not 100% complete, but |
| there is already enough in place to allow you to do some nifty things |
| with other programs from your python program. </p> |
| |
| |
| <p> |
| In this example, we will look at a scriptable application, extract its |
| “AppleScript Dictionary,” generate a Python interface package from |
| the dictionary, and use that package to control the application. |
| The application we are going to script is Disk Copy, Apple's standard |
| utility for making copies of floppies, creating files that are mountable |
| as disk images, etc. |
| Because we want |
| to concentrate on the OSA details, we won’t bother with a real |
| user-interface for our application. </p> |
| |
| |
| <p> |
| <em>When we say “AppleScript” in this document we actually mean |
| “the Open Scripting Architecture.” There is nothing |
| AppleScript-specific in the Python implementation. Most of this document |
| focuses on the classic Mac OS; <a href="#osx">Mac OS X</a> users have some |
| additional tools.</em> |
| </p> |
| |
| <h2>Python OSA architecture</h2> |
| |
| <p>Open Scripting suites and inheritance can be modelled rather nicely |
| with Python packages, so we generate |
| a package for each application we want to script. Each suite defined in |
| the application becomes a module in the |
| package, and the package main module imports everything from all the |
| submodules and glues together all the classes (in Python terminology— |
| events in OSA terminology or verbs in AppleScript terminology). </p> |
| |
| <p> |
| A suite in an OSA application can extend the functionality of a standard |
| suite. This is implemented in Python by importing everything from the |
| module that implements the standard suites and overriding anything that has |
| been extended. The standard suites live in the StdSuite package. </p> |
| |
| <p> |
| This all sounds complicated, but the good news is that basic |
| scripting is actually pretty simple. You can do strange and wondrous things |
| with OSA scripting once you fully understand it. </p> |
| |
| <h2>Creating the Python interface package</h2> |
| |
| |
| <p>There is a tool in the standard distribution that can automatically |
| generate the interface packages. This tool is called |
| <code>gensuitemodule.py</code>, and lives in <code>Mac:scripts</code>. |
| It looks through a file |
| for an ‘AETE’ or ‘AEUT’ resource, |
| the internal representation of the |
| AppleScript dictionary, and parses the resource to generate the suite |
| modules. |
| When we start <code>gensuitemodule</code>, it asks us for an input file; |
| for our example, |
| we point it to the Disk Copy executable. </p> |
| |
| <p> |
| Next, <code>gensuitemodule</code> wants a folder where it will store the |
| package it is going to generate. |
| Note that this is the package folder, not the parent folder, so we |
| navigate to <code>Python:Mac:Demo:applescript</code>, create a folder |
| <code>Disk_Copy</code>, and select that. </p> |
| |
| <p> |
| We next specify the folder from which <code>gensuitemodule</code> |
| should import the standard suites. Here, |
| we always select <code>Python:Mac:Lib:lib-scriptpackages:StdSuites</code>. (There is |
| one exception to this rule: when you are generating <code>StdSuites</code> itself |
| you select <code>_builtinSuites</code>.) |
| </p> |
| |
| <p> |
| It starts parsing the AETE resource, and for |
| each AppleEvent suite it finds, <code>gensuitemodule.py</code> |
| 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, say, the |
| Disk Copy folder |
| with your python |
| interfaces. If you want to skip a suite, press <code>cancel</code> and the process |
| continues with the next suite. </p> |
| |
| <h3>Summary</h3> |
| |
| <ol> |
| |
| <li>Run <code>gensuitemodule</code>.</li> |
| |
| <li>Select the application (or OSAX) for which you would like a Python interface.</li> |
| |
| <li>Select the package folder where the interface modules should be |
| stored.</li> |
| |
| <li>Specify the folder <code>Python:Mac:Lib:lib-scriptpackages:StdSuites</code> |
| to import the standard suites (or <code>_builtinSuites</code> if you are |
| generating <code>StdSuites</code> itself). </li> |
| |
| <li>Save the generated suites (use <code>cancel</code> to skip a suite).</li> |
| |
| |
| </ol> |
| |
| |
| <h3>Notes</h3> |
| |
| |
| <ul> |
| |
| <li>The interface package may occasionally need some editing by hand. For example, |
| <code>gensuitemodule</code> does not handle all Python reserved words, so |
| if |
| one of the AppleScript verbs is a Python reserved word, a <code>SyntaxError</code> |
| may be raised when the package is imported. |
| Simply rename the class into something acceptable, if this happens; |
| take a look at how the |
| <code>print</code> verb is handled (automatically by <code>gensuitemodule</code>) |
| in the standard suites. But: f you need to edit your package this should be considered a |
| bug in gensuitemodule, so please report it so it can be fixed in future releases. |
| </li> |
| |
| |
| <li>If you want to re-create the StdSuite modules, |
| you should look in one of two places. With versions of AppleScript older than 1.4.0 |
| (which first shipped with OS 9.0), you will find the |
| AEUT resources in <code>System Folder:Extensions:Scripting |
| Additions:Dialects:English Dialect</code>. For newer versions, you will |
| find them in <code>System Folder:Extensions:Applescript</code>. |
| </li> |
| |
| <li>Since MacPython 2.0, this new structure, with packages |
| per application and submodules per suite, is used. Older MacPythons had a |
| single level of modules, with uncertain semantics. With the new structure, |
| it is possible for programs to override standard suites, as programs often do. |
| |
| </li> |
| |
| <li><code>Gensuitemodule.py</code> may ask you questions |
| like “Where is enum 'xyz ' declared?”. |
| This is either due to a misunderstanding on my part or (rather too commonly) |
| bugs in the AETE resources. Pressing <code>cancel</code> is usually the |
| right choice: it will cause the specific enum not to be treated as an enum |
| but as a “normal” type. As things like fsspecs and TEXT strings clearly are |
| not enumerators, this is correct. If someone understands what is really going on |
| here, please let me know.</li> |
| |
| </ul> |
| |
| |
| |
| <h2>The Python interface package contents</h2> |
| |
| <p> |
| Let’s glance at the |
| <a href="applescript/Disk_Copy">Disk_Copy</a> package just created. You |
| may want to open Script Editor alongside to see how it |
| interprets the dictionary. |
| </p> |
| |
| |
| <p> |
| The main package module is in <code>__init__.py</code>. |
| The only interesting bit is the <code>Disk_Copy</code> class, which |
| includes the event handling classes from the individual suites. It also |
| inherits <code>aetools.TalkTo</code>, which is a base class that handles all |
| details on how to start the program and talk to it, and a class variable |
| <code>_signature</code> which is the default application this class will talk |
| to (you can override this in various ways when you instantiate your class, see |
| <code>aetools.py</code> for details). |
| </p> |
| |
| <p> |
| The <a href="applescript/Disk_Copy/Special_Events.py">Special_Events</a> |
| module is a nice example of a suite module. |
| The <code>Special_Events_Events</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 use of keyword |
| arguments to present a palatable |
| interface to the python programmer. |
| |
| Notice that each method |
| calls some routines from <code>aetools</code>, an auxiliary module |
| living in <code>Mac:Lib</code>. |
| The other thing to notice is that each method calls |
| <code>self.send</code>. This comes from the <code>aetools.TalkTo</code> |
| baseclass. </p> |
| |
| |
| <p> |
| After the big class, there are 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, |
| when scripting the popular email program Eudora, |
| you would use <code>mailbox("inbox").message(1).sender</code> |
| to get the name of the sender of the first message in mailbox |
| inbox. It is |
| also possible to specify this as <code>sender(message(1, mailbox("inbox")))</code>, |
| which is sometimes needed because these classes don’t always inherit correctly |
| from baseclasses, so you may have to use a class or property from another |
| suite. </p> |
| |
| <p> |
| 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 |
| <code> |
| diskcopy.create(..., filesystem="Mac OS Standard") |
| </code> |
| as it is called in Script Editor, instead of the cryptic lowlevel |
| <code> |
| diskcopy.create(..., filesystem="Fhfs") |
| </code></p> |
| |
| <p> |
| Finally, we get the “table of contents” of the module, listing all |
| classes and such |
| by code, which is used by <code>gensuitemodule</code> itself: if you use this |
| suite as a base package in a later run this is how it knows what is defined in this |
| suite, and what the Python names are. |
| </p> |
| |
| <h3>Notes</h3> |
| |
| <ul> |
| |
| <li>The <code>aetools</code> module contains some other nifty |
| AppleEvent tools as well. Have a look at it sometime, there is (of |
| course) no documentation yet. |
| </li> |
| |
| <li>There are also some older object specifiers for standard objects in aetools. |
| 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 |
| <code>aetools</code> and <code>aetools.TalkTo</code> |
| along with |
| the comments at the end of your suite module if you need to create |
| more than the standard object specifiers. |
| </li> |
| |
| </ul> |
| |
| |
| |
| |
| <h2>Using a Python suite module</h2> |
| |
| <p> |
| Now that we have created the suite module, we can use it in a Python script. |
| In older MacPython distributions this used to be a rather |
| complicated affair, but with the package scheme and with the application signature |
| known by the package it is very simple: you import the package and instantiate |
| the class, e.g. |
| <code> |
| talker = Disk_Copy.Disk_Copy(start=1) |
| </code> |
| You will usually specify the <code>start=1</code>: it will run the application if it is |
| not already running. |
| You may want to omit it if you want to talk to the application |
| only if it is already running, or if the application is something like the Finder. |
| Another way to ensure that the application is running is to call <code>talker._start()</code>. |
| </p> |
| |
| <p> |
| Looking at the sourcefile <a |
| href="applescript/makedisk.py">makedisk.py</a>, we see that it starts |
| with some imports. Naturally, one of these is the Python interface to Disk |
| Copy.</p> |
| |
| <p> |
| The main program itself is a wonder of simplicity: we create the |
| object (<code>talker</code>) that talks to Disk Copy, |
| create a disk, and mount it. The bulk of |
| the work is done by <code>talker</code> and the Python interface package we |
| just created.</p> |
| |
| <p> |
| The exception handling does warrant a few comments, though. Since |
| AppleScript is basically a connectionless RPC protocol, |
| nothing happens |
| when we create the <code>talker</code> object. Hence, if the destination application |
| is not running, we will not notice until we send our first |
| command (avoid this as described above). 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, |
| while |
| server generated errors raise <code>aetools.Error</code>. </p> |
| |
| <h2>Scripting Additions</h2> |
| |
| <p> |
| 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:Scripting Additions</code> |
| or something similar). There is one minor gotcha: the application |
| signature to use is <code>MACS</code>. You will need to edit the main class |
| in the <code>__init__.py</code> file of the created package and change the value |
| of <code>_signature</code> to <code>MACS</code>, or use a subclass to the |
| same effect. |
| </p> |
| |
| <p> |
| There are two minor points to watch out for when using <code>gensuitemodule</code> |
| 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 and make sure you select a reasonable dialect |
| (some of the non-English dialects cause <code>gensuitemodule</code> to generate incorrect |
| Python code). </p> |
| |
| Despite these difficulties, OSAXen offer a lot of possibilities. Take a |
| look at some of the OSAXen in the Scripting Additions folder, or |
| <A HREF="http://www.osaxen.com/index.php">download</A> some from the net. |
| |
| <h2>Further Reading</h2> |
| |
| <p> |
| If you want to look at more involved examples of applescripting, look at the standard |
| modules <code>findertools</code> and <code>nsremote</code>, or (possibly better, as it |
| is more involved) <code>fullbuild</code> from the <code>Mac:scripts</code> folder. |
| </p> |
| |
| <h2><a name="alternatives">Alternatives</a></h2> |
| |
| <h3><a name="osx">Mac OS X</a></h3> |
| |
| <p> |
| Under Mac OS X, the above still works, but with some new difficulties. |
| The application package structure can hide the ‘AETE’ or |
| ‘AEUT’ resource from <code>gensuitemodule</code>, so that, |
| for example, it cannot generate an OSA interface to iTunes. Script |
| Editor gets at the dictionary of such programs using a ‘Get |
| AETE’ AppleEvent, if someone wants to donate code to use the same |
| method for gensuitemodule: by all means! |
| </p> |
| |
| <p> |
| One alternative is available through the Unix command line version of python. |
| Apple has provided the <code>osacompile</code> and <code>osascript</code> tools, |
| which can be used to compile and execute scripts written in OSA languages. See the |
| man pages for more details. |
| </p> |
| |
| |
| </body> |
| </html> |
