Doc/mac/scripting.tex

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