PageRenderTime 244ms CodeModel.GetById 121ms app.highlight 4ms RepoModel.GetById 117ms app.codeStats 0ms

/Doc/library/macosa.rst

http://unladen-swallow.googlecode.com/
ReStructuredText | 92 lines | 69 code | 23 blank | 0 comment | 0 complexity | dd4b3c4ff44344e949043b26d9dcd58c MD5 | raw file
 1
 2.. _mac-scripting:
 3
 4*********************
 5MacPython OSA Modules
 6*********************
 7
 8This chapter describes the current implementation of the Open Scripting
 9Architecture (OSA, also commonly referred to as AppleScript) for Python,
10allowing you to control scriptable applications from your Python program,
11and with a fairly pythonic interface. Development on this set of modules has
12stopped, and a replacement is expected for Python 2.5.
13
14For a description of the various components of AppleScript and OSA, and to get
15an understanding of the architecture and terminology, you should read Apple's
16documentation. The "Applescript Language Guide" explains the conceptual model
17and the terminology, and documents the standard suite. The "Open Scripting
18Architecture" document explains how to use OSA from an application programmers
19point of view. In the Apple Help Viewer these books are located in the Developer
20Documentation, Core Technologies section.
21
22As an example of scripting an application, the following piece of AppleScript
23will get the name of the frontmost :program:`Finder` window and print it::
24
25   tell application "Finder"
26       get name of window 1
27   end tell
28
29In Python, the following code fragment will do the same::
30
31   import Finder
32
33   f = Finder.Finder()
34   print f.get(f.window(1).name)
35
36As distributed the Python library includes packages that implement the standard
37suites, plus packages that interface to a small number of common applications.
38
39To send AppleEvents to an application you must first create the Python package
40interfacing to the terminology of the application (what :program:`Script Editor`
41calls the "Dictionary"). This can be done from within the :program:`PythonIDE`
42or by running the :file:`gensuitemodule.py` module as a standalone program from
43the command line.
44
45The generated output is a package with a number of modules, one for every suite
46used in the program plus an :mod:`__init__` module to glue it all together. The
47Python inheritance graph follows the AppleScript inheritance graph, so if a
48program's dictionary specifies that it includes support for the Standard Suite,
49but extends one or two verbs with extra arguments then the output suite will
50contain a module :mod:`Standard_Suite` that imports and re-exports everything
51from :mod:`StdSuites.Standard_Suite` but overrides the methods that have extra
52functionality. The output of :mod:`gensuitemodule` is pretty readable, and
53contains the documentation that was in the original AppleScript dictionary in
54Python docstrings, so reading it is a good source of documentation.
55
56The output package implements a main class with the same name as the package
57which contains all the AppleScript verbs as methods, with the direct object as
58the first argument and all optional parameters as keyword arguments. AppleScript
59classes are also implemented as Python classes, as are comparisons and all the
60other thingies.
61
62The main Python class implementing the verbs also allows access to the
63properties and elements declared in the AppleScript class "application". In the
64current release that is as far as the object orientation goes, so in the example
65above we need to use ``f.get(f.window(1).name)`` instead of the more Pythonic
66``f.window(1).name.get()``.
67
68If an AppleScript identifier is not a Python identifier the name is mangled
69according to a small number of rules:
70
71* spaces are replaced with underscores
72
73* other non-alphanumeric characters are replaced with ``_xx_`` where ``xx`` is
74  the hexadecimal character value
75
76* any Python reserved word gets an underscore appended
77
78Python also has support for creating scriptable applications in Python, but The
79following modules are relevant to MacPython AppleScript support:
80
81.. toctree::
82
83   gensuitemodule.rst
84   aetools.rst
85   aepack.rst
86   aetypes.rst
87   miniaeframe.rst
88
89
90In addition, support modules have been pre-generated for :mod:`Finder`,
91:mod:`Terminal`, :mod:`Explorer`, :mod:`Netscape`, :mod:`CodeWarrior`,
92:mod:`SystemEvents` and :mod:`StdSuites`.