Commits

Ronald Oussoren committed feefa47

- Remove users.txt and warts.txt (+ HTML version), the information in these
files has been transfered to intro.txt
- Update PyObjCTools.txt
- Clearly state the pyobjc-api.h is not yet a stable api in wrapping.txt and
C-API.txt.
- Add a note about triple-quoted strings to PB-SytaxHighlighting.txt
- Update TODO
- Regenerate HTML

  • Participants
  • Parent commits 39f1475

Comments (0)

Files changed (23)

pyobjc/Doc/C-API.html

 <body>
 <h2>Documentation for the PyObjC C-API (Preliminary)</h2>
 <h2><a name="introduction">Introduction</a></h2>
-<p><i>WARNING: This API is unstable and might change in the future.</i></p>
+<p><i>WARNING: This API is unstable and might change in the future. Please let
+us know if you want to use the C-API in your own code</i></p>
 <p>The PyObjC package can be extended in C (or more likely Objective-C) using
 the C API described in this document. This API should be used to write
 custom wrappers for &quot;hard&quot; methods and to create/access Objective-C proxy

pyobjc/Doc/C-API.txt

 Introduction
 ------------
 
-*WARNING: This API is unstable and might change in the future.*
+*WARNING: This API is unstable and might change in the future. Please let
+us know if you want to use the C-API in your own code*
 
 The PyObjC package can be extended in C (or more likely Objective-C) using
 the C API described in this document. This API should be used to write

pyobjc/Doc/ProjectBuilder-SyntaxHighlighting.html

 <li><a href="#to-do" id="id4" name="id4">To Do</a></li>
 <li><a href="#misc" id="id5" name="id5">Misc.</a></li>
 </ul>
+<p>Triple-quoted strings are not always treated correctly by Project Builder. This
+seems to be a Project Builder bug.</p>
 <h2><a href="#id2" name="installation">Installation</a></h2>
 <p>Create the directory 'Specifications' within
 <i>~/Developer/ProjectBuilder Extras/</i> or <i>/Developer/ProjectBuilder
 <pre>
 cp Python.pb*spec ~/Developer/ProjectBuilder\ Extras/Specifications/
 </pre>
+<p>The binary installer will install the specifications for you.</p>
 <h2><a href="#id3" name="documentation">Documentation</a></h2>
 <p>The version of Project Builder that ships with the December Developer Tools
 modularizes the support for file types and syntax based colorizing of

pyobjc/Doc/ProjectBuilder-SyntaxHighlighting.txt

 
 .. Contents::
 
+Triple-quoted strings are not always treated correctly by Project Builder. This
+seems to be a Project Builder bug.
+
 Installation
 ------------
 
 
     cp Python.pb*spec ~/Developer/ProjectBuilder\ Extras/Specifications/
 
+The binary installer will install the specifications for you.
+
 Documentation
 -------------
 
 
 .. _reStructuredText: http://docutils.sourceforge.net/docs/rst/quickstart.html
 .. __: http://docutils.sourceforge.net/
-.. _PyChecker: http://pychecker.sourceforge.net/
+.. _PyChecker: http://pychecker.sourceforge.net/

pyobjc/Doc/PyObjCTools.html

 </ul>
 <p>A python API for working with Key-Value Coding. XXX: Link</p>
 <ul>
-<li><code><span>PyObjCTools.KeyValueCodingSupport.py</span></code></li>
-</ul>
-<p>Utility functions and mix-in classes for working with Key-Value Coding. This
-module is deprecated.</p>
-<ul>
 <li><code><span>PyObjCTools.NibClassBuilder.py</span></code></li>
 </ul>
 <p>Module containing a magic super-class that can read information about the
 </ul>
 <p>Module that tries to print usefull information when the program gets a fatal
 exception. This module should only be used during development.</p>
