[OpenSPARC-T2-SAM] / sam-t2 / devtools / v9 / html / python / mac / scripting.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="mac.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="mac.html" title='Macintosh Library Modules' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="toolbox.html" />
<link rel="prev" href="macpython-modules.html" />
<link rel="parent" href="mac.html" />
<link rel="next" href="module-gensuitemodule.html" />
<meta name='aesop' content='information' />
<title>3. MacPython OSA Modules </title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="2.9 autoGIL  "
  href="module-autoGIL.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="Macintosh Library Modules"
  href="mac.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="3.1 gensuitemodule  "
  href="module-gensuitemodule.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Macintosh Library Modules</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-autoGIL.html">2.9 autoGIL  </A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="mac.html">Macintosh Library Modules</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="module-gensuitemodule.html">3.1 gensuitemodule  </A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION005000000000000000000"></A><A NAME="scripting"></A>
<BR>
3. MacPython OSA Modules 
</H1>

<P>
This chapter describes the current implementation of the Open Scripting
Architecure (OSA, also commonly referred to as AppleScript) for Python, allowing
you to control scriptable applications from your Python program,
and with a fairly pythonic interface. Development on this set of modules
has stopped, and a replacement is expected for Python 2.5.

<P>
For a description of the various components of AppleScript and OSA, and
to get an understanding of the architecture and terminology, you should
read Apple's documentation. The "Applescript Language Guide" explains
the conceptual model and the terminology, and documents the standard
suite. The "Open Scripting Architecture" document explains how to use
OSA from an application programmers point of view. In the Apple Help
Viewer these book sare located in the Developer Documentation, Core
Technologies section.

<P>
As an example of scripting an application, the following piece of
AppleScript will get the name of the frontmost <b class="program">Finder</b> window
and print it:

<P>
<div class="verbatim"><pre>
tell application "Finder"
    get name of window 1
end tell
</pre></div>

<P>
In Python, the following code fragment will do the same:

<P>
<div class="verbatim"><pre>
import Finder

f = Finder.Finder()
print f.get(f.window(1).name)
</pre></div>

<P>
As distributed the Python library includes packages that implement the
standard suites, plus packages that interface to a small number of
common applications.

<P>
To send AppleEvents to an application you must first create the Python
package interfacing to the terminology of the application (what
<b class="program">Script Editor</b> calls the "Dictionary"). This can be done from
within the <b class="program">PythonIDE</b> or by running the
<span class="file">gensuitemodule.py</span> module as a standalone program from the command
line.

<P>
The generated output is a package with a number of modules, one for
every suite used in the program plus an <tt class="module">__init__</tt> module to glue
it all together. The Python inheritance graph follows the AppleScript
inheritance graph, so if a programs dictionary specifies that it
includes support for the Standard Suite, but extends one or two verbs
with extra arguments then the output suite will contain a module
<tt class="module">Standard_Suite</tt> that imports and re-exports everything from
<tt class="module">StdSuites.Standard_Suite</tt> but overrides the methods that have
extra functionality. The output of <tt class="module">gensuitemodule</tt> is pretty
readable, and contains the documentation that was in the original
AppleScript dictionary in Python docstrings, so reading it is a good
source of documentation.

<P>
The output package implements a main class with the same name as the
package which contains all the AppleScript verbs as methods, with the
direct object as the first argument and all optional parameters as
keyword arguments. AppleScript classes are also implemented as Python
classes, as are comparisons and all the other thingies.

<P>
The main
Python class implementing the verbs also allows access to the properties
and elements declared in the AppleScript class "application". In the
current release that is as far as the object orientation goes, so
in the example above we need to use
<code>f.get(f.window(1).name)</code> instead of the more Pythonic
<code>f.window(1).name.get()</code>.

<P>
If an AppleScript identifier is not a Python identifier the name is
mangled according to a small number of rules:

<UL>
<LI>spaces are replaced with underscores
</LI>
<LI>other non-alphanumeric characters are replaced with
    <code>_xx_</code> where <code>xx</code> is the hexadecimal character value
</LI>
<LI>any Python reserved word gets an underscore appended
</LI>
</UL>

<P>
Python also has support for creating scriptable applications
in Python, but
The following modules are relevant to MacPython AppleScript support:

