Doc/mac/libaepack.tex

   1 \section{\module{aepack} ---
   2          Conversion between Python variables and AppleEvent data containers}
   3
   4 \declaremodule{standard}{aepack}
   5   \platform{Mac}
   6 %\moduleauthor{Jack Jansen?}{email}
   7 \modulesynopsis{Conversion between Python variables and AppleEvent
   8                 data containers.}
   9 \sectionauthor{Vincent Marchetti}{vincem@en.com}
  10
  11
  12 The \module{aepack} module defines functions for converting (packing)
  13 Python variables to AppleEvent descriptors and back (unpacking).
  14 Within Python the AppleEvent descriptor is handled by Python objects
  15 of built-in type \class{AEDesc}, defined in module \refmodule{Carbon.AE}.
  16
  17 The \module{aepack} module defines the following functions:
  18
  19
  20 \begin{funcdesc}{pack}{x\optional{, forcetype}}
  21 Returns an \class{AEDesc} object  containing a conversion of Python
  22 value x. If \var{forcetype} is provided it specifies the descriptor
  23 type of the result. Otherwise, a default mapping of Python types to
  24 Apple Event descriptor types is used, as follows:
  25
  26 \begin{tableii}{l|l}{textrm}{Python type}{descriptor type}
  27   \lineii{\class{FSSpec}}{typeFSS}
  28   \lineii{\class{FSRef}}{typeFSRef}
  29   \lineii{\class{Alias}}{typeAlias}
  30   \lineii{integer}{typeLong (32 bit integer)}
  31   \lineii{float}{typeFloat (64 bit floating point)}
  32   \lineii{string}{typeText}
  33   \lineii{unicode}{typeUnicodeText}
  34   \lineii{list}{typeAEList}
  35   \lineii{dictionary}{typeAERecord}
  36   \lineii{instance}{\emph{see below}}
  37 \end{tableii}
  38
  39 If \var{x} is a Python instance then this function attempts to call an
  40 \method{__aepack__()} method.  This method should return an
  41 \class{AEDesc} object.
  42
  43 If the conversion \var{x} is not defined above, this function returns
  44 the Python string representation of a value (the repr() function)
  45 encoded as a text descriptor.
  46 \end{funcdesc}
  47
  48 \begin{funcdesc}{unpack}{x\optional{, formodulename}}
  49   \var{x} must be an object of type \class{AEDesc}. This function
  50   returns a Python object representation of the data in the Apple
  51   Event descriptor \var{x}. Simple AppleEvent data types (integer,
  52   text, float) are returned as their obvious Python counterparts.
  53   Apple Event lists are returned as Python lists, and the list
  54   elements are recursively unpacked.  Object references
  55   (ex. \code{line 3 of document 1}) are returned as instances of
  56   \class{aetypes.ObjectSpecifier}, unless \code{formodulename}
  57   is specified.  AppleEvent descriptors with
  58   descriptor type typeFSS are returned as \class{FSSpec}
  59   objects.  AppleEvent record descriptors are returned as Python
  60   dictionaries, with 4-character string keys and elements recursively
  61   unpacked.
  62
  63   The optional \code{formodulename} argument is used by the stub packages
  64   generated by \module{gensuitemodule}, and ensures that the OSA classes
  65   for object specifiers are looked up in the correct module. This ensures
  66   that if, say, the Finder returns an object specifier for a window
  67   you get an instance of \code{Finder.Window} and not a generic
  68   \code{aetypes.Window}. The former knows about all the properties
  69   and elements a window has in the Finder, while the latter knows
  70   no such things.
  71 \end{funcdesc}
  72
  73
  74 \begin{seealso}
  75   \seemodule{Carbon.AE}{Built-in access to Apple Event Manager routines.}
  76   \seemodule{aetypes}{Python definitions of codes for Apple Event
  77                       descriptor types.}
  78   \seetitle[http://developer.apple.com/techpubs/mac/IAC/IAC-2.html]{
  79             Inside Macintosh: Interapplication
  80             Communication}{Information about inter-process
  81             communications on the Macintosh.}
  82 \end{seealso}