+<h2><a name="pyobjctools-apphelper"><code><span>PyObjCTools.AppHelper</span></code></a></h2>
+<p>This module exports two functions that are usefull when working with the
+<code><span>AppKit</span></code> framework.</p>
+<ul>
+<li><code><span>endSheetMethod(method)</span> <span>-&gt;</span> <span>selector</span></code><p>Convert a method to a form that is suitable to use as the delegate callback
+for sheet methods.</p>
+</li>
+<li><code><span>runEventLoop(argv=None,</span> <span>unexpectedErrorAlert=unexpectedErrorAlert)</span> <span>-&gt;</span> <span>None</span></code><p>Run the evenloop using <code><span>NSApplicationMain</span></code> and ask the user if we should
+continue if an exception is caught.</p>
+<p>This function doesn't return unless it throws an exception.</p>
+</li>
+</ul>
+<h2><a name="pyobjctools-conversion-py"><code><span>PyObjCTools.Conversion.py</span></code></a></h2>
+<p>Functions for converting between Cocoa and pure Python data structures.</p>
+<ul>
+<li><code><span>propertyListFromPythonCollection(pyCol,</span> <span>conversionHelper=None)</span> <span>-&gt;</span> <span>ocCol</span></code><p>Convert a Python collection (dictionary, array, tuple, string) into an 
+Objective-C collection.</p>
+<p>If conversionHelper is defined, it must be a callable.  It will be called 
+for any object encountered for which <code><span>propertyListFromPythonCollection()</span></code>
+cannot automatically convert the object.   The supplied helper function 
+should convert the object and return the converted form.  If the conversion 
+helper cannot convert the type, it should raise an exception or return None.</p>
+</li>
+<li><code><span>pythonCollectionFromPropertyList(ocCol,</span> <span>conversionHelper=None)</span> <span>-&gt;</span> <span>pyCol</span></code><p>Converts a Foundation based collection-- a property list-- into a Python 
+collection.  Like <code><span>propertyListFromPythonCollection()</span></code>, <code><span>conversionHelper</span></code>
+is an optional callable that will be invoked any time an encountered object 
+cannot be converted.</p>
+</li>
+</ul>
+<h2><a name="pyobjctools-keyvaluecoding"><code><span>PyObjCTools.KeyValueCoding</span></code></a></h2>
+<p>A module for working with Key-Value Coding in python. Key-Value coding is
+explained <a href="http://developer.apple.com/documentation/Cocoa/Conceptual/KeyValueCoding/index.html#//apple_ref/doc/uid/10000107i">on the apple website</a></p>
+<p>This module provides a python interface to some of that functionality. The
+interface is modelled on the <code><span>getattr</span></code> and <code><span>setattr</span></code> functions.</p>
+<ul>
+<li><code><span>getKey(object,</span> <span>key)</span> <span>-&gt;</span> <span>value</span></code><p>Find the value for <code><span>key</span></code>. Raises <code><span>KeyError</span></code> if the key is not a valid
+attribute of the object.</p>
+<p>To find the value of a key the following values are tried for a key named
+<code><span>key</span></code> (first match wins):</p>
+<ul>
+<li>the return value of <code><span>object.get_key()</span></code></li>
+<li>the return value of <code><span>object.getKey()</span></code></li>
+<li>the return value of <code><span>object._get_key()</span></code></li>
+<li>the return value of <code><span>object._getKey()</span></code></li>
+<li>the value of the attribute <code><span>key</span></code></li>
+<li>the value of the attribue <code><span>_key</span></code></li>
+</ul>
+</li>
+<li><code><span>getKeyPath(object,</span> <span>keypath)</span> <span>-&gt;</span> <span>value</span></code><p>Like <code><span>getKey</span></code> but using a key path. The <code><span>keypath</span></code> is a sequence of keys
+seperated by dots. It calls <code><span>getKey</span></code> to follow the path and returns the
+final value.</p>
+</li>
+<li><code><span>setKey(object,</span> <span>key,</span> <span>value)</span> <span>-&gt;</span> <span>None</span></code><p>Set the value of <code><span>key</span></code> to <code><span>value</span></code>.</p>
+<p>The following values are used for setting the value for a key named <code><span>key</span></code>
+(first match wins):</p>
+<ul>
+<li>Call <code><span>object.set_key(value)</span></code></li>
+<li>Call <code><span>object.setKey(value)</span></code></li>
+<li>Call <code><span>object._set_key(value)</span></code></li>
+<li>Call <code><span>object._setKey(value)</span></code></li>
+<li>Check if <code><span>_key</span></code> is an attribute and if so, set its value</li>
+<li>Try to set the attribute <code><span>key</span></code>.</li>
+</ul>
+<p>Raises <code><span>KeyError</span></code> if the key cannot be changed.</p>
+</li>
+<li><code><span>setKeyPath(object,</span> <span>keypath,</span> <span>value)</span> <span>-&gt;</span> <span>None</span></code><p>The same as <code><span>setKey</span></code>, but now using a key path. A key path is a sequence
+of keys seperated by dots. The <code><span>getKey</span></code> function is used to traverse 
+the path upto the last item, and then <code><span>setKey</span></code> is used to change the value.</p>
+</li>
+</ul>
+<h2><a name="pyobjctools-nibclassbuilder">PyObjCTools.NibClassBuilder</a></h2>
+<p>XXX: Read the online documetation</p>
+<h2><a name="pyobjctools-signals">PyObjCTools.Signals</a></h2>
+<p>XXX: Read the online documetation</p>
+<h2><a name="pyobjctools-pluginbuilder">PyObjCTools.pluginbuilder</a></h2>
+<p>XXX: Read the online documetation</p>
 </body>
 </html>

pyobjc/Doc/PyObjCTools.txt

 
 A python API for working with Key-Value Coding. XXX: Link
 
-* ``PyObjCTools.KeyValueCodingSupport.py``
-
-Utility functions and mix-in classes for working with Key-Value Coding. This
-module is deprecated.
-
 * ``PyObjCTools.NibClassBuilder.py``
 
 Module containing a magic super-class that can read information about the
 
 Module that tries to print usefull information when the program gets a fatal
 exception. This module should only be used during development.
