==============================
Project Builder Python Support
==============================
:Author: Bill Bumgarner
:Contact: <bbum@codefab.com>
:Version: 0.1 (unsupported)
:Date: 12/16/2002

.. WARNING::
   None of this is documented or supported by **Apple**.  Don't ask **Apple** for
   support and don't blame me if something breaks.  A lot could break as
   **Project Builder** stores a tremendous amount of highly dynamic information in
   both the user defaults and within project files.

.. Contents::

Triple-quoted strings are not always treated correctly by Project Builder. This
seems to be a Project Builder bug.

Installation
------------

Create the directory 'Specifications' within
*~/Developer/ProjectBuilder Extras/* or */Developer/ProjectBuilder
Extras/*::

    mkdir -p ~/Developer/ProjectBuilder\ Extras/Specifications/

Copy the specification files into that directory::

    cp Python.pb*spec ~/Developer/ProjectBuilder\ Extras/Specifications/

The binary installer will install the specifications for you.

Documentation
-------------

The version of Project Builder that ships with the December Developer Tools
modularizes the support for file types and syntax based colorizing of
source files.  The base mechanisms and definitions are found in:

file:///System/Library/PrivateFrameworks/PBXCore.framework/Resources/

Not surprisingly, Apple has provided a mechanism for augmenting and
overriding the configuration information found within the PBXCore
framework.  By creating a 'Specifications' directory within any of the
*ProjectBuilder Extras* directories (*/Developer/ProjectBuilder Extras*
and *~/Developer/ProjectBuilder Extras* being the two most common).

All of the various specification files are simply property lists.  The file
names do not appear to be significant beyond the extension.  That is,
*Python.pblangspec* could have been called *Foo.pblangspec* and it would still
work as expected.

The contents of the two files were determined largely by looking through the
files found in the PBXCore framework.  The list of keywords for python was
generated by python itself::

      In [1]: import keyword            
      In [2]: keyword.kwlist
      Out[2]: 
      ['and',
       'assert',
       'break',
       'class',
       'continue',
       'def',
       'del',
       'elif',
       'else',
       'except',
       'exec',
       'finally',
       'for',
       'from',
       'global',
       'if',
       'import',
       'in',
       'is',
       'lambda',
       'not',
       'or',
       'pass',
       'print',
       'raise',
       'return',
       'try',
       'while',
       'yield']

To Do
-----

- NOTE: PyObjC's Project Builder support is unmaintained.  It is unlikely that
  any of these items will ever be completed.

- There are a number of other specification files found within the PBXCore.  Of
  particular relevance to Python would be the Compiler Specifications.  It
  would be extremely handy to be able to check syntax and compile Python code
  from within PBX directly.   This appears to be a matter of both specifying
  how the compiler should be invoked and providing a set of regular
  expressions for parsing the output.

- Instead of invoking Python directly, a compiler specification that used
  PyChecker_ would provide both syntactical checker and higher level script
  integrity tests. 

- Expanding the language definition to include a list of alternative keywords
  would provide for highlighting many common Python constructs and modules, as
  well.

- Looking at the internals to PBXCore, support for context-clicking (i.e. cmd-
  and opt- double-clicking on keywords found in Python source) could be
  supported if one were to build a custom Python Parser/Lexer as a PBX
  plugin.

- Support for Jython.  On the syntax front, this would be a matter of
  duplicating a number of the keyword bits from the Java configuration.  On
  the compiler front, support would focus on feeding through to the mechanism
  that turns Python source into .class files.   All of this assumes that
  Python and Jython source can (and should?) be differentiated.

.. _PyChecker: http://pychecker.sourceforge.net/