Doc/library/aepack.rst

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