+
+
+``PyObjCTools.AppHelper``
+.........................
+
+This module exports two functions that are usefull when working with the
+``AppKit`` framework.
+
+* ``endSheetMethod(method) -> selector``
+
+  Convert a method to a form that is suitable to use as the delegate callback
+  for sheet methods.
+
+* ``runEventLoop(argv=None, unexpectedErrorAlert=unexpectedErrorAlert) -> None``
+
+  Run the evenloop using ``NSApplicationMain`` and ask the user if we should
+  continue if an exception is caught.
+
+  This function doesn't return unless it throws an exception.
+
+
+``PyObjCTools.Conversion.py``
+.............................
+
+Functions for converting between Cocoa and pure Python data structures.
+
+* ``propertyListFromPythonCollection(pyCol, conversionHelper=None) -> ocCol``
+
+  Convert a Python collection (dictionary, array, tuple, string) into an 
+  Objective-C collection.
+
+  If conversionHelper is defined, it must be a callable.  It will be called 
+  for any object encountered for which ``propertyListFromPythonCollection()``
+  cannot automatically convert the object.   The supplied helper function 
+  should convert the object and return the converted form.  If the conversion 
+  helper cannot convert the type, it should raise an exception or return None.
+
+* ``pythonCollectionFromPropertyList(ocCol, conversionHelper=None) -> pyCol``
+
+  Converts a Foundation based collection-- a property list-- into a Python 
+  collection.  Like ``propertyListFromPythonCollection()``, ``conversionHelper``
+  is an optional callable that will be invoked any time an encountered object 
+  cannot be converted.
+
+``PyObjCTools.KeyValueCoding``
+..............................
+
+A module for working with Key-Value Coding in python. Key-Value coding is
+explained `on the apple website`__
+
+.. __: http://developer.apple.com/documentation/Cocoa/Conceptual/KeyValueCoding/index.html#//apple_ref/doc/uid/10000107i
+
+This module provides a python interface to some of that functionality. The
+interface is modelled on the ``getattr`` and ``setattr`` functions.
+
+* ``getKey(object, key) -> value``
+
+  Find the value for ``key``. Raises ``KeyError`` if the key is not a valid
+  attribute of the object.
+
+  To find the value of a key the following values are tried for a key named
+  ``key`` (first match wins):
+
+  - the return value of ``object.get_key()``
+
+  - the return value of ``object.getKey()``
+
+  - the return value of ``object._get_key()``
+
+  - the return value of ``object._getKey()``
+
+  - the value of the attribute ``key``
+
+  - the value of the attribue ``_key``
+
+* ``getKeyPath(object, keypath) -> value``
+
+  Like ``getKey`` but using a key path. The ``keypath`` is a sequence of keys
+  seperated by dots. It calls ``getKey`` to follow the path and returns the
+  final value.
+
+* ``setKey(object, key, value) -> None``
+
+  Set the value of ``key`` to ``value``.
+
+  The following values are used for setting the value for a key named ``key``
+  (first match wins):
+
+  - Call ``object.set_key(value)``
+
+  - Call ``object.setKey(value)``
+
+  - Call ``object._set_key(value)``
+
+  - Call ``object._setKey(value)``
+
+  - Check if ``_key`` is an attribute and if so, set its value
+
+  - Try to set the attribute ``key``.
+
+  Raises ``KeyError`` if the key cannot be changed.
+
+* ``setKeyPath(object, keypath, value) -> None``
+
+  The same as ``setKey``, but now using a key path. A key path is a sequence
+  of keys seperated by dots. The ``getKey`` function is used to traverse 
+  the path upto the last item, and then ``setKey`` is used to change the value.
+
+PyObjCTools.NibClassBuilder
+...........................
+
+XXX: Read the online documetation
+
+PyObjCTools.Signals
+...................
+
+XXX: Read the online documetation
+
+PyObjCTools.pluginbuilder
+.........................
+
+XXX: Read the online documetation
 
 NOTE3: This is not really an important item.
 
+XXX (Ronald): I'll probably add PEP311 support after we do a release  with
+Panther support. This would make it safer to use PyObjC embedded in an 
+multithreaded application. Specifically: grab the GIL when going from ObjC
+to python, and release it when going back again. This is a half-way solution.
 
 Test suite
 ..........
 Implement the Key-Value encoding protocol for Py-ObjC hybrids, in a Pythonic
 way. Do the same in OC_PythonObject (e.g. for pure-python objects used from
 Objective-C)
+
+Formal Protocols, Distributed Objects
+.....................................
+
+``DO`` seems to use formal protocols, we don't support those at all. 
+
+Links to Apple documentation
+............................
+
+Links to Apple documentation are not stable, can we add a layer of indirection
+here, e.g. link to the PyObjC website that will redirect to the right
+location?
+
+But: we should also provide links to locally installed documetation, especially
+in the documentation that will be installed on the users machine.

pyobjc/Doc/architecture.html

 </tbody>
 </table>
 <h2><a name="introduction">Introduction</a></h2>
+<p>XXX: This documented is outdated and incomplete.</p>
 <p>This document gives a (brief) description of how the PyObjc package is 
-structured. Too bad this document is outdated and incomplete...</p>
+structured.</p>
 <h2><a name="objective-c-classes-and-objects">Objective-C classes and objects</a></h2>
 <p>Objective-C classes are represented directly as python classes. This allows
 us to implement subclassing of Objective-C classes with the full power that

pyobjc/Doc/architecture.txt

 Introduction
 ------------
 
+XXX: This documented is outdated and incomplete.
+
 This document gives a (brief) description of how the PyObjc package is 
-structured. Too bad this document is outdated and incomplete...
+structured. 
 
 Objective-C classes and objects
 -------------------------------

pyobjc/Doc/intro.html

 :copyright: 2003 The PyObjC Project -->
 <h2>Contents</h2>
 <ul>
-<li><a href="#work-in-progress" id="id3" name="id3">WORK IN PROGRESS</a></li>
-<li><a href="#preface" id="id4" name="id4">Preface</a></li>
-<li><a href="#objective-c-for-pyobjc-users" id="id5" name="id5">Objective-C for PyObjC users</a></li>
-<li><a href="#overview-of-the-bridge" id="id6" name="id6">Overview of the bridge</a><ul>
-<li><a href="#classes" id="id7" name="id7">Classes</a></li>
-<li><a href="#methods-and-functions" id="id8" name="id8">Methods and functions</a></li>
-<li><a href="#reference-counts" id="id9" name="id9">Reference counts</a></li>
+<li><a href="#preface" id="id3" name="id3">Preface</a></li>
+<li><a href="#objective-c-for-pyobjc-users" id="id4" name="id4">Objective-C for PyObjC users</a></li>
+<li><a href="#overview-of-the-bridge" id="id5" name="id5">Overview of the bridge</a><ul>
+<li><a href="#classes" id="id6" name="id6">Classes</a></li>
+<li><a href="#methods-and-functions" id="id7" name="id7">Methods and functions</a></li>
+<li><a href="#reference-counting" id="id8" name="id8">Reference counting</a></li>
+<li><a href="#informal-protocols" id="id9" name="id9">(Informal) protocols</a></li>
 </ul>
 </li>
 <li><a href="#cocoa-for-python-programmers" id="id10" name="id10">Cocoa for Python programmers</a></li>
