Home | History | Annotate | Download | only in library 
      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 (a] 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.
     93