Doc/mac/scripting.tex

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