<P>
<table class='synopsistable' valign='baseline'>
  <tr class='oddrow'>
      <td><b><tt class='module'><a href='module-gensuitemodule.html'>gensuitemodule</a></tt></b></td>
      <td>&nbsp;</td>
      <td class='synopsis'>Create a stub package from an OSA dictionary</td></tr>
  <tr><td><b><tt class='module'><a href='module-aetools.html'>aetools</a></tt></b></td>
      <td>&nbsp;</td>
      <td class='synopsis'>Basic support for sending Apple Events</td></tr>
  <tr class='oddrow'>
      <td><b><tt class='module'><a href='module-aepack.html'>aepack</a></tt></b></td>
      <td>&nbsp;</td>
      <td class='synopsis'>Conversion between Python variables and AppleEvent
                data containers.</td></tr>
  <tr><td><b><tt class='module'><a href='module-aetypes.html'>aetypes</a></tt></b></td>
      <td>&nbsp;</td>
      <td class='synopsis'>Python representation of the Apple Event Object Model.</td></tr>
  <tr class='oddrow'>
      <td><b><tt class='module'><a href='module-MiniAEFrame.html'>MiniAEFrame</a></tt></b></td>
      <td>&nbsp;</td>
      <td class='synopsis'>Support to act as an Open Scripting Architecture (OSA) server
(``Apple Events'').</td></tr>
</table>

<BR>
<P>
In addition, support modules have been pre-generated for
<tt class="module">Finder</tt>, <tt class="module">Terminal</tt>, <tt class="module">Explorer</tt>,
<tt class="module">Netscape</tt>, <tt class="module">CodeWarrior</tt>, <tt class="module">SystemEvents</tt> and
<tt class="module">StdSuites</tt>.

<P>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="2.9 autoGIL  "
  href="module-autoGIL.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="Macintosh Library Modules"
  href="mac.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="3.1 gensuitemodule  "
  href="module-gensuitemodule.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Macintosh Library Modules</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-autoGIL.html">2.9 autoGIL  </A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="mac.html">Macintosh Library Modules</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="module-gensuitemodule.html">3.1 gensuitemodule  </A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>
Commit	Line	Data
920dae64 AT	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	2	<html>
	3	<head>
	4	<link rel="STYLESHEET" href="mac.css" type='text/css' />
	5	<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
	6	<link rel='start' href='../index.html' title='Python Documentation Index' />
	7	<link rel="first" href="mac.html" title='Macintosh Library Modules' />
	8	<link rel='contents' href='contents.html' title="Contents" />
	9	<link rel='index' href='genindex.html' title='Index' />
	10	<link rel='last' href='about.html' title='About this document...' />
	11	<link rel='help' href='about.html' title='About this document...' />
	12	<link rel="next" href="toolbox.html" />
	13	<link rel="prev" href="macpython-modules.html" />
	14	<link rel="parent" href="mac.html" />
	15	<link rel="next" href="module-gensuitemodule.html" />
	16	<meta name='aesop' content='information' />
	17	<title>3. MacPython OSA Modules </title>
	18	</head>
	19	<body>
	20	<DIV CLASS="navigation">
	21	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	22	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	23	<tr>
	24	<td class='online-navigation'><a rel="prev" title="2.9 autoGIL "
	25	href="module-autoGIL.html"><img src='../icons/previous.png'
	26	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	27	<td class='online-navigation'><a rel="parent" title="Macintosh Library Modules"
	28	href="mac.html"><img src='../icons/up.png'
	29	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	30	<td class='online-navigation'><a rel="next" title="3.1 gensuitemodule "
	31	href="module-gensuitemodule.html"><img src='../icons/next.png'
	32	border='0' height='32' alt='Next Page' width='32' /></A></td>
	33	<td align="center" width="100%">Macintosh Library Modules</td>
	34	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	35	href="contents.html"><img src='../icons/contents.png'
	36	border='0' height='32' alt='Contents' width='32' /></A></td>
	37	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
	38	border='0' height='32' alt='Module Index' width='32' /></a></td>
	39	<td class='online-navigation'><a rel="index" title="Index"
	40	href="genindex.html"><img src='../icons/index.png'
	41	border='0' height='32' alt='Index' width='32' /></A></td>
	42	</tr></table>
	43	<div class='online-navigation'>
	44	<b class="navlabel">Previous:</b>
	45	<a class="sectref" rel="prev" href="module-autoGIL.html">2.9 autoGIL </A>
	46	<b class="navlabel">Up:</b>
	47	<a class="sectref" rel="parent" href="mac.html">Macintosh Library Modules</A>
	48	<b class="navlabel">Next:</b>
	49	<a class="sectref" rel="next" href="module-gensuitemodule.html">3.1 gensuitemodule </A>
	50	</div>
	51	<hr /></div>
	52	</DIV>
	53	<!--End of Navigation Panel-->
	54
	55	<H1><A NAME="SECTION005000000000000000000"></A><A NAME="scripting"></A>
	56	<BR>
	57	3. MacPython OSA Modules
	58	</H1>
	59
	60	<P>
	61	This chapter describes the current implementation of the Open Scripting
	62	Architecure (OSA, also commonly referred to as AppleScript) for Python, allowing
	63	you to control scriptable applications from your Python program,
	64	and with a fairly pythonic interface. Development on this set of modules
