[Stackless-checkins] CVS: slpdev/src/2.2/src/Doc/mac libaetools.tex, NONE, 1.1 libautogil.tex, NONE, 1.1 libgensuitemodule.tex, NONE, 1.1 libscrap.tex, NONE, 1.1 scripting.tex, NONE, 1.1

[Christian Tismer]

Update of /home/cvs/slpdev/src/2.2/src/Doc/mac
In directory centera.de:/home/tismer/slpdev/src/2.2/src/Doc/mac

Added Files:
	libaetools.tex libautogil.tex libgensuitemodule.tex 
	libscrap.tex scripting.tex 
Log Message:
added files

--- NEW FILE: libaetools.tex ---
\section{\module{aetools} ---
         OSA client support}

\declaremodule{standard}{aetools}
  \platform{Mac}
%\moduleauthor{Jack Jansen?}{email}
\modulesynopsis{Basic support for sending Apple Events}
\sectionauthor{Jack Jansen}{Jack.Jansen at cwi.nl}


The \module{aetools} module contains the basic functionality
on which Python AppleScript client support is built. It also
imports and re-exports the core functionality of the
\module{aetypes} and \module{aepack} modules. The stub packages
generated by \module{gensuitemodule} import the relevant
portions of \module{aetools}, so usually you do not need to
import it yourself. The exception to this is when you
cannot use a generated suite package and need lower-level
access to scripting.

The \module{aetools} module itself uses the AppleEvent support
provided by the \module{Carbon.AE} module. This has one drawback:
you need access to the window manager, see section \ref{osx-gui-scripts}
for details. This restriction may be lifted in future releases.


The \module{aetools} module defines the following functions:

\begin{funcdesc}{packevent}{ae, parameters, attributes}
Stores parameters and attributes in a pre-created \code{Carbon.AE.AEDesc}
object. \code{parameters} and \code{attributes} are 
dictionaries mapping 4-character OSA parameter keys to Python objects. The
objects are packed using \code{aepack.pack()}.
\end{funcdesc}

\begin{funcdesc}{unpackevent}{ae\optional{, formodulename}}
Recursively unpacks a \code{Carbon.AE.AEDesc} event to Python objects.
The function returns the parameter dictionary and the attribute dictionary.
The \code{formodulename} argument is used by generated stub packages to
control where AppleScript classes are looked up.
\end{funcdesc}

\begin{funcdesc}{keysubst}{arguments, keydict}
Converts a Python keyword argument dictionary \code{arguments} to
the format required by \code{packevent} by replacing the keys,
which are Python identifiers, by the four-character OSA keys according
to the mapping specified in \code{keydict}. Used by the generated suite
packages.
\end{funcdesc}

\begin{funcdesc}{enumsubst}{arguments, key, edict}
If the \code{arguments} dictionary contains an entry for \code{key}
convert the value for that entry according to dictionary \code{edict}.
This converts human-readable Python enumeration names to the OSA 4-character
codes.
Used by the generated suite
packages.
\end{funcdesc}

The \module{aetools} module defines the following class:

\begin{classdesc}{TalkTo}{\optional{signature=None, start=0, timeout=0}}

Base class for the proxy used to talk to an application. \code{signature}
overrides the class attribute \code{_signature} (which is usually set by subclasses)
and is the 4-char creator code defining the application to talk to.
\code{start} can be set to true to enable running the application on
class instantiation. \code{timeout} can be specified to change the
default timeout used while waiting for an AppleEvent reply.
\end{classdesc}

\begin{methoddesc}{_start}{}
Test whether the application is running, and attempt to start it if not.
\end{methoddesc}

\begin{methoddesc}{send}{code, subcode\optional{, parameters, attributes}}
Create the AppleEvent \code{Carbon.AE.AEDesc} for the verb with
the OSA designation \code{code, subcode} (which are the usual 4-character
strings), pack the \code{parameters} and \code{attributes} into it, send it
to the target application, wait for the reply, unpack the reply with
\code{unpackevent} and return the reply appleevent, the unpacked return values
as a dictionary and the return attributes.
\end{methoddesc}

--- NEW FILE: libautogil.tex ---
\section{\module{autoGIL} ---
         Global Interpreter Lock handling in event loops}

\declaremodule{extension}{autoGIL}
  \platform{Mac}
\modulesynopsis{Global Interpreter Lock handling in event loops.}
\moduleauthor{Just van Rossum}{just at letterror.com}


The \module{autoGIL} module provides a function \function{installAutoGIL} that
automatically locks and unlocks Python's Global Interpreter Lock
when running an event loop.

\begin{excdesc}{AutoGILError}
Raised if the observer callback cannot be installed, for example because
the current thread does not have a run loop.
\end{excdesc}

\begin{funcdesc}{installAutoGIL}{}
	Install an observer callback in the event loop (CFRunLoop) for the
	current thread, that will lock and unlock the Global Interpreter Lock
	(GIL) at appropriate times, allowing other Python threads to run while
	the event loop is idle.
	
	Availability: OSX 10.1 or later.
\end{funcdesc}

--- NEW FILE: libgensuitemodule.tex ---
\section{\module{gensuitemodule} ---
         Generate OSA stub packages}

\declaremodule{standard}{gensuitemodule}
  \platform{Mac}
%\moduleauthor{Jack Jansen?}{email}
\modulesynopsis{Create a stub package from an OSA dictionary}
\sectionauthor{Jack Jansen}{Jack.Jansen at cwi.nl}

The \module{gensuitemodule} module creates a Python package implementing
stub code for the AppleScript suites that are implemented by a specific
application, according to its AppleScript dictionary.

