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 .. warning::

    18 

    19    This module is removed in 3.0.

    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.