65	has stopped, and a replacement is expected for Python 2.5.
66
67	<P>
68	For a description of the various components of AppleScript and OSA, and
69	to get an understanding of the architecture and terminology, you should
70	read Apple's documentation. The "Applescript Language Guide" explains
71	the conceptual model and the terminology, and documents the standard
72	suite. The "Open Scripting Architecture" document explains how to use
73	OSA from an application programmers point of view. In the Apple Help
74	Viewer these book sare located in the Developer Documentation, Core
75	Technologies section.
76
77	<P>
78	As an example of scripting an application, the following piece of
79	AppleScript will get the name of the frontmost <b class="program">Finder</b> window
80	and print it:
81
82	<P>
83	<div class="verbatim"><pre>
84	tell application "Finder"
85	get name of window 1
86	end tell
87	</pre></div>
88
89	<P>
90	In Python, the following code fragment will do the same:
91
92	<P>
93	<div class="verbatim"><pre>
94	import Finder
95
96	f = Finder.Finder()
97	print f.get(f.window(1).name)
98	</pre></div>
99
100	<P>
101	As distributed the Python library includes packages that implement the
102	standard suites, plus packages that interface to a small number of
103	common applications.
104
105	<P>
106	To send AppleEvents to an application you must first create the Python
107	package interfacing to the terminology of the application (what
108	<b class="program">Script Editor</b> calls the "Dictionary"). This can be done from
109	within the <b class="program">PythonIDE</b> or by running the
110	<span class="file">gensuitemodule.py</span> module as a standalone program from the command
111	line.
112
113	<P>
114	The generated output is a package with a number of modules, one for
115	every suite used in the program plus an <tt class="module">__init__</tt> module to glue
116	it all together. The Python inheritance graph follows the AppleScript
117	inheritance graph, so if a programs dictionary specifies that it
118	includes support for the Standard Suite, but extends one or two verbs
119	with extra arguments then the output suite will contain a module
120	<tt class="module">Standard_Suite</tt> that imports and re-exports everything from
121	<tt class="module">StdSuites.Standard_Suite</tt> but overrides the methods that have
122	extra functionality. The output of <tt class="module">gensuitemodule</tt> is pretty
123	readable, and contains the documentation that was in the original
124	AppleScript dictionary in Python docstrings, so reading it is a good
125	source of documentation.
126
127	<P>
128	The output package implements a main class with the same name as the
129	package which contains all the AppleScript verbs as methods, with the
130	direct object as the first argument and all optional parameters as
131	keyword arguments. AppleScript classes are also implemented as Python
132	classes, as are comparisons and all the other thingies.
133
134	<P>
135	The main
136	Python class implementing the verbs also allows access to the properties
137	and elements declared in the AppleScript class "application". In the
138	current release that is as far as the object orientation goes, so
139	in the example above we need to use
140	<code>f.get(f.window(1).name)</code> instead of the more Pythonic
141	<code>f.window(1).name.get()</code>.
142
143	<P>
144	If an AppleScript identifier is not a Python identifier the name is
145	mangled according to a small number of rules:
146
147	<UL>
148	<LI>spaces are replaced with underscores
149	</LI>
150	<LI>other non-alphanumeric characters are replaced with
151	<code>_xx_</code> where <code>xx</code> is the hexadecimal character value
152	</LI>
153	<LI>any Python reserved word gets an underscore appended
154	</LI>
155	</UL>
156
157	<P>
158	Python also has support for creating scriptable applications
159	in Python, but
160	The following modules are relevant to MacPython AppleScript support:
161
162	<P>
163	<table class='synopsistable' valign='baseline'>
164	<tr class='oddrow'>
165	<td><b><tt class='module'><a href='module-gensuitemodule.html'>gensuitemodule</a></tt></b></td>
166	<td> </td>
167	<td class='synopsis'>Create a stub package from an OSA dictionary</td></tr>
168	<tr><td><b><tt class='module'><a href='module-aetools.html'>aetools</a></tt></b></td>
169	<td> </td>
170	<td class='synopsis'>Basic support for sending Apple Events</td></tr>
171	<tr class='oddrow'>
172	<td><b><tt class='module'><a href='module-aepack.html'>aepack</a></tt></b></td>
173	<td> </td>
174	<td class='synopsis'>Conversion between Python variables and AppleEvent
175	data containers.</td></tr>
176	<tr><td><b><tt class='module'><a href='module-aetypes.html'>aetypes</a></tt></b></td>
177	<td> </td>
178	<td class='synopsis'>Python representation of the Apple Event Object Model.</td></tr>
179	<tr class='oddrow'>
180	<td><b><tt class='module'><a href='module-MiniAEFrame.html'>MiniAEFrame</a></tt></b></td>
181	<td> </td>
182	<td class='synopsis'>Support to act as an Open Scripting Architecture (OSA) server
183	(``Apple Events'').</td></tr>
184	</table>
185
186	<BR>
187	<P>
188	In addition, support modules have been pre-generated for
189	<tt class="module">Finder</tt>, <tt class="module">Terminal</tt>, <tt class="module">Explorer</tt>,
190	<tt class="module">Netscape</tt>, <tt class="module">CodeWarrior</tt>, <tt class="module">SystemEvents</tt> and
191	<tt class="module">StdSuites</tt>.
192
193	<P>
194
195	<DIV CLASS="navigation">
196	<div class='online-navigation'>
197	<p></p><hr />
198	<table align="center" width="100%" cellpadding="0" cellspacing="2">
199	<tr>
200	<td class='online-navigation'><a rel="prev" title="2.9 autoGIL "
201	href="module-autoGIL.html"><img src='../icons/previous.png'
202	border='0' height='32' alt='Previous Page' width='32' /></A></td>
203	<td class='online-navigation'><a rel="parent" title="Macintosh Library Modules"
204	href="mac.html"><img src='../icons/up.png'
205	border='0' height='32' alt='Up One Level' width='32' /></A></td>
206	<td class='online-navigation'><a rel="next" title="3.1 gensuitemodule "
207	href="module-gensuitemodule.html"><img src='../icons/next.png'
208	border='0' height='32' alt='Next Page' width='32' /></A></td>
209	<td align="center" width="100%">Macintosh Library Modules</td>
210	<td class='online-navigation'><a rel="contents" title="Table of Contents"
211	href="contents.html"><img src='../icons/contents.png'
212	border='0' height='32' alt='Contents' width='32' /></A></td>
213	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
214	border='0' height='32' alt='Module Index' width='32' /></a></td>
215	<td class='online-navigation'><a rel="index" title="Index"
216	href="genindex.html"><img src='../icons/index.png'
217	border='0' height='32' alt='Index' width='32' /></A></td>
218	</tr></table>
219	<div class='online-navigation'>
220	<b class="navlabel">Previous:</b>
221	<a class="sectref" rel="prev" href="module-autoGIL.html">2.9 autoGIL </A>
222	<b class="navlabel">Up:</b>
223	<a class="sectref" rel="parent" href="mac.html">Macintosh Library Modules</A>
224	<b class="navlabel">Next:</b>
225	<a class="sectref" rel="next" href="module-gensuitemodule.html">3.1 gensuitemodule </A>
226	</div>
227	</div>
228	<hr />
229	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
230	</DIV>
231	<!--End of Navigation Panel-->
232	<ADDRESS>
233	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
234	</ADDRESS>
235	</BODY>
236	</HTML>