-<li><a href="#building-applications" id="id11" name="id11">Building applications</a><ul>
-<li><a href="#pure-python-buildapp-py" id="id12" name="id12">&quot;Pure Python&quot; :  buildapp.py</a></li>
-<li><a href="#ide-approach-project-builder" id="id13" name="id13">&quot;IDE approach&quot; : Project builder</a></li>
+<li><a href="#special-tasks" id="id11" name="id11">Special tasks</a><ul>
+<li><a href="#working-with-threads" id="id12" name="id12">Working with threads</a></li>
+</ul>
+</li>
+<li><a href="#building-applications" id="id13" name="id13">Building applications</a><ul>
+<li><a href="#pure-python-buildapp-py" id="id14" name="id14">&quot;Pure Python&quot; :  buildapp.py</a></li>
+<li><a href="#ide-approach-project-builder" id="id15" name="id15">&quot;IDE approach&quot; : Project builder</a></li>
 </ul>
 </li>
 </ul>
-<h2><a href="#id3" name="work-in-progress">WORK IN PROGRESS</a></h2>
-<p>This document is work in progress.</p>
-<h2><a href="#id4" name="preface">Preface</a></h2>
+<h2><a href="#id3" name="preface">Preface</a></h2>
 <p>PyObjC is a bridge between Python and Objective-C. It allows you to write 
 Python scripts that use and extend existing Objective-C class libraries, 
 most importantly the <a href="http://developer.apple.com/techpubs/macosx/Cocoa/CocoaTopics.html">Cocoa libraries</a> by <a href="http://www.apple.com/">Apple</a>.</p>
 <p>This document describes how to use Objective-C class libraries from Python
 scripts and how to interpret the documentation of those libraries, from the 
 point of view of a Python programmer.</p>
-<h2><a href="#id5" name="objective-c-for-pyobjc-users">Objective-C for PyObjC users</a></h2>
+<h2><a href="#id4" name="objective-c-for-pyobjc-users">Objective-C for PyObjC users</a></h2>
 <p>It is necessary to understand a little bit of Objective-C to use PyObjC,
 this helps you to better understand the class libraries and makes it easier
 to read (and translate) example code.</p>
 recovery and not for normal error handling you won't see them very often
 in example code. The <a href="http://developer.apple.com/techpubs/macosx/Cocoa/ObjectiveC/index.html">The Objective-C Programming Language</a> if you want to
 know more about exceptions in Objective-C.</p>
+<p>One thing to keep in mind when translating Objective-C snippets to python is
+that it is valid to call methods on <code><span>nil</span></code> (that is the NULL pointer). Those
+method calls are ignored by the runtime. The value <code><span>nil</span></code> is represented in
+Python by the <code><span>None</span></code>, this means that calls to non-existing methods are
+not ignored but will raise <code><span>AttributeError</span></code>.</p>
 <p>For more information about Objective-C see:</p>
 <ul>
 <li><a href="http://developer.apple.com/techpubs/macosx/Cocoa/ObjectiveC/index.html">The Objective-C Programming Language</a> at <a href="http://www.apple.com/">Apple</a>.</li>
 </ul>
-<h2><a href="#id6" name="overview-of-the-bridge">Overview of the bridge</a></h2>
-<h3><a href="#id7" name="classes">Classes</a></h3>
-<p>Objective-C classes are visible as Python classes and can be subclassed just
-like normal Python classes. The major differences between normal Python classes
-and Objective-C classes are the way you create instances and the fact that 
-Objective-C methods have odd names.</p>
+<h2><a href="#id5" name="overview-of-the-bridge">Overview of the bridge</a></h2>
+<h3><a href="#id6" name="classes">Classes</a></h3>
+<p>Objective-C classes are visible as (new-style) Python classes and can be 
+subclassed just like normal Python classes. All the usual introspection
+mechanism work as well, as do __slots__ and descriptors. The major 
+differences between normal Python classes and Objective-C classes are the way 
+you create instances and the fact that Objective-C methods have odd names.</p>
+<p>You can use multiple inheritance with Objective-C classes, as long as the
+Objetive-C is the first base-class and there is only one Objective-C 
+base-class. E.g. it is not possible to subclass from the Objective-C classes
+at the same time. Multiple inheritance should also not be used to mix-in
+different implementations for Objective-C methods, that will not work and
+you won't get errors about this.</p>
 <p>Another thing to keep in mind is that the names of Objective-C classes must
 be unique, without taking modules into account. That is, it is <i>not</i> possible
 to have two modules that define a class with the same name. If you write classes
 then call some variation of <code><span>init</span></code> to initialize the objects. The newly
 created object is the result of the call to <code><span>init</span></code>. Most classes have 
 convienence class methods that combine the calls to <code><span>alloc</span></code> and <code><span>init</span></code>.</p>
-<h3><a href="#id8" name="methods-and-functions">Methods and functions</a></h3>
+<h3><a href="#id7" name="methods-and-functions">Methods and functions</a></h3>
 <p>Objective-C methods are bridged to Python callables. Because Objective-C method 
 names can contain colons it is necessary to translate methods names. The rules
 for translation are:</p>
 
         someMethod_ = objc.selector(someMethod_, ...)
 </pre>
-<h3><a href="#id9" name="reference-counts">Reference counts</a></h3>
+<h3><a href="#id8" name="reference-counting">Reference counting</a></h3>
 <p>The <a href="http://developer.apple.com/techpubs/macosx/Cocoa/CocoaTopics.html">Cocoa libraries</a>, and most (if not all) other class libraries for 
 Objective-C use explicit reference counting to manage memory. The methods
 <code><span>retain</span></code>, <code><span>release</span></code> and <code><span>autorelease</span></code> are used to manage these 
 <code><span>outlineView:child:ofItem:</span></code> of its data source. The easiest way to avoid
 crashes with outline views is to make sure that you model for the view uses
 subclasses of <code><span>NSObject</span></code> to represent the nodes in the outline view.</p>
