[Pythonmac-SIG] [ANN] PyMacApp - Flexible Executable Stub For
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
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
- It should consider non-framework builds of Python, but there are no
to test this scenario.
PyMacApp has three required preconditions for use:
- PyMacApp must be the CFBundleExecutable for your application
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
- 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
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
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
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 "$2: $3"
echo "See the Console for a detailed traceback."
echo "$1 Error"
echo "MacPython 2.3 is required to run this application.";
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".
- 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
obvious how this could be solved.
More information about the Pythonmac-SIG