1 

     2 :mod:`gensuitemodule` --- Generate OSA stub packages

     3 ====================================================

     4 

     5 .. module:: gensuitemodule

     6    :platform: Mac

     7    :synopsis: Create a stub package from an OSA dictionary

     8 .. sectionauthor:: Jack Jansen <Jack.Jansen@cwi.nl>

     9 .. moduleauthor:: Jack Jansen

    10 

    11 The :mod:`gensuitemodule` module creates a Python package implementing stub code

    12 for the AppleScript suites that are implemented by a specific application,

    13 according to its AppleScript dictionary.

    14 

    15 It is usually invoked by the user through the :program:`PythonIDE`, but it can

    16 also be run as a script from the command line (pass :option:`--help` for help on

    17 the options) or imported from Python code. For an example of its use see

    18 :file:`Mac/scripts/genallsuites.py` in a source distribution, which generates

    19 the stub packages that are included in the standard library.

    20 

    21 It defines the following public functions:

    22 

    23 

    24 .. function:: is_scriptable(application)

    25 

    26    Returns true if ``application``, which should be passed as a pathname, appears

    27    to be scriptable. Take the return value with a grain of salt: :program:`Internet

    28    Explorer` appears not to be scriptable but definitely is.

    29 

    30 

    31 .. function:: processfile(application[, output, basepkgname,  edit_modnames, creatorsignature, dump, verbose])

    32 

    33    Create a stub package for ``application``, which should be passed as a full

    34    pathname. For a :file:`.app` bundle this is the pathname to the bundle, not to

    35    the executable inside the bundle; for an unbundled CFM application you pass the

    36    filename of the application binary.

    37 

    38    This function asks the application for its OSA terminology resources, decodes

    39    these resources and uses the resultant data to create the Python code for the

    40    package implementing the client stubs.

    41 

    42    ``output`` is the pathname where the resulting package is stored, if not

    43    specified a standard "save file as" dialog is presented to the user.

    44    ``basepkgname`` is the base package on which this package will build, and

    45    defaults to :mod:`StdSuites`. Only when generating :mod:`StdSuites` itself do

    46    you need to specify this. ``edit_modnames`` is a dictionary that can be used to

    47    change modulenames that are too ugly after name mangling. ``creator_signature``

    48    can be used to override the 4-char creator code, which is normally obtained from

    49    the :file:`PkgInfo` file in the package or from the CFM file creator signature.

    50    When ``dump`` is given it should refer to a file object, and ``processfile``

    51    will stop after decoding the resources and dump the Python representation of the

    52    terminology resources to this file. ``verbose`` should also be a file object,

    53    and specifying it will cause ``processfile`` to tell you what it is doing.

    54 

    55 

    56 .. function:: processfile_fromresource(application[, output,  basepkgname, edit_modnames, creatorsignature, dump, verbose])

    57 

    58    This function does the same as ``processfile``, except that it uses a different

    59    method to get the terminology resources. It opens ``application`` as a resource

    60    file and reads all ``"aete"`` and ``"aeut"`` resources from this file.

    61