+<p>Another gotcha is when you're manually allocating and assigning delegate(-like)
+objects: most of the time <code><span>obj.setDelegate_()</span></code> will <i>not</i> retain the 
+delegate, so you must keep a reference manually.</p>
+<h3><a href="#id9" name="informal-protocols">(Informal) protocols</a></h3>
+<p>Cocoa defines a number of formal and informal protocols that specify methods
+that should be implemented by a class if it is to be used in a specific role,
+such as the data source for an NSTableView.</p>
+<p>Those protocols are represented by instances of <code><span>objc.informal_protocol</span></code>. The
+only ones that have to care about these objects are the maintainers of 
+wrappers around Objective-C frameworks: they have to keep these protocol
+wrappers up-to-date.</p>
+<p>PyObjC will automaticly use the information in the <code><span>informal_protocol</span></code> 
+objects to add the right method signatures to methods, and to warn about
+classes that partially implement a protocol.</p>
 <h2><a href="#id10" name="cocoa-for-python-programmers">Cocoa for Python programmers</a></h2>
 <p>Cocoa frameworks are mapped onto Python packages with the same name, that is
 the classes, constants and functioins from the AppKit framework are available
 after you import <code><span>AppKit</span></code> in your Python script.</p>
 <p>These helper modules contain <i>only</i> functions, constants and classes that 
 wrap items in the corresponding framework. All utility functions and classes 
-are located in the <code><span>PyObjCTools</span></code> package and <code><span>objc</span></code> module.</p>
+are located in the <code><span>PyObjCTools</span></code> package and <code><span>objc</span></code> module. Note that it
+is possible to use <code><span>pydoc</span></code> (or the <code><span>help()</span></code>) function with the framework
+wrappers, but that this is not very usefull for the entire module due to the
+size of these modules.</p>
 <p>This makes it easier to find documentation for an item: if you import it 
 from the wrapper module for an Objective-C framework the documentation for
 that item can be found in the documentation for the framework, otherwise the
 <li><a href="http://www.stepwise.com/">stepwise.com</a></li>
 <li>Your local bookstore or library</li>
 </ul>
-<h2><a href="#id11" name="building-applications">Building applications</a></h2>
+<h2><a href="#id11" name="special-tasks">Special tasks</a></h2>
+<p>XXX: Rename this section</p>
+<h3><a href="#id12" name="working-with-threads">Working with threads</a></h3>
+<p>When you create a thread and want to use PyObjC from that thread you will
+have to create an <code><span>NSAutoreleasePool</span></code> in that thread and clean it up when
+you're done. The easiest way to that is to create an instance of that class
+bound to a local variable. If the thread is long-lived you may want to arrange
+for recycling the pool once in a while.</p>
+<p>There are some limitiation w.r.t. threading. You cannot use <code><span>NSThread</span></code> to 
+create new threads, but must use the python primitives instead.</p>
+<p>You must also make sure that Objective-C only makes calls to Python from a 
+thread that owns the Python GIL (that's also the reason for not being able 
+to use <code><span>NSThread</span></code> to create new threads).  This restriction will be lifted
+in a future version of PyObjC (at least when using Python 2.3).</p>
+<h2><a href="#id13" name="building-applications">Building applications</a></h2>
 <p>There are two different ways to build applications with PyObjC. There are no
 major advantages to using either one of them, use the one that is most 
 convenient to you.</p>
-<h3><a href="#id12" name="pure-python-buildapp-py">&quot;Pure Python&quot; :  buildapp.py</a></h3>
+<h3><a href="#id14" name="pure-python-buildapp-py">&quot;Pure Python&quot; :  buildapp.py</a></h3>
 <p>PyObjC includes a copy of the <code><span>bundlebuilder</span></code> module. This module will be
 part of the Python 2.3 MacPython release and offers a way to build
 distutils-style scripts  for building (standalone) applications.</p>
 <p>The online documentation for <code><span>bundlebuilder</span></code> contains more information on 
 building <code><span>buildapp.py</span></code> scripts and how to invoke them. There are plenty of
 example <code><span>buildapp.py</span></code> scripts in the various <a href="../Examples/00ReadMe.txt">Examples</a> subfolders.</p>
-<h3><a href="#id13" name="ide-approach-project-builder">&quot;IDE approach&quot; : Project builder</a></h3>
+<h3><a href="#id15" name="ide-approach-project-builder">&quot;IDE approach&quot; : Project builder</a></h3>
 <p>PyObjC includes a number of Project Builder templates that can be used to 
 build (standalone) applications. Those templates are used like any other
 Project Builder template. The only non-obvious detail is that you have to

pyobjc/Doc/intro.txt

 
 .. contents::
 
-WORK IN PROGRESS
-----------------
-
-This document is work in progress.
-
-
 Preface
 -------
 
 in example code. The `The Objective-C Programming Language`_ if you want to
 know more about exceptions in Objective-C. 
 
+One thing to keep in mind when translating Objective-C snippets to python is
+that it is valid to call methods on ``nil`` (that is the NULL pointer). Those
+method calls are ignored by the runtime. The value ``nil`` is represented in
+Python by the ``None``, this means that calls to non-existing methods are
+not ignored but will raise ``AttributeError``.
+
 For more information about Objective-C see:
 
 * `The Objective-C Programming Language`_ at `Apple`_.
 Classes
 .......
 
-Objective-C classes are visible as Python classes and can be subclassed just
-like normal Python classes. The major differences between normal Python classes
-and Objective-C classes are the way you create instances and the fact that 
-Objective-C methods have odd names.
+Objective-C classes are visible as (new-style) Python classes and can be 
+subclassed just like normal Python classes. All the usual introspection
+mechanism work as well, as do __slots__ and descriptors. The major 
+differences between normal Python classes and Objective-C classes are the way 
+you create instances and the fact that Objective-C methods have odd names.
+
+You can use multiple inheritance with Objective-C classes, as long as the
+Objetive-C is the first base-class and there is only one Objective-C 
+base-class. E.g. it is not possible to subclass from the Objective-C classes
+at the same time. Multiple inheritance should also not be used to mix-in
+different implementations for Objective-C methods, that will not work and
+you won't get errors about this.
 
 Another thing to keep in mind is that the names of Objective-C classes must
 be unique, without taking modules into account. That is, it is *not* possible
 
 		someMethod_ = objc.selector(someMethod_, ...)
 
