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 12The :mod:`aepack` module defines functions for converting (packing) Python 13variables to AppleEvent descriptors and back (unpacking). Within Python the 14AppleEvent 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 22The :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