Commits

Ronald Oussoren  committed 13be1fa

- 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 d847b98
  • Branches pyobjc-ancient

Comments (0)

Files changed (23)

File 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

File 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

File 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

File 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/

File 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>

File 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.

File 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

File 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
 -------------------------------

File 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

File 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
 ---------------------

File 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

File 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>

File 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.

File 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>

File 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.

File 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>

File 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.

File 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

File 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>

File 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.

File 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