-Reference counts
-................
+Reference counting
+..................
 
 The `Cocoa libraries`_, and most (if not all) other class libraries for 
 Objective-C use explicit reference counting to manage memory. The methods
 crashes with outline views is to make sure that you model for the view uses
 subclasses of ``NSObject`` to represent the nodes in the outline view.
 
+Another gotcha is when you're manually allocating and assigning delegate(-like)
+objects: most of the time ``obj.setDelegate_()`` will *not* retain the 
+delegate, so you must keep a reference manually.
+
+(Informal) protocols
+....................
+
+Cocoa defines a number of formal and informal protocols that specify methods
+that should be implemented by a class if it is to be used in a specific role,
+such as the data source for an NSTableView.
+
+Those protocols are represented by instances of ``objc.informal_protocol``. The
+only ones that have to care about these objects are the maintainers of 
+wrappers around Objective-C frameworks: they have to keep these protocol
+wrappers up-to-date.
+
+PyObjC will automaticly use the information in the ``informal_protocol`` 
+objects to add the right method signatures to methods, and to warn about
+classes that partially implement a protocol.
+
 
 Cocoa for Python programmers
 ----------------------------
 
 .. _`stepwise.com`: http://www.stepwise.com/
 
+Special tasks
+-------------
+
+XXX: Rename this section
+
+Working with threads
+....................
+
+When you create a thread and want to use PyObjC from that thread you will
+have to create an ``NSAutoreleasePool`` in that thread and clean it up when
+you're done. The easiest way to that is to create an instance of that class
+bound to a local variable. If the thread is long-lived you may want to arrange
+for recycling the pool once in a while.
+
+There are some limitiation w.r.t. threading. You cannot use ``NSThread`` to 
+create new threads, but must use the python primitives instead. 
+
+You must also make sure that Objective-C only makes calls to Python from a 
+thread that owns the Python GIL (that's also the reason for not being able 
+to use ``NSThread`` to create new threads).  This restriction will be lifted
+in a future version of PyObjC (at least when using Python 2.3).
+
 
 Building applications
 ---------------------

pyobjc/Doc/release-process.html

 <h2><a name="release-date-3-days">Release-date -3 days</a></h2>
 <p>Build the release tarball and dmg:</p>
 <ul>
+<li>Add the correct date to the NEWS file, and set the right version in
+<code><span>Modules/objc/pyobjc.h</span></code>.</li>
 <li>Run Scripts/make_distrib.py</li>
 <li>Create an empty disk image (named <code><span>PyObjC</span> <span>X.Y</span></code>) and copy the installer
 package, License and ReadMe to this disk image. Resize the icons in this

pyobjc/Doc/structure.html

 <!-- This document is in structured text markup to enable easy translation to 
 HTML. -->
 <h2><a name="introduction">Introduction</a></h2>
+<p>XXX:  This documet is outdated and incomplete.</p>
 <p>This document gives an overview of the PyObjC for developers (of the package).</p>
 <p>One of the sections describes how all of it works, and some of the limitation.</p>
 <p>This document is a little dated, it should be updated.</p>

pyobjc/Doc/structure.txt

 Introduction
 ------------
 
+XXX:  This documet is outdated and incomplete.
+
 This document gives an overview of the PyObjC for developers (of the package).
 
 One of the sections describes how all of it works, and some of the limitation.

pyobjc/Doc/users.html

-<?xml version="1.0" encoding="utf-8" ?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<title>
-Userguide for PyObjC</title>
-</head>
-<body>
-<h2>Userguide for PyObjC</h2>
-<!-- This file is formatted using the rules for StructuredText -->
-<h2><a name="introduction">Introduction</a></h2>
-<p>This is the user guide for PyObjC. It describes how to use this package to
-implement Python scripts that use Objective-C classes and objects. It also
-describes the limitations of this Package.</p>
-<p>The last section describes the C API of this package and why you may want to
-use it.</p>
-<h2><a name="overview">Overview</a></h2>
-<p>Using PyObjC is pretty simple, as it strives to make the bridge completely
-transparent. On the lowest level you can import the 'objc' module and use that
-to locate classes (objc.lookUpClass). For most users it is more usefull to
-just import 'Foundation' and 'AppKit' and use the familiar Cocoa classes
-and functions.</p>
-<p>Objective-C classes are make available as new-style classes, and can be queried
-using the normal introspection techniques.</p>
-<p>Methodnames for Objective-C classes are constructed as follows: Concatenate all 
-elements of the selector and replace colons by underscores.</p>
-<p>The order of arguments is the same as in Objective-C, with one exception: If
-a method as output-only arguments those arguments are not present in the python
-version of the method. If a method has output parameters (either input-output
-or output-only) the values of these parameters are passed back in the return
-value of the python version. The return value of methods with output parameters
-is a tuple where the first element is the return-value of the Objective-C 
-method (or None if it is a method returning 'void') and the other elements are
-the values of output arguments.</p>
-<h2><a name="informal-protocols">(Informal) Protocols</a></h2>
-<p>Cocoa defines a number of formal and informal protocols that specify the 
-methods that should be defined by a class if it wants to be used in particular
-roles (such as the data source for an NSTableView).</p>
-<p>The type objc.informal_protocol can be used to specify the selectors used by
-those (informal) protocols in Objective-C. Instances of objc.informal_protocol 
-are used when defineing subclasses of Objective-C classes and signal that the 
-class implements the given protocol.</p>
-<p>The AppKit and Foundation modules export a number of usefull protocols, 
-corresponding to the protocols defined in the Cocoa documentation. It is 
-essential to use these protocol definitions as mixins when defining classes that
-conform to the protocol. This not only helps catching typos when developing
-classes, but also provides information to the bridge that is essential for
-correct operation of the bridge.</p>
-<h2><a name="building-an-application">Building an application</a></h2>
-<p>There are two different ways to build application bundles. The resulting 
-applications are functionally equivalent, although not identical.</p>
-<p>If Apple's developer tools are installed you can use one of the PyObjC 
-project templates to build your application. (TODO: Add link to documentation
-on the templates). The <code><span>TableModel2</span></code> example uses Project Builder.</p>
-<p>If is also possible to build application bundles using bundlebuilder, using
-scripts that are simular to the <code><span>setup.py</span></code> script used by distutils. The
-<code><span>TableModel</span></code> example uses this method. For more documentation, see the
-online documentation of module <code><span>bundlebuilder</span></code>.</p>
-<h2><a name="limitations">Limitations</a></h2>
-<p>The objc module automaticly wraps classes and objects. This works correctly in
-the easy case where there are no methods with variable arguments or 
-pass-by-reference arguments. If there are, the core module needs some help.</p>
-<p>For this reason it is best to not use just the core API when your working with
-this module, but to use packages like 'Foundation' that provide the help 
-needed and might also wrap other functionality (constants, functions) in a framework.</p>
-<p>The current version of the module does not provide support for threading. It
-might be possible to create threads using the 'thread' module if you manually
-create an NSAutoreleasePool for the thread. This has not been tested. The
-Cocoa threading classes should not be used because they don't update the 
-state of the Python interpreter when creating a new thread.</p>
-</body>
-</html>