It is usually invoked by the user through the \program{PythonIDE}, but
it can also be run as a script from the command line (pass
\longprogramopt{help} for help on the options) or imported from Python
code. For an example of its use see \file{Mac/scripts/genallsuites.py}
in a source distribution, which generates the stub packages that are
included in the standard library.

It defines the following public functions:

\begin{funcdesc}{is_scriptable}{application}
Returns true if \code{application}, which should be passed as a pathname,
appears to be scriptable. Take the return value with a grain of salt:
\program{Internet Explorer} appears not to be scriptable but definitely is.
\end{funcdesc}

\begin{funcdesc}{processfile}{application\optional{, output, basepkgname, 
        edit_modnames, creatorsignature, dump, verbose}}
Create a stub package for \code{application}, which should be passed as
a full pathname. For a \file{.app} bundle this is the pathname to the
bundle, not to the executable inside the bundle; for an unbundled CFM
application you pass the filename of the application binary.

This function asks the application for its OSA terminology resources,
decodes these resources and uses the resultant data to create the Python
code for the package implementing the client stubs.

\code{output} is the pathname where the resulting package is stored, if
not specified a standard "save file as" dialog is presented to
the user. \code{basepkgname} is the base package on which this package
will build, and defaults to \module{StdSuites}. Only when generating
\module{StdSuites} itself do you need to specify this.
\code{edit_modnames} is a dictionary that can be used to change
modulenames that are too ugly after name mangling.
\code{creator_signature} can be used to override the 4-char creator
code, which is normally obtained from the \file{PkgInfo} file in the
package or from the CFM file creator signature. When \code{dump} is
given it should refer to a file object, and \code{processfile} will stop
after decoding the resources and dump the Python representation of the
terminology resources to this file. \code{verbose} should also be a file
object, and specifying it will cause \code{processfile} to tell you what
it is doing.
\end{funcdesc}

\begin{funcdesc}{processfile_fromresource}{application\optional{, output, 
	basepkgname, edit_modnames, creatorsignature, dump, verbose}}
This function does the same as \code{processfile}, except that it uses a
different method to get the terminology resources. It opens \code{application}
as a resource file and reads all \code{"aete"} and \code{"aeut"} resources
from this file.
\end{funcdesc}


--- NEW FILE: libscrap.tex ---
\section{\module{Carbon.Scrap} --- Scrap Manager}
\declaremodule{standard}{Carbon.Scrap}
  \platform{Mac}
\modulesynopsis{The Scrap Manager provides basic services for
                implementing cut \&\ paste and clipboard operations.}


This module is only fully available on MacOS9 and earlier under
classic PPC MacPython.  Very limited functionality is available under
Carbon MacPython.

The Scrap\index{Scrap Manager} Manager supports the simplest form of
cut \&\ paste operations on the Macintosh.  It can be use for both
inter- and intra-application clipboard operations.

The \module{Scrap} module provides low-level access to the functions
of the Scrap Manager.  It contains the following functions:


\begin{funcdesc}{InfoScrap}{}
  Return current information about the scrap.  The information is
  encoded as a tuple containing the fields \code{(\var{size},
  \var{handle}, \var{count}, \var{state}, \var{path})}.

  \begin{tableii}{l|l}{var}{Field}{Meaning}
    \lineii{size}{Size of the scrap in bytes.}
    \lineii{handle}{Resource object representing the scrap.}
    \lineii{count}{Serial number of the scrap contents.}
    \lineii{state}{Integer; positive if in memory, \code{0} if on
                   disk, negative if uninitialized.}
    \lineii{path}{Filename of the scrap when stored on disk.}
  \end{tableii}
\end{funcdesc}



\begin{seealso}
  \seetitle[http://developer.apple.com/documentation/mac/MoreToolbox/MoreToolbox-109.html]
           {Scrap Manager}{Apple's documentation for the Scrap Manager
            gives a lot of useful information about using the Scrap
            Manager in applications.}
\end{seealso}

--- NEW FILE: scripting.tex ---
\chapter{MacPython OSA Modules \label{scripting}}

Python has a fairly complete implementation of the Open Scripting
Architecure (OSA, also commonly referred to as AppleScript), allowing
you to control scriptable applications from your Python program,
and with a fairly pythonic interface. 

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.


As an example of scripting an application, the following piece of
AppleScript will get the name of the frontmost \program{Finder} window
and print it:
	
\begin{verbatim}
tell application "Finder"
    get name of window 1
end tell
\end{verbatim}

In Python, the following code fragment will do the same:

\begin{verbatim}
import Finder

f = Finder.Finder()
print f.get(f.window(1).name)
\end{verbatim}

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

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

The generated output is a package with a number of modules, one for
every suite used in the program plus an \module{__init__} 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
\module{Standard_Suite} that imports and re-exports everything from
\module{StdSuites.Standard_Suite} but overrides the methods that have
extra functionality. The output of \module{gensuitemodule} 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.

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.

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)} instead of the more Pythonic
\code{f.window(1).name.get()}.


If an AppleScript identifier is not a Python identifier the name is
mangled according to a small number of rules:
\begin{itemize}
    \item spaces are replaced with underscores
    \item other non-alphanumeric characters are replaced with
    \code{_xx_} where \code{xx} is the hexadecimal character value
    \item any Python reserved word gets an underscore appended
\end{itemize}

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

\localmoduletable

In addition, support modules have been pre-generated for
\module{Finder}, \module{Terminal}, \module{Explorer},
\module{Netscape}, \module{CodeWarrior}, \module{SystemEvents} and
\module{StdSuites}.

\input{libgensuitemodule}
\input{libaetools}
\input{libaepack}
\input{libaetypes}
\input{libminiae}


_______________________________________________
Stackless-checkins mailing list
Stackless-checkins at stackless.com
http://www.stackless.com/mailman/listinfo/stackless-checkins