diff options
Diffstat (limited to 'Mac/Demo/applescript.html')
| -rw-r--r-- | Mac/Demo/applescript.html | 362 |
1 files changed, 0 insertions, 362 deletions
diff --git a/Mac/Demo/applescript.html b/Mac/Demo/applescript.html deleted file mode 100644 index 5e4fac7..0000000 --- a/Mac/Demo/applescript.html +++ /dev/null @@ -1,362 +0,0 @@ -<!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> |