pyobjc/Doc/users.txt

-====================
-Userguide for PyObjC
-====================
-
-.. This file is formatted using the rules for StructuredText
-
-Introduction
-------------
-
-This is the user guide for PyObjC. It describes how to use this package to
-implement Python scripts that use Objective-C classes and objects. It also
-describes the limitations of this Package. 
-
-The last section describes the C API of this package and why you may want to
-use it.
-
-Overview
---------
-
-Using PyObjC is pretty simple, as it strives to make the bridge completely
-transparent. On the lowest level you can import the 'objc' module and use that
-to locate classes (objc.lookUpClass). For most users it is more usefull to
-just import 'Foundation' and 'AppKit' and use the familiar Cocoa classes
-and functions.
-
-Objective-C classes are make available as new-style classes, and can be queried
-using the normal introspection techniques. 
-
-Methodnames for Objective-C classes are constructed as follows: Concatenate all 
-elements of the selector and replace colons by underscores. 
-
-The order of arguments is the same as in Objective-C, with one exception: If
-a method as output-only arguments those arguments are not present in the python
-version of the method. If a method has output parameters (either input-output
-or output-only) the values of these parameters are passed back in the return
-value of the python version. The return value of methods with output parameters
-is a tuple where the first element is the return-value of the Objective-C 
-method (or None if it is a method returning 'void') and the other elements are
-the values of output arguments.
-
-(Informal) Protocols
---------------------
-
-Cocoa defines a number of formal and informal protocols that specify the 
-methods that should be defined by a class if it wants to be used in particular
-roles (such as the data source for an NSTableView).
-
-The type objc.informal_protocol can be used to specify the selectors used by
-those (informal) protocols in Objective-C. Instances of objc.informal_protocol 
-are used when defineing subclasses of Objective-C classes and signal that the 
-class implements the given protocol. 
-
-The AppKit and Foundation modules export a number of usefull protocols, 
-corresponding to the protocols defined in the Cocoa documentation. It is 
-essential to use these protocol definitions as mixins when defining classes that
-conform to the protocol. This not only helps catching typos when developing
-classes, but also provides information to the bridge that is essential for
-correct operation of the bridge.
-
-Building an application
------------------------
-
-There are two different ways to build application bundles. The resulting 
-applications are functionally equivalent, although not identical.
-
-If Apple's developer tools are installed you can use one of the PyObjC 
-project templates to build your application. (TODO: Add link to documentation
-on the templates). The ``TableModel2`` example uses Project Builder.
-
-
-If is also possible to build application bundles using bundlebuilder, using
-scripts that are simular to the ``setup.py`` script used by distutils. The
-``TableModel`` example uses this method. For more documentation, see the
-online documentation of module ``bundlebuilder``.
-
-Limitations
------------
-
-The objc module automaticly wraps classes and objects. This works correctly in
-the easy case where there are no methods with variable arguments or 
-pass-by-reference arguments. If there are, the core module needs some help.
-
-For this reason it is best to not use just the core API when your working with
-this module, but to use packages like 'Foundation' that provide the help 
-needed and might also wrap other functionality (constants, functions) in a framework.
-
-The current version of the module does not provide support for threading. It
-might be possible to create threads using the 'thread' module if you manually
-create an NSAutoreleasePool for the thread. This has not been tested. The
-Cocoa threading classes should not be used because they don't update the 
-state of the Python interpreter when creating a new thread.

pyobjc/Doc/warts.html

