[Pythonmac-SIG] rewritten documentation for OSA

[Jacob Kaplan-Moss]

Michael --

First off, great job.  I actually tried my hand at something like 
this a while ago, and it really is hard.  This document makes a lot 
of sense out of some tricky stuff.

I've read your comments, and I have some answers to the questions you raised:

>If you want to re-create the StdSuite modules,
>you should look in one of two places. On older systems you will find the
><!-- How old is that?  It is so in 8.6, did the change come with 9?  -->

AFAIK, the "English Dialect" file was removed with AppleScript 1.3.4, 
which shipped with MacOS 8.5, so I belive that generating StdSuites 
should be done from the AppleScript extension itself in all post-8.5 
systems.  I've you've upgraded 8.5 from 8.0, the Dialect file may 
still be floating around, but it is out of date.

>Examine <code>aetools</code> and <code>aetools.TalkTo</code>
><!--the two modules mentioned above -->
><!--Are these the right two modules?-->

Yup.  aetools has most of the code for OSA communication, and the 
aetools.TalkTo class parent class for all application classes 
generated by gensuitemodule.

>The exception handling does warrant a few comments, though. Since
>AppleScript is basically a connectionless RPC protocol, <!--I don't 
>know what that means, so somebody else should read this paragraph 
>carefully-->
>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. 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>

This paragraph sounds right to me, although you should probably note 
that the best way to ensure that the application you want to talk to 
is running is to create the class with "start=1" or to call 
talker.start() right off the bat, ie:

# Either do this:
talker = Eudora.Eudora(start=1)		# or whatever app you are using

# Or do this:
talker = Eudora.Eudora()
talker.start()

>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>.
><!-- And what do we recommend to do about that gotcha?  Edit the 
>automatically generated module or override by subclassing? -->

The best way to do it is to edit the main class in the __init__.py 
file from the created package and change _signature to "MACS":

# For some hypothetical OSAX "MyCoolOSAX", in
# lib-scriptpackages/MyCoolOSAX/__init__.py:

class MyCoolOSAX(MyCoolOSAX_Events):
	_signature = 'MACS'


Hope all that makes sense to you; let me know if you have any questions.

Jacob Kaplan-Moss