[Pythonmac-SIG] [ANN] PyMacApp - Flexible Executable Stub For Python (v0.2)

Bob Ippolito bob at redivi.com
Thu Mar 4 17:33:14 EST 2004

I've polished off some more things, written documentation (in the 
email, as reST), and added new features.. today's snapshot is here:


And now for your documentation reading pleasure..

  PyMacApp: Flexible Executable Stub For Python


PyMacApp is a Cocoa executable stub for Python that accomplishes the 

- A single binary can run on OS X 10.1 or later, with no recompilation
   required under any circumstance.  Therefore, bundles can be built on 
   without Xcode and/or the SDKs installed.

- It must provide helpful and somewhat customizable errors to the user 
in the
   form of GUI alert panels.

- It must be able to link to one of many possible Python frameworks at
   runtime.  This allows the same executable bundle to run in just about
   any environment, even if the developer does have to explicitly manage
   a separate set of extensions per-framework until we resolve linking 

- It must be able to gracefully handle Python exceptions, because they 
   prevent the application from starting.

- It must not use execve for performance reasons and to ease debugging.

- It should be integrated with BundleBuilder2.

- It should be integrated with Python/PyObjC Xcode templates in source 
   binary form.

- It should consider non-framework builds of Python, but there are no 
   to test this scenario.

Using PyMacApp

PyMacApp has three required preconditions for use:

- PyMacApp must be the CFBundleExecutable for your application 
according to
   Info.plist.  It is recommended to rename PyMacApp to agree with the
   name of your application bundle.

- A ``PyRuntimeLocations`` key must be added to your Info.plist, it is 
   ordered array of strings.  Here are some examples:

   - Embedded Python 2.3 runtime, as created by BundleBuilder2's 
--standalone option.


   - User-installed Python 2.3 runtime.


   - Vendor-installed Python 2.3 runtime, such as the one in OS X 10.3.


- A main script must be placed in the Resources folder of your 
   bundle.  By default, PyMacApp will first check Info.plist for a
   ``PyMainFileNames`` key, which should be an array of possible names as
   strings.  If this key is not present, or if no main script is found, 
   these script names are attempted (in this order):

   - ``__main__.py``, ``__main__.pyc``, ``__main__.pyo``

   - ``__realmain__.py``, ``__realmain__.pyc``, ``__realmain__.pyo``

   - ``Main.py``, ``Main.pyc``, ``Main.pyo``

Handling Errors Gracefully

PyMacApp offers alert panels for several common errors that can happen. 
following errors are low level, and their responses can not be 

   - The ``PyRuntimeLocations`` key is not present in the Info.plist.

   - No main script could be located.

   - A link error occurred when attempting to load the Python runtime or 
     of its symbols.

   - The main script exited with an exception, but there was an error 
     the name of the exception type.

In addition to this, several common high level errors can be handled by 
error handling script.  There is an optional Info.plist key analagous to
``PyMainFileNames`` called ``PyErrorScripts`, and the additional script 
attempted are: ``__error__``, ``__error__.py``, and ``__error__.sh``.  
that the script must be executable (chmod +x), or error handling will 
work.  Also note that the script may be written in any language (with 
appropriate "hash-bang" line), or may even be a compiled executable.

An error handling script will always receive the user displayable name 
of the
application, such as "PyMacApp" as the first argument.  If no other 
are received, then there was an error locating a suitable Python 
Otherwise, the second argument is the name of the Python exception type
(e.g. "ImportError") and the third argument is the string value of the
exception instance (e.g. "No module named foobar").

The stdout of the script is parsed under the following conditions:

- The newline character is '\n'

- The first line of output is required, and will be the title of the 
   dialog (displayed in bold).

- Any additional lines of text are optional, and will be the body of 
the error
   dialog (not displayed in bold).

Additionally, if the last line of the script is in the form

``ERRORURL: http://example.com/detailederror/ View Detailed Error 

then the "Open Console" button will be replaced with a
"View Detailed Error Report" button that when clicked, will open the
user's default web browser to http://example.com/detailederror/.  If a
title is not provided (just the URL), then the button will be named
"Visit Website".  It is recommended that this is used to direct a user 
instructions on how to solve their problem (i.e. download Python, file 
a bug,

This is an example ``__error__.sh`` script::

     if ( test -n "$2" ) ; then
             echo "$1 Error"
             echo "An unexpected error has occurred during execution of 
the main script"
             echo ""
             echo "$2: $3"
             echo ""
             echo "See the Console for a detailed traceback."
             echo "$1 Error"
             echo "MacPython 2.3 is required to run this application.";
             echo "ERRORURL: 
http://homepages.cwi.nl/~jack/macpython/index.html Visit the MacPython 


     This environment variable is set to

     A required Info.plist key, see "Using PyMacApp" and Apple's 

     A required Info.plist key, see "Using PyMacApp".

     An optional Info.plist key representing the name of the python 
     It will be merged with the found Python runtime location and will 
     sys.executable and sys.prefix.  The default, ``python``, is 

     An optional Info.plist key, see "Handling Errors Gracefully".

Known Bugs

- It is not currently possible to use a Py_TRACE_REFS Python runtime as 
   PyObject structure does not have the reference count at the head.  It 
is not
   obvious how this could be solved.

More information about the Pythonmac-SIG mailing list