-<?xml version="1.0" encoding="utf-8" ?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<title>
-Odd features</title>
-</head>
-<body>
-<h2>Odd features</h2>
-<!-- :author: Ronald Oussoren -->
-<p>The mapping from Objective-C onto Python is almost complete, but the following
-things should be kept in mind:</p>
-<ul>
-<li>Objective-C only has single inheritance. You can use multiple inheritance in
-the python code, but only to mix in 'fully python' classes. Do <i>not</i> use 
-multiple inheritance, this feature may not survive beyond 0.9.</li>
-<li>In objective-C it is valid to call methods on nil, these calls will be
-ignored. The nil 'object' is mapped to None and None will not ignore method
-calls, but will most likely raise an AttributeError. You'll have to remember
-this when translating from Objective-C to python.</li>
-<li>Some Cocoa classes store references to objects while not increasing the 
-reference count. One of those is NSOutlineView. A side-effect of this is that
-you <i>must</i> use subclasses of NSObject in your NSOutlineView model, and you
-<i>must</i> keep a reference to the objects you pass to NSOutlineView.  Another
-gotcha is when you're manually allocating and assigning delegate(-like)
-objects: most of the time obj.setDelegate_() will <i>not</i> retain the delegate,
-so you must keep a reference manually.</li>
-</ul>
-</body>
-</html>

pyobjc/Doc/warts.txt

-============
-Odd features
-============
-
-.. :author: Ronald Oussoren
-
-The mapping from Objective-C onto Python is almost complete, but the following
-things should be kept in mind:
-
-- Objective-C only has single inheritance. You can use multiple inheritance in
-  the python code, but only to mix in 'fully python' classes. Do *not* use 
-  multiple inheritance, this feature may not survive beyond 0.9.
-
-- In objective-C it is valid to call methods on nil, these calls will be
-  ignored. The nil 'object' is mapped to None and None will not ignore method
-  calls, but will most likely raise an AttributeError. You'll have to remember
-  this when translating from Objective-C to python.
-
-- Some Cocoa classes store references to objects while not increasing the 
-  reference count. One of those is NSOutlineView. A side-effect of this is that
-  you *must* use subclasses of NSObject in your NSOutlineView model, and you
-  *must* keep a reference to the objects you pass to NSOutlineView.  Another
-  gotcha is when you're manually allocating and assigning delegate(-like)
-  objects: most of the time obj.setDelegate_() will *not* retain the delegate,
-  so you must keep a reference manually.

pyobjc/Doc/website.lst

 # This should be done inline, I don't know how at the moment how to do that
 Install.txt,user,0
 intro.txt,user,5
-users.txt,user,10
 tutorial.txt,user,12
 extending_objc_with_python.txt,user,13
 tutorial_reading.txt,user,14
 ProjectBuilder-SyntaxHighlighting.txt,user,15
 PyObjCTools.txt,user,16
 api-notes-macosx.txt,user,17
-warts.txt,user,20
 wrapping.txt,user,30
 coding-style.txt,developer,10
 architecture.txt,developer,30

pyobjc/Doc/wrapping.html

 is all that is needed.</p>
 <p>Don't forget to import the frameworks that are used by your framework before
 calling <code><span>objc.loadBundle</span></code>. This is necessary to arrange for the helper code
-for these modules (if there is any) to be loaded.</p>
+for these modules (if there is any) to be loaded. Not importing the those
+wrappers can lead to subtle bugs in unrelated code!</p>
 <h2><a name="wrapping-global-functions-and-constants">Wrapping global functions and constants</a></h2>
 <p>The code above only provides wrappers for Objective-C classes, if the library
 also defines global functions and/or constants you'll have to write an 
 this module for you. These scripts are both very rough and tuned for the Apple
 headers, so YMMV.</p>
 <p>Note that we currently do not install the <code><span>pyobjc-api.h</span></code> header, you'll have
-to copy it from the source-tree until we do.</p>
+to copy it from the source-tree until we do. This header is not installed 
+because the interface is not yet stable, please let us know if you want to
+use the API.</p>
 <h2><a name="pointer-arguments">Pointer arguments</a></h2>
 <p>Methods with pointer arguments (other then arguments that are equivalent to 
 an 'id') require more work. If the pointer arguments are used to pass a single 
 three functions: 1 to call the method from Python, 1 to call the superclass
 implementation of the method from Python and 1 to call a Python implementation
 of the method from Objective-C.</p>
+<p>You also must write a custom wrapper when the method has a variable number
+of arguments. It is often adviseable to documented varargs method as 
+unsupported, or to support them only using a fixed number of arguments.</p>
 <p>For now it is best to check the source code for the wrappers for the Cocoa 
 class library for more information. We'll add documentation for this in the
 future.</p>

pyobjc/Doc/wrapping.txt

 
 Don't forget to import the frameworks that are used by your framework before
 calling ``objc.loadBundle``. This is necessary to arrange for the helper code
-for these modules (if there is any) to be loaded.
+for these modules (if there is any) to be loaded. Not importing the those
+wrappers can lead to subtle bugs in unrelated code!
 
 Wrapping global functions and constants
 ---------------------------------------
 headers, so YMMV.
 
 Note that we currently do not install the ``pyobjc-api.h`` header, you'll have
-to copy it from the source-tree until we do.
+to copy it from the source-tree until we do. This header is not installed 
+because the interface is not yet stable, please let us know if you want to
+use the API.
 
 Pointer arguments
 -----------------
 implementation of the method from Python and 1 to call a Python implementation
 of the method from Objective-C.
 
+You also must write a custom wrapper when the method has a variable number
+of arguments. It is often adviseable to documented varargs method as 
+unsupported, or to support them only using a fixed number of arguments.
+
 For now it is best to check the source code for the wrappers for the Cocoa 
 class library for more information. We'll add documentation for this in the
 future.

pyobjc/Lib/PyObjCTools/Conversion.py

     elif isinstance(aPyCollection, float):
         return NSNumber.numberWithLongDouble_( aPyCollection )
     elif aPyCollection is None:
+        # XXX: None cannot be represented in PLists.
         return NSNull.null()
     else:
         if conversionHelper:
 </head>
 <body>
 <h2>PyObjC NEWS</h2>
+<p>An overview of the relevant changes in new, and older, releases.</p>
 <h2><a name="version-1-0b1-cvs">Version 1.0b1+ (CVS)</a></h2>
 <ul>
 <li>Better support for the NSKeyValueCoding protocol.  The module