<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>38. MacPython OSA Modules — Python v2.6.5 documentation</title>
<link rel="stylesheet" href="../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '2.6.5',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python v2.6.5 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="top" title="Python v2.6.5 documentation" href="../index.html" />
<link rel="up" title="The Python Standard Library" href="index.html" />
<link rel="next" title="38.1. gensuitemodule — Generate OSA stub packages" href="gensuitemodule.html" />
<link rel="prev" title="37.9. ColorPicker — Color selection dialog" href="colorpicker.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../modindex.html" title="Global Module Index"
accesskey="M">modules</a> |</li>
<li class="right" >
<a href="gensuitemodule.html" title="38.1. gensuitemodule — Generate OSA stub packages"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="colorpicker.html" title="37.9. ColorPicker — Color selection dialog"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="../index.html">Python v2.6.5 documentation</a> »</li>
<li><a href="index.html" accesskey="U">The Python Standard Library</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="macpython-osa-modules">
<span id="mac-scripting"></span><h1>38. MacPython OSA Modules<a class="headerlink" href="#macpython-osa-modules" title="Permalink to this headline">¶</a></h1>
<p>This chapter describes the current implementation of the Open Scripting
Architecture (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>
<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 books are located in the Developer
Documentation, Core Technologies section.</p>
<p>As an example of scripting an application, the following piece of AppleScript
will get the name of the frontmost <strong>Finder</strong> window and print it:</p>
<div class="highlight-python"><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="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">Finder</span>
<span class="n">f</span> <span class="o">=</span> <span class="n">Finder</span><span class="o">.</span><span class="n">Finder</span><span class="p">()</span>
<span class="k">print</span> <span class="n">f</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">window</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>
</pre></div>
</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>
<p>To send AppleEvents to an application you must first create the Python package
interfacing to the terminology of the application (what <strong>Script Editor</strong>
calls the “Dictionary”). This can be done from within the <strong>PythonIDE</strong>
or by running the <tt class="docutils literal"><span class="pre">gensuitemodule.py</span></tt> module as a standalone program from
the command line.</p>
<p>The generated output is a package with a number of modules, one for every suite
used in the program plus an <tt class="xref docutils literal"><span class="pre">__init__</span></tt> module to glue it all together. The
Python inheritance graph follows the AppleScript inheritance graph, so if a
program’s 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="xref docutils literal"><span class="pre">Standard_Suite</span></tt> that imports and re-exports everything
from <tt class="xref docutils literal"><span class="pre">StdSuites.Standard_Suite</span></tt> but overrides the methods that have extra
functionality. The output of <a title="(Mac) Create a stub package from an OSA dictionary" class="reference external" href="gensuitemodule.html#module-gensuitemodule"><tt class="xref docutils literal"><span class="pre">gensuitemodule</span></tt></a> 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>
<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>
<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 <tt class="docutils literal"><span class="pre">f.get(f.window(1).name)</span></tt> instead of the more Pythonic
<tt class="docutils literal"><span class="pre">f.window(1).name.get()</span></tt>.</p>
<p>If an AppleScript identifier is not a Python identifier the name is mangled
according to a small number of rules:</p>
<ul class="simple">
<li>spaces are replaced with underscores</li>
<li>other non-alphanumeric characters are replaced with <tt class="docutils literal"><span class="pre">_xx_</span></tt> where <tt class="docutils literal"><span class="pre">xx</span></tt> 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>
<ul>
<li class="toctree-l1"><a class="reference external" href="gensuitemodule.html">38.1. <tt class="docutils literal"><span class="pre">gensuitemodule</span></tt> — Generate OSA stub packages</a></li>
<li class="toctree-l1"><a class="reference external" href="aetools.html">38.2. <tt class="docutils literal"><span class="pre">aetools</span></tt> — OSA client support</a></li>
<li class="toctree-l1"><a class="reference external" href="aepack.html">38.3. <tt class="docutils literal"><span class="pre">aepack</span></tt> — Conversion between Python variables and AppleEvent data containers</a></li>
<li class="toctree-l1"><a class="reference external" href="aetypes.html">38.4. <tt class="docutils literal"><span class="pre">aetypes</span></tt> — AppleEvent objects</a></li>
<li class="toctree-l1"><a class="reference external" href="miniaeframe.html">38.5. <tt class="docutils literal"><span class="pre">MiniAEFrame</span></tt> — Open Scripting Architecture server support</a><ul>
<li class="toctree-l2"><a class="reference external" href="miniaeframe.html#aeserver-objects">38.5.1. AEServer Objects</a></li>
</ul>
</li>
</ul>
<p>In addition, support modules have been pre-generated for <tt class="xref docutils literal"><span class="pre">Finder</span></tt>,
<tt class="xref docutils literal"><span class="pre">Terminal</span></tt>, <tt class="xref docutils literal"><span class="pre">Explorer</span></tt>, <tt class="xref docutils literal"><span class="pre">Netscape</span></tt>, <tt class="xref docutils literal"><span class="pre">CodeWarrior</span></tt>,
<tt class="xref docutils literal"><span class="pre">SystemEvents</span></tt> and <tt class="xref docutils literal"><span class="pre">StdSuites</span></tt>.</p>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="colorpicker.html"
title="previous chapter">37.9. <tt class="docutils literal docutils literal docutils literal"><span class="pre">ColorPicker</span></tt> — Color selection dialog</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="gensuitemodule.html"
title="next chapter">38.1. <tt class="docutils literal docutils literal docutils literal"><span class="pre">gensuitemodule</span></tt> — Generate OSA stub packages</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/library/macosa.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../modindex.html" title="Global Module Index"
>modules</a> |</li>
<li class="right" >
<a href="gensuitemodule.html" title="38.1. gensuitemodule — Generate OSA stub packages"
>next</a> |</li>
<li class="right" >
<a href="colorpicker.html" title="37.9. ColorPicker — Color selection dialog"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="../index.html">Python v2.6.5 documentation</a> »</li>
<li><a href="index.html" >The Python Standard Library</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2010, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="http://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 19, 2010.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.5.
</div>